ngio 0.2.0a1__tar.gz → 0.2.0a2__tar.gz

{ngio-0.2.0a1 → ngio-0.2.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ngio
-Version: 0.2.0a1
+Version: 0.2.0a2
 Summary: Next Generation file format IO
 Project-URL: homepage, https://github.com/lorenzocerrone/ngio
 Project-URL: repository, https://github.com/lorenzocerrone/ngio

{ngio-0.2.0a1 → ngio-0.2.0a2}/docs/notebooks/image.ipynb

@@ -17,12 +17,12 @@
    "source": [
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "from ngio.core.ngff_image import NgffImage\n",
+    "from ngio import open_omezarr_container\n",
     "from ngio.utils import download_ome_zarr_dataset\n",
     "\n",
     "hcs_path = download_ome_zarr_dataset(\"CardiomyocyteSmallMip\")\n",
     "image_path = hcs_path / \"B\" / \"03\" / \"0\"\n",
-    "ngff_image = NgffImage(image_path)"
+    "omezarr = open_omezarr_container(image_path)"
    ]
   },
   {
@@ -31,7 +31,7 @@
    "source": [
     "## Images\n",
     "\n",
-    "Images can be loaded from a `NgffImage` object."
+    "Images can be loaded from a `OmeZarrContainer` object."
    ]
   },
   {
@@ -40,11 +40,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "image = ngff_image.get_image()\n",
+    "image = omezarr.get_image()\n",
     "\n",
     "print(\"Image information:\")\n",
     "print(f\"{image.shape=}\")\n",
-    "print(f\"{image.axes_names=}\")\n",
     "print(f\"{image.pixel_size=}\")\n",
     "print(f\"{image.channel_labels=}\")\n",
     "print(f\"{image.dimensions=}\")"
@@ -71,18 +70,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Get image as a dask array\n",
-    "dask_array = image.on_disk_dask_array\n",
-    "dask_array"
+    "image.get_array(mode=\"dask\")  # this call is lazy"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note, directly accessing the `.on_disk_array` or `.on_disk_dask_array` attributes will load the image as stored in the file.\n",
-    "\n",
-    "Since in principle the images can have different axes order. A safer way to access the image data is to use the `.get_array()` method, which will return the image data in canonical order (TCZYX)."
+    "Images can be queried for any axes, in any order"
    ]
   },
   {
@@ -91,11 +86,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "image_numpy = image.get_array(\n",
-    "    c=0, x=slice(0, 250), y=slice(0, 250), preserve_dimensions=False, mode=\"numpy\"\n",
-    ")\n",
+    "print(\"On disk shape: \", image.shape)\n",
+    "\n",
+    "# Axes order can be specified\n",
+    "# if an axis is not present in the array, it will be added as a singleton dimension\n",
+    "array = image.get_array(axes_order=[\"x\", \"t\", \"c\", \"y\", \"z\"], mode=\"dask\")\n",
     "\n",
-    "print(f\"{image_numpy.shape=}\")"
+    "print(\"Array shape: \", array.shape)"
    ]
   },
   {
@@ -113,13 +110,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "roi_table = ngff_image.tables.get_table(\"FOV_ROI_table\")\n",
-    "roi = roi_table.get_roi(\"FOV_1\")\n",
+    "roi_table = omezarr.get_table(\"FOV_ROI_table\", check_type=\"roi_table\")\n",
+    "# Get a roi by name\n",
+    "roi = roi_table.get(\"FOV_1\")\n",
     "print(f\"{roi=}\")\n",
     "\n",
-    "image_roi_1 = image.get_array_from_roi(\n",
-    "    roi=roi, c=0, preserve_dimensions=True, mode=\"dask\"\n",
-    ")\n",
+    "# .get_roi works exactly like .get_array\n",
+    "# the only difference is that x, y, z, axes are queried from the roi object\n",
+    "image_roi_1 = image.get_roi(roi=roi, c=0, mode=\"dask\")\n",
     "image_roi_1"
    ]
   },
@@ -136,21 +134,21 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "image_2 = ngff_image.get_image(path=\"2\")\n",
+    "image_2 = omezarr.get_image(path=\"2\")\n",
     "# Two images at different resolutions\n",
     "print(f\"{image.pixel_size=}\")\n",
     "print(f\"{image_2.pixel_size=}\")\n",
     "\n",
     "# Get roi for higher resolution image\n",
-    "image_1_roi_1 = image.get_array_from_roi(roi=roi, c=0, preserve_dimensions=False)\n",
+    "image_1_roi_1 = image.get_roi(roi=roi, c=0, mode=\"dask\")\n",
     "\n",
     "# Get roi for lower resolution image\n",
