TissueViewer

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

Table of Contents

• About TissueViewer
• Usage
  • Supported Formats
  • File Structure
  • Run as Docker
  • Access over Network
  • Adding Files
  • Deploy in cloud
• Acknowledgements

About TissueViewer

TissueViewer 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!

Supported Formats

TissueViewer utilizes Bioformats2raw to convert various file formats to OME-ZARR. This means that TissueViewer supports any format compatible with Bioformats. For a comprehensive list of supported formats, refer to the Bioformats supported formats page.

File Structure

file-storage/
│
├── import/             # Directory for images to be imported
│   └── ...
│
└── storage/            # Directory for storing the raw processed images
    └── ...

Explanation:

• import/public/: Place your images to be processed here.
• storage/: TissueViewer uses this directory to store raw processed images.

Run as Docker

To run TissueViewer within a Docker container, follow these steps. This setup allows you to run the viewer and automatically watch a folder for new image files, which will then be processed into multiple deep zoom images.

1. Build the Docker Image

   Start by building the Docker image from your Dockerfile. This image will include all the necessary dependencies and configurations to run TissueViewer.

   git clone https://github.com/davidvi/tissueviewer.git
   cd tissueviewer
   docker build -t tv .

2. Run the Docker Container

   Run the Docker container by mapping your local directories to the appropriate directories within the container. This allows the application to access and store data on your local machine.

   • -p 8080:8080 maps the port 8080 of the container to port 8080 on your host, allowing you to access the viewer via localhost:8080.
   • -v /your/local/import/directory:/tv-import maps your local directory for importing images to the corresponding directory in the container.
   • -v /your/local/storage/directory:/tv-store maps your local directory for storing processed images to the corresponding directory in the container.

   Run the following command, replacing /your/local/import/directory and /your/local/storage/directory with the paths to your actual directories:

   docker run -p 8080:8080 -v /your/local/import/directory:/tv-import -v /your/local/storage/directory:/tv-store tv

After executing these steps, TissueViewer will be running inside the Docker container, monitoring the specified import directory for new files to process, and accessible through your web browser at http://localhost:8080.

Access over Network

To access TissueViewer from an external computer (not the computer running TissueViewer), follow these steps:

1. Ensure your host computer's IP address is accessible on your network.

2. Make sure the port TissueViewer is using (default 8080) is open on your host computer's firewall.

3. When running the Docker container, bind it to the host's network interface:

   -p 0.0.0.0:8080:8080
   

   This allows connections from any IP address.

4. Access TissueViewer from another computer on the same network using:

   http://<host-ip-address>:8080
   

   Replace <host-ip-address> with the actual IP address of the computer running TissueViewer.

Note: If you're accessing TissueViewer over the internet (not just your local network), ensure you have proper security measures in place, such as a VPN or secure gateway. It's also recommended to use a reverse proxy like Nginx to route traffic, which can provide additional security and management features.

Adding Files

There are two methods available for adding or uploading files to TissueViewer:

1. Direct Addition to Import Folder:

   • Locate the import/public folder in your file-storage directory.
   • Copy or move your files directly into this folder.
   • TissueViewer will automatically detect and process these files.

2. Web Application Upload:

   • Access the TissueViewer web interface.
   • Navigate to the upload page.
   • Use the provided interface to select and upload your files.

Both methods will result in your files being processed by TissueViewer. Choose the method that best suits your workflow and the size of the files you're working with.

Note: Large files may be better suited for the direct addition method, as web uploads can be limited by browser and server configurations.

Cloud deploy

See instructions in folder cloud-deploy.

Acknowledgements

TissueViewer uses OpenSeadragon for robust, high-performance image visualization.