Metadata-Version: 2.4
Name: napari-ome-zarr-navigator
Version: 0.3.0
Summary: A plugin to browse OME-Zarr plates by conditions and load images, labels and features from ROIs
Project-URL: Homepage, https://github.com/fractal-analytics-platform/napari-ome-zarr-navigator
Project-URL: Bug Tracker, https://github.com/fractal-analytics-platform/napari-ome-zarr-navigator/issues
Project-URL: Documentation, https://github.com/fractal-analytics-platform/napari-ome-zarr-navigator#README.md
Project-URL: Source Code, https://github.com/fractal-analytics-platform/napari-ome-zarr-navigator
Project-URL: User Support, https://github.com/fractal-analytics-platform/napari-ome-zarr-navigator/issues
Author-email: Fabio Steffen <fabio.steffen@uzh.ch>, Joel Luethi <joel.luethi@uzh.ch>
License: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: napari
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: <3.13,>=3.11
Requires-Dist: magicgui
Requires-Dist: napari-ome-zarr<0.8
Requires-Dist: ngio<0.6,>=0.5
Requires-Dist: numcodecs!=0.14.0,!=0.14.1,!=0.16
Requires-Dist: numpy
Requires-Dist: ome-zarr
Requires-Dist: qtpy
Requires-Dist: scikit-image
Requires-Dist: wget
Provides-Extra: testing
Requires-Dist: napari; extra == 'testing'
Requires-Dist: pytest; extra == 'testing'
Requires-Dist: pytest-cov; extra == 'testing'
Requires-Dist: pytest-qt; extra == 'testing'
Requires-Dist: qtpy; extra == 'testing'
Description-Content-Type: text/markdown

# 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">

[![License BSD-3](https://img.shields.io/pypi/l/napari-ome-zarr-navigator.svg?color=green)](https://github.com/fractal-analytics-platform/napari-ome-zarr-navigator/raw/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/napari-ome-zarr-navigator.svg?color=green)](https://pypi.org/project/napari-ome-zarr-navigator)
[![Python Version](https://img.shields.io/pypi/pyversions/napari-ome-zarr-navigator.svg?color=green)](https://python.org)
[![tests](https://github.com/fractal-analytics-platform/napari-ome-zarr-navigator/workflows/tests/badge.svg)](https://github.com/fractal-analytics-platform/napari-ome-zarr-navigator/actions)
[![codecov](https://codecov.io/gh/fractal-analytics-platform/napari-ome-zarr-navigator/branch/main/graph/badge.svg)](https://codecov.io/gh/fractal-analytics-platform/napari-ome-zarr-navigator)

A plugin to browse OME-Zarr plates by conditions and load images, labels and features from ROIs


## Usage

### Plate Browser

The Plate Browser loads an OME-Zarr plate from the local filesystem or via authenticated HTTPS (e.g. a [Fractal Server](https://fractal-analytics-platform.github.io/) instance). It also auto-detects plates opened via [napari-ome-zarr](https://github.com/ome/napari-ome-zarr).

<img width="1624" alt="navigator_plate_browser" src="https://github.com/user-attachments/assets/ed1f1c13-1055-4b21-a3e6-100279f64f5b" />

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.

<img width="1624" alt="plate_browser_go_to_well" src="https://github.com/user-attachments/assets/c83c1daf-a5d2-41b7-8685-564f80eb0122" />

Using [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.

<img width="1512" alt="plate_browser_filtering" src="https://github.com/user-attachments/assets/7938ed80-31ee-4e58-b896-20ed92ea6508" />

### ROI Loader

The 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:

- Loading images from different multiplexing cycles / acquisitions
- 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
- Loading label images
- Loading feature measurements from [feature tables](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/feature_table/)
- **Multi-resolution (lazy)** mode — streams a full dask pyramid, optimal for large images and remote data
- **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)

Once 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.

<img width="1624" alt="roi_loader" src="https://github.com/user-attachments/assets/ddd8268f-52ae-4a43-9c00-f52df4422ba3" />

This 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).

----------------------------------


## Test data

Test & sample data is available at https://zenodo.org/records/20429951


## Installation

### Via pixi (recommended)

[pixi](https://pixi.sh) manages all Python and system dependencies in a single step:

```bash
git clone https://github.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator
cd napari-ome-zarr-navigator
pixi run napari
```

To 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)):

```bash
pixi run napari-fractal
```

### Via pip

Install into an existing Python ≥ 3.11 environment with [napari] already present:

```bash
pip install napari-ome-zarr-navigator
```

For a fresh environment we recommend [miniforge](https://github.com/conda-forge/miniforge):

```bash
conda create -n napari-ome-zarr python=3.12 napari pyqt -c conda-forge
conda activate napari-ome-zarr
pip install napari-ome-zarr-navigator
napari
```

Optionally also install additional plugins like `napari-feature-classifier` and `napari-feature-visualization`, as in:
```bash
pip install napari-feature-classifier napari-feature-visualization
```

## Contributing

Contributions are very welcome. Tests can be run with `pixi run test`; please ensure coverage stays the same before submitting a pull request.

## License

Distributed under the terms of the [BSD-3] license,
"napari-ome-zarr-navigator" is free and open source software

## Issues

If you encounter any problems, please [file an issue] along with a detailed description.

[napari]: https://github.com/napari/napari
[BSD-3]: http://opensource.org/licenses/BSD-3-Clause
[file an issue]: https://github.com/fractal-analytics-platform/napari-ome-zarr-navigator/issues
[pip]: https://pypi.org/project/pip/
