V2 dev

.gitignore

@@ -96,3 +96,4 @@ uv.lock
 
 # Claude
 CLAUDE.md
+.claude/

docs/features.md

@@ -92,7 +92,6 @@ classDiagram
         +value_type: Literal
         +num_values: int
         +display_name: str|Sequence
-        +required: bool
         +default_value: Any
     }
 
@@ -150,7 +149,7 @@ classDiagram
     }
 
     class Tracks {
-        +graph: nx.DiGraph
+        +graph: td.graph.GraphView
         +segmentation: ndarray|None
         +features: FeatureDict
         +annotators: AnnotatorRegistry
@@ -203,32 +202,40 @@ These features are **automatically checked** during initialization:
 
 **Scenario 1: Loading tracks from CSV with pre-computed features**
 ```python
-# CSV has columns: id, time, y, x, area, track_id
-graph = load_graph_from_csv(df)  # Nodes already have area, track_id
-tracks = SolutionTracks(graph, segmentation=seg)
+from funtracks.import_export import tracks_from_df
+
+# CSV/DataFrame has columns: id, time, y, x, area, track_id, parent_id
+tracks = tracks_from_df(df, segmentation=seg)
 # Auto-detection: pos, area, track_id exist → activate without recomputing
 ```
 
 **Scenario 2: Creating tracks from raw segmentation**
 ```python
-# Graph has no features yet
-graph = nx.DiGraph()
-graph.add_node(1, time=0)
+from funtracks.utils import create_empty_graphview_graph
+from funtracks.data_model import Tracks
+
+# Create empty graph and add nodes
+graph = create_empty_graphview_graph()
+graph.add_node(index=1, attrs={"t": 0})
 tracks = Tracks(graph, segmentation=seg)
-# Auto-detection: pos, area don't exist → compute them
+# Auto-detection: pos, area don't exist → compute them from segmentation
 ```
 
 **Scenario 3: Explicit feature control with FeatureDict**
 ```python
+from funtracks.features import FeatureDict, Time, Position, Area
+from funtracks.data_model import Tracks
+
 # Bypass auto-detection entirely
 feature_dict = FeatureDict({"t": Time(), "pos": Position(), "area": Area()})
 tracks = Tracks(graph, segmentation=seg, features=feature_dict)
 # All features in feature_dict are activated, none are computed
 ```
 
 **Scenario 4: Enable a new feature**
-
 ```python
+from funtracks.data_model import Tracks
+
 tracks = Tracks(graph, segmentation)
 # Initially has: time, pos, area (auto-detected or computed)
 
@@ -240,8 +247,7 @@ print(tracks.features.keys())  # All features in FeatureDict (including static)
 print(tracks.annotators.features.keys())  # Only active computed features
 ```
 
-**Scenario 4: Disable a feature**
-
+**Scenario 5: Disable a feature**
 ```python
 tracks.disable_features(["area"])
 # Removes from FeatureDict, deactivates in annotators
@@ -272,9 +278,9 @@ tracks.disable_features(["area"])
         def compute(self, feature_keys=None):
             # Compute feature values in bulk
             if "custom" in self.features:
-                for node in self.tracks.graph.nodes():
+                for node in self.tracks.graph.node_ids():
                     value = self._compute_custom(node)
-                    self.tracks.graph.nodes[node]["custom"] = value
+                    self.tracks[node]["custom"] = value
 
         def update(self, action):
             # Incremental update when graph changes

pyproject.toml

@@ -39,6 +39,8 @@ dependencies =[
     "pandas>=2.3.3",
     "zarr>=2.18,<4",
     "numcodecs>=0.13,<0.16",
+    #TODO Teun: replace after release
+    "tracksdata[spatial] @ git+https://github.com/royerlab/tracksdata@3efb92a66b39e597c498e1f88077911c206427f2",
     "tqdm>=4.66.1",
 ]
 

src/funtracks/actions/add_delete_edge.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from ._base import BasicAction
 
@@ -10,6 +10,8 @@
     from funtracks.data_model import Tracks
     from funtracks.data_model.tracks import Edge
 
+import tracksdata as td
+
 
 class AddEdge(BasicAction):
     """Action for adding a new edge. Endpoints must exist already."""
@@ -52,7 +54,24 @@ def _apply(self) -> None:
                     f"Cannot add edge {self.edge}: endpoint {node} not in graph yet"
                 )
 
-        self.tracks.graph.add_edge(self.edge[0], self.edge[1], **self.attributes)
+        if self.tracks.graph.has_edge(*self.edge):
+            raise ValueError(f"Edge {self.edge} already exists in the graph")
+
+        # Add required solution attribute
+        attrs = dict(self.attributes)
+        attrs[td.DEFAULT_ATTR_KEYS.SOLUTION] = 1
+
+        schemas = self.tracks.graph._edge_attr_schemas()
+        for attr in self.tracks.graph.edge_attr_keys():
+            if attr not in attrs:
+                attrs[attr] = schemas[attr].default_value
+
+        # Create edge attributes for this specific edge
+        self.tracks.graph.add_edge(
+            source_id=self.edge[0],
+            target_id=self.edge[1],
+            attrs=attrs,
+        )
 
         # Notify annotators to recompute features (will overwrite computed ones)
         self.tracks.notify_annotators(self)

src/funtracks/actions/add_delete_node.py

@@ -7,13 +7,16 @@
 if TYPE_CHECKING:
     from typing import Any
 
-    from funtracks.data_model import SolutionTracks
-    from funtracks.data_model.tracks import Node, SegMask
+    from funtracks.data_model.solution_tracks import SolutionTracks
+    from funtracks.data_model.tracks import Node
+
+import tracksdata as td
+from tracksdata.nodes._mask import Mask
 
 
 class AddNode(BasicAction):
     """Action for adding new nodes. If a segmentation should also be added, the
-    pixels for each node should be provided. The label to set the pixels will
+    mask for the node should be provided. The label to set the mask will
     be taken from the node id. The existing pixel values are assumed to be
     zero - you must explicitly update any other segmentations that were overwritten
     using an UpdateNodes action if you want to be able to undo the action.
@@ -24,20 +27,20 @@ def __init__(
         tracks: SolutionTracks,
         node: Node,
         attributes: dict[str, Any],
-        pixels: SegMask | None = None,
+        mask: Mask | None = None,
     ):
         """Create an action to add a new node, with optional segmentation
 
         Args:
             tracks (Tracks): The Tracks to add the node to
             node (Node): A node id
             attributes (Attrs): Includes times, track_ids, and optionally positions
-            pixels (SegMask | None, optional): The segmentation associated with
+            mask (Mask | None, optional): The segmentation mask associated with
                 the node. Defaults to None.
         Raises:
             ValueError: If time attribute is not in attributes.
             ValueError: If track_id is not in attributes.
-            ValueError: If pixels is None and position is not in attributes.
+            ValueError: If mask is None and position is not in attributes.
         """
         super().__init__(tracks)
         self.tracks: SolutionTracks  # Narrow type from base class
@@ -55,7 +58,7 @@ def __init__(
             raise ValueError(f"Must provide a {track_id_key} attribute for node {node}")
 
         # Check for position - handle both single key and list of keys
-        if pixels is None:
+        if mask is None:
             if isinstance(pos_key, list):
                 # Multi-axis position keys
                 if not all(key in attributes for key in pos_key):
@@ -68,7 +71,7 @@ def __init__(
                     raise ValueError(
                         f"Must provide position or segmentation for node {node}"
                     )
-        self.pixels = pixels
+        self.mask = mask
         self.attributes = attributes
         self._apply()
 
@@ -77,31 +80,35 @@ def inverse(self) -> BasicAction:
         return DeleteNode(self.tracks, self.node)
 
     def _apply(self) -> None:
-        """Apply the action, and set segmentation if provided in self.pixels"""
-        if self.pixels is not None:
-            self.tracks.set_pixels(self.pixels, self.node)
-        attrs = self.attributes
-        self.tracks.graph.add_node(self.node)
+        """Apply the action, and set segmentation if provided in self.mask"""
+        attrs = dict(self.attributes)
+
+        if self.tracks.segmentation is not None and self.mask is not None:
+            attrs[td.DEFAULT_ATTR_KEYS.MASK] = self.mask
+            attrs[td.DEFAULT_ATTR_KEYS.BBOX] = self.mask.bbox
 
-        # set all user provided attributes including time and position
-        for attr, value in attrs.items():
-            self.tracks._set_node_attr(self.node, attr, value)
+        self.tracks.graph.add_node(attrs=attrs, index=self.node, validate_keys=False)
+
+        # Invalidate cache for the new node's region so the GraphArrayView reflects it
+        if self.tracks.segmentation is not None and self.mask is not None:
+            time = self.tracks.get_time(self.node)
+            self.tracks._update_segmentation_cache(mask=self.mask, time=time)
 
         # Always notify annotators - they will check their own preconditions
         self.tracks.notify_annotators(self)
 
 
 class DeleteNode(BasicAction):
-    """Action of deleting existing nodes
+    """Action of deleting existing node
     If the tracks contain a segmentation, this action also constructs a reversible
-    operation for setting involved pixels to zero
+    operation for setting involved masks to zero
     """
 
     def __init__(
         self,
         tracks: SolutionTracks,
         node: Node,
-        pixels: SegMask | None = None,
+        mask: Mask | None = None,
     ):
         super().__init__(tracks)
         self.tracks: SolutionTracks  # Narrow type from base class
@@ -114,24 +121,39 @@ def __init__(
             if val is not None:
                 self.attributes[key] = val
 
-        self.pixels = self.tracks.get_pixels(node) if pixels is None else pixels
+        if td.DEFAULT_ATTR_KEYS.MASK in self.tracks.graph.node_attr_keys():
+            self.attributes[td.DEFAULT_ATTR_KEYS.MASK] = self.tracks.get_nodes_attr(
+                [self.node], td.DEFAULT_ATTR_KEYS.MASK
+            )[0]
+            self.attributes[td.DEFAULT_ATTR_KEYS.BBOX] = self.tracks.get_nodes_attr(
+                [self.node], td.DEFAULT_ATTR_KEYS.BBOX
+            )[0]
+        self.attributes[td.DEFAULT_ATTR_KEYS.SOLUTION] = self.tracks.get_nodes_attr(
+            [self.node], td.DEFAULT_ATTR_KEYS.SOLUTION
+        )[0]
+
+        mask = self.tracks.get_mask(node) if mask is None else mask
+
+        self.mask = mask
         self._apply()
 
     def inverse(self) -> BasicAction:
         """Invert this action, and provide inverse segmentation operation if given"""
 
-        return AddNode(self.tracks, self.node, self.attributes, pixels=self.pixels)
+        return AddNode(self.tracks, self.node, self.attributes, mask=self.mask)
 
     def _apply(self) -> None:
         """ASSUMES THERE ARE NO INCIDENT EDGES - raises valueerror if an edge will be
         removed by this operation
         Steps:
-        - For each node
-            set pixels to 0 if self.pixels is provided
         - Remove nodes from graph
+        - Update annotators
         """
-        if self.pixels is not None:
-            self.tracks.set_pixels(self.pixels, 0)
-
         self.tracks.graph.remove_node(self.node)
+
+        # Invalidate cache for the deleted node's region so the GraphArrayView reflects it
+        if self.tracks.segmentation is not None and self.mask is not None:
+            time = self.attributes[self.tracks.features.time_key]
+            self.tracks._update_segmentation_cache(mask=self.mask, time=time)
+
         self.tracks.notify_annotators(self)

src/funtracks/actions/update_segmentation.py

@@ -2,37 +2,40 @@
 
 from typing import TYPE_CHECKING
 
+import tracksdata as td
+from tracksdata.nodes._mask import Mask
+
 from ._base import BasicAction
 
 if TYPE_CHECKING:
     from funtracks.data_model import Tracks
-    from funtracks.data_model.tracks import Node, SegMask
+    from funtracks.data_model.tracks import Node
 
 
 class UpdateNodeSeg(BasicAction):
     """Action for updating the segmentation associated with a node.
 
-    New nodes call AddNode with pixels instead of this action.
+    New nodes call AddNode with mask instead of this action.
     """
 
     def __init__(
         self,
         tracks: Tracks,
         node: Node,
-        pixels: SegMask,
+        mask: Mask,
         added: bool = True,
     ):
         """
         Args:
-            tracks (Tracks): The tracks to update the segmenatations for
-            node (Node): The node with updated segmenatation
-            pixels (SegMask): The pixels that were updated for the node
-            added (bool, optional): If the provided pixels were added (True) or deleted
+            tracks (Tracks): The tracks to update the segmentations for
+            node (Node): The node with updated segmentation
+            mask (Mask): The mask that was updated for the node
+            added (bool, optional): If the provided mask were added (True) or deleted
                 (False) from this node. Defaults to True
         """
         super().__init__(tracks)
         self.node = node
-        self.pixels = pixels
+        self.mask = mask
         self.added = added
         self._apply()
 
@@ -41,12 +44,42 @@ def inverse(self) -> BasicAction:
         return UpdateNodeSeg(
             self.tracks,
             self.node,
-            pixels=self.pixels,
+            mask=self.mask,
             added=not self.added,
         )
 
     def _apply(self) -> None:
         """Set new attributes"""
         value = self.node if self.added else 0
-        self.tracks.set_pixels(self.pixels, value)
+
+        mask_new = self.mask
+
+        if value == 0:
+            # val=0 means deleting (part of) the mask
+            mask_old = self.tracks.graph.nodes[self.node][td.DEFAULT_ATTR_KEYS.MASK]
+            mask_subtracted = mask_old.__isub__(mask_new)
+            self.tracks.graph.update_node_attrs(
+                attrs={
+                    td.DEFAULT_ATTR_KEYS.MASK: [mask_subtracted],
+                    td.DEFAULT_ATTR_KEYS.BBOX: [mask_subtracted.bbox],
+                },
+                node_ids=[self.node],
+            )
+
+        elif self.tracks.graph.has_node(value):
+            # if node already exists:
+            mask_old = self.tracks.graph.nodes[value][td.DEFAULT_ATTR_KEYS.MASK]
+            mask_combined = mask_old.__or__(mask_new)
+            self.tracks.graph.update_node_attrs(
+                attrs={
+                    td.DEFAULT_ATTR_KEYS.MASK: [mask_combined],
+                    td.DEFAULT_ATTR_KEYS.BBOX: [mask_combined.bbox],
+                },
+                node_ids=[value],
+            )
+
+        # Invalidate cache for affected chunks
+        time = self.tracks.get_time(self.node)
+        self.tracks._update_segmentation_cache(mask=mask_new, time=time)
+
         self.tracks.notify_annotators(self)