TissueViewer

Standalone multi-channel OME-TIFF viewer with a built-in web UI.

Point it at a file or a folder and open your browser.

Contents

• What it is
• Supported formats
• Installation
• Quick start
• Command-line reference
• Environment variables
• Configuration file
• Filename conventions
• Programmatic use
• Troubleshooting
• Development
• Docker migration
• License
• Acknowledgements

What it is

TissueViewer is a zero-config viewer for high-resolution multi-channel microscopy images. It serves deep-zoom tiles over HTTP and ships with a pre-built OpenSeadragon front-end that lets you colourise channels, adjust gains and windowing, and save per-slide settings.

Supported formats

• OME-TIFF (.ome.tif, .ome.tiff) — any bit depth, any number of channels, with or without a built-in pyramid.

Support for additional formats (plain TIFF, OME-Zarr) is planned as pluggable handlers; see src/tissueviewer/formats/ for the registry.

Installation

pip install tissueviewer

Or from a source checkout:

git clone https://github.com/davidvi/tissueviewer.git
cd tissueviewer
pip install .

Requires Python 3.10 or later. On macOS / Linux / Windows.

Quick start

Open a single file:

tissueviewer /path/to/slide.ome.tiff

Browse a folder of slides (root folder becomes the public location):

tissueviewer /path/to/slides

Browse a nested tree of folders:

tissueviewer /path/to/slides --recursive --open

Use a config file:

tissueviewer --config config.yaml

Check every file in a directory can be opened, then exit:

tissueviewer /path/to/slides --validate

Command-line reference

usage: tissueviewer [TARGET] [options]

positional:
  TARGET                Path to an .ome.tif(f) file or a directory of them.

options:
  -r, --recursive       Include nested subdirectories.
  -c, --config FILE     YAML configuration file.
  -p, --port N          Listen port (default 8000).
  -H, --host HOST       Bind address (default 127.0.0.1).
  -o, --open            Open the default web browser after start.
  -w, --watch           Rescan TARGET on filesystem changes.
      --validate        Verify every OME-TIFF, then exit.
      --no-save         Disable writing .sample.json sidecars.
      --log-level LEVEL DEBUG | INFO | WARNING | ERROR  (default INFO).
  -V, --version         Show version and exit.
  -h, --help            Show help and exit.

TARGET is optional if either --config is given or TV_SLIDE_DIR is set.

Environment variables

Kept for backward compatibility with the Docker deployment. CLI and config values take precedence.

Configuration file

# config.yaml
data_dir: /srv/tissue-viewer/slides
recursive: true
host: 0.0.0.0
port: 8000
save_enabled: false
log_level: INFO
colors:
  - red
  - green
  - blue

tissueviewer --config config.yaml

Precedence (highest wins): CLI flags → environment variables → YAML → built-in defaults.

Filename conventions

All recognized slide files end in .ome.tif or .ome.tiff (case-insensitive).

For a slide named patient42.ome.tiff, two sidecar files may appear next to it:

Delete them freely to reset.

Locations

The web UI groups slides into locations. The mapping:

• Single-file mode → the file lives under the public location.
• Directory mode (no --recursive) → files at the root → public; every immediate subdirectory → its own location named after the subdirectory.
• Directory mode with --recursive → files at the root still go to public; files in nested subdirectories are grouped under a slash-joined location path like 2024/batch_A.

Programmatic use

create_app builds a regular FastAPI instance, suitable for any ASGI server (uvicorn, hypercorn, daphne).

from tissueviewer import Config, create_app

app = create_app(Config(data_dir="/srv/slides", recursive=True))

uvicorn my_module:app --host 0.0.0.0 --port 8000

Troubleshooting

• <COMPRESSION.LZW: 5> requires the 'imagecodecs' package (or the same for JPEG) — imagecodecs is missing. Slides open and the .dzi manifest loads, but every tile returns HTTP 500 and the slide renders blank. Other slides in the same library keep working, so this often appears only when the first LZW slide arrives — uncompressed slides are unaffected, and Deflate, PackBits and Zstd are decoded by tifffile itself. Install it with pip install imagecodecs. imagecodecs is a declared dependency, so this normally means the package is being run from a source checkout (e.g. via PYTHONPATH) that was never pip installed. The server logs a warning at startup when it is absent, and tissueviewer --validate reports the affected files.
• Port already in use — tissueviewer --port 8001.
• Blank tiles / wrong colours — delete the slide's .sample.json to reset settings, then reload.
• Apple Silicon wheels — imagecodecs and opencv-python-headless ship arm64 wheels; no local build required.
• Zarr 2 vs 3 — both are supported. The pin is zarr>=2.15,<4.
• OpenCV GUI warning — tissueviewer depends on opencv-python-headless; a warning about cv2.imshow not being available is normal and harmless.

Development

See CONTRIBUTING.md for local setup, how to rebuild the Vue UI, and how to cut a release.

Docker migration

TissueViewer used to ship as a Docker image with a Java-based bioformats2raw conversion pipeline. That mode is gone in 0.2; see MIGRATION.md for guidance.

License

Creative Commons Attribution-NonCommercial 4.0 International — see LICENSE.md.

Acknowledgements

TissueViewer uses OpenSeadragon for high-performance tiled image visualisation.