-    "image_2_roi_1 = image_2.get_array_from_roi(roi=roi, c=0, preserve_dimensions=False)\n",
+    "image_2_roi_1 = image_2.get_roi(roi=roi, c=0, mode=\"dask\")\n",
     "\n",
     "# Plot the two images side by side\n",
     "fig, axs = plt.subplots(1, 2, figsize=(10, 5))\n",
-    "axs[0].imshow(image_1_roi_1[0], cmap=\"gray\")\n",
-    "axs[1].imshow(image_2_roi_1[0], cmap=\"gray\")\n",
+    "axs[0].imshow(image_1_roi_1[0, 0], cmap=\"gray\")\n",
+    "axs[1].imshow(image_2_roi_1[0, 0], cmap=\"gray\")\n",
     "plt.show()"
    ]
   },
@@ -180,17 +178,26 @@
     "\n",
     "\n",
     "# Load the image from disk and show the edited image\n",
-    "nuclei = ngff_image.labels.get_label(\"nuclei\")\n",
+    "nuclei = omezarr.get_label(\"nuclei\", path=\"0\")\n",
     "fig, axs = plt.subplots(1, 2, figsize=(10, 5))\n",
-    "axs[0].imshow(image.on_disk_array[0, 0], cmap=\"gray\")\n",
-    "axs[1].imshow(nuclei.on_disk_array[0])\n",
+    "\n",
+    "axs[0].imshow(image.get_array()[0, 0], cmap=\"gray\")\n",
+    "axs[1].imshow(nuclei.get_array()[0])\n",
     "for ax in axs:\n",
     "    ax.axis(\"off\")\n",
     "plt.tight_layout()\n",
     "plt.show()\n",
     "\n",
     "# Add back the original slice to the image\n",
