Metadata-Version: 2.4
Name: omero-annotate-ai
Version: 0.5.2
Summary: OMERO integration for AI-powered image annotation and segmentation workflows
Author-email: Maarten Paul <m.w.paul@lacdr.leidenuniv.nl>
Maintainer-email: Maarten Paul <m.w.paul@lacdr.leidenuniv.nl>
License-Expression: GPL-2.0-or-later
Project-URL: Homepage, https://github.com/Leiden-Cell-Observatory/omero_annotate_ai
Project-URL: Repository, https://github.com/Leiden-Cell-Observatory/omero_annotate_ai.git
Project-URL: Issues, https://github.com/Leiden-Cell-Observatory/omero_annotate_ai/issues
Project-URL: Documentation, https://leiden-cell-observatory.github.io/omero_annotate_ai/
Project-URL: Changelog, https://github.com/Leiden-Cell-Observatory/omero_annotate_ai/releases
Keywords: omero,microscopy,segmentation,ai,annotation,sam,micro-sam
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Framework :: napari
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Environment :: Console
Classifier: Environment :: Other Environment
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: imageio>=2.9.0
Requires-Dist: dask>=2021.6.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: ezomero>=3.1.0
Requires-Dist: opencv-python
Requires-Dist: tifffile
Provides-Extra: notebooks
Requires-Dist: ipywidgets>=7.6.0; extra == "notebooks"
Requires-Dist: ipykernel; extra == "notebooks"
Requires-Dist: pixi-kernel<0.7,>=0.6.6; extra == "notebooks"
Requires-Dist: marimo<0.20,>=0.19.2; extra == "notebooks"
Requires-Dist: keyring>=23.0.0; extra == "notebooks"
Provides-Extra: microsam
Requires-Dist: micro-sam>=1.8; extra == "microsam"
Provides-Extra: napari
Requires-Dist: micro-sam<1.9,>=1.8; extra == "napari"
Requires-Dist: qtpy>=2.4; extra == "napari"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: ruff>=0.17; extra == "dev"
Requires-Dist: pyright>=1.1.414; extra == "dev"
Provides-Extra: docs
Requires-Dist: zensical>=0.0.73; extra == "docs"
Requires-Dist: mkdocstrings>=1.0.8; extra == "docs"
Requires-Dist: mkdocstrings-python>=1.18; extra == "docs"
Requires-Dist: griffe-pydantic>=1.1.7; extra == "docs"
Provides-Extra: zarr
Requires-Dist: ome-zarr>=0.16; extra == "zarr"
Provides-Extra: provenance
Requires-Dist: iscc-lib<0.8,>=0.7; extra == "provenance"
Provides-Extra: all
Requires-Dist: omero-annotate-ai[microsam,notebooks,provenance,zarr]; extra == "all"
Dynamic: license-file

# OMERO Annotate.AI

