NAPS Functions

sleap_utils.py: General helper functions for interfacing with SLEAP

naps.sleap_utils.get_location_matrix(labels: Labels, all_frames: bool, video: Optional[Video] = None) → Tuple[ndarray, List]

Builds numpy matrix with point location data. Note: This function assumes either all instances have tracks or no instances have tracks.

Parameters

• labels (sleap.Labels) – The sleap.Labels from which to get data.

• all_frames (bool) – If True, then includes zeros so that frame index will line up with columns in the output. Otherwise, there will only be columns for the frames between the first and last frames with labeling data.

• video (sleap.Video, optional) – The Video from which to get data. If no video is specified, then the first video in source_object videos list will be used. If there are no labeled frames in the video, then None will be returned. Defaults to None.

Returns

point location array with shape (frames, nodes, 2, tracks) List[str]: list of node names

Return type

Tuple[np.ndarray, List[str]]

naps.sleap_utils.load_tracks_from_slp(slp_path: str) → Tuple[ndarray, List[str]]

Loads tracks from a sleap project file or analysis h5

Parameters

slp_path (str) – Path to SLEAP project file or analysis h5. This file is typically generated using sleap-convert. Analysis h5s are much faster to load and thus preferable.

Returns

Tuple of (locations_matrix, node_names) where location matrix is a numpy array with shape (frames, nodes, 2, tracks) and node_names is a list of node names.

Return type

Tuple[np.ndarray, List[str]]

naps.sleap_utils.update_labeled_frames(slp_path: str, matching_dict: dict, first_frame_idx: int, last_frame_idx: int) → List[LabeledFrame]

Generates a list of labeled frames from a sleap project file with tracks updated from the provided matching_dict.

Parameters

• slp_path (str) – Path to SLEAP project file (.slp) file.

• matching_dict (dict) – Dictionary of format [Frame][Track] containing the tag number for each track in each frame.

• first_frame_idx (int) – First frame index to include in the reconstructed h5.

• last_frame_idx (int) – Last frame index to include in the reconstructed h5.

Returns

List of labeled frames with updated tracks.

Return type

List[sleap.LabeledFrame]

class naps.matching.MatchFrame(frame_exists: bool, frame: ndarray, *args, **kwargs)

Class used to assign markers for a frame and associated data.

frame

Value array of the frame image.

Type

np.ndarray

frame_exists

Boolean indicating if the frame was read correctly.

Type

bool

frame_images

Dictionary to store value arrays for each marker image.

Type

dict

cropMarkerWithCoordsArray(coords_dict, crop_size: int)

Creates cropped images for each marker in the coords_dict.

Parameters

• coords_dict (dict) – Dictionary of marker coordinates to crop for each track.

• crop_size (float) – Crop size.

classmethod fromCV2(*args, **kwargs)

Class methods to create a MatchFrame from CV2.read()

Parameters

• bool – Boolean indicating if the frame was read correctly.

• np.ndarray – Value array of the frame image.

Returns

A MatchFrame object.

Return type

MatchFrame

returnMarkerTags(marker_detect: Callable)

Detect marker tags using the specified marker_detect function

Parameters

• marker_detect (Callable) – Marker detector function. Function is expected

• assignments. (to return a list of marker) –

Returns

Dictionary of matching results for a single frame.

Return type

defaultdict(list)

class naps.matching.Matching(video_filename: str, video_first_frame: int, video_last_frame: int, marker_detector: Callable, aruco_crop_size: int, half_rolling_window_size: int, tag_node_dict: dict, min_sleap_score: float = 0.1, **kwargs)

Matching pipeline.

video_filename

Matching video filename (i.e. path).

Type

str

video_first_frame

Frame to start matching.

Type

str

video_last_frame

Frame to end matching.

Type

str

marker_detector

Function used to detect/assign markers.

Type

Callable

aruco_crop_size

Crop size used for marker detection.

Type

int

half_rolling_window_size

Window size (upstream/downstream) used by the cost matrix.

Type

int

tag_node_dict

Dictionary of frames, tracks, and node coordinates.

Type

dict

threads

The number of CPU threads to use.

Type

int

min_sleap_score

Minimum sleap score required for matching. Should this be removed?

Type

float

match() -> defaultdict(<function Matching.<lambda> at 0x7f6162bb8e60>, {})

Performs matching.

Returns

defaultdict(str)): Dictionary of matching results with the form dictionary[frame][track] = tag.

Return type

defaultdict(lambda

class naps.aruco.ArUcoModel(tag_set: str, adaptiveThreshWinSizeMin: int, adaptiveThreshWinSizeMax: int, adaptiveThreshWinSizeStep: int, adaptiveThreshConstant: float, perspectiveRemoveIgnoredMarginPerCell: float, errorCorrectionRate: float, tag_subset_list: list = [], **kwargs)

Class providing a wrapper around the cv2.aruco library

aruco_dict

ArUco parameters: These have been adjusted by dyknapp but are worth playing with if ArUco is too slow or not detecting enough tags. These thresholding parameters DRAMATICALLY improve detection rate, while DRAMATICALLY hurting performance. Since super fast processing isn’t really necessary here they should be fine as is.

aruco_params

Assign the corner refinement method:

Should we permit all options?