Mask as a struct attribute.

pyproject.toml

@@ -60,10 +60,15 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-spatial = ["spatial-graph"]
+# witty 0.3.2 changed `source_files` from "files to watch for cache
+# invalidation" to "files to compile and link". spatial-graph still lists its
+# .h headers there, so building its C extensions fails with
+# `UnknownFileType: unknown file type '.h'`. Allow a future fixed release.
+spatial = ["spatial-graph", "witty!=0.3.2"]
 motile = ["motile"]
 test = [
   "spatial-graph",
+  "witty!=0.3.2",
   "motile",
   "pytest>=7.0",
   "pytest-cov",
@@ -129,6 +134,9 @@ select = [
 
 # https://docs.astral.sh/ruff/formatter/
 [tool.ruff.format]
+# ruff >= 0.16 formats markdown code blocks, which rewrites the mkdocs
+# snippet directives (`--8<-- "..."`) in docs/ into invalid syntax.
+exclude = ["*.md"]
 docstring-code-format = true
 skip-magic-trailing-comma = false # default is false
 

src/tracksdata/array/_graph_array.py

@@ -1,6 +1,6 @@
 from collections.abc import Sequence
 from copy import copy
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
 import numpy as np
 
@@ -11,9 +11,6 @@
 from tracksdata.options import get_options
 from tracksdata.utils._dtypes import polars_dtype_to_numpy_dtype
 
-if TYPE_CHECKING:
-    from tracksdata.nodes._mask import Mask
-
 
 def _validate_shape(
     shape: tuple[int, ...] | None,
@@ -346,14 +343,19 @@ def _fill_array(self, time: int, volume_slicing: Sequence[slice], buffer: np.nda
         np.ndarray
             The filled buffer.
         """
+        # Local import: avoids the graph <-> nodes package import cycle (importing
+        # tracksdata.nodes re-enters the partially-initialized graph package).
+        from tracksdata.nodes._mask import mask_paint_buffer, masks_from_column
+
         subgraph = self._spatial_filter[(slice(time, time), *volume_slicing)]
         df = subgraph.node_attrs(
             attr_keys=[self._attr_key, DEFAULT_ATTR_KEYS.MASK],
         )
 
-        for mask, value in zip(df[DEFAULT_ATTR_KEYS.MASK], df[self._attr_key], strict=True):
-            mask: Mask
-            mask.paint_buffer(buffer, value, offset=self._offset)
+        masks = masks_from_column(df[DEFAULT_ATTR_KEYS.MASK])
+
+        for mask, value in zip(masks, df[self._attr_key], strict=True):
+            mask_paint_buffer(mask, buffer, value, offset=self._offset)
 
     def _offset_as_array(self, ndim: int) -> np.ndarray:
         """Normalize `offset` to a vector for each spatial axis."""
@@ -489,4 +491,7 @@ def _mask_changed(old_attr: dict, new_attr: dict) -> bool:
             return False
         elif old_mask is None or new_mask is None:
             return True
+
+        # `Mask` compares by value; struct values are dicts of scalars plus the
+        # compressed blob, which also compare directly.
         return old_mask != new_mask

src/tracksdata/array/_test/test_graph_array.py

@@ -86,7 +86,7 @@ def test_graph_array_view_getitem_with_nodes(graph_backend: BaseGraph) -> None:
 
     # Create a mask
     mask_data = np.array([[True, True], [True, False]], dtype=bool)
-    mask = Mask(mask_data, bbox=np.array([10, 20, 12, 22]))  # y_min, x_min, y_max, x_max
+    mask = Mask(bbox=np.array([10, 20, 12, 22]), mask=mask_data)  # y_min, x_min, y_max, x_max
 
     # Add a node with mask and label
     graph_backend.add_node(
@@ -136,10 +136,10 @@ def test_graph_array_view_getitem_multiple_nodes(graph_backend: BaseGraph) -> No
 
     # Create two masks at different locations
     mask1_data = np.array([[True, True]], dtype=bool)
-    mask1 = Mask(mask1_data, bbox=np.array([10, 20, 11, 22]))
+    mask1 = Mask(bbox=np.array([10, 20, 11, 22]), mask=mask1_data)
 
     mask2_data = np.array([[True]], dtype=bool)
-    mask2 = Mask(mask2_data, bbox=np.array([30, 40, 31, 41]))
+    mask2 = Mask(bbox=np.array([30, 40, 31, 41]), mask=mask2_data)
 
     # Add nodes with different labels
     graph_backend.add_node(
@@ -191,7 +191,7 @@ def test_graph_array_view_getitem_boolean_dtype(graph_backend: BaseGraph) -> Non
 
     # Create a mask
     mask_data = np.array([[True]], dtype=bool)
-    mask = Mask(mask_data, bbox=np.array([10, 20, 11, 21]))
+    mask = Mask(bbox=np.array([10, 20, 11, 21]), mask=mask_data)
 
     # Add a node with boolean attribute
     graph_backend.add_node(
@@ -228,7 +228,7 @@ def test_graph_array_view_dtype_inference(graph_backend: BaseGraph) -> None:
 
     # Create a mask
     mask_data = np.array([[True]], dtype=bool)
-    mask = Mask(mask_data, bbox=np.array([10, 20, 11, 21]))
+    mask = Mask(bbox=np.array([10, 20, 11, 21]), mask=mask_data)
 
     # Add a node with float attribute
     graph_backend.add_node(
@@ -407,7 +407,7 @@ def test_graph_array_raise_error_on_non_scalar_attr_key(graph_backend: BaseGraph
         {
             DEFAULT_ATTR_KEYS.T: 0,
             "label": np.array([1, 2]),  # Non-scalar value
-            DEFAULT_ATTR_KEYS.MASK: Mask(np.array([[True]], dtype=bool), bbox=np.array([0, 0, 1, 1])),
+            DEFAULT_ATTR_KEYS.MASK: Mask(bbox=np.array([0, 0, 1, 1]), mask=np.array([[True]], dtype=bool)),
         }
     )
 
@@ -422,7 +422,7 @@ def _add_graph_array_node_attrs(graph_backend: BaseGraph) -> None:
 
 
 def _make_square_mask(y: int, x: int, size: int = 2) -> Mask:
-    return Mask(np.ones((size, size), dtype=bool), bbox=np.array([y, x, y + size, x + size]))
+    return Mask(bbox=np.array([y, x, y + size, x + size]), mask=np.ones((size, size), dtype=bool))
 
 
 def test_graph_array_view_invalidates_only_affected_chunk_on_add(graph_backend: BaseGraph) -> None:
@@ -695,7 +695,7 @@ def test_graph_array_view_invalidates_once_when_mask_changes_but_bbox_unchanged(
     np.testing.assert_array_equal(array_view._cache._store[0].ready, np.ones((2, 2), dtype=bool))
 
     # Same bbox [1, 1, 3, 3], but only the diagonal pixels are set.
-    new_mask = Mask(np.array([[True, False], [False, True]], dtype=bool), bbox=np.array([1, 1, 3, 3]))
+    new_mask = Mask(bbox=np.array([1, 1, 3, 3]), mask=np.array([[True, False], [False, True]], dtype=bool))
     mock_invalidate = MagicMock(wraps=array_view._invalidate_bbox)
     with patch.object(array_view, "_invalidate_bbox", mock_invalidate):
         graph_backend.update_node_attrs(
@@ -737,7 +737,7 @@ def test_graph_array_view_no_invalidation_when_mask_unchanged(graph_backend: Bas
     np.testing.assert_array_equal(array_view._cache._store[0].ready, np.ones((2, 2), dtype=bool))
 
     # A fresh Mask object with identical bbox and pixels: no rendered change.
-    same_mask = Mask(np.ones((2, 2), dtype=bool), bbox=np.array([1, 1, 3, 3]))
+    same_mask = Mask(bbox=np.array([1, 1, 3, 3]), mask=np.ones((2, 2), dtype=bool))
     mock_invalidate = MagicMock(wraps=array_view._invalidate_bbox)
     with patch.object(array_view, "_invalidate_bbox", mock_invalidate):
         graph_backend.update_node_attrs(

src/tracksdata/edges/_iou_edges.py

@@ -1,6 +1,13 @@
+from typing import Any
+
 from tracksdata.constants import DEFAULT_ATTR_KEYS
 from tracksdata.edges._generic_edges import GenericFuncEdgeAttrs
-from tracksdata.nodes._mask import Mask
+from tracksdata.nodes._mask import Mask, _decode_mask, mask_iou
+
+
+def _mask_iou(source_mask: "Mask | dict[str, Any]", target_mask: "Mask | dict[str, Any]") -> float:
+    """IoU between two mask attribute values (struct dicts or `Mask` values)."""
+    return mask_iou(_decode_mask(source_mask), _decode_mask(target_mask))
 
 
 class IoUEdgeAttr(GenericFuncEdgeAttrs):
@@ -22,7 +29,7 @@ def __init__(
         mask_key: str = DEFAULT_ATTR_KEYS.MASK,
     ):
         super().__init__(
-            func=Mask.iou,
+            func=_mask_iou,
             attr_keys=mask_key,
             output_key=output_key,
         )

src/tracksdata/edges/_test/test_iou_edges.py

@@ -4,6 +4,7 @@
 
 from tracksdata.constants import DEFAULT_ATTR_KEYS
 from tracksdata.edges import IoUEdgeAttr
+from tracksdata.edges._iou_edges import _mask_iou
 from tracksdata.graph import RustWorkXGraph
 from tracksdata.nodes import Mask
 from tracksdata.options import get_options, options_context
@@ -15,7 +16,7 @@ def test_iou_edges_init_default() -> None:
 
     assert operator.output_key == "iou_score"
     assert operator.attr_keys == DEFAULT_ATTR_KEYS.MASK
-    assert operator.func == Mask.iou
+    assert operator.func == _mask_iou
 
 
 def test_iou_edges_init_custom() -> None:
@@ -24,7 +25,7 @@ def test_iou_edges_init_custom() -> None:
 
     assert operator.output_key == "custom_iou"
     assert operator.attr_keys == "custom_mask"
-    assert operator.func == Mask.iou
+    assert operator.func == _mask_iou
 
 
 @pytest.mark.parametrize("n_workers", [1, 2])
@@ -38,13 +39,13 @@ def test_iou_edges_add_weights(n_workers: int) -> None:
 
     # Create test masks
     mask1_data = np.array([[True, True], [True, False]], dtype=bool)
-    mask1 = Mask(mask1_data, bbox=np.array([0, 0, 2, 2]))
+    mask1 = Mask(bbox=np.array([0, 0, 2, 2]), mask=mask1_data)
 
     mask2_data = np.array([[True, False], [False, False]], dtype=bool)
-    mask2 = Mask(mask2_data, bbox=np.array([0, 0, 2, 2]))
+    mask2 = Mask(bbox=np.array([0, 0, 2, 2]), mask=mask2_data)
 
     mask3_data = np.array([[True, True], [True, True]], dtype=bool)
-    mask3 = Mask(mask3_data, bbox=np.array([0, 0, 2, 2]))
+    mask3 = Mask(bbox=np.array([0, 0, 2, 2]), mask=mask3_data)
 
     # Add nodes with masks
     node1 = graph.add_node({DEFAULT_ATTR_KEYS.T: 0, DEFAULT_ATTR_KEYS.MASK: mask1})
@@ -88,10 +89,10 @@ def test_iou_edges_no_overlap() -> None:
 
     # Create non-overlapping masks
     mask1_data = np.array([[True, True], [False, False]], dtype=bool)
-    mask1 = Mask(mask1_data, bbox=np.array([0, 0, 2, 2]))
+    mask1 = Mask(bbox=np.array([0, 0, 2, 2]), mask=mask1_data)
 
     mask2_data = np.array([[False, False], [True, True]], dtype=bool)
-    mask2 = Mask(mask2_data, bbox=np.array([0, 0, 2, 2]))
+    mask2 = Mask(bbox=np.array([0, 0, 2, 2]), mask=mask2_data)
 
     # Add nodes with masks
     node1 = graph.add_node({DEFAULT_ATTR_KEYS.T: 0, DEFAULT_ATTR_KEYS.MASK: mask1})
@@ -127,8 +128,8 @@ def test_iou_edges_perfect_overlap() -> None:
 
     # Create identical masks
     mask_data = np.array([[True, True], [True, False]], dtype=bool)
-    mask1 = Mask(mask_data, bbox=np.array([0, 0, 2, 2]))
-    mask2 = Mask(mask_data, bbox=np.array([0, 0, 2, 2]))
+    mask1 = Mask(bbox=np.array([0, 0, 2, 2]), mask=mask_data)
+    mask2 = Mask(bbox=np.array([0, 0, 2, 2]), mask=mask_data)
 
     # Add nodes with masks
     node1 = graph.add_node({DEFAULT_ATTR_KEYS.T: 0, DEFAULT_ATTR_KEYS.MASK: mask1})
@@ -163,10 +164,10 @@ def test_iou_edges_custom_mask_key() -> None:
 
     # Create test masks
     mask1_data = np.array([[True, True], [True, True]], dtype=bool)
-    mask1 = Mask(mask1_data, bbox=np.array([0, 0, 2, 2]))
+    mask1 = Mask(bbox=np.array([0, 0, 2, 2]), mask=mask1_data)
 
     mask2_data = np.array([[True, True], [False, False]], dtype=bool)
-    mask2 = Mask(mask2_data, bbox=np.array([0, 0, 2, 2]))
+    mask2 = Mask(bbox=np.array([0, 0, 2, 2]), mask=mask2_data)
 
     # Add nodes with custom mask key
     node1 = graph.add_node({DEFAULT_ATTR_KEYS.T: 0, "custom_mask": mask1})

src/tracksdata/functional/_test/test_division.py

@@ -635,10 +635,10 @@ def _make_graph_with_mask() -> tuple[td.graph.RustWorkXGraph, dict[str, int]]:
     g = td.graph.RustWorkXGraph()
     g.add_node_attr_key(DEFAULT_ATTR_KEYS.MASK, pl.Object)
 
-    mask_p = Mask(np.ones((4, 4), dtype=bool), bbox=np.array([0, 0, 4, 4]))
-    mask_d = Mask(np.ones((4, 4), dtype=bool), bbox=np.array([0, 0, 4, 4]))
-    mask_c1 = Mask(np.ones((2, 2), dtype=bool), bbox=np.array([0, 0, 2, 2]))
-    mask_c2 = Mask(np.ones((2, 2), dtype=bool), bbox=np.array([2, 2, 4, 4]))
+    mask_p = Mask(bbox=np.array([0, 0, 4, 4]), mask=np.ones((4, 4), dtype=bool))
+    mask_d = Mask(bbox=np.array([0, 0, 4, 4]), mask=np.ones((4, 4), dtype=bool))
+    mask_c1 = Mask(bbox=np.array([0, 0, 2, 2]), mask=np.ones((2, 2), dtype=bool))
+    mask_c2 = Mask(bbox=np.array([2, 2, 4, 4]), mask=np.ones((2, 2), dtype=bool))
 
     ids: dict[str, int] = {}
     ids["p"] = g.add_node({"t": 0, DEFAULT_ATTR_KEYS.MASK: mask_p})

src/tracksdata/functional/_test/test_napari.py

@@ -5,7 +5,7 @@
 from tracksdata.constants import DEFAULT_ATTR_KEYS
 from tracksdata.functional import to_napari_format
 from tracksdata.graph import RustWorkXGraph
-from tracksdata.nodes import MaskDiskAttrs
+from tracksdata.nodes import MaskDiskAttrs, masks_from_column
 
 
 @pytest.mark.parametrize("metadata_shape", [True, False])
@@ -45,7 +45,7 @@ def test_napari_conversion(metadata_shape: bool) -> None:
 
     # Maybe we should update the MaskDiskAttrs to handle bounding boxes
     graph.add_node_attr_key(DEFAULT_ATTR_KEYS.BBOX, dtype=pl.Array(pl.Int64, 6))
-    masks = graph.node_attrs(attr_keys=[DEFAULT_ATTR_KEYS.MASK])[DEFAULT_ATTR_KEYS.MASK]
+    masks = masks_from_column(graph.node_attrs(attr_keys=[DEFAULT_ATTR_KEYS.MASK])[DEFAULT_ATTR_KEYS.MASK])
     graph.update_node_attrs(
         attrs={DEFAULT_ATTR_KEYS.BBOX: [mask.bbox for mask in masks]},
         node_ids=graph.node_ids(),

src/tracksdata/graph/_base_graph.py

@@ -1378,16 +1378,19 @@ def compute_overlaps(self, iou_threshold: float = 0.0) -> None:
             raise ValueError("iou_threshold must be between 0.0 and 1.0")
 
         def _estimate_overlaps(t: int) -> list[list[int, 2]]:
+            # Local import: avoids the graph <-> nodes package import cycle.
+            from tracksdata.nodes._mask import mask_iou, masks_from_column
+
             node_attrs = self.filter(NodeAttr(DEFAULT_ATTR_KEYS.T) == t).node_attrs(
                 attr_keys=[DEFAULT_ATTR_KEYS.NODE_ID, DEFAULT_ATTR_KEYS.MASK],
             )
             node_ids = node_attrs[DEFAULT_ATTR_KEYS.NODE_ID].to_list()
-            masks = node_attrs[DEFAULT_ATTR_KEYS.MASK].to_list()
+            masks = masks_from_column(node_attrs[DEFAULT_ATTR_KEYS.MASK])
             overlaps = []
             for i in range(len(masks)):
                 mask_i = masks[i]
                 for j in range(i + 1, len(masks)):
-                    if mask_i.iou(masks[j]) > iou_threshold:
+                    if mask_iou(mask_i, masks[j]) > iou_threshold:
                         overlaps.append([node_ids[i], node_ids[j]])
             return overlaps
 
@@ -1840,8 +1843,8 @@ def from_geff(
             # unsafe operation, changing graph content inplace
             for node_attr in indexed_graph.rx_graph.nodes():
                 node_attr[DEFAULT_ATTR_KEYS.MASK] = Mask(
-                    node_attr[DEFAULT_ATTR_KEYS.MASK].astype(bool),
-                    bbox=node_attr[DEFAULT_ATTR_KEYS.BBOX],
+                    bbox=np.asarray(node_attr[DEFAULT_ATTR_KEYS.BBOX], dtype=np.int64),
+                    mask=node_attr[DEFAULT_ATTR_KEYS.MASK].astype(bool),
                 )
 
         if cls == IndexedRXGraph:
@@ -1939,8 +1942,11 @@ def to_geff(
         }
 
         if DEFAULT_ATTR_KEYS.MASK in node_attrs.columns:
+            # Local import: avoids the graph <-> nodes package import cycle.
+            from tracksdata.nodes._mask import masks_from_column
+
             node_dict[DEFAULT_ATTR_KEYS.MASK] = construct_var_len_props(
-                [mask.mask.astype(bool) for mask in node_attrs[DEFAULT_ATTR_KEYS.MASK]]
+                [mask.mask.astype(bool) for mask in masks_from_column(node_attrs[DEFAULT_ATTR_KEYS.MASK])]
             )
 
         edge_dict = {k: {"values": column_to_numpy(v), "missing": None} for k, v in edge_attrs.to_dict().items()}

src/tracksdata/graph/_rustworkx_graph.py

@@ -66,7 +66,10 @@ def _pop_time_eq(
 def _maybe_fill_null(s: pl.Series, schema: AttrSchema) -> pl.Series:
     if s.has_nulls() and schema.default_value is not None:
         if schema.dtype == pl.Object:
-            value = pl.lit(schema.default_value, allow_object=True)
+            # `pl.lit` infers a struct from a dict default (e.g. a `Mask`), which then
+            # has no supertype with the object column. Wrapping in an object-typed
+            # series forces the literal to stay an object.
+            value = pl.lit(pl.Series([schema.default_value], dtype=pl.Object)).first()
         elif isinstance(schema.dtype, pl.Array):
             if isinstance(schema.default_value, np.ndarray):
                 value = schema.default_value.tolist()