{"id":13717223,"url":"https://github.com/AllenCellModeling/napari-aicsimageio","last_synced_at":"2025-05-07T07:30:38.239Z","repository":{"id":37861621,"uuid":"248818912","full_name":"AllenCellModeling/napari-aicsimageio","owner":"AllenCellModeling","description":"Multiple file format reading directly into napari using pure Python","archived":false,"fork":false,"pushed_at":"2024-07-21T00:01:26.000Z","size":57448,"stargazers_count":35,"open_issues_count":19,"forks_count":10,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-14T02:38:54.584Z","etag":null,"topics":["imageio","microscopy","napari"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AllenCellModeling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2020-03-20T17:52:38.000Z","updated_at":"2025-01-28T21:06:45.000Z","dependencies_parsed_at":"2024-07-21T01:36:07.765Z","dependency_job_id":null,"html_url":"https://github.com/AllenCellModeling/napari-aicsimageio","commit_stats":{"total_commits":67,"total_committers":7,"mean_commits":9.571428571428571,"dds":0.3731343283582089,"last_synced_commit":"2b00d4019fed06437c6ae098a9f217ce00e85bb1"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenCellModeling%2Fnapari-aicsimageio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenCellModeling%2Fnapari-aicsimageio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenCellModeling%2Fnapari-aicsimageio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenCellModeling%2Fnapari-aicsimageio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AllenCellModeling","download_url":"https://codeload.github.com/AllenCellModeling/napari-aicsimageio/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252833401,"owners_count":21811174,"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":["imageio","microscopy","napari"],"created_at":"2024-08-03T00:01:19.513Z","updated_at":"2025-05-07T07:30:35.382Z","avatar_url":"https://github.com/AllenCellModeling.png","language":"Python","readme":"# napari-aicsimageio\n\n[![License](https://img.shields.io/pypi/l/napari-aicsimageio.svg?color=green)](https://github.com/AllenCellModeling/napari-aicsimageio/raw/main/LICENSE)\n[![Build Status](https://github.com/AllenCellModeling/napari-aicsimageio/workflows/Build%20Main/badge.svg)](https://github.com/AllenCellModeling/napari-aicsimageio/actions)\n[![Code Coverage](https://codecov.io/gh/AllenCellModeling/napari-aicsimageio/branch/main/graph/badge.svg)](https://codecov.io/gh/AllenCellModeling/napari-aicsimageio)\n\nAICSImageIO bindings for napari\n\n---\n\n## Features\n\n-   Supports reading metadata and imaging data for:\n    -   `OME-TIFF`\n    -   `TIFF`\n    -   `CZI` (Zeiss)\n    -   `LIF` (Leica)\n    -   `ND2` (Nikon)\n    -   `DV` (DeltaVision)\n    -   Any formats supported by [aicsimageio](https://github.com/AllenCellModeling/aicsimageio)\n    -   Any formats supported by [bioformats](https://github.com/tlambert03/bioformats_jar)\n(Note: requires `java` and `mvn` executables)\n        -   `SLD` (Slidebook)\n        -   `SVS` (Aperio)\n        -   [Full List](https://docs.openmicroscopy.org/bio-formats/6.5.1/supported-formats.html)\n    -   Any additional format supported by [imageio](https://github.com/imageio/imageio)\n        -   `PNG`\n        -   `JPG`\n        -   `GIF`\n        -   `AVI`\n        -   [Full List](https://imageio.readthedocs.io/en/v2.4.1/formats.html)\n\n_While upstream `aicsimageio` is released under BSD-3 license, this plugin is released under GPLv3 license because it installs all format reader dependencies._\n\n## Installation\n\n**Stable Release:** `pip install napari-aicsimageio` or `conda install napari-aicsimageio -c conda-forge`\u003cbr\u003e\n**Development Head:** `pip install git+https://github.com/AllenCellModeling/napari-aicsimageio.git`\n\n\u003e **Warning**  \n\u003e The `bioformats` reader requires `java` and `mvn` executables, which cannot be pip installed.\n\u003e As a result, it's simplest to install it from conda-forge, ensuring both are also installed:  \n\u003e `conda install -c conda-forge bioformats_jar`\n\n### Reading Mode Threshold\n\nThis image reading plugin will load the provided image directly into memory if it meets\nthe following two conditions:\n\n1. The filesize is less than 4GB.\n2. The filesize is less than 30% of machine memory available.\n\nIf either of these conditions isn't met, the image is loaded in chunks only as needed.\n\n### Use napari-aicsimageio as the Reader for All File Formats\n\nIf you want to force napari to always use this plugin as the reader for all file formats,\ntry running this snippet:\n\n```python\nfrom napari.settings import get_settings\n\nget_settings().plugins.extension2reader = {'*': 'napari-aicsimageio', **get_settings().plugins.extension2reader}\n```\n\nFor more details, see [#37](https://github.com/AllenCellModeling/napari-aicsimageio/issues/37).\n\n## Examples of Features\n\n#### General Image Reading\n\nAll image file formats supported by\n[aicsimageio](https://github.com/AllenCellModeling/aicsimageio) will be read and all\nraw data will be available in the napari viewer.\n\nIn addition, when reading an OME-TIFF, you can view all OME metadata directly in the\nnapari viewer thanks to `ome-types`.\n\n![screenshot of an OME-TIFF image view, multi-channel, z-stack, with metadata viewer](https://raw.githubusercontent.com/AllenCellModeling/napari-aicsimageio/main/images/ome-tiff-with-metadata-viewer.png)\n\n#### Multi-Scene Selection\n\nWhen reading a multi-scene file, a widget will be added to the napari viewer to manage\nscene selection (clearing the viewer each time you change scene or adding the\nscene content to the viewer) and a list of all scenes in the file.\n\n![gif of drag and drop file to scene selection and management](https://raw.githubusercontent.com/AllenCellModeling/napari-aicsimageio/main/images/scene-selection.gif)\n\n#### Access to the AICSImage Object and Metadata\n\n![napari viewer with console open showing `viewer.layers[0].metadata`](https://raw.githubusercontent.com/AllenCellModeling/napari-aicsimageio/main/images/console-access.png)\n\nYou can access the `AICSImage` object used to load the image pixel data and\nimage metadata using the built-in napari console:\n\n```python\nimg = viewer.layers[0].metadata[\"aicsimage\"]\nimg.dims.order  # TCZYX\nimg.channel_names  # [\"Bright\", \"Struct\", \"Nuc\", \"Memb\"]\nimg.get_image_dask_data(\"ZYX\")  # dask.array.Array\n```\n\nThe napari layer metadata dictionary also stores a shorthand\nfor the raw image metadata:\n\n```python\nviewer.layers[0].metadata[\"raw_image_metadata\"]\n```\n\nThe metadata is returned in whichever format is used by the underlying\nfile format reader, i.e. for CZI the raw metadata is returned as\nan `xml.etree.ElementTree.Element`, for OME-TIFF the raw metadata is returned\nas an `OME` object from `ome-types`.\n\nLastly, if the underlying file format reader has an OME metadata conversion function,\nyou may additionally see a key in the napari layer metadata dictionary\ncalled `\"ome_types\"`. For example, because the AICSImageIO\n`CZIReader` and `BioformatsReader` both support converting raw image metadata\nto OME metadata, you will see an `\"ome_types\"` key that stores the metadata transformed\ninto the OME metadata model.\n\n```python\nviewer.layers[0].metadata[\"ome_types\"]  # OME object from ome-types\n```\n\n#### Mosaic Reading\n\nWhen reading CZI or LIF images, if the image is a mosaic tiled image, `napari-aicsimageio`\nwill return the reconstructed image:\n\n![screenshot of a reconstructed / restitched mosaic tile LIF](https://raw.githubusercontent.com/AllenCellModeling/napari-aicsimageio/main/images/tiled-lif.png)\n\n## Development\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for information related to developing the code.\n\nFor additional file format support, contributed directly to\n[AICSImageIO](https://github.com/AllenCellModeling/aicsimageio).\nNew file format support will become directly available in this\nplugin on new `aicsimageio` releases.\n\n## Citation\n\nIf you find `aicsimageio` and `napari-aicsimageio` useful, please cite this work as:\n\n\u003e Eva Maxfield Brown, Dan Toloudis, Jamie Sherman, Madison Swain-Bowden, Talley Lambert, AICSImageIO Contributors (2021). AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python [Computer software]. GitHub. https://github.com/AllenCellModeling/aicsimageio\n\n\u003e Eva Maxfield Brown, Talley Lambert, Peter Sobolewski, Napari-AICSImageIO Contributors (2021). Napari-AICSImageIO: Image Reading in Napari using AICSImageIO [Computer software]. GitHub. https://github.com/AllenCellModeling/napari-aicsimageio\n\nbibtex:\n```bibtex\n@misc{aicsimageio,\n  author    = {Brown, Eva Maxfield and Toloudis, Dan and Sherman, Jamie and Swain-Bowden, Madison and Lambert, Talley and {AICSImageIO Contributors}},\n  title     = {AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python},\n  year      = {2021},\n  publisher = {GitHub},\n  url       = {https://github.com/AllenCellModeling/aicsimageio}\n}\n\n@misc{napari-aicsimageio,\n  author    = {Brown, Eva Maxfield and Lambert, Talley and Sobolewski, Peter and {Napari-AICSImageIO Contributors}},\n  title     = {Napari-AICSImageIO: Image Reading in Napari using AICSImageIO},\n  year      = {2021},\n  publisher = {GitHub},\n  url       = {https://github.com/AllenCellModeling/napari-aicsimageio}\n}\n```\n\n_Free software: GPLv3_\n","funding_links":[],"categories":["Other"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAllenCellModeling%2Fnapari-aicsimageio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAllenCellModeling%2Fnapari-aicsimageio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAllenCellModeling%2Fnapari-aicsimageio/lists"}