Merge remote-tracking branch 'origin/main' into validator-framework

Author: msschwartz21

.github/PULL_REQUEST_TEMPLATE.md

@@ -23,7 +23,7 @@ Put an x in the boxes that apply. You can also fill these out after creating the
 
 ## If you changed the specification
 - [ ] I have checked that any validation functions and tests reflect the changes.
-- [ ] I have updated the GeffMetadata and the json schema using `pixi run update-schema` if necessary.
+- [ ] I have updated the GeffMetadata and the json schema using `pixi run update-json` if necessary.
 - [ ] I have updated docs/specification.md to reflect the change.
 - [ ] I have updated implementations to reflect the change. (This can happen in separate PRs on a feature branch, but must be complete before merging into main.)
 

.gitignore

@@ -12,6 +12,7 @@ wheels/
 
 # Virtual environments
 .venv
+.python-version
 
 # pixi environments
 .pixi
@@ -29,4 +30,5 @@ coverage.xml
 
 uv.lock
 /.idea
+.vscode/
 site

docs/specification.md

@@ -22,6 +22,13 @@ Currently, `geff` supports zarr specifications [2](https://zarr-specs.readthedoc
 
     ::: geff.units.VALID_TIME_UNITS  
 
+### Affine transformations
+The optional `affine` field allows specifying a global affine transformation that maps the graph coordinates stored in the node properties to a physical coordinate system. The value **matrix** is stored as a `(N + 1) × (N + 1)` homogeneous matrix following the `scipy.ndimage.affine_transform` convention, where **N** equals the number of spatio-temporal axes declared in `axes`.
+
+### Extra attributes 
+
+The optional `extra` object is a free-form dictionary that can hold any additional, application-specific metadata that is **not** covered by the core geff schema. Users may place arbitrary keys and values inside `extra` without fear of clashing with future reserved fields. Although the core `geff` reader makes these attributes available, their meaning and use are left entirely to downstream applications. 
+
 ## The `nodes` group
 The nodes group will contain an `ids` array and optionally a `props` group. 
 ### The `ids` array
@@ -37,6 +44,10 @@ The `nodes\props` group is optional and will contain one or more `node property`
 -  Geff provides special support for spatio-temporal properties, although they are not required. When `axes` are specified in the `geff` metadata, each axis name identifies a spatio-temporal property. Spatio-temporal properties are not allowed to have missing arrays. Otherwise, they are identical to other properties from a storage specification perspective.
 
 - The `seg_id` property is an optional, special node property that stores the segmenatation label for each node. The `seg_id` values do not need to be unique, in case labels are repeated between time points. If the `seg_id` property is not present, it is assumed that the graph is not associated with a segmentation. 
+
+-  Geff provides special support for predefined shape properties, although they are not required. These currently include: `sphere`, `ellipsoid`. Values can be marked as `missing`, and a geff graph may contain multiple different shape properties. Units of shapes are assumed to be the same as the units on the spatial axes. Otherwise, shape properties are identical to other properties from a storage specification perspective.
+    - `sphere`: Hypersphere in n spatial dimensions, defined by a scalar radius.
+    - `ellipsoid`: Defined by a symmetric positive-definite covariance matrix, whose dimensionality is assumed to match the spatial axes.
 <!-- Perhaps we just let the user specify the seg id property in the metadata instead? Then you can point it to the node ids if you wanted to -->
 
 !!! note
@@ -76,6 +87,12 @@ Here is a schematic of the expected file structure.
                     values # shape: (N,) dtype: float32
                 x/
                     values # shape: (N,) dtype: float32
+                radius/
+                    values # shape: (N,) dtype: int | float
+                    missing # shape: (N,) dtype: bool
+                covariance3d/
+                    values # shape: (N, 3, 3) dtype: float
+                    missing # shape: (N,) dtype: bool
                 color/
                     values # shape: (N, 4) dtype: float16
                     missing # shape: (N,) dtype: bool
@@ -105,8 +122,41 @@ This is a geff metadata zattrs file that matches the above example structure.
             {'name': 'z', 'type': "space", 'unit': "micrometers", 'min': 1523.36, 'max': 4398.1},
             {'name': 'y', 'type': "space", 'unit': "micrometers", 'min': 81.667, 'max': 1877.7},
             {'name': 'x', 'type': "space", 'unit': "micrometers", 'min': 764.42, 'max': 2152.3},
-        ]
+        ],
+        # predefined node attributes for storing detections as spheres or ellipsoids
+        "sphere": "radius", # optional
+        "ellipsoid": "covariance3d", # optional
+        "display_hints": {
+            "display_horizontal": "x",
+            "display_vertical": "y",
+            "display_depth": "z",
+            "display_time": "t",
+        },
+        # node attributes corresponding to tracklet and/or lineage IDs
+        "track_node_props": {
+            "lineage": "ultrack_lineage_id",
+            "tracklet": "ultrack_id"
+        },
+        "related_objects": {
+            {
+                "type":"labels", "path":"../segmentation/", "label_prop": "seg_id",
+            },
+            {
+                "type":"image", "path":"../raw/",
+            },
+        },
+        # optional coordinate transformation is defined as homogeneous coordinates
+        # It is expected to be a (D+1)x(D+1) matrix where D is the number of axes
+        "affine": [
+            [1, 0, 0, 0, 0],
+            [0, 1, 0, 0, 0],
+            [0, 0, 1, 0, 0],
+            [0, 0, 0, 1, 0],
+            [0, 0, 0, 0, 1],
+        # custom other things must be placed **inside** the extra attribute
+        "extra": {
+            ...
+        }
     }
