napari_layers_to_ds#

movement.napari.convert.napari_layers_to_ds(points_as_napari, properties, properties_with_nans, attrs=None)[source]#

Convert napari Points layer data to a movement dataset.

Parameters:

  • points_as_napari (ndarray) – Live napari Points layer data, shape (N, 3): (frame_idx, y, x). NaN rows are excluded (napari cannot handle NaN coordinates), so this may be shorter than the full timeline.

  • properties (dict) – Live napari Point properties data. It is in-sync with the Points layer data. It is a dictionary with keys individual, keypoint, time and confidence, each mapping to a list of values, and each value corresponding to a point.

  • properties_with_nans (DataFrame) – Properties DataFrame derived from the original loaded dataset including any NaN position data.

  • attrs (dict | None) – Attributes of the original loaded dataset (e.g. source_software, fps, time_unit and source_file).

Returns:

movement dataset derived from the napari Points layer, containing pose tracks, confidence scores, and associated metadata.

Return type:

Dataset

Raises:

NotImplementedError – If the napari Points layer data does not represent a pose dataset.

See also

ds_to_napari_layers

The function carrying out the inverse conversion.

Notes

The dataset type is inferred from the presence of keypoint in properties. If present, a poses dataset is returned. Currently, bounding box datasets are not supported.

ds_to_napari_layers() returns a Tracks array of shape (N, 4) with columns (track_id, frame, y, x). When loading into napari, the DataLoader widget derives a Points layer from this Tracks array by dropping the track_id column, giving a (N, 3) array of (frame, y, x). The Points layer is considered the “source of truth”, as it immediately reflects any manipulation of the data done in the napari UI. The function napari_layers_to_ds() therefore relies on the Points layer data as one of its inputs, and uses it to reconstruct the corresponding dataset.

ds_to_napari_layers() preserves NaN values in the output arrays, but napari cannot handle NaN coordinates, so the DataLoader widget filters them out upon creation of the napari layers. As a result, when reconstructing a dataset via napari_layers_to_ds(), the input arrays will have no NaN (i.e. missing) coordinates. This function reconstructs the full dataset by restoring missing points using the full coordinate structure from properties_with_nans