Zarrcade is a web application for easily browsing, searching, and visualizing collections of OME-NGFF (i.e. OME-Zarr) images. It implements the following features:
- Automatic discovery of OME-Zarr images on any storage backend supported by fsspec including file system, AWS S3, Azure Blob, Google Cloud Storage, Dropbox, etc.
- MIP/thumbnail generation
- Web-based MIP gallery with convenient viewing links to NGFF-compliant viewers
- Searchable/filterable metadata and annotations
- Neuroglancer state generation for multichannel images
- Build-in file proxy for non-public storage backends
- Integration with external file proxies (e.g. x2s3)
Install miniforge if you don't already have it.
git clone https://github.com/JaneliaSciComp/zarrcade.git
cd zarrcadeconda env create -f environment.yml
conda activate zarrcadeSee the Example section below to try out the example before working with your own data.
If your images are not already in OME-Zarr format, you will need to convert them, e.g. using bioformats2raw:
bioformats2raw -w 128 -h 128 -z 64 --compression zlib /path/to/input /path/to/zarrIf you have many images to convert, we recommend using the nf-omezarr Nextflow pipeline to efficiently run bioformats2raw on a collection of images. This pipeline also lets you scale the conversion processes to your available compute resources (cluster, cloud, etc).
You can import images into Zarrcade using the provided command line script:
bin/import.py -d /root/data/dir -c mycollectionThis will automatically create a local Sqlite database containing a Zarrcade collection named "mycollection" and populate it with information about the images in the specified directory. By default, this will also create MIPs and thumbnails for each image in ./static/.zarrcade.
To add extra metadata about the images, you can provide a CSV file with the -i flag:
./bin/import.py -d /root/data/dir -c collection_name -i input.csvThe CSV file's first column must be a relative path to the OME-Zarr image within the root data directory. The remaining columns can be any annotations that will be searched and displayed within the gallery, e.g.:
Path,Line,Marker
relative/path/to/ome1.zarr,JKF6363,Blu
relative/path/to/ome2.zarr,JDH3562,Blu
Read more about the import options in the Data Import section of the documentation.
Start the development server, pointing it to your OME-Zarr data:
uvicorn zarrcade.serve:app --host 0.0.0.0 --reloadYour images and annotations will be indexed and browseable at http://0.0.0.0:8000. Read the documentation below for more details on how to configure the web UI and deploy the service in production.
To try an example, follow steps 1 and 2 above and use the following command to import the example data:
./bin/import.py -d s3://janelia-data-examples/fly-efish -c flyefish -m docs/flyefish-example.csvCopy the example settings.yaml file to your working directory and start the server:
cp docs/settings.yaml.example settings.yaml
uvicorn zarrcade.serve:app --host 0.0.0.0 --reloadThe example should be visible at http://0.0.0.0:8000.
- Overview - learn about the data model and overall architecture
- Configuration - configure the Zarrcade service using settings.yaml or environment variables
- Deployment - instructions for deploying the service with Docker and in production mode
- Development Notes - technical notes for developers working on Zarrcade itself
- Zarrcade has so far only been tested with OME-Zarr images generated by the bioformats2raw tool.
- The
OmeZarrAgentdoes not currently support the full OME-Zarr specification, and may fail with certain types of images. If you encounter an error with your data, please open an issue on the Github repository.