{"id":18963874,"url":"https://github.com/janeliascicomp/zarrcade","last_synced_at":"2025-04-19T12:48:18.486Z","repository":{"id":227656471,"uuid":"769317478","full_name":"JaneliaSciComp/zarrcade","owner":"JaneliaSciComp","description":"Create web-based OME-Zarr galleries","archived":false,"fork":false,"pushed_at":"2025-01-25T18:35:55.000Z","size":5163,"stargazers_count":16,"open_issues_count":3,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-29T08:02:10.676Z","etag":null,"topics":["microscopy-images","ome-zarr","webapp"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JaneliaSciComp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-08T19:48:41.000Z","updated_at":"2025-03-26T03:45:34.000Z","dependencies_parsed_at":"2024-05-03T22:31:11.746Z","dependency_job_id":"449fc3e3-3741-47ee-ab6b-10f0fade7016","html_url":"https://github.com/JaneliaSciComp/zarrcade","commit_stats":null,"previous_names":["krokicki/ngffbrowse","janeliascicomp/ngffbrowse","janeliascicomp/zarrcade"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaneliaSciComp%2Fzarrcade","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaneliaSciComp%2Fzarrcade/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaneliaSciComp%2Fzarrcade/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaneliaSciComp%2Fzarrcade/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JaneliaSciComp","download_url":"https://codeload.github.com/JaneliaSciComp/zarrcade/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249201117,"owners_count":21229004,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["microscopy-images","ome-zarr","webapp"],"created_at":"2024-11-08T14:22:12.928Z","updated_at":"2025-04-16T05:31:29.017Z","avatar_url":"https://github.com/JaneliaSciComp.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zarrcade \n\n![logoz@0 1x](https://github.com/user-attachments/assets/21e45ddf-f53b-4391-9014-e1cad0243e7e)\n\n[![Python CI](https://github.com/JaneliaSciComp/zarrcade/actions/workflows/python-ci.yml/badge.svg)](https://github.com/JaneliaSciComp/zarrcade/actions/workflows/python-ci.yml)\n\nZarrcade is a web application for easily browsing, searching, and visualizing collections of [OME-NGFF](https://github.com/ome/ngff) (i.e. OME-Zarr) images. It implements the following features:\n\n* Automatic discovery of OME-Zarr images on [any storage backend supported by fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#other-known-implementations) including file system, AWS S3, Azure Blob, Google Cloud Storage, Dropbox, etc.\n* MIP/thumbnail generation\n* Web-based MIP gallery with convenient viewing links to NGFF-compliant viewers\n* Searchable/filterable metadata and annotations\n* Neuroglancer state generation for multichannel images\n* Build-in file proxy for non-public storage backends\n* Integration with external file proxies (e.g. [x2s3](https://github.com/JaneliaSciComp/x2s3))\n \n![screenshot](https://github.com/user-attachments/assets/15ff03b4-2c90-4307-9771-fb6041676588)\n\n\n## Getting Started\n\n### 1. Install miniforge\n\n[Install miniforge]([https://docs.conda.io/en/latest/miniforge.html](https://github.com/conda-forge/miniforge)) if you don't already have it.\n\n\n### 2. Clone this repo\n\n```bash\ngit clone https://github.com/JaneliaSciComp/zarrcade.git\ncd zarrcade\n```\n\n### 3. Initialize the conda environment\n\n```bash\nconda env create -f environment.yml\nconda activate zarrcade\n```\n\n\n### (Optional) Try an example\n\nSee the [Example](#example) section below to try out the example before working with your own data.\n\n\n### 4. Create OME-Zarr images\n\nIf your images are not already in OME-Zarr format, you will need to convert them, e.g. using bioformats2raw:\n\n```bash\nbioformats2raw -w 128 -h 128 -z 64 --compression zlib /path/to/input /path/to/zarr\n```\n\nIf you have many images to convert, we recommend using the [nf-omezarr Nextflow pipeline](https://github.com/JaneliaSciComp/nf-omezarr) 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).\n\n\n### 5. Import images and metadata into Zarrcade\n\nYou can import images into Zarrcade using the provided command line script:\n\n```bash\nbin/import.py -d /root/data/dir -c mycollection\n```\n\nThis 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`. \n\nTo add extra metadata about the images, you can provide a CSV file with the `-i` flag:\n\n```bash\n./bin/import.py -d /root/data/dir -c collection_name -i input.csv\n```\n\nThe 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.:\n\n```csv\nPath,Line,Marker\nrelative/path/to/ome1.zarr,JKF6363,Blu\nrelative/path/to/ome2.zarr,JDH3562,Blu\n```\n\nRead more about the import options in the [Data Import](./docs/DataImport.md) section of the documentation.\n\n\n### 6. Run the Zarrcade web application\n\nStart the development server, pointing it to your OME-Zarr data:\n\n```bash\nuvicorn zarrcade.serve:app --host 0.0.0.0 --reload\n```\n\nYour images and annotations will be indexed and browseable at [http://0.0.0.0:8000](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.\n\n\n## Example\n\nTo try an example, follow steps 1 and 2 above and use the following command to import the example data:\n\n```bash\n./bin/import.py -d s3://janelia-data-examples/fly-efish -c flyefish -m docs/flyefish-example.csv\n```\n\nCopy the example settings.yaml file to your working directory and start the server:\n\n```bash\ncp docs/settings.yaml.example settings.yaml\nuvicorn zarrcade.serve:app --host 0.0.0.0 --reload\n```\n\nThe example should be visible at [http://0.0.0.0:8000](http://0.0.0.0:8000).\n\n\n## Documentation\n\n* [Overview](./docs/Overview.md) - learn about the data model and overall architecture\n* [Configuration](./docs/Configuration.md) - configure the Zarrcade service using settings.yaml or environment variables\n* [Deployment](./docs/Deployment.md) - instructions for deploying the service with Docker and in production mode\n* [Development Notes](./docs/Development.md) - technical notes for developers working on Zarrcade itself\n\n\n## Known Limitations\n\n* Zarrcade has so far only been tested with OME-Zarr images generated by the [bioformats2raw](https://github.com/ome/bioformats2raw) tool.\n* The `OmeZarrAgent` does 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](https://github.com/JaneliaSciComp/zarrcade/issues).\n\n\n## Attributions\n\n* \u003chttps://www.iconsdb.com/black-icons/copy-link-icon.html\u003e\n* \u003chttps://www.veryicon.com/icons/education-technology/smart-campus-1/view-details-2.html\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaneliascicomp%2Fzarrcade","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaneliascicomp%2Fzarrcade","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaneliascicomp%2Fzarrcade/lists"}