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 (plus edited once any point has been dragged), 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. Must include a position_is_nan boolean column flagging any such points.

  • 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:

  • ValueError – If no keypoint or individual has any data left, i.e. all points have been removed from the dataset.

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

If a keypoint or individual has no remaining points in any frame, it is dropped from the returned dataset rather than kept as an all-NaN entry. The time dimension is never reduced in this way: a frame from which every point has been removed is kept, with NaN values for position and confidence.