Add image class

docs/source/_toc.yml

@@ -16,6 +16,11 @@ parts:
 
   - caption: Advanced
     chapters:
+    - file: advanced/labels/index
+      sections:
+      - file: advanced/labels/adding_labels
+      - file: advanced/labels/labels_metadata
+
     - file: advanced/sharding
     - file: advanced/build_custom_pyramid
     - file: advanced/write_hcs_plate
@@ -30,6 +35,7 @@ parts:
     chapters:
     - file: api
       sections:
+      - file: api/image
       - file: api/writer
       - file: api/reader
       - file: api/io

docs/source/advanced/build_custom_pyramid.ipynb

@@ -11,7 +11,7 @@
         "\n",
         "Multi-resolution pyramids are an integral part of ome-zarr image data\n",
         "and enable fast rendering of large images.\n",
-        "The entrypoints to writing ome-zarr images in ome-zarr-py ({py:func}`ome_zarr.writer.write_image` and {py:func}`ome_zarr.writer.write_labels`)\n",
+        "The entrypoints to writing ome-zarr images in ome-zarr-py ({py:func}`ome_zarr.classes.image.OMEZarrMultiscale`, {py:func}`ome_zarr.writer.write_image` and {py:func}`ome_zarr.writer.write_labels`)\n",
         "build these pyramids under the hood as delayed dask arrays based on the settings for the scaling functions and scale factors.\n",
         "\n",
         "In this example, the downsampling will be applied in all spatial dimensions *except the z dimension*, which will be left at a scale factor of 1.\n",
@@ -20,36 +20,78 @@
     },
     {
       "cell_type": "code",
-      "execution_count": 16,
+      "execution_count": 1,
       "id": "642955b1",
       "metadata": {},
+      "outputs": [],
+      "source": [
+        "import numpy as np\n",
+        "\n",
+        "from ome_zarr import OMEZarrImage, OMEZarrLabels, OMEZarrMultiscale\n",
+        "from ome_zarr.writer import write_image\n",
+        "\n",
+        "scale_factors = [2, 4, 8]\n",
+        "rng = np.random.default_rng(0)\n",
+        "data = rng.poisson(lam=10, size=(64, 64, 64)).astype(np.uint8)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 2,
+      "id": "a8f0defa",
+      "metadata": {},
       "outputs": [
         {
           "data": {
             "text/plain": [
               "[]"
             ]
           },
-          "execution_count": 16,
+          "execution_count": 2,
           "metadata": {},
           "output_type": "execute_result"
         }
       ],
       "source": [
-        "import numpy as np\n",
-        "\n",
-        "from ome_zarr.writer import write_image\n",
-        "\n",
-        "scale_factors = [2, 4, 8]\n",
-        "rng = np.random.default_rng(0)\n",
-        "data = rng.poisson(lam=10, size=(64, 64, 64)).astype(np.uint8)\n",
-        "\n",
         "write_image(\n",
         "    data,\n",
         "    \"test_ngff_image.ome.zarr\",\n",
         "    axes=\"zyx\",\n",
         "    scale_factors=scale_factors,\n",
-        "    )"
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "c3f7a5aa",
+      "metadata": {},
+      "source": [
+        "Or, if you choose to work with the {py:class}`ome_zarr.classes.image.OMEZarrMultiscale` and {py:class}`ome_zarr.classes.image.OMEZarrImage` classes directly,\n",
+        "they accept the same arguments:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "d0315903",
+      "metadata": {},
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "[]"
+            ]
+          },
+          "execution_count": 3,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "source": [
+        "ngff_image = OMEZarrImage(data, axes=\"zyx\")\n",
+        "ngff_multiscales = OMEZarrMultiscale(ngff_image, scale_factors=scale_factors)\n",
+        "\n",
+        "ngff_multiscales.to_ome_zarr(\"test_ngff_image_multiscales.ome.zarr\")"
       ]
     },
     {
@@ -66,7 +108,7 @@
     },
     {
       "cell_type": "code",
-      "execution_count": 17,
+      "execution_count": 4,
       "id": "60dcd278",
       "metadata": {},
       "outputs": [
@@ -76,7 +118,7 @@
               "[]"
             ]
           },
-          "execution_count": 17,
+          "execution_count": 4,
           "metadata": {},
           "output_type": "execute_result"
         }
@@ -108,7 +150,7 @@
     },
     {
       "cell_type": "code",
-      "execution_count": 18,
+      "execution_count": 5,
       "id": "877ab60d",
       "metadata": {},
       "outputs": [
@@ -136,7 +178,7 @@
     },
     {
       "cell_type": "code",
-      "execution_count": 19,
+      "execution_count": 6,
       "id": "859ca482",
       "metadata": {},
       "outputs": [
@@ -146,7 +188,7 @@
               "[]"
             ]
           },
-          "execution_count": 19,
+          "execution_count": 6,
           "metadata": {},
           "output_type": "execute_result"
         }
@@ -161,6 +203,38 @@
         ")\n"
       ]
     },
+    {
+      "cell_type": "markdown",
+      "id": "9b33ad31",
+      "metadata": {},
+      "source": [
+        "Again, the {py:class}`ome_zarr.OMEZarrMultiscale` accepts the same argument:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "84c73869",
+      "metadata": {},
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "[]"
+            ]
+          },
+          "execution_count": 7,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "source": [
+        "ngff_image = OMEZarrImage(data, axes=\"zyx\")\n",
+        "ngff_multiscales = OMEZarrMultiscale(ngff_image, scale_factors=scale_factors, method=\"nearest\")\n",
+        "\n",
+        "ngff_multiscales.to_ome_zarr(\"test_ngff_image_multiscales.ome.zarr\")"
+      ]
+    },
     {
       "cell_type": "markdown",
       "id": "893a1b3b",
@@ -175,20 +249,32 @@
         "you will want to use a method that preserves the label values, such as {py:func}`ome_zarr.scale.Methods.NEAREST`.\n",
         "\n",
         "See also section on [writing labels](basic:labels)\n",
+        "```\n",
         "\n",
-        "```"
+        "If you specifically want to create a labels image, you can use the {py:class}`ome_zarr.classes.image.OMEZarrLabels` class.\n",
+        "It provides the same functionality as the {py:class}`ome_zarr.classes.image.OMEZarrMultiscale` class, but the downsampling function used under the hood defaults to {py:func}`ome_zarr.scale.Methods.NEAREST`,\n",
+        "which is typically the most appropriate for labels data.\n",
+        "\n",
+        "For more information on writing labels data, see the [labels writing section](advanced/labels/index)."
       ]
     },
     {
-      "cell_type": "markdown",
-      "id": "fbbeecf3",
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "2e5edc2e",
       "metadata": {},
-      "source": []
+      "outputs": [],
+      "source": [
+        "ngff_image = OMEZarrImage(data, axes=\"zyx\")\n",
+        "ngff_multiscales = OMEZarrLabels(ngff_image, scale_factors=scale_factors)\n",
+        "\n",
+        "ngff_multiscales.to_ome_zarr(\"test_ngff_image_multiscales_labels.ome.zarr\")"
+      ]
     }
   ],
   "metadata": {
     "kernelspec": {
-      "display_name": "ngff-spec",
+      "display_name": "ome-zarr (3.12.12)",
       "language": "python",
       "name": "python3"
     },