Introduce scene class

docs/source/_toc.yml

@@ -24,6 +24,9 @@ parts:
     - file: advanced/transforms/index
       sections:
       - file: advanced/transforms/add_transforms_to_multiscales
+      - file: advanced/transforms/create_scenes
+      - file: advanced/transforms/reading_scenes
+      - file: advanced/transforms/scene_2d_to_3d
 
     - file: advanced/sharding
     - file: advanced/build_custom_pyramid

docs/source/advanced/transforms/add_transforms_to_multiscales.ipynb

@@ -157,7 +157,7 @@
     },
     {
       "cell_type": "code",
-      "execution_count": 6,
+      "execution_count": null,
       "id": "2e7d870d",
       "metadata": {},
       "outputs": [
@@ -175,7 +175,7 @@
       "source": [
         "ms.to_ome_zarr(\n",
         "    \"multiscale_with_transforms.ome.zarr\",\n",
-        "    version=\"0.6.dev4\",  # specify the desired ome-zarr version\n",
+        "    version=\"0.6\",  # specify the desired ome-zarr version\n",
         "    overwrite=True,\n",
         ")"
       ]

docs/source/advanced/transforms/create_scenes.ipynb

@@ -0,0 +1,255 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "id": "8b0be7e9",
+      "metadata": {},
+      "source": [
+        "# Create Scenes\n",
+        "\n",
+        "(advanced:create-scenes)=\n",
+        "\n",
+        "This tutorial demonstrates basic usage around writing and reading [Ngff Scenes](https://ngff.openmicroscopy.org/specifications/dev/index.html#scene-metadata) using the {py:class}`ome_zarr.classes.scene.OMEZarrScene` class."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 1,
+      "id": "a49ec1c2",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from skimage import data\n",
+        "\n",
+        "from ome_zarr import OMEZarrImage, OMEZarrMultiscale, OMEZarrScene"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "98bbabd7",
+      "metadata": {},
+      "source": [
+        "We create some sample data, which we will store as a tiled layout in a scene zarr group:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 2,
+      "id": "e3023c95",
+      "metadata": {},
+      "outputs": [
+        {
+          "name": "stderr",
+          "output_type": "stream",
+          "text": [
+            "c:\\Users\\johan\\Documents\\GitHub\\ome-zarr-py\\.venv\\Lib\\site-packages\\tqdm\\auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n",
+            "  from .autonotebook import tqdm as notebook_tqdm\n"
+          ]
+        },
+        {
+          "data": {
+            "text/plain": [
+              "(512, 512)"
+            ]
+          },
+          "execution_count": 2,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "source": [
+        "example_image = data.human_mitosis()\n",
+        "example_image.shape"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "71e31e2a",
+      "metadata": {},
+      "source": [
+        "First, we cut the image into four tiles and convert them into instances of {py:class}`ome_zarr.classes.image.OMEZarrMultiscale`:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 3,
+      "id": "017d4c59",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "img1 = OMEZarrImage(data=example_image[:256, :256], axes=[\"y\", \"x\"], name=\"img1\")\n",
+        "img2 = OMEZarrImage(data=example_image[256:, :256], axes=[\"y\", \"x\"], name=\"img2\")\n",
+        "img3 = OMEZarrImage(data=example_image[:256, 256:], axes=[\"y\", \"x\"], name=\"img3\")\n",
+        "img4 = OMEZarrImage(data=example_image[256:, 256:], axes=[\"y\", \"x\"], name=\"img4\")\n",
+        "\n",
+        "img1_ms = OMEZarrMultiscale(img1)\n",
+        "img2_ms = OMEZarrMultiscale(img2)\n",
+        "img3_ms = OMEZarrMultiscale(img3)\n",
+        "img4_ms = OMEZarrMultiscale(img4)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "cf59df32",
+      "metadata": {},
+      "source": [
+        "Next, we need to define a coordinate system into which all images are projected.\n",
+        "This is defined in accordance with the NGFF [coordinate systems specification](https://ngff.openmicroscopy.org/specifications/dev/index.html#coordinatesystems-metadata)."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 4,
+      "id": "994674c2",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "coordinate_system = {\n",
+        "    \"name\": \"world\",\n",
+        "    \"axes\": [\n",
+        "        {\"name\": \"y\", \"type\": \"space\"},\n",
+        "        {\"name\": \"x\", \"type\": \"space\"},\n",
+        "    ],\n",
+        "}"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "c1d629be",
+      "metadata": {},
+      "source": [
+        "We then define translations that move each tile into the appropriate position in the world coordinate system.\n",
+        "In this example, these are simple translations in the y and x dimensions:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 5,
+      "id": "d6329caa",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "coordinate_transformations = [\n",
+        "    {\n",
+        "        \"type\": \"translation\",\n",
+        "        \"translation\": [0, 0],\n",
+        "        \"input\": {\"path\": \"img1\", \"name\": \"physical\"},\n",
+        "        \"output\": {\"name\": \"world\"},\n",
+        "    },\n",
+        "    {\n",
+        "        \"type\": \"translation\",\n",
+        "        \"translation\": [256, 0],\n",
+        "        \"input\": {\"path\": \"img2\", \"name\": \"physical\"},\n",
+        "        \"output\": {\"name\": \"world\"},\n",
+        "    },\n",
+        "    {\n",
+        "        \"type\": \"translation\",\n",
+        "        \"translation\": [0, 256],\n",
+        "        \"input\": {\"path\": \"img3\", \"name\": \"physical\"},\n",
+        "        \"output\": {\"name\": \"world\"},\n",
+        "    },\n",
+        "    {\n",
+        "        \"type\": \"translation\",\n",
+        "        \"translation\": [256, 256],\n",
+        "        \"input\": {\"path\": \"img4\", \"name\": \"physical\"},\n",
+        "        \"output\": {\"name\": \"world\"},\n",
+        "    },\n",
+        "]"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "4444a8d3",
+      "metadata": {},
+      "source": [
+        "We can then create and write a scene like this:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 6,
+      "id": "d05be093",
+      "metadata": {},
+      "outputs": [
+        {
+          "name": "stderr",
+          "output_type": "stream",
+          "text": [
+            "Writing images: 100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 4/4 [00:00<00:00,  7.08it/s]\n"
+          ]
+        }
+      ],
+      "source": [
+        "scene = OMEZarrScene(\n",
+        "    images=[img1_ms, img2_ms, img3_ms, img4_ms],\n",
+        "    coordinate_systems=[coordinate_system],\n",
+        "    coordinate_transformations=coordinate_transformations\n",
+        ")\n",
+        "\n",
+        "scene.to_ome_zarr(\"test_example_scene.zarr\", overwrite=True)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "9333cd91",
+      "metadata": {},
+      "source": [
+        "....and load it back like this:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 12,
+      "id": "8b87b923",
+      "metadata": {},
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "(Translation(type='translation', input=CoordinateSystemIdentifier(name='physical', path='img1'), output=CoordinateSystemIdentifier(name='world', path=None), name=None, translation=(0.0, 0.0)),\n",
+              " Translation(type='translation', input=CoordinateSystemIdentifier(name='physical', path='img2'), output=CoordinateSystemIdentifier(name='world', path=None), name=None, translation=(256.0, 0.0)),\n",
+              " Translation(type='translation', input=CoordinateSystemIdentifier(name='physical', path='img3'), output=CoordinateSystemIdentifier(name='world', path=None), name=None, translation=(0.0, 256.0)),\n",
+              " Translation(type='translation', input=CoordinateSystemIdentifier(name='physical', path='img4'), output=CoordinateSystemIdentifier(name='world', path=None), name=None, translation=(256.0, 256.0)))"
+            ]
+          },
+          "execution_count": 12,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "source": [
+        "loaded_scene = OMEZarrScene.from_ome_zarr(\"test_example_scene.zarr\")\n",
+        "loaded_scene.coordinate_transformations"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "cd5dda7c",
+      "metadata": {},
+      "outputs": [],
+      "source": []
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "ome-zarr (3.13.12)",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.13.12"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}