-    ... # custom other things are allowed and ignored by geff
 }
 ```

geff-schema.json

@@ -1,5 +1,19 @@
 {
   "$defs": {
+    "Affine": {
+      "description": "Affine transformation class following scipy conventions.\n\nInternally stores transformations as homogeneous coordinate matrices (N+1, N+1).\nThe transformation matrix follows scipy.ndimage.affine_transform convention\nwhere the matrix maps output coordinates to input coordinates (inverse/pull transformation).\n\nFor a point p_out in output space, the corresponding input point p_in is computed as:\np_in_homo = matrix @ p_out_homo\nwhere p_out_homo = [p_out; 1] and p_in = p_in_homo[:-1]\n\nAttributes:\n    matrix: Homogeneous transformation matrix as list of lists (ndim+1, ndim+1)",
+      "properties": {
+        "matrix": {
+          "description": "Homogeneous transformation matrix as list of lists (ndim+1, ndim+1)",
+          "title": "Matrix"
+        }
+      },
+      "required": [
+        "matrix"
+      ],
+      "title": "Affine",
+      "type": "object"
+    },
     "Axis": {
       "properties": {
         "name": {
@@ -61,6 +75,53 @@
       "title": "Axis",
       "type": "object"
     },
+    "DisplayHint": {
+      "description": "Metadata indicating how spatiotemporal axes are displayed by a viewer",
+      "properties": {
+        "display_horizontal": {
+          "description": "Which spatial axis to use for horizontal display",
+          "title": "Display Horizontal",
+          "type": "string"
+        },
+        "display_vertical": {
+          "description": "Which spatial axis to use for vertical display",
+          "title": "Display Vertical",
+          "type": "string"
+        },
+        "display_depth": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Optional, which spatial axis to use for depth display",
+          "title": "Display Depth"
+        },
+        "display_time": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Optional, which temporal axis to use for time",
+          "title": "Display Time"
+        }
+      },
+      "required": [
+        "display_horizontal",
+        "display_vertical"
+      ],
+      "title": "DisplayHint",
+      "type": "object"
+    },
     "GeffMetadata": {
       "description": "Geff metadata schema to validate the attributes json file in a geff zarr",
       "properties": {
@@ -90,6 +151,98 @@
           "default": null,
           "description": "Optional list of Axis objects defining the axes of each node in the graph.\nEach object's `name` must be an existing attribute on the nodes. The optional `type` keymust be one of `space`, `time` or `channel`, though readers may not use this information. Each axis can additionally optionally define a `unit` key, which should match the validOME-Zarr units, and `min` and `max` keys to define the range of the axis.",
           "title": "Axes"
+        },
+        "sphere": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "\n            Name of the optional `sphere` property.\n\n            A sphere is defined by\n            - a center point, already given by the `space` type properties\n            - a radius scalar, stored in this property\n            ",
+          "title": "Node property: Detections as spheres"
+        },
+        "ellipsoid": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "\n            Name of the `ellipsoid` property.\n\n            An ellipsoid is assumed to be in the same coordinate system as the `space` type\n            properties.\n\n            It is defined by\n            - a center point :math:`c`, already given by the `space` type properties\n            - a covariance matrix :math:`\\Sigma`, symmetric and positive-definite, stored in this\n              property as a `2x2`/`3x3` array.\n\n            To plot the ellipsoid:\n            - Compute the eigendecomposition of the covariance matrix\n            :math:`\\Sigma = Q \\Lambda Q^{\\top}`\n            - Sample points :math:`z` on the unit sphere\n            - Transform the points to the ellipsoid by\n            :math:`x = c + Q \\Lambda^{(1/2)} z`.\n            ",
+          "title": "Node property: Detections as ellipsoids"
+        },
+        "track_node_props": {
+          "anyOf": [
+            {
+              "additionalProperties": {
+                "type": "string"
+              },
+              "propertyNames": {
+                "enum": [
+                  "lineage",
+                  "tracklet"
+                ]
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Node properties denoting tracklet and/or lineage IDs.\nA tracklet is defined as a simple path of connected nodes where the initiating node has any incoming degree and outgoing degree at most 1,and the terminating node has incoming degree at most 1 and any outgoing degree, and other nodes along the path have in/out degree of 1. Each tracklet must contain the maximal set of connected nodes that match this definition - no sub-tracklets.\nA lineage is defined as a weakly connected component on the graph.\nThe dictionary can store one or both of 'tracklet' or 'lineage' keys.",
+          "title": "Track Node Props"
+        },
+        "related_objects": {
+          "anyOf": [
+            {
+              "items": {
+                "$ref": "#/$defs/RelatedObject"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "A list of dictionaries of related objects such as labels or images. Each dictionary must contain 'type', 'path', and optionally 'label_prop' properties. The 'type' represents the data type. 'labels' and 'image' should be used for label and image objects, respectively. Other types are also allowed, The 'path' should be relative to the geff zarr-attributes file. It is strongly recommended all related objects are stored as siblings of the geff group within the top-level zarr group. The 'label_prop' is only valid for type 'labels' and specifies the node property that will be used to identify the labels in the related object. ",
+          "title": "Related Objects"
+        },
+        "affine": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Affine"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Affine transformation matrix to transform the graph coordinates to the physical coordinates. The matrix must have the same number of dimensions as the number of axes in the graph."
+        },
+        "display_hints": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/DisplayHint"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Metadata indicating how spatiotemporal axes are displayed by a viewer"
+        },
+        "extra": {
+          "description": "Extra metadata that is not part of the schema",
+          "title": "Extra"
         }
       },
       "required": [
@@ -98,6 +251,39 @@
       ],
       "title": "geff_metadata",
       "type": "object"
+    },
+    "RelatedObject": {
+      "properties": {
+        "type": {
+          "description": "Type of the related object. 'labels' for label objects, 'image' for image objects. Other types are also allowed, but may not be recognized by reader applications. ",
+          "title": "Type",
+          "type": "string"
+        },
+        "path": {
+          "description": "Path of the related object within the zarr group, relative to the geff zarr-attributes file. It is strongly recommended all related objects are stored as siblings of the geff group within the top-level zarr group.",
+          "title": "Path",
+          "type": "string"
+        },
+        "label_prop": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Property name for label objects. This is the node property that will be used to identify the labels in the related object. This is only valid for type 'labels'.",
+          "title": "Label Prop"
+        }
+      },
+      "required": [
+        "type",
+        "path"
+      ],
+      "title": "RelatedObject",
+      "type": "object"
     }
   },
   "properties": {

pyproject.toml

@@ -12,6 +12,7 @@ requires-python = ">=3.10"
 license = { text = "MIT License" }
 dynamic = ['version']
 dependencies = [
+    "typer",
     "zarr>2,<4",
     "pydantic>=2",
     "numcodecs<0.16", # TODO: remove pin once the 16 release is stable
@@ -31,6 +32,7 @@ classifiers = [
 
 [project.optional-dependencies]
 spatial-graph = ["spatial-graph"]
+ctc = ["dask", "scikit-image", "tifffile", "imagecodecs"]
 
 [dependency-groups]
 test = ["pytest>=8.3.4", "pytest-cov>=6.2"]
@@ -42,6 +44,7 @@ dev = [
     "ipython",
     "types-PyYAML",
     "spatial-graph",
+    "geff[ctc]"
 ]
 docs = [
     "mkdocs-material",
@@ -83,6 +86,7 @@ update-json = "python scripts/export_json_schema.py"
 
 [tool.pixi.feature.dev.tasks]
 test = "coverage run -m pytest"
+test-cov = "coverage run -m pytest && coverage xml && coverage report --show-missing"
 benchmark = { cmd = "pytest tests/bench.py" }
 
 [tool.pixi.feature.bench.tasks]
@@ -189,5 +193,5 @@ extend-ignore-identifiers-re = ["(?i)ome"]
 #     "tests/**/*",
 # ]
 
-[project.entry-points.pytest11]
-geff = "geff._pytest_plugin"
+[project.entry-points.console_scripts]
+ctc2geff = "geff.interops.ctc:app"