[![PyPI version](https://img.shields.io/pypi/v/omero-annotate-ai)](https://pypi.org/project/omero-annotate-ai/)
[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/omero-annotate-ai/README.html)
[![Python versions](https://img.shields.io/pypi/pyversions/omero-annotate-ai)](https://pypi.org/project/omero-annotate-ai/)
[![CI/CD](https://github.com/Leiden-Cell-Observatory/omero_annotate_ai/actions/workflows/ci.yml/badge.svg)](https://github.com/Leiden-Cell-Observatory/omero_annotate_ai/actions)
[![Documentation](https://github.com/Leiden-Cell-Observatory/omero_annotate_ai/actions/workflows/docs.yml/badge.svg)](https://leiden-cell-observatory.github.io/omero_annotate_ai/)
[![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh)
[![License](https://img.shields.io/github/license/Leiden-Cell-Observatory/omero_annotate_ai)](https://github.com/Leiden-Cell-Observatory/omero_annotate_ai/blob/main/LICENSE)

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.svg">
  <img src="docs/images/logo.svg" alt="OMERO Annotate.AI logo" width="120" align="right">
</picture>

**Reproducible AI-assisted annotation of OMERO data, from image selection to training-ready datasets.**

Pick images from an OMERO project, dataset, plate or screen. Annotate them in napari with
[micro-SAM](https://github.com/computational-cell-analytics/micro-sam) or prepare them for
[Cellpose](https://www.cellpose.org). The masks, ROIs and a tracking table go back to OMERO.
Every run is described by one YAML file, so you can resume it, repeat it or share it.
<br clear="right">

![micro-SAM segmentation of a Cell Painting field in napari](docs/images/napari_microsam.jpg)
<sub>micro-SAM (`vit_b_lm`) instance segmentation of nuclei in a Cell Painting field from the BioImage Archive (S-BIAD855), shown in napari.</sub>

## How it works

```mermaid
flowchart LR
    A[OMERO<br/>project · dataset · plate · screen] --> B[Select images<br/>train / val / test split]
    B --> C[Annotate in napari<br/>micro-SAM or Cellpose]
    C --> D[Back to OMERO<br/>masks · ROIs · tracking table]
    D --> E[Training data<br/>micro-SAM · BiaPy · DL4MicEverywhere]
    D --> F[BioImage Archive<br/>MIFA export]
```

- **Jupyter widgets** to connect to OMERO and create a training set or open one to continue, no code needed.
- **Resumable and crash-safe:** each mask is saved locally, uploaded with a tag and then recorded in the tracking table, so an interrupted run continues where it stopped without duplicate uploads; pixel digests flag files that changed afterwards.
- **Review and correct** earlier annotations with their saved masks; record a note per session.
- **Flexible sampling:** timepoints, z-slices, 3D volumes, random patches, and filtering plate wells on their key-value pairs.
- **Training-ready output:** one folder layout for micro-SAM, BiaPy and DL4MicEverywhere, with images and labels paired by name.
- **FAIR by default:** the config carries study and method metadata and exports to the BioImage Archive (MIFA).
- **Local-only storage** (`storage: local`) for data you cannot write to, such as public [IDR](https://idr.openmicroscopy.org) OME-Zarr.

## Jupyter widgets

<table>
  <tr>
    <td width="45%"><img src="docs/images/widget_connect.png" alt="OMERO connection widget"></td>
    <td width="55%"><img src="docs/images/widget_open_set.png" alt="Opening a training set in the workflow widget: progress per split and session notes"></td>
  </tr>
  <tr>
    <td><sub>Connect to any OMERO server.</sub></td>
    <td><sub>Pick a container, then start a new training set or continue one: progress per split and the notes of earlier sessions.</sub></td>
  </tr>
</table>

## napari plugin (experimental)

Annotate in your own napari window: **Plugins → OMERO Annotate AI → Annotate training
set** (install with `pip install "omero-annotate-ai[napari]"`). It opens existing
training sets on OMERO or in a local folder, saves each accepted image straight away,
and can review annotated images starting from their saved masks. See the
[napari plugin guide](https://leiden-cell-observatory.github.io/omero_annotate_ai/napari-plugin/).

## Installation

```bash
# Recommended: pixi
pixi init myproject && cd myproject
pixi add micro_sam jupyterlab
pixi add --pypi "omero-annotate-ai[notebooks]"

# Or: conda + pip
conda install -c conda-forge micro_sam jupyterlab
pip install "omero-annotate-ai[notebooks]"

# Or: pip only (micro-SAM and napari from PyPI)
pip install "omero-annotate-ai[microsam,notebooks]" jupyterlab
```

See the [installation guide](https://leiden-cell-observatory.github.io/omero_annotate_ai/installation/) for details and troubleshooting.

## Quick start

**With widgets** (in Jupyter):

```python
from omero_annotate_ai import create_omero_connection_widget, create_workflow_widget

conn_widget = create_omero_connection_widget()
conn_widget.display()
conn = conn_widget.get_connection()

workflow_widget = create_workflow_widget(connection=conn)
workflow_widget.display()  # New training set, or Open one to continue

ts = workflow_widget.training_set()
workflow_widget.annotate(note="nuclei only, small debris skipped")
```

**From a YAML config** (scripts, batch runs, or repeating a run):

```python
from omero_annotate_ai import TrainingSet, load_config

config = load_config("annotation_config.yaml")
ts = TrainingSet.create(config, conn)
ts.annotate()
```

**Continue later** (after closing napari, or a crash): open the set by its table ID and
annotate what is left; anything a crash left half-done is repaired first.

```python
ts = TrainingSet.open(12345, conn)
ts.extend(train_n=10)  # optional: add images to the same table
ts.annotate(note="second round")
```

Each training set keeps its files in one folder: images, masks, `config.yaml` (with the
sessions and their notes) and a local copy of the tracking table. By default that is
`~/omero_annotate_ai/<server>/<table id>_<name>/`; set `OMERO_ANNOTATE_AI_HOME` (or pass
`home=` to `TrainingSet.create` / `open`) to keep the sets elsewhere.
`ts.review()` reopens annotated images with their masks to correct them.
Open the same set on another computer to carry on there; two people can even annotate
it at the same time, because each session claims the images it shows (your own claims,
e.g. after a dropped connection, never block you).
`create_pipeline(config, conn).run_full_micro_sam_workflow()` from 0.4 still works but
is deprecated.

The [configuration guide](https://leiden-cell-observatory.github.io/omero_annotate_ai/configuration/) lists every option.

## Example notebooks

| | Jupyter | marimo |
|---|---|---|
| Annotate with micro-SAM or Cellpose | [widget workflow](notebooks/jupyter/annotation/omero-annotate-ai-annotation-widget.ipynb) | [annotation](notebooks/marimo/omero-annotate-ai-annotation.py) |
| Run from YAML (OMERO or OME-Zarr) | | [from YAML](notebooks/marimo/annotate-from-yaml.py) |
| Train micro-SAM | | [micro-SAM](notebooks/marimo/omero-training-microsam.py) |
| Export for BiaPy / DL4MicEverywhere | [export](notebooks/jupyter/training/omero-training-export.ipynb) | |
| Export to the BioImage Archive | [BIA export](notebooks/jupyter/export_annotations/omero-table-to-bioimage-archive.ipynb) | |
| Try it on public data | | [IDR OME-Zarr demo](notebooks/marimo/idr-zarr-demo.py) |

## Documentation

Upgrading from 0.4? The [release notes](https://leiden-cell-observatory.github.io/omero_annotate_ai/release-notes/) list the changes and how to migrate.

Full documentation: **https://leiden-cell-observatory.github.io/omero_annotate_ai/**
([micro-SAM tutorial](https://leiden-cell-observatory.github.io/omero_annotate_ai/tutorials/microsam-annotation-pipeline/),
[API reference](https://leiden-cell-observatory.github.io/omero_annotate_ai/api/)).

## Contributing

```bash
git clone https://github.com/Leiden-Cell-Observatory/omero_annotate_ai.git
cd omero_annotate_ai
pixi install                         # default env: everything to run the notebooks
pixi run -e dev install-hooks        # once per clone: ruff + notebook-output hooks
pixi run -e dev pytest tests/        # dev env adds test, lint and type-check tools
```

Issues and pull requests are welcome on [GitHub](https://github.com/Leiden-Cell-Observatory/omero_annotate_ai/issues).

## Contact and acknowledgements

**Maarten Paul**, m.w.paul@lacdr.leidenuniv.nl

Developed at the [Leiden Cell Observatory](https://github.com/Leiden-Cell-Observatory) within the
[NL-BioImaging](https://github.com/NL-BioImaging) infrastructure, funded by NWO.

## License

GNU General Public License v2.0 or later (GPL-2.0-or-later); see [LICENSE](LICENSE).
The package builds on [omero-py](https://github.com/ome/omero-py) (GPL-2.0-or-later) and
[ezomero](https://github.com/TheJacksonLaboratory/ezomero) (GPL-2.0), so it uses a compatible
license. Releases up to and including 0.4.x were published under Apache-2.0.
