Support predefined object detection shapes (#159)

This adds storing object detections as pre-defined shapes on a geff graph ( #144).

We start off with
- circles and spheres as type `sphere` with a single number.
- 2D ellipses/3D ellipsoids as type `ellipsoid`, represented by a
2x2/3x3covariance matrix.

Thoughts:
- Convariance matrices: Store full matrix, using appropriate zarr compression for minimal overhead.

# Types of Changes
- New feature or enhancement

Which topics does your change affect? Delete those that do not apply.
- Specification
- Schema

# Checklist
Put an x in the boxes that apply. You can also fill these out after
creating the PR. If you're unsure about any of them, don't hesitate to
ask. We're here to help! This is simply a reminder of what we are going
to look for before merging your code.

- [x] I have read the
[developer/contributing](https://github.com/live-image-tracking-tools/geff/blob/main/CONTRIBUTING)
docs.
- [ ] I have added tests that prove that my feature works in various
situations or tests the bugfix (if appropriate).
- [x] I have checked that I maintained or improved code coverage.
- [x] I have written docstrings and checked that they render correctly.

## If you changed the specification
- [x] I have checked that any validation functions and tests reflect the
changes.
- [x] I have updated the GeffMetadata and the json schema using `pixi
run update-schema` if necessary.
- [x] 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.)

## If you have added or changed an implementation
- [ ] I wrote tests for the new implementation using standard fixtures
supplied in conftest.py.
- [ ] I updated pyproject.toml with new dependencies if needed.
- [ ] I added a function to tests/bench.py to benchmark the new
implementation.

---------

Co-authored-by: Jean-Yves Tinevez <[email protected]>
Co-authored-by: Caroline Malin-Mayor <[email protected]>
Co-authored-by: Morgan Schwartz <[email protected]>

Author: 4 people

.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.)
 

docs/specification.md

@@ -44,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
@@ -83,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
@@ -113,6 +123,9 @@ This is a geff metadata zattrs file that matches the above example structure.
             {'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",

geff-schema.json

@@ -152,6 +152,32 @@
           "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": [
             {

src/geff/metadata_schema.py

@@ -208,6 +208,43 @@ class GeffMetadata(BaseModel):
         "Each axis can additionally optionally define a `unit` key, which should match the valid"
         "OME-Zarr units, and `min` and `max` keys to define the range of the axis.",
     )
+    sphere: str | None = Field(
+        None,
+        title="Node property: Detections as spheres",
+        description=(
+            """
+            Name of the optional `sphere` property.
+
+            A sphere is defined by
+            - a center point, already given by the `space` type properties
+            - a radius scalar, stored in this property
+            """
+        ),
+    )
+    ellipsoid: str | None = Field(
+        None,
+        title="Node property: Detections as ellipsoids",
+        description=(
+            """
+            Name of the `ellipsoid` property.
+
+            An ellipsoid is assumed to be in the same coordinate system as the `space` type
+            properties.
+
+            It is defined by
+            - a center point :math:`c`, already given by the `space` type properties
+            - a covariance matrix :math:`\\Sigma`, symmetric and positive-definite, stored in this
+              property as a `2x2`/`3x3` array.
+
+            To plot the ellipsoid:
+            - Compute the eigendecomposition of the covariance matrix
+            :math:`\\Sigma = Q \\Lambda Q^{\\top}`
+            - Sample points :math:`z` on the unit sphere
+            - Transform the points to the ellipsoid by
+            :math:`x = c + Q \\Lambda^{(1/2)} z`.
+            """
+        ),
+    )
     track_node_props: dict[Literal["lineage", "tracklet"], str] | None = Field(
         None,
         description=(