{
  "name": "napari-ome-zarr-navigator",
  "display_name": "napari OME-Zarr Navigator",
  "visibility": "public",
  "icon": null,
  "categories": [
    "Dataset",
    "Visualization"
  ],
  "schema_version": "0.3.0",
  "on_activate": null,
  "on_deactivate": null,
  "contributions": {
    "commands": [
      {
        "id": "napari-ome-zarr-navigator.make_plate_browser",
        "title": "Plate Browser",
        "python_name": "napari_ome_zarr_navigator:PlateBrowser",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      },
      {
        "id": "napari-ome-zarr-navigator.make_roi_loader",
        "title": "ROI Loader",
        "python_name": "napari_ome_zarr_navigator.roi_loader:ROILoaderImage",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      },
      {
        "id": "napari-ome-zarr-navigator.make_roi_annotator",
        "title": "ROI Annotator",
        "python_name": "napari_ome_zarr_navigator.roi_annotator:ROIAnnotatorImage",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      },
      {
        "id": "napari-ome-zarr-navigator.make_label_saver",
        "title": "Save label layer to OME-Zarr",
        "python_name": "napari_ome_zarr_navigator.label_saver:LabelSaverImage",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      },
      {
        "id": "napari-ome-zarr-navigator.hiPSC_zarr",
        "title": "Load hiPSC sample data from Zenodo",
        "python_name": "napari_ome_zarr_navigator._sample_data:hiPSC_zarr",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      },
      {
        "id": "napari-ome-zarr-navigator.leukemia_zarr",
        "title": "Load leukemia PDX sample data from Zenodo",
        "python_name": "napari_ome_zarr_navigator._sample_data:leukemia_zarr",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      }
    ],
    "readers": null,
    "writers": null,
    "widgets": [
      {
        "command": "napari-ome-zarr-navigator.make_plate_browser",
        "display_name": "Plate Browser",
        "autogenerate": false,
        "default_dock_area": "right",
        "tabify": false
      },
      {
        "command": "napari-ome-zarr-navigator.make_roi_loader",
        "display_name": "ROI Loader",
        "autogenerate": false,
        "default_dock_area": "right",
        "tabify": false
      },
      {
        "command": "napari-ome-zarr-navigator.make_roi_annotator",
        "display_name": "ROI Annotator",
        "autogenerate": false,
        "default_dock_area": "right",
        "tabify": false
      },
      {
        "command": "napari-ome-zarr-navigator.make_label_saver",
        "display_name": "Save label layer to OME-Zarr",
        "autogenerate": false,
        "default_dock_area": "right",
        "tabify": false
      }
    ],
    "sample_data": [
      {
        "command": "napari-ome-zarr-navigator.hiPSC_zarr",
        "key": "unique_id.1",
        "display_name": "hiPSC"
      },
      {
        "command": "napari-ome-zarr-navigator.leukemia_zarr",
        "key": "unique_id.2",
        "display_name": "leukemia"
      }
    ],
    "themes": null,
    "menus": {},
    "submenus": null,
    "keybindings": null,
    "configurations": {}
  },
  "package_metadata": {
    "metadata_version": "2.5",
    "name": "napari-ome-zarr-navigator",
    "version": "0.5.0",
    "dynamic": null,
    "platform": null,
    "supported_platform": null,
    "summary": "A plugin to browse OME-Zarr plates by conditions and load images, labels and features from ROIs",
    "description": "# napari-ome-zarr-navigator <img align=\"right\" height=\"150\" src=\"https://raw.githubusercontent.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator/master/docs/images/navigator_logo.png\">\n\n[![License BSD-3](https://img.shields.io/pypi/l/napari-ome-zarr-navigator.svg?color=green)](https://github.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator/raw/main/LICENSE)\n[![PyPI](https://img.shields.io/pypi/v/napari-ome-zarr-navigator.svg?color=green)](https://pypi.org/project/napari-ome-zarr-navigator)\n[![Python Version](https://img.shields.io/pypi/pyversions/napari-ome-zarr-navigator.svg?color=green)](https://python.org)\n[![tests](https://github.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator/actions/workflows/test_and_deploy.yml/badge.svg?branch=main)](https://github.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator/actions)\n[![codecov](https://codecov.io/gh/fractal-napari-plugins-collection/napari-ome-zarr-navigator/graph/badge.svg?token=Mg1081BoRA)](https://codecov.io/gh/fractal-napari-plugins-collection/napari-ome-zarr-navigator)\n\nA plugin to interact with OME-Zarr images and plates. Enables integrating OME-Zarrs & [Fractal tables](https://biovisioncenter.github.io/ngio/stable/table_specs/overview/), browsing plates by conditions, loading ROIs from ROI tables, loading features from feature tables, annotating new ROI tables and saving labels back into OME-Zarr.\n\n<p align=\"center\">\n  <a href=\"https://www.youtube.com/watch?v=aUlbiQJXx_I\">\n    <img src=\"https://img.youtube.com/vi/aUlbiQJXx_I/maxresdefault.jpg\" width=\"1080\" alt=\"Watch the demo\">\n  </a>\n</p>\n(click the picture above to see the walkthrough video)\n\n\n## Usage\n\n### Plate Browser\n\nThe Plate Browser loads an OME-Zarr plate from the local filesystem, via authenticated HTTPS (e.g. a [Fractal Server](https://fractal-analytics-platform.github.io/) instance) or from S3 (`s3://` URIs, using the credentials of your AWS environment; when no credentials are found, public buckets are opened anonymously). It also auto-detects plates opened via [napari-ome-zarr](https://github.com/ome/napari-ome-zarr). The Plate Browser lets you zoom to a selected well (\"Go to well\"), which draws a bounding box and centers the camera on that well.\n\n<img width=\"1624\" alt=\"plate_browser_go_to_well\" src=\"https://github.com/user-attachments/assets/c83c1daf-a5d2-41b7-8685-564f80eb0122\" />\n\nUsing [ngio condition tables](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/condition_table/), the Plate Browser can filter the well list to any subset defined by one or more conditions. Plate-level condition tables (fast) and image-level condition tables (slower, aggregated on the fly) are both supported.\n\n<img width=\"1512\" alt=\"plate_browser_filtering\" src=\"https://github.com/user-attachments/assets/7938ed80-31ee-4e58-b896-20ed92ea6508\" />\n\n### ROI Loader\n\nThe ROI Loader can be launched directly from napari's *Plugins* menu (standalone) or by selecting a well in the Plate Browser (\"Select ROI to load\"). It supports:\n\n- Loading images from different multiplexing cycles / acquisitions\n- Loading any ROI from [ROI tables](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/roi_table/), or the whole image when no ROI table is selected\n- Loading label images\n- Loading feature measurements from [feature tables](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/feature_table/)\n- **Multi-resolution (lazy)** mode — streams a full dask pyramid, optimal for large images and remote data\n- **Fixed resolution** mode — loads a single numpy array, optimal for 3D images and downstream tools in napari that don't handle multi-resolution layers (e.g. the label layer needs to be loaded as fixed resolution for using it in the classifier)\n\nOnce a ROI has been loaded for one well, \"Load selected ROI for additional well(s)\" reuses the same settings for any further wells selected in the Plate Browser.\n\n#### ROI position options\n\nTwo options under **Advanced settings** change where a ROI is placed. Each one is only available when the selected ROI table has the columns it needs, and they can be combined.\n\n- **Load ROI at original position** uses the ROI table's `x/y/z_micrometer_original` columns, e.g. in the `FOV_ROI_table` written by Fractal's converters. Positions are taken relative to the smallest original position in the table, so fields of view stay in their well and keep the overlaps they had during acquisition. This is useful for stitching, e.g. with [multiview-stitcher](https://github.com/multiview-stitcher/napari-stitcher). Fields of view that didn't overlap land at their regular position.\n- **Add registration translation** shifts the ROI by the table's `translation_x/y/z` columns, as written by Fractal's registration tasks, to overlay a multiplexing acquisition on the reference acquisition. Use it only when the registration was calculated but not yet applied to the images; otherwise the shift is applied twice.\n\nLayers loaded with either option don't line up with the image on disk, so the Label Saver won't save them and the ROI Annotator won't allow for saving ROI tables for them. Reload the ROI without these options to do so.\n\n#### Masked loading\n\nWhen the selected ROI table is a masking ROI table (one ROI per object of a label image, e.g. organoids or nuclei), **Mask ROI by its label** under **Advanced settings** keeps only the selected object: image and label pixels outside the object become 0, and loaded features only cover that object. This shows a single object without the neighbours that share its bounding box, e.g. to make a clean projection of one organoid from its 3D segmentation. Masked label layers only contain the selected object, so the Label Saver won't save them.\n\n<img width=\"1624\" alt=\"roi_loader\" src=\"https://github.com/user-attachments/assets/ddd8268f-52ae-4a43-9c00-f52df4422ba3\" />\n\nThis plugin is tested with OME-Zarr files generated by [Fractal](https://fractal-analytics-platform.github.io/) and is designed to work with any OME-Zarr ≥ v0.4. The feature loading workflow is optimised for use with the [napari-feature-classifier](https://github.com/fractal-napari-plugins-collection/napari-feature-classifier).\n\n### ROI Annotator\n\nThe ROI Annotator can be launched from napari's *Plugins* menu (standalone, for single images), from the ROI Loader, or from the Plate Browser (\"Annotate ROIs\", for individual wells). It writes [ROI tables](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/roi_table/) and [Masking ROI tables](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/masking_roi_table/) back to the OME-Zarr store using [ngio](https://biovisioncenter.github.io/ngio/stable/).\n\n#### Interactive ROI annotation\n\nDraw rectangular ROIs by hand on any loaded image. Select **Initialize empty ROI layer**, click **Initialize ROI Layer** to create a shapes layer in drawing mode, then draw rectangles. The table name, backend (CSV, JSON, Parquet, AnnData), and overwrite flag can all be configured before saving. Only rectangle annotations are supported.\n\n<img width=\"1726\" alt=\"interactive_roi_table_creation\" src=\"https://github.com/user-attachments/assets/c91c7496-27a2-4236-a8bd-c13c5002070b\" />\n\n\n> **Limitations (napari shapes layer)**\n> - Interactively drawn ROIs are always 2D — napari shapes cannot represent 3D extents.\n> - Each ROI covers a single time point — shapes do not span multiple frames.\n\n#### ROI creation from labels (Masking ROI table)\n\nSelect **Masking ROI layer**, choose a label layer that has been loaded into the viewer for a given OME-Zarr image (e.g. loaded by the ROI loader above), and click **Calculate masking ROI table**. The annotator computes one bounding-box ROI per labelled object using [ngio's `compute_masking_roi`](https://biovisioncenter.github.io/ngio/stable/) and adds the results as a shapes layer for review. Z-extents are inferred from the label data and stored as shape properties; 3D bounding boxes are supported when the image is 3D. Clicking **Save ROI Table** writes the result as a [Masking ROI table](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/masking_roi_table/) to the OME-Zarr, if a corresponding label is available.\n\n<img width=\"1726\" alt=\"masking_roi_table_creation\" src=\"https://github.com/user-attachments/assets/0caeea55-f080-4b19-b5e8-da89d6ddf8c2\" />\n\n\n#### Remote OME-Zarr stores\n\nThe annotator opens images from local files, authenticated HTTPS stores or S3. Saving back to a remote store is not supported (the store is read-only from the plugin's perspective). When a remote image is loaded, a **Save to folder** picker appears so the table can be written to a local directory instead.\n\n\n### Save Labels\n\nThe Save Labels widget can be launched from napari's *Plugins* menu (standalone, for single images) or from the ROI Loader (\"Save label layer to OME-Zarr\"). It saves any napari label layer back to an OME-Zarr image as a label image using [ngio](https://biovisioncenter.github.io/ngio/stable/), with optional [Masking ROI table](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/masking_roi_table/) generation.\n\nThree write modes cover the main use cases:\n\n- **Save as new label** — creates the label for the first time; fails if the label already exists\n- **Edit existing label** — patches only the pixels in the currently loaded ROI; every pixel outside that region stays unchanged (intended for proof-reading individual ROIs)\n- **Reset existing label** — overwrites the full label with the current layer\n\n#### Creating new labels\n\nLoad an image with the ROI Loader, segment or annotate it in napari, then open the Save Labels widget. Select the label layer, choose a name, and click **Save label to OME-Zarr**. The pixel size metadata is taken from the napari label layer. Optionally enable **Save masking ROI table** to derive per-object bounding-box ROIs at the same time.\n\n<img width=\"1631\" alt=\"save_new_label\" src=\"https://github.com/user-attachments/assets/bda2e077-155c-4a08-a1c1-e79673841ab4\" />\n\n#### Proof-reading labels ROI by ROI\n\nLoad a single ROI using the ROI Loader, edit the label layer in napari, then switch the write mode to **Edit existing label** and save. Only the pixels within the loaded ROI are written back; the rest of the label is untouched. Importantly, neither the ROI loader nor the label saving perform masking. Thus, if you load masking ROI tables, be aware that labels outside the mask will still load and you should not remove them, otherwise they get removed from the final label image.\n\n<img width=\"1631\" alt=\"edit_label\" src=\"https://github.com/user-attachments/assets/49495b59-af2c-45d8-b329-90d2236fa020\" />\n\n#### Remote OME-Zarr stores\n\nWhen the source image is on an authenticated remote store (e.g. served by the [Fractal data service](https://github.com/fractal-analytics-platform/fractal-data)) or on S3, the label cannot be written back to the read-only remote container. In this case a **Local output** folder picker appears and the label is saved there instead.\n\n### S3 access\n\nSelect the **S3** source and enter an `s3://` URI. Credentials come from the standard AWS chain (environment variables, `~/.aws/credentials` / `~/.aws/config`, instance role); the plugin has no credential fields. When no credentials are found, public buckets are opened anonymously.\n\nKnown limitations:\n\n- S3 stores are read-only: ROI tables and labels are saved to a local folder.\n- Credentials are read when S3 is first accessed. If you configure or refresh credentials while napari is running, restart napari to use them.\n- Expired or invalid credentials are still used, so they also block public buckets (no anonymous retry). The same problem could occur if using corporate credentials. Refresh them and restart napari, or start napari without them, e.g. `AWS_SHARED_CREDENTIALS_FILE=/dev/null napari`.\n\n\n----------------------------------\n\n\n## Test data\n\nTest & sample data is available at https://zenodo.org/records/20429951\n\n\n## Installation\n\n### Via pixi (recommended)\n\n[pixi](https://pixi.sh) manages all Python and system dependencies in a single step:\n\n```bash\ngit clone https://github.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator\ncd napari-ome-zarr-navigator\npixi run napari\n```\n\nTo launch with the full feature-analysis environment (adds [napari-feature-classifier](https://github.com/fractal-napari-plugins-collection/napari-feature-classifier) and [napari-feature-visualization](https://github.com/fractal-napari-plugins-collection/napari-feature-visualization)):\n\n```bash\npixi run --frozen napari-fractal\n```\n\n### Via pip\n\nInstall into an existing Python ≥ 3.11 environment with [napari] already present:\n\n```bash\npip install napari-ome-zarr-navigator\n```\n\nFor a fresh environment we recommend [miniforge](https://github.com/conda-forge/miniforge):\n\n```bash\nconda create -n napari-ome-zarr python=3.12 napari pyqt -c conda-forge\nconda activate napari-ome-zarr\npip install napari-ome-zarr-navigator\nnapari\n```\n\nOptionally also install additional plugins like `napari-feature-classifier` and `napari-feature-visualization`, as in:\n```bash\npip install napari-feature-classifier napari-feature-visualization\n```\n\n## Contributing\n\nContributions are very welcome. Tests can be run with `pixi run test`; please ensure coverage stays the same before submitting a pull request.\n\nSet up the pre-commit hooks once with `pixi run pre-commit install`. They run ruff from the pixi environment, so they use the same version as `pixi run lint` and `pixi run format`. `pixi run check` runs lint, type checking and tests together.\n\n## License\n\nDistributed under the terms of the [BSD-3] license,\n\"napari-ome-zarr-navigator\" is free and open source software\n\n## Issues\n\nIf you encounter any problems, please [file an issue] along with a detailed description.\n\n[napari]: https://github.com/napari/napari\n[BSD-3]: http://opensource.org/licenses/BSD-3-Clause\n[file an issue]: https://github.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator/issues\n[pip]: https://pypi.org/project/pip/\n",
    "description_content_type": "text/markdown",
    "keywords": null,
    "home_page": null,
    "download_url": null,
    "author": null,
    "author_email": "Fabio Steffen <fabio.steffen@uzh.ch>, Joel Luethi <joel.luethi@uzh.ch>",
    "maintainer": null,
    "maintainer_email": null,
    "license": "BSD-3-Clause",
    "classifier": [
      "Development Status :: 2 - Pre-Alpha",
      "Framework :: napari",
      "Intended Audience :: Developers",
      "License :: OSI Approved :: BSD License",
      "Operating System :: OS Independent",
      "Programming Language :: Python",
      "Programming Language :: Python :: 3",
      "Programming Language :: Python :: 3.11",
      "Programming Language :: Python :: 3.12",
      "Programming Language :: Python :: 3.13",
      "Programming Language :: Python :: 3.14",
      "Topic :: Scientific/Engineering :: Image Processing"
    ],
    "requires_dist": [
      "magicgui",
      "napari-ome-zarr!=0.8.0,!=0.8.1",
      "napari>=0.7",
      "ngio<1.2,>=1.1.2",
      "numcodecs!=0.14.0,!=0.14.1,!=0.16",
      "numpy",
      "ome-zarr",
      "pandas",
      "qtpy",
      "requests",
      "s3fs>=2024.2.0"
    ],
    "requires_python": "<3.15,>=3.11",
    "requires_external": null,
    "project_url": [
      "Homepage, https://github.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator",
      "Bug Tracker, https://github.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator/issues",
      "Documentation, https://github.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator#README.md",
      "Source Code, https://github.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator",
      "User Support, https://github.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator/issues"
    ],
    "provides_extra": null,
    "provides_dist": null,
    "obsoletes_dist": null
  },
  "npe1_shim": false
}