# ome-writers

[![License](https://img.shields.io/pypi/l/ome-writers.svg?color=green)](https://github.com/pymmcore-plus/ome-writers/raw/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/ome-writers.svg?color=green)](https://pypi.org/project/ome-writers)
[![Python
Version](https://img.shields.io/pypi/pyversions/ome-writers.svg?color=green)](https://python.org)
[![CI](https://github.com/pymmcore-plus/ome-writers/actions/workflows/ci.yml/badge.svg)](https://github.com/pymmcore-plus/ome-writers/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/pymmcore-plus/ome-writers/branch/main/graph/badge.svg)](https://codecov.io/gh/pymmcore-plus/ome-writers)

OME-TIFF and OME-ZARR writer APIs designed for microscopy acquisition.

This package provides a unified interface for writing OME-TIFF and OME-ZARR files,
with various different backends.  It is currently designed/optimized for
"deterministic" use cases where the shape of the data is known ahead of time, and
the data can be efficiently chunked and written in a predictable manner with a
series of calls to `stream.append(frame)` as the data is generated.

## Installation

```bash
pip install ome-writers
```

Or, include all optional dependencies for specific backends:

 - `tensorstore`: for [`tensorstore`](https://github.com/google/tensorstore) backend support
 - `acquire-zarr`: for [`acquire-zarr`](https://github.com/acquire-project/acquire-zarr) backend support
 - `tiff`: for `tiff` backend support using [`tifffile`](https://github.com/cgohlke/tifffile).
 - `all`: install all backends

```bash
pip install "ome-writers[all]"
```

## Basic Usage

```python
from ome_writers import Dimension, create_stream

# Configure the dimensions of the data stream
# The stream expects that data will be appended in the order and shape
# defined by the dimensions.
# labels must currently be one of 't', 'c', 'z', 'y', 'x', or 'p' (stage position).
dims = [
    Dimension(label="t", size=10, unit=(1.0, "s")),
    Dimension(label="c", size=3),
    Dimension(label="z", size=5, unit=(1.0, "um")),
    Dimension(label="y", size=512, unit=(1.0, "um"), chunk_size=128),
    Dimension(label="x", size=512, unit=(1.0, "um"), chunk_size=128),
]

stream = create_stream(
    "my_data.zarr",
    dimensions=dims,
    dtype='uint16',
    # backend may be any of
    # "acquire-zarr", "tensorstore", "tiff" (for ome-tiff) or "auto"
    backend="acquire-zarr"  
)

# Write data frame by frame, as it is generated by your application
for frame in ...:
    stream.append(frame)

# Flush any pending writes to disk
stream.flush()
```

## Contributing

This is a work in progress; we absolutely welcome and appreciate contributions!
If you have suggestions, improvements, or bug fixes, please open an issue or
submit a pull request.

```sh
git clone https://github.com/pymmcore-plus/ome-writers.git
cd ome-writers

# setup env
uv sync

# test
uv run pytest

# lint
uv run pre-commit run -a
```
