funtracks.utils.tracksdata_utils

add_masks_and_bboxes_to_graph

add_masks_and_bboxes_to_graph(
    graph: GraphView, segmentation: ndarray
) -> td.graph.GraphView

Add mask and bbox attributes to graph nodes from segmentation.

Parameters

graph : td.graph.GraphView Graph to add attributes to segmentation : np.ndarray Segmentation array of shape (T, Z, Y, X) or (T, Y, X)

Returns

td.graph.GraphView Graph with 'mask' and 'bbox' attributes added to nodes

assert_node_attrs_equal_with_masks

assert_node_attrs_equal_with_masks(
    object1,
    object2,
    check_column_order: bool = False,
    check_row_order: bool = False,
)

Fully compare the content of two graphs (node attributes and Masks)

convert_graph_nx_to_td

convert_graph_nx_to_td(
    graph_nx: DiGraph,
) -> td.graph.GraphView

Convert a NetworkX DiGraph to a tracksdata graph.

Parameters:

Name	Type	Description	Default
`graph_nx`	`DiGraph`	The NetworkX DiGraph to convert.	required

Returns:

Type	Description
`GraphView`	A tracksdata graph representing the same graph.

create_empty_graphview_graph

create_empty_graphview_graph(
    node_attributes: list[str] | None = None,
    edge_attributes: list[str] | None = None,
    node_default_values: list[Any] | None = None,
    edge_default_values: list[Any] | None = None,
    database: str | None = None,
    position_attrs: list[str] | None = None,
    ndim: int = 3,
) -> td.graph.GraphView

Create an empty tracksdata GraphView with standard node and edge attributes. Parameters

node_attributes : list[str] | None List of node attribute names to include. (providing time attribute not necessary) edge_attributes : list[str] | None List of edge attribute names to include. node_default_values : list[Any] | None List of default values for each node attribute. Must match length of node_attributes. edge_default_values : list[Any] | None List of default values for each edge attribute. Must match length of edge_attributes. database : str | None Path to the SQLite database file. If None, creates a unique temporary file. Use ':memory:' for in-memory database (may cause issues with pickling in pytest). position_attrs : list[str] | None List of position attribute names, e.g. ['pos'] or ['x', 'y', 'z']. Defaults to ['pos'] if None. ndim : int Number of dimensions including time, so 2D+T dataset has ndim = 3. Defaults to 3 (2D+time).

Returns

td.graph.GraphView An empty tracksdata GraphView with standard node and edge attributes.

pixels_to_td_mask

pixels_to_td_mask(
    pix: tuple[ndarray, ...],
    ndim: int,
    scale: list[float] | None = None,
    include_area: bool = False,
) -> Mask | tuple[Mask, float]

Convert pixel coordinates to tracksdata mask format.

Parameters:

Name	Type	Description	Default
`pix`	`tuple[ndarray, ...]`	Pixel coordinates for 1 node!	required
`ndim`	`int`	Number of dimensions (2D or 3D).	required
`scale`	`list[float] \| None`	Scale factors for each dimension, used for area calculation	`None`
`include_area`	`bool`	Whether to compute and return the area.	`False`

Returns:

Type	Description
`Mask \| tuple[Mask, float]`	Mask \| tuple[Mask, float]: A tuple containing the tracksdata mask and the area if include_area is True. Otherwise, just the tracksdata mask.

segmentation_to_masks

segmentation_to_masks(
    segmentation: ndarray,
) -> list[tuple[int, int, Mask]]

Convert a segmentation array to individual masks and bounding boxes.

Parameters

segmentation : np.ndarray Segmentation array of shape (T, Z, Y, X) or (T, Y, X) Each unique value represents a different segment/object.

Returns

list[tuple[int, int, Mask]] List of tuples, one per segment, containing: - label (int): original label ID - time (int): time point - mask (Mask): tracksdata Mask object with boolean mask and bbox

td_mask_to_pixels

td_mask_to_pixels(
    mask: Mask, time: int, ndim: int
) -> tuple[np.ndarray, ...]

Convert tracksdata mask to pixel coordinates.

This is the inverse of pixels_to_td_mask.

Parameters:

Name	Type	Description	Default
`mask`	`Mask`	Tracksdata Mask object with .mask (boolean array) and .bbox attributes	required
`time`	`int`	Time point for this mask	required
`ndim`	`int`	Number of dimensions (3 for 2D+time, 4 for 3D+time)	required

Returns:

Type	Description
`ndarray`	Tuple of numpy arrays: (time_array, *spatial_coords)
`...`	For 2D: (t, y, x) where each is a 1D array of pixel coordinates
`tuple[ndarray, ...]`	For 3D: (t, z, y, x) where each is a 1D array of pixel coordinates

Example

mask = Mask(np.array([[True, False], [False, True]]), ... bbox=np.array([10, 20, 12, 22])) pixels = td_mask_to_pixels(mask, time=5, ndim=3)

Returns: (array([5, 5]), array([10, 11]), array([20, 21]))

td_relabel_nodes

td_relabel_nodes(
    graph, mapping: dict[int, int]
) -> td.graph.IndexedRXGraph

Relabel nodes in a tracksdata graph according to a mapping.

Parameters:

Name	Type	Description	Default
`graph`		A tracksdata graph	required
`mapping`	`dict[int, int]`	Dictionary mapping old node IDs to new node IDs	required

Returns:

Type	Description
`IndexedRXGraph`	A new tracksdata graph with relabeled nodes

to_polars_dtype

to_polars_dtype(dtype_or_value: str | Any) -> pl.DataType

Convert a type string or value to polars dtype.

Parameters:

Name	Type	Description	Default
`dtype_or_value`	`str \| Any`	Either a type string ("int", "float", "str", "bool") or a value whose type should be inferred	required

Returns:

Type	Description
`DataType`	Corresponding polars dtype

Raises:

Type	Description
`ValueError`	If the type is not supported

Examples:

>>> to_polars_dtype("int")
Int64
>>> to_polars_dtype(5)
Int64
>>> to_polars_dtype(np.int64(5))
Int64
>>> to_polars_dtype("")  # String value
String