diff --git a/docs/index.md b/docs/index.md index f459debc..7e206623 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,7 +29,7 @@ A lean and kind quick_start.md installation.md -array_api.md +python.md cli.md itk.md methods.md diff --git a/docs/itk.md b/docs/itk.md index 5bf734b4..dcbdc967 100644 --- a/docs/itk.md +++ b/docs/itk.md @@ -8,7 +8,7 @@ Bidirectional type conversion that preserves spatial metadata is available with Once represented as an `NgffImage`, a multiscale representation can be generated with `to_multiscales`. And an OME-Zarr can be generated from the multiscales with `to_ngff_zarr`. For more information, see the -[Python Array API documentation](./array_api.md). +[Python interface documentation](./python.md). ## ITK Python diff --git a/docs/array_api.md b/docs/python.md similarity index 72% rename from docs/array_api.md rename to docs/python.md index d50606da..731a18d3 100644 --- a/docs/array_api.md +++ b/docs/python.md @@ -1,15 +1,22 @@ -# 🐍 Python Array API +# 🐍 Python Interface -NGFF-Zarr supports conversion of any NumPy array-like object that follows the -[Python Array API Standard](https://data-apis.org/array-api/latest/) into -OME-Zarr. This includes such objects an NumPy `ndarray`'s, Dask Arrays, PyTorch -Tensors, CuPy arrays, Zarr array, etc. +NGFF-Zarr is a Python library that provides a simple, natural interface for +working with OME-Zarr data structures, creating chunked, multiscale OME-Zarr +image pyramids, and reading and writing OME-Zarr multiscale image files. + +NGFF-Zarr's interface, which reflects the OME-Zarr data model, is built on +Python's built-in [dataclasses] and [Dask arrays]. It is designed to be simple, +flexible, and easy to use. ## Array to NGFF Image -Convert the array to an `NgffImage`, which is a standard -[Python dataclass](https://docs.python.org/3/library/dataclasses.html) that -represents an OME-Zarr image for a single scale. +NGFF-Zarr supports conversion of any NumPy array-like object that follows the +[Python Array API Standard] into the OME-Zarr data model. This includes such +objects an NumPy `ndarray`'s, Dask Arrays, PyTorch Tensors, CuPy arrays, Zarr +array, etc. + +Convert the array to an [`NgffImage`], which is a standard Python [dataclass] +that represents an OME-Zarr image for a single scale. When creating the image from the array, you can specify @@ -17,8 +24,7 @@ When creating the image from the array, you can specify - the `scale`, the pixel spacing for the spatial dims - the `translation`, the origin or offset of the center of the first pixel - a `name` for the image -- and `axes_units` with - [UDUNITS-2 identifiers](https://ngff.openmicroscopy.org/latest/#axes-md) +- and `axes_units` with [UDUNITS-2 identifiers] ```python >>> # Load an image as a NumPy array @@ -28,7 +34,7 @@ When creating the image from the array, you can specify ``` -Specify optional additional metadata with `to_ngff_zarr`. +Specify optional additional metadata with [`to_ngff_image`]. ```python >>> import ngff_zarr as nz @@ -50,16 +56,16 @@ chunksize=(256, 256), chunktype=numpy.ndarray>, ) ``` -The image data is nested in a lazy `dask.array` and chucked. +The image data is nested in a lazy `dask.Array` and chucked. If `dims`, `scale`, or `translation` are not specified, NumPy-compatible defaults are used. -## Generate multiscales +## Generate Multiscales OME-Zarr represents images in a chunked, multiscale data structure. Use -`to_multiscales` to build a task graph that will produce a chunked, multiscale -image pyramid. `to_multiscales` has optional `scale_factors` and `chunks` +[`to_multiscales`] to build a task graph that will produce a chunked, multiscale +image pyramid. [`to_multiscales`] has optional `scale_factors` and `chunks` parameters. An [antialiasing method](./methods.md) can also be prescribed. ```python @@ -152,7 +158,7 @@ scale according the OME-Zarr data model. Note that the correct `scale` and ## Write to Zarr -To write the multiscales to Zarr, use `to_ngff_zarr`. +To write the multiscales to Zarr, use [`to_ngff_zarr`]. ```python nz.to_ngff_zarr('cthead1.ome.zarr', multiscales) @@ -165,3 +171,13 @@ Any other also be used. The multiscales will be computed and written out-of-core, limiting memory usage. + +[dataclass]: https://docs.python.org/3/library/dataclasses.html +[dataclasses]: https://docs.python.org/3/library/dataclasses.html +[Dask arrays]: https://docs.dask.org/en/stable/array.html +[Python Array API Standard]: https://data-apis.org/array-api/latest/ +[UDUNITS-2 identifiers]: https://ngff.openmicroscopy.org/latest/#axes-md +[`NgffImage`]: ./apidocs/ngff_zarr/ngff_zarr.ngff_image.md +[`to_ngff_zarr`]: ./apidocs/ngff_zarr/ngff_zarr.to_ngff_zarr.md +[`to_ngff_image`]: ./apidocs/ngff_zarr/ngff_zarr.to_ngff_image.md +[`to_multiscales`]: ./apidocs/ngff_zarr/ngff_zarr.to_multiscales.md diff --git a/pixi.lock b/pixi.lock index 1be8c2a3..dc2693eb 100644 --- a/pixi.lock +++ b/pixi.lock @@ -3987,7 +3987,7 @@ packages: name: ngff-zarr version: 0.9.1 path: . - sha256: 496ef9944dd92d1a0e0aa6d7cd6df7385e48edc1cb0b4789599f25e2901db941 + sha256: d8f01f63ea17ad4d8e7fa6bd0afd6cf5d84ee41cbc6d65dc1d82ad1ac13eaffb requires_dist: - dask[array] - importlib-resources @@ -4000,6 +4000,27 @@ packages: - rich-argparse - typing-extensions - zarr + - dask-image ; extra == 'all' + - dask[distributed] ; extra == 'all' + - deepdiff ; extra == 'all' + - furo<2025,>=2024.7.18 ; extra == 'all' + - imagecodecs ; extra == 'all' + - imageio ; extra == 'all' + - itk-filtering>=5.3.0 ; extra == 'all' + - itk-io>=5.3.0 ; extra == 'all' + - itkwasm-image-io ; extra == 'all' + - jsonschema ; extra == 'all' + - myst-parser<4,>=3.0.1 ; extra == 'all' + - pooch ; extra == 'all' + - pytest>=6 ; extra == 'all' + - sphinx-autobuild<2025,>=2024.4.16 ; extra == 'all' + - sphinx-autodoc2<0.6,>=0.5.0 ; extra == 'all' + - sphinx-copybutton<0.6,>=0.5.2 ; extra == 'all' + - sphinx-design<0.7,>=0.6.0 ; extra == 'all' + - sphinx<8,>=7.4.7 ; extra == 'all' + - sphinxext-opengraph<0.10,>=0.9.1 ; extra == 'all' + - tensorstore ; extra == 'all' + - tifffile>=2024.7.24 ; extra == 'all' - dask-image ; extra == 'cli' - dask[distributed] ; extra == 'cli' - imagecodecs ; extra == 'cli'