Zarrcade is a web application for easily browsing collections of NGFF (e.g. OME-Zarr) images. Implements the following useful features:
- Automatic discovery of images on any storage backend supported by fsspec including file system, AWS S3, Azure Blob, Google Cloud Storage, Dropbox, etc.
- Web gallery with convenient viewing links to compliant viewers
- Neuroglancer state generation for multichannel images
- File proxy for non-public storage backends
- Support for optional image thumbnails
The nf-omezarr tool can be used to easily convert images to OME-Zarr format.
To run the service locally using Docker, just point it at your OME-Zarr data:
docker run -it -v /path/to/data:/data -p 8000:8000 ghcr.io/janeliascicomp/zarrcade
This will index your data and make it browseable at http://127.0.0.1:8000.
If your server is running remotely it will need to use HTTPS in order to be able to accessible to the viewers. You'll need to provide a TLS certificate and a base URL for generating links to your server. This is possible with Uvicorn, but using an Nginx reverse proxy server is usually preferred. Furthermore, by default Zarrcade uses an in-memory Sqlite database. If you want to use something else, set the DB_URL
variable to point to a SQL database.
You can do this using Docker Compose. Make sure you have this installed on your system before proceeding.
First, create a .env
file in the ./docker
folder. You can copy the template like this:
cd docker
cp env.template .env
Customize the .env
file and then start the services:
docker compose up -d
You can import metadata into Zarrcade by pre-populating the SQLite database from a CSV file:
conda env create -f environment.yml -y
conda activate zarrcade
bin/import_metadata.py -i input.csv -r /root/data/dir --overwrite
The CSV file's first column must be a relative path pointing to OME-Zarr images within the root data directory. The remaining columns can be any metadata to be searched and displayed within the gallery:
Path,Line,Marker
relative/path/to/ome1.zarr,JKF6363,Blu
relative/path/to/ome2.zarr,JDH3562,Blu
Install the necessary packages using conda and pip:
conda env create -f environment.yml
conda activate zarrcade
pip install neuroglancer --no-dependencies
Start the development server, pointing it to your OME-Zarr data:
DATA_URL=/path/to/data uvicorn zarrcade.serve:app --host 0.0.0.0 --reload
If you are running the service remote, you'll need to use HTTPS. Just point Uvicorn to your certificate and set your BASE_URL:
BASE_URL=https://myserver.mydomain.org:8000 DATA_URL=/path/to/data uvicorn zarrcade.serve:app --host 0.0.0.0 \
--ssl-keyfile certs/cert.key --ssl-certfile certs/cert.crt --reload
python -m pytest --cov=zarrcade --cov-report html -W ignore::DeprecationWarning
To rebuild the Docker container:
docker build --no-cache docker -t ghcr.io/janeliascicomp/zarrcade:latest
docker push ghcr.io/janeliascicomp/zarrcade:latest