-    "image.set_array(patch=small_slice, x=slice(1000, 2000), y=slice(1000, 2000))"
+    "image.set_array(patch=small_slice, x=slice(1000, 2000), y=slice(1000, 2000))\n",
+    "\n",
+    "fig, axs = plt.subplots(1, 2, figsize=(10, 5))\n",
+    "axs[0].imshow(image.get_array()[0, 0], cmap=\"gray\")\n",
+    "axs[1].imshow(nuclei.get_array()[0])\n",
+    "for ax in axs:\n",
+    "    ax.axis(\"off\")\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
    ]
   },
   {
@@ -209,15 +216,16 @@
    "outputs": [],
    "source": [
     "# Create a a new label object and set it to a simple segmentation\n",
-    "new_label = ngff_image.labels.derive(\"new_label\", overwrite=True)\n",
+    "new_label = omezarr.derive_label(\"new_label_2\", overwrite=True)\n",
     "\n",
-    "simple_segmentation = image.on_disk_array[0] > 100\n",
-    "new_label.on_disk_array[...] = simple_segmentation\n",
+    "simple_segmentation = image.get_array(c=0) > 100\n",
+    "simple_segmentation = simple_segmentation[0]\n",
+    "new_label.set_array(simple_segmentation)\n",
     "\n",
     "# make a subplot with two image show side by side\n",
     "fig, axs = plt.subplots(1, 2, figsize=(10, 5))\n",
-    "axs[0].imshow(image.on_disk_array[0, 0], cmap=\"gray\")\n",
-    "axs[1].imshow(new_label.on_disk_array[0], cmap=\"gray\")\n",
+    "axs[0].imshow(image.get_array()[0, 0], cmap=\"gray\")\n",
+    "axs[1].imshow(new_label.get_array()[0], cmap=\"gray\")\n",
     "for ax in axs:\n",
     "    ax.axis(\"off\")\n",
     "plt.tight_layout()\n",
@@ -241,15 +249,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "label_0 = ngff_image.labels.get_label(\"new_label\", path=\"0\")\n",
-    "label_2 = ngff_image.labels.get_label(\"new_label\", path=\"2\")\n",
+    "label_0 = omezarr.get_label(\"new_label\", path=\"0\")\n",
+    "label_2 = omezarr.get_label(\"new_label\", path=\"2\")\n",
     "\n",
-    "label_before_consolidation = label_2.on_disk_array[...]\n",
+    "label_before_consolidation = label_2.zarr_array[...]\n",
     "\n",
     "# Consolidate the label\n",
     "label_0.consolidate()\n",
     "\n",
-    "label_after_consolidation = label_2.on_disk_array[...]\n",
+    "label_after_consolidation = label_2.zarr_array[...]\n",
     "\n",
     "\n",
     "# make a subplot with two image show side by side\n",
@@ -281,42 +289,43 @@
     "import numpy as np\n",
     "import pandas as pd\n",
     "\n",
-    "print(f\"List of feature table: {ngff_image.tables.list(table_type='feature_table')}\")\n",
+    "from ngio.tables import FeatureTable\n",
+    "\n",
+    "print(f\"List of all tables: {omezarr.list_tables()}\")\n",
     "\n",
     "\n",
-    "nuclei = ngff_image.labels.get_label(\"nuclei\")\n",
+    "nuclei = omezarr.get_label(\"nuclei\", path=\"0\")\n",
+    "roi_table = omezarr.get_table(\"FOV_ROI_table\", check_type=\"roi_table\")\n",
     "\n",
     "# Create a table with random features for each nuclei in each ROI\n",
     "list_of_records = []\n",
-    "for roi in roi_table.rois:\n",
-    "    nuclei_in_roi = nuclei.get_array_from_roi(roi, mode=\"numpy\")\n",
+    "for roi in roi_table.rois():\n",
+    "    nuclei_in_roi = nuclei.get_roi(roi, mode=\"numpy\")\n",
     "    for nuclei_id in np.unique(nuclei_in_roi)[1:]:\n",
     "        list_of_records.append(\n",
     "            {\n",
     "                \"label\": nuclei_id,\n",
     "                \"feat1\": np.random.rand(),\n",
     "                \"feat2\": np.random.rand(),\n",
-    "                \"ROI\": roi.infos.get(\"FieldIndex\"),\n",
+    "                \"ROI\": roi.name,\n",
     "            }\n",
     "        )\n",
     "\n",
     "feat_df = pd.DataFrame.from_records(list_of_records)\n",
     "\n",
-    "# Create a new feature table\n",
-    "feat_table = ngff_image.tables.new(\n",
-    "    name=\"new_feature_table\",\n",
-    "    label_image=\"../nuclei\",\n",
-    "    table_type=\"feature_table\",\n",
-    "    overwrite=True,\n",
-    ")\n",
-    "\n",
-    "print(\n",
-    "    f\"New list of feature table: {ngff_image.tables.list(table_type='feature_table')}\"\n",
-    ")\n",
-    "feat_table.set_table(feat_df)\n",
-    "feat_table.consolidate()\n",
-    "\n",
-    "feat_table.table"
+    "feat_table = FeatureTable(feat_df, reference_label=\"nuclei\")\n",
+    "\n",
+    "omezarr.add_table(\"new_feature_table\", feat_table, overwrite=True)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "feat_table = omezarr.get_table(\"new_feature_table\")\n",
+    "feat_table.dataframe"
    ]
   },
   {

{ngio-0.2.0a1 → ngio-0.2.0a2}/docs/notebooks/processing.ipynb

@@ -35,12 +35,12 @@
    "source": [
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "from ngio.core import NgffImage\n",
+    "from ngio import open_omezarr_container\n",
     "from ngio.utils import download_ome_zarr_dataset\n",
     "\n",
     "hcs_path = download_ome_zarr_dataset(\"CardiomyocyteTiny\")\n",
     "image_path = hcs_path / \"B\" / \"03\" / \"0\"\n",
-    "ngff_image = NgffImage(image_path)"
+    "omezarr = open_omezarr_container(image_path)"
    ]
   },
   {
@@ -56,10 +56,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "mip_ngff = ngff_image.derive_new_image(\n",
+    "mip_omezarr = omezarr.derive_image(\n",
     "    \"data/20200812-CardiomyocyteDifferentiation14-Cycle1.zarr/B/03/0_mip\",\n",
-    "    name=\"MIP\",\n",
-    "    on_disk_shape=(1, 1, 2160, 5120),\n",
+    "    shape=(1, 1, 2160, 5120),\n",
+    "    overwrite=True,\n",
     ")"
    ]
   },
@@ -78,32 +78,32 @@
    "outputs": [],
    "source": [
     "# Get the source imag\n",
-    "source_image = ngff_image.get_image()\n",
+    "source_image = omezarr.get_image()\n",
     "print(\"Source image loaded with shape:\", source_image.shape)\n",
     "\n",
     "# Get the MIP image\n",
-    "mip_image = mip_ngff.get_image()\n",
+    "mip_image = mip_omezarr.get_image()\n",
     "print(\"MIP image loaded with shape:\", mip_image.shape)\n",
     "\n",
     "# Get a ROI table\n",
-    "roi_table = ngff_image.tables.get_table(\"FOV_ROI_table\")\n",
-    "print(\"ROI table loaded with\", len(roi_table.rois), \"ROIs\")\n",
+    "roi_table = omezarr.get_table(\"FOV_ROI_table\", check_type=\"roi_table\")\n",
+    "print(\"ROI table loaded with\", len(roi_table.rois()), \"ROIs\")\n",
     "\n",
     "# For each ROI in the table\n",
     "# - get the data from the source image\n",
     "# - calculate the MIP\n",
     "# - set the data in the MIP image\n",
-    "for roi in roi_table.rois:\n",
-    "    print(f\" - Processing ROI {roi.infos.get('field_index')}\")\n",
-    "    patch = source_image.get_array_from_roi(roi)\n",
+    "for roi in roi_table.rois():\n",
+    "    print(f\" - Processing ROI {roi.name}\")\n",
+    "    patch = source_image.get_roi(roi)\n",
     "    mip_patch = patch.max(axis=1, keepdims=True)\n",
-    "    mip_image.set_array_from_roi(patch=mip_patch, roi=roi)\n",
+    "    mip_image.set_roi(patch=mip_patch, roi=roi)\n",
     "\n",
     "print(\"MIP image saved\")\n",
     "\n",
     "plt.figure(figsize=(5, 5))\n",
     "plt.title(\"Mip\")\n",
-    "plt.imshow(mip_image.on_disk_array[0, 0, :, :], cmap=\"gray\")\n",
+    "plt.imshow(mip_image.zarr_array[0, 0, :, :], cmap=\"gray\")\n",
     "plt.axis(\"off\")\n",
     "plt.tight_layout()\n",
     "plt.show()"
@@ -126,7 +126,7 @@
    "outputs": [],
    "source": [
     "# Get the MIP image at a lower resolution\n",
-    "mip_image_2 = mip_ngff.get_image(path=\"2\")\n",
+    "mip_image_2 = mip_omezarr.get_image(path=\"2\")\n",
     "\n",
     "image_before_consolidation = mip_image_2.get_array(c=0, z=0)\n",
     "\n",
@@ -137,9 +137,9 @@
     "\n",
     "fig, axs = plt.subplots(2, 1, figsize=(10, 5))\n",
     "axs[0].set_title(\"Before consolidation\")\n",
-    "axs[0].imshow(image_before_consolidation, cmap=\"gray\")\n",
+    "axs[0].imshow(image_before_consolidation[0, 0], cmap=\"gray\")\n",
     "axs[1].set_title(\"After consolidation\")\n",
-    "axs[1].imshow(image_after_consolidation, cmap=\"gray\")\n",
+    "axs[1].imshow(image_after_consolidation[0, 0], cmap=\"gray\")\n",
     "for ax in axs:\n",
     "    ax.axis(\"off\")\n",
     "plt.tight_layout()\n",
@@ -162,18 +162,17 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "mip_roi_table = mip_ngff.tables.new(\"FOV_ROI_table\", overwrite=True)\n",
+    "from ngio.tables import RoiTable\n",
     "\n",
     "roi_list = []\n",
-    "for roi in roi_table.rois:\n",
-    "    print(f\" - Processing ROI {roi.infos.get('field_index')}\")\n",
+    "for roi in roi_table.rois():\n",
+    "    print(f\" - Processing ROI {roi.name}\")\n",
     "    roi.z_length = 1  # In the MIP image, the z dimension is 1\n",
     "    roi_list.append(roi)\n",
     "\n",
-    "mip_roi_table.set_rois(roi_list, overwrite=True)\n",
-    "mip_roi_table.consolidate()\n",
+    "mip_roi_table = RoiTable(rois=roi_list)\n",
     "\n",
-    "mip_roi_table.table"
+    "mip_omezarr.add_table(\"FOV_ROI_table\", mip_roi_table)"
    ]
   },
   {
@@ -226,7 +225,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "nuclei_image = mip_ngff.labels.derive(name=\"nuclei\", overwrite=True)"
+    "nuclei_image = mip_omezarr.derive_label(name=\"nuclei\", overwrite=True)"
    ]
   },
   {
@@ -243,30 +242,31 @@
    "outputs": [],
    "source": [
     "# Get the source imag\n",
-    "source_image = mip_ngff.get_image()\n",
+    "source_image = mip_omezarr.get_image()\n",
     "print(\"Source image loaded with shape:\", source_image.shape)\n",
     "\n",
     "# Get a ROI table\n",
-    "roi_table = mip_ngff.tables.get_table(\"FOV_ROI_table\")\n",
-    "print(\"ROI table loaded with\", len(roi_table.rois), \"ROIs\")\n",
+    "roi_table = mip_omezarr.get_table(\"FOV_ROI_table\", check_type=\"roi_table\")\n",
+    "print(\"ROI table loaded with\", len(roi_table.rois()), \"ROIs\")\n",
     "\n",
     "# Find the DAPI channel\n",
-    "dapi_idx = source_image.get_channel_idx(label=\"DAPI\")\n",
+    "dapi_idx = source_image.channel_labels.index(\"DAPI\")\n",
     "\n",
     "# For each ROI in the table\n",
     "# - get the data from the source image\n",
     "# - calculate the Segmentation\n",
     "# - set the data in segmentation image\n",
     "max_label = 0\n",
-    "for roi in roi_table.rois:\n",
-    "    print(f\" - Processing ROI {roi.infos.get('field_index')}\")\n",
-    "    patch = source_image.get_array_from_roi(roi, c=dapi_idx)\n",
+    "for roi in roi_table.rois():\n",
+    "    print(f\" - Processing ROI {roi.name}\")\n",
+    "    patch = source_image.get_roi(roi, c=dapi_idx)\n",
     "    segmentation = otsu_threshold_segmentation(patch, max_label)\n",
     "\n",
     "    # Add the max label of the previous segmentation to avoid overlapping labels\n",
+    "    segmentation = segmentation[0]\n",
     "    max_label = segmentation.max()\n",
     "\n",
-    "    nuclei_image.set_array_from_roi(patch=segmentation, roi=roi)\n",
+    "    nuclei_image.set_roi(patch=segmentation, roi=roi)\n",
     "\n",
     "# Consolidate the segmentation image\n",
     "nuclei_image.consolidate()\n",
@@ -274,9 +274,9 @@
     "print(\"Segmentation image saved\")\n",
     "fig, axs = plt.subplots(2, 1, figsize=(10, 5))\n",
     "axs[0].set_title(\"MIP\")\n",
-    "axs[0].imshow(source_image.on_disk_array[0, 0], cmap=\"gray\")\n",
+    "axs[0].imshow(source_image.zarr_array[0, 0], cmap=\"gray\")\n",
     "axs[1].set_title(\"Nuclei segmentation\")\n",
-    "axs[1].imshow(nuclei_image.on_disk_array[0], cmap=rand_cmap, interpolation=\"nearest\")\n",
+    "axs[1].imshow(nuclei_image.zarr_array[0], cmap=rand_cmap, interpolation=\"nearest\")\n",
     "for ax in axs:\n",
     "    ax.axis(\"off\")\n",
     "plt.tight_layout()\n",

{ngio-0.2.0a1 → ngio-0.2.0a2}/src/ngio/common/_pyramid.py

@@ -203,6 +203,7 @@ def init_empty_pyramid(
             dtype=dtype,
             chunks=chunks,
             dimension_separator="/",
+            overwrite=True,
         )
 
         # Todo redo this with when a proper build of pyramid is implemented

{ngio-0.2.0a1 → ngio-0.2.0a2}/src/ngio/images/image.py

@@ -236,6 +236,8 @@ class ImagesContainer:
         ref_path: str | None = None,
         shape: Collection[int] | None = None,
         chunks: Collection[int] | None = None,
+        xy_scaling_factor: float = 2.0,
+        z_scaling_factor: float = 1.0,
         overwrite: bool = False,
     ) -> "ImagesContainer":
         """Create an OME-Zarr image from a numpy array."""
@@ -245,6 +247,8 @@ class ImagesContainer:
             ref_path=ref_path,
             shape=shape,
             chunks=chunks,
+            xy_scaling_factor=xy_scaling_factor,
+            z_scaling_factor=z_scaling_factor,
             overwrite=overwrite,
         )
 
@@ -314,6 +318,8 @@ def derive_image_container(
     ref_path: str | None = None,
     shape: Collection[int] | None = None,
     chunks: Collection[int] | None = None,
+    xy_scaling_factor: float = 2.0,
+    z_scaling_factor: float = 1.0,
     overwrite: bool = False,
 ) -> ImagesContainer:
     """Create an OME-Zarr image from a numpy array."""
@@ -347,8 +353,8 @@ def derive_image_container(
         z_spacing=ref_image.pixel_size.z,
         time_spacing=ref_image.pixel_size.t,
         levels=ref_meta.levels,
-        xy_scaling_factor=2.0,  # will need to be fixed
-        z_scaling_factor=1.0,  # will need to be fixed
+        xy_scaling_factor=xy_scaling_factor,
+        z_scaling_factor=z_scaling_factor,
         time_unit=ref_image.pixel_size.time_unit,
         space_unit=ref_image.pixel_size.space_unit,
         axes_names=ref_image.dataset.axes_mapper.on_disk_axes_names,

ngio-0.2.0a2/src/ngio/images/label.py

@@ -0,0 +1,236 @@
+"""A module for handling label images in OME-NGFF files."""
+
+from collections.abc import Collection
+from typing import Literal
+
+from ngio.images.abstract_image import AbstractImage, consolidate_image
+from ngio.images.create import _create_empty_label
+from ngio.images.image import Image
+from ngio.ome_zarr_meta import (
+    ImplementedLabelMetaHandlers,
+    LabelMetaHandler,
+    NgioLabelMeta,
+)
+from ngio.ome_zarr_meta.ngio_specs import SpaceUnits, TimeUnits
+from ngio.utils import (
+    NgioValidationError,
+    NgioValueError,
+    StoreOrGroup,
+    ZarrGroupHandler,
+)
+
+
+class Label(AbstractImage[LabelMetaHandler]):
+    """Placeholder class for a label."""
+
+    def __init__(
+        self,
+        group_handler: ZarrGroupHandler,
+        path: str,
+        meta_handler: LabelMetaHandler | None,
+    ) -> None:
+        """Initialize the Image at a single level.
+
+        Args:
+            group_handler: The Zarr group handler.
+            path: The path to the image in the omezarr file.
+            meta_handler: The image metadata handler.
+
+        """
+        if meta_handler is None:
+            meta_handler = ImplementedLabelMetaHandlers().find_meta_handler(
+                group_handler
+            )
+        super().__init__(
+            group_handler=group_handler, path=path, meta_handler=meta_handler
+        )
+
+    @property
+    def meta(self) -> NgioLabelMeta:
+        """Return the metadata."""
+        return self._meta_handler.meta
+
+    def consolidate(
+        self,
+        mode: Literal["dask", "numpy", "coarsen"] = "dask",
+    ) -> None:
+        """Consolidate the label on disk."""
+        consolidate_image(self, mode=mode, order=0)
+
+
+class LabelsContainer:
+    """A class to handle the /labels group in an OME-NGFF file."""
+
+    def __init__(self, group_handler: ZarrGroupHandler) -> None:
+        """Initialize the LabelGroupHandler."""
+        self._group_handler = group_handler
+
+        # Validate the group
+        # Either contains a labels attribute or is empty
+        attrs = self._group_handler.load_attrs()
+        if len(attrs) == 0:
+            # It's an empty group
+            pass
+        elif "labels" in attrs and isinstance(attrs["labels"], list):
+            # It's a valid group
+            pass
+        else:
+            raise NgioValidationError(
+                f"Invalid /labels group. "
+                f"Expected a single labels attribute with a list of label names. "
+                f"Found: {attrs}"
+            )
+
+    def list(self) -> list[str]:
+        """Create the /labels group if it doesn't exist."""
+        attrs = self._group_handler.load_attrs()
+        return attrs.get("labels", [])
+
+    def get(self, name: str, path: str) -> Label:
+        """Get a label from the group."""
+        group_handler = self._group_handler.derive_handler(name)
+        return Label(group_handler, path, None)
+
+    def derive(
+        self,
+        name: str,
+        ref_image: Image,
+        shape: Collection[int] | None = None,
+        chunks: Collection[int] | None = None,
+        dtype: str = "uint16",
+        xy_scaling_factor=2.0,
+        z_scaling_factor=1.0,
+        overwrite: bool = False,
+    ) -> None:
+        """Add a label to the group."""
+        existing_labels = self.list()
+        if name in existing_labels and not overwrite:
+            raise NgioValueError(
+                f"Table '{name}' already exists in the group. "
+                "Use overwrite=True to replace it."
+            )
+
+        label_group = self._group_handler.get_group(name, create_mode=True)
+
+        _derive_label(
+            ref_image=ref_image,
+            store=label_group,
+            shape=shape,
+            chunks=chunks,
+            dtype=dtype,
+            xy_scaling_factor=xy_scaling_factor,
+            z_scaling_factor=z_scaling_factor,
+            overwrite=overwrite,
+        )
+
+        if name not in existing_labels:
+            existing_labels.append(name)
+            self._group_handler.write_attrs({"labels": existing_labels})
+
+    def new(
+        self,
+        name: str,
+        shape: Collection[int],
+        xy_pixelsize: float,
+        z_spacing: float = 1.0,
+        time_spacing: float = 1.0,
+        levels: "int | list[str]" = 5,
+        xy_scaling_factor: float = 2.0,
+        z_scaling_factor: float = 1.0,
+        space_unit: SpaceUnits | str | None = None,
+        time_unit: TimeUnits | str | None = None,
+        axes_names: Collection[str] | None = None,
+        chunks: Collection[int] | None = None,
+        dtype: str = "uint16",
+        overwrite: bool = False,
+        version: str = "0.4",
+    ) -> None:
+        """Add a label to the group."""
+        existing_labels = self.list()
+        if name in existing_labels and not overwrite:
+            raise NgioValueError(
+                f"Table '{name}' already exists in the group. "
+                "Use overwrite=True to replace it."
+            )
+
+        label_group = self._group_handler.get_group(name, create_mode=True)
+
+        _create_empty_label(
+            store=label_group,
+            shape=shape,
+            xy_pixelsize=xy_pixelsize,
+            z_spacing=z_spacing,
+            time_spacing=time_spacing,
+            levels=levels,
+            xy_scaling_factor=xy_scaling_factor,
+            z_scaling_factor=z_scaling_factor,
+            space_unit=space_unit,
+            time_unit=time_unit,
+            axes_names=axes_names,
+            chunks=chunks,
+            dtype=dtype,
+            overwrite=overwrite,
+            version=version,
+        )
+
+        if name not in existing_labels:
+            existing_labels.append(name)
+            self._group_handler.write_attrs({"labels": existing_labels})
+
+
+def _derive_label(
+    ref_image: Image,
+    store: StoreOrGroup,
+    shape: Collection[int] | None = None,
+    chunks: Collection[int] | None = None,
+    dtype: str = "uint16",
+    xy_scaling_factor=2.0,
+    z_scaling_factor=1.0,
+    overwrite: bool = False,
+) -> None:
+    """Create an OME-Zarr image from a numpy array."""
+    ref_meta = ref_image.meta
+    # remove channls if present
+    shape_ref = ref_image.shape
+    chunks_ref = ref_image.chunks
+    axes_names_ref = ref_image.dataset.axes_mapper.on_disk_axes_names
+    c_axis = ref_image.dataset.axes_mapper.get_index("c")
+    if c_axis is not None:
+        shape_ref = shape_ref[:c_axis] + shape_ref[c_axis + 1 :]
+        chunks_ref = chunks_ref[:c_axis] + chunks_ref[c_axis + 1 :]
+        axes_names_ref = axes_names_ref[:c_axis] + axes_names_ref[c_axis + 1 :]
+
+    if shape is None:
+        shape = shape_ref
+
+    if chunks is None:
+        chunks = chunks_ref
+
+    if len(shape) != len(shape_ref):
+        raise NgioValidationError(
+            "The shape of the new image does not match the reference image."
+        )
+
+    if len(chunks) != len(chunks_ref):
+        raise NgioValidationError(
+            "The chunks of the new image does not match the reference image."
+        )
+
+    _ = _create_empty_label(
+        store=store,
+        shape=shape,
+        xy_pixelsize=ref_image.pixel_size.x,
+        z_spacing=ref_image.pixel_size.z,
+        time_spacing=ref_image.pixel_size.t,
+        levels=ref_meta.levels,
+        xy_scaling_factor=xy_scaling_factor,
+        z_scaling_factor=z_scaling_factor,
+        time_unit=ref_image.pixel_size.time_unit,
+        space_unit=ref_image.pixel_size.space_unit,
+        axes_names=axes_names_ref,
+        chunks=chunks,
+        dtype=dtype,
+        overwrite=overwrite,
+        version=ref_meta.version,
+    )
+    return None

{ngio-0.2.0a1 → ngio-0.2.0a2}/src/ngio/images/omezarr_container.py

@@ -175,6 +175,8 @@ class OmeZarrContainer:
         ref_path: str | None = None,
         shape: Collection[int] | None = None,
         chunks: Collection[int] | None = None,
+        xy_scaling_factor: float = 2.0,
+        z_scaling_factor: float = 1.0,
         copy_tables: bool = False,
         copy_labels: bool = False,
         overwrite: bool = False,
@@ -191,6 +193,8 @@ class OmeZarrContainer:
             ref_path=ref_path,
             shape=shape,
             chunks=chunks,
+            xy_scaling_factor=xy_scaling_factor,
+            z_scaling_factor=z_scaling_factor,
             overwrite=overwrite,
         )
         return OmeZarrContainer(
@@ -281,15 +285,34 @@ class OmeZarrContainer:
             raise NgioValidationError("No labels found in the image.")
         return self._labels_container.get(name=name, path=path)
 
-    def derive_label(self, name: str, **kwargs) -> Label:
+    def derive_label(
+        self,
+        name: str,
+        ref_image: Image | None = None,
+        shape: Collection[int] | None = None,
+        chunks: Collection[int] | None = None,
+        dtype: str = "uint16",
+        xy_scaling_factor=2.0,
+        z_scaling_factor=1.0,
+        overwrite: bool = False,
+    ) -> Label:
         """Derive a label from an image."""
         if self._labels_container is None:
             raise NgioValidationError("No labels found in the image.")
 
-        ref_image = self.get_image()
-        return self._labels_container.derive(
-            name=name, reference_image=ref_image, **kwargs
+        if ref_image is None:
+            ref_image = self.get_image()
+        self._labels_container.derive(
+            name=name,
+            ref_image=ref_image,
+            shape=shape,
+            chunks=chunks,
+            dtype=dtype,
+            xy_scaling_factor=xy_scaling_factor,
+            z_scaling_factor=z_scaling_factor,
+            overwrite=overwrite,
         )
+        return self.get_label(name, path="0")
 
 
 def open_omezarr_container(

{ngio-0.2.0a1 → ngio-0.2.0a2}/src/ngio/utils/_datasets.py

@@ -28,7 +28,7 @@ def list_ome_zarr_datasets() -> list[str]:
 def download_ome_zarr_dataset(
     dataset_name: str,
     download_dir: str = "data",
-) -> str:
+) -> Path:
     """Download an OME-Zarr dataset.
 
     To list available datasets, use `list_ome_zarr_datasets`.

ngio-0.2.0a1/src/ngio/images/label.py

@@ -1,96 +0,0 @@
-"""A module for handling label images in OME-NGFF files."""
-
-from typing import Literal
-
-from ngio.images.abstract_image import AbstractImage, consolidate_image
-from ngio.ome_zarr_meta import (
-    ImplementedLabelMetaHandlers,
-    LabelMetaHandler,
-    NgioLabelMeta,
-)
-from ngio.utils import (
-    NgioValidationError,
-    ZarrGroupHandler,
-)
-
-
-class Label(AbstractImage[LabelMetaHandler]):
-    """Placeholder class for a label."""
-
-    def __init__(
-        self,
-        group_handler: ZarrGroupHandler,
-        path: str,
-        meta_handler: LabelMetaHandler | None,
-    ) -> None:
-        """Initialize the Image at a single level.
-
-        Args:
-            group_handler: The Zarr group handler.
-            path: The path to the image in the omezarr file.
-            meta_handler: The image metadata handler.
-
-        """
-        if meta_handler is None:
-            meta_handler = ImplementedLabelMetaHandlers().find_meta_handler(
-                group_handler
-            )
-        super().__init__(
-            group_handler=group_handler, path=path, meta_handler=meta_handler
-        )
-
-    @property
-    def meta(self) -> NgioLabelMeta:
-        """Return the metadata."""
-        return self._meta_handler.meta
-
-    def consolidate(
-        self,
-        mode: Literal["dask", "numpy", "coarsen"] = "dask",
-    ) -> None:
-        """Consolidate the label on disk."""
-        consolidate_image(self, mode=mode, order=0)
-
-
-class LabelsContainer:
-    """A class to handle the /labels group in an OME-NGFF file."""
-
-    def __init__(self, group_handler: ZarrGroupHandler) -> None:
-        """Initialize the LabelGroupHandler."""
-        self._group_handler = group_handler
-
-        # Validate the group
-        # Either contains a labels attribute or is empty
-        attrs = self._group_handler.load_attrs()
-        if len(attrs) == 0:
-            # It's an empty group
-            pass
-        elif "labels" in attrs and isinstance(attrs["labels"], list):
-            # It's a valid group
-            pass
-        else:
-            raise NgioValidationError(
-                f"Invalid /labels group. "
-                f"Expected a single labels attribute with a list of label names. "
-                f"Found: {attrs}"
-            )
-
-    def list(self) -> list[str]:
-        """Create the /labels group if it doesn't exist."""
-        attrs = self._group_handler.load_attrs()
-        return attrs.get("labels", [])
-
-    def get(self, name: str, path: str) -> Label:
-        """Get a label from the group."""
-        group_handler = self._group_handler.derive_handler(name)
-        return Label(group_handler, path, None)
-
-    def derive(
-        self,
-        name: str,
-        reference_image: AbstractImage,
-        overwrite: bool = False,
-        **kwargs,
-    ) -> Label:
-        """Derive a label from an image."""
-        raise NotImplementedError