RFC5: coordinate systems and transformations

.github/workflows/validation.yml

@@ -0,0 +1,16 @@
+name: Validation
+on:
+  push:
+  pull_request:
+
+jobs:
+  validate:
+    name: Validation
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -mpip install --upgrade wheel tox
+      - run: tox

.gitignore

@@ -9,6 +9,9 @@ _bikeshed
 
 # do not sync auto-generated md files
 ngff_spec/_generated
+ngff_spec/footer.md
+ngff_spec/examples.md
+ngff_spec/schemas.md
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

ngff_spec/examples/coordinate_systems/arrayCoordSys.json

@@ -0,0 +1,10 @@
+{
+  "arrayCoordinateSystem" : {
+    "name" : "myDataArray",
+    "axes" : [
+      {"name": "k", "type": "array"},
+      {"name": "j", "type": "array"},
+      {"name": "i", "type": "array"}
+    ]
+  }
+}

ngff_spec/examples/multiscales_strict/multiscales_example.json

@@ -3,61 +3,61 @@
   "node_type": "group",
   "attributes": {
     "ome": {
-      "version": "0.6dev2",
+      "version": "0.5",
       "multiscales": [
         {
-          "name": "physical",
+          "name": "example",
           "coordinateSystems": [
-            {
-              "name": "physical",
-              "axes": [
-                { "name": "t", "type": "time", "unit": "millisecond" },
-                { "name": "c", "type": "channel" },
-                { "name": "z", "type": "space", "unit": "micrometer" },
-                { "name": "y", "type": "space", "unit": "micrometer" },
-                { "name": "x", "type": "space", "unit": "micrometer" }
-              ]
-            }
+              {
+                "name": "intrinsic",
+                "axes": [
+                  { "name": "t", "type": "time", "unit": "millisecond" },
+                  { "name": "c", "type": "channel" },
+                  { "name": "z", "type": "space", "unit": "micrometer" },
+                  { "name": "y", "type": "space", "unit": "micrometer" },
+                  { "name": "x", "type": "space", "unit": "micrometer" }
+                ]
+              }
           ],
           "datasets": [
             {
               "path": "0",
               "coordinateTransformations": [
                 {
                   // the voxel size for the first scale level (0.5 micrometer)
-                  // the time unit (0.1 milliseconds), which is the same for each scale level
+                  // and the time unit (0.1 milliseconds), which is the same for each scale level
                   "type": "scale",
                   "scale": [0.1, 1.0, 0.5, 0.5, 0.5],
                   "input": "0",
-                  "output": "physical"
+                  "output": "intrinsic"
                 }
               ]
             },
             {
               "path": "1",
               "coordinateTransformations": [
                 {
-                  // the voxel size for the second scale level (1 micrometer)
-                  // the time unit (0.1 milliseconds), which is the same for each scale level
+                  // the voxel size for the second scale level (downscaled by a factor of 2 -> 1 micrometer)
+                  // and the time unit (0.1 milliseconds), which is the same for each scale level
                   "type": "scale",
                   "scale": [0.1, 1.0, 1.0, 1.0, 1.0],
                   "input": "1",
-                  "output": "physical"
+                  "output": "intrinsic"
                 }
               ]
             },
             {
               "path": "2",
               "coordinateTransformations": [
                 {
-                  // the voxel size for the third scale level (2 micrometer)
-                  // the time unit (0.1 milliseconds), which is the same for each scale level
+                  // the voxel size for the third scale level (downscaled by a factor of 4 -> 2 micrometer)
+                  // and the time unit (0.1 milliseconds), which is the same for each scale level
                   "type": "scale",
                   "scale": [0.1, 1.0, 2.0, 2.0, 2.0],
                   "input": "2",
-                  "output": "physical"
+                  "output": "intrinsic"
                 }
-            ]
+              ]
             }
           ],
           "type": "gaussian",
@@ -72,4 +72,4 @@
       ]
     }
   }
-}
+}

ngff_spec/examples/multiscales_strict/multiscales_example_relative.json

@@ -1,76 +1,72 @@
 {
-    "multiscales": [
+  "multiscales": [
+    {
+      "version": "0.6.dev2",
+      "name": "example",
+      "coordinateSystems" : [
         {
-            "version": "0.5-dev",
-            "name": "example",
-            "coordinateSystems" : [
-                {
-                    "name" : "exampleCoordinateSystem",
-                    "axes": [
-                        {"name": "t", "type": "time", "unit": "millisecond"},
-                        {"name": "c", "type": "channel"},
-                        {"name": "z", "type": "space", "unit": "micrometer"},
-                        {"name": "y", "type": "space", "unit": "micrometer"},
-                        {"name": "x", "type": "space", "unit": "micrometer"}
-                    ]
-                },
-                {
-                    "name" : "array_0",
-                    "axes": [
-                        {"name": "t", "type": "time", "unit": "millisecond"},
-                        {"name": "c", "type": "channel"},
-                        {"name": "z", "type": "space", "unit": "micrometer"},
-                        {"name": "y", "type": "space", "unit": "micrometer"},
-                        {"name": "x", "type": "space", "unit": "micrometer"}
-                    ]
-                }
-            ],
-            "datasets": [
-                {
-                    "path": "0",
-                    // the transformation of other arrays are defined relative to this, the highest resolution, array
-                    "coordinateTransformations": [{
-                        "type": "identity",
-                        "input": "/0",
-                        "output": "array_0"
-                    }]
-                },
-                {
-                    "path": "1",
-                    "coordinateTransformations": [{
-                        // the second scale level (downscaled by a factor of 2 relative to "0" in zyx)
-                        "type": "scale",
-                        "scale": [1, 1, 2, 2, 2],
-                        "input" : "/1",
-                        "output" : "array_0"
-                    }]
-                },
-                {
-                    "path": "2",
-                    "coordinateTransformations": [{
-                        // the third scale level (downscaled by a factor of 4 relative to "0" in zyx)
-                        "type": "scale",
-                        "scale": [1, 1, 4, 4, 4],
-                        "input" : "/2",
-                        "output" : "array_0"
-                    }]
-                }
-            ],
-            "coordinateTransformations": [{
-                // the time unit (0.1 milliseconds), the voxel size for all spatial axes of "0" (0.5 micrometers)
-                "type": "scale",
-                "scale": [0.1, 1.0, 0.5, 0.5, 0.5],
-                "input" : "array_0",
-                "output" : "exampleCoordinateSystem"
-            }],
-            "type": "gaussian",
-            "metadata": {
-                "description": "the fields in metadata depend on the downscaling implementation. Here, the parameters passed to the skimage function are given",
-                "method": "skimage.transform.pyramid_gaussian",
-                "version": "0.16.1",
-                "args": "[true]",
-                "kwargs": {"multichannel": true}
-            }
+          "name" : "world",
+          "axes": {
+            "t": {"type": "time", "unit": "millisecond"},
+            "c": {"type": "channel"},
+            "z": {"type": "space", "unit": "micrometer"},
+            "y": {"type": "space", "unit": "micrometer"},
+            "x": {"type": "space", "unit": "micrometer"}
+          }
+        },
+        {
+          "name" : "intrinsic",
+          "axes": [
+            {"name": "t", "type": "time", "unit": "millisecond"},
+            {"name": "c", "type": "channel"},
+            {"name": "z", "type": "space", "unit": "micrometer"},
+            {"name": "y", "type": "space", "unit": "micrometer"},
+            {"name": "x", "type": "space", "unit": "micrometer"}
+          ]
+        }
+      ],
+      "datasets": [
+        {
+          "path": "s0",
+          // the transformation of other arrays are
+          // defined relative to this, the highest resolution, array
+          "coordinateTransformations": [{
+            "type": "scale",
+            "scale": [1, 1, 1, 1, 1],
+            "input": "s0",
+            "output": "intrinsic"
+          }]
+        },
+        {
+          "path": "1",
+          "coordinateTransformations": [{
+            // the second scale level (downscaled by a factor of 2 relative to "0" in zyx)
+            "type": "scale",
+            "scale": [1, 1, 2, 2, 2],
+            "input" : "/1",
+            "output" : "array_0"
+          }]
+        },
+        {
+          "path": "2",
+          "coordinateTransformations": [{
+            // the third scale level (downscaled by a factor of 4 relative to "0" in zyx)
+            "type": "scale",
+            "scale": [1, 1, 4, 4, 4],
+            "input" : "/2",
+            "output" : "array_0"
+          }]
+        }
+      ],
+      "coordinateTransformations": [
+        {
+          "name": "additional_translation",
+          "type": "translation",
+          "translation": [0, 0, 10, 20, 30],
+          "input": "intrinsic",
+          "output": "world"
         }
-    ]
+      ]
+    }
+  ]
 }