# ImmunoViewer

Explore and annotate your multi-channel, large TIF files with this user-friendly viewer designed for high-resolution multiplex imaging.

## Table of Contents

- [About ImmunoViewer](#about-immunoviewer)
- [Installation](#installation)
    - [Install from GitHub](#install-from-github)
    - [Install from pip](#install-from-pip)
- [Usage](#usage)
    - [Folder Structure](#folder-structure)
    - [Generate Tiles](#generate-tiles)
    - [Run the Viewer](#run-the-viewer)
    - [Deploy in cloud](#cloud-deploy)
- [Acknowledgements](#acknowledgements)

## About ImmunoViewer

ImmunoViewer is designed to efficiently handle high-resolution multiplex imaging files, such as those generated by Orion Rarecyte or Keyence Immuno Fluorescence scanners. It supports multi-channel images and allows users to add annotations, customize colors, and adjust signal intensities for each channel. Your suggestions for additional features are highly welcomed!

![ImmunoViewer Screenshot](https://github.com/davidvi/ImmunoViewer/raw/main/img/screenshot.png)

## Installation

ImmunoViewer requires Python 3.10 or higher. We recommend installing ImmunoViewer within a Python virtual environment to manage dependencies effectively.

### Using venv

```bash
python -m venv /path/to/new/virtual/environment
source /path/to/new/virtual/environment/bin/activate
```

### Using Conda

```bash
conda create -n ImmunoViewer
conda activate ImmunoViewer
```

### Install from GitHub

```bash
git clone https://github.com/davidvi/ImmunoViewer.git
cd ImmunoViewer
pip install .
```

### Install from pip

```bash
pip install ImmunoViewer
```

## Usage

### Folder Structure

Configure your data directory to manage input and output files efficiently:

```
data_directory/
  sample1.ome.tiff
  sample2/
    dapi.tiff
    CD68.tiff
```

Files are automatically processed and stored in a separate 'processed' directory.

### Generate Tiles

Generate image tiles for easier viewing and processing:

```bash
ImmunoViewerWatch [data_directory] [processed_directory]
```

### Run the Viewer

Launch the viewer server with the following command:

```bash
ImmunoViewerServe --port [port (default is 8000)] --host [IP address (default = 0.0.0.0)] [processed_directory]
```

Access the viewer by navigating to `http://[IP address]:[port]` in your web browser. Note: If you use the default IP address (0.0.0.0), ensure the port is properly secured if exposed over the network.

### Cloud deploy

See instructions in folder [cloud-deploy](https://github.com/davidvi/ImmunoViewer/tree/main/cloud-deploy). 

## Acknowledgements

ImmunoViewer uses [OpenSeadragon](https://openseadragon.github.io/) for robust, high-performance image visualization.
