commands

sleap.gui.commands

Module for gui command context and commands objects.

Each open project (i.e., MainWindow) will have its own CommandContext. The context enables commands to access and modify the GuiState and Labels, as well as potentially maintaining a command history (so we can add support for undo!). See sleap.gui.app for how the context is created and used.

Every command will have both a method in CommandContext (this is what should be used to trigger the command, e.g., connected to the menu action) and a class which inherits from AppCommand (or a more specialized class such as NavCommand, GoIteratorCommand, or EditCommand). Note that this code relies on inheritance, so some care and attention is required.

A typical command will override the ask and do_action methods. If the command updates something which affects the GUI, it should override the topic attribute (this then gets passed back to the update_callback from the context. If a command doesn't require any input from the user, then it doesn't need to override the ask method.

If it's not possible to separate the GUI "ask" and the non-GUI "do" code, then instead of ask and do_action you should add an ask_and_do method (for instance, DeleteDialogCommand and MergeProject show dialogues which handle both the GUI and the action). Ideally we'd endorse separation of "ask" and "do" for all commands (this is important if we're going to implement undo)-- for now it's at least easy to see where this separation is violated.

Classes:

Name	Description
AddInstance
AddMissingInstanceNodes
AddUserInstancesFromPredictions
AddVideo
AppCommand	Base class for specific commands.
CommandContext	Context within in which commands are executed.
DeleteFrameLimitPredictions
DeleteMultipleTracks
DeleteUserFramePredictions	Delete predictions on frames that have user instances.
EditCommand	Class for commands which change data in project.
ExportLabeledClip	Export a labeled video clip with skeleton overlay.
ExportLabelsSubset	Export a subset of labels to a new file with either images or a trimmed video.
ExportPackageThread	Background thread for exporting labels package without freezing GUI.
ExportVideoClip	Base class for exporting video clips.
FakeApp	Use if you want to execute commands independently of the GUI app.
GenerateSuggestionsThread	Background thread for generating frame suggestions without freezing GUI.
GoIteratorCommand
InstanceDeleteCommand
LoadLabelsObject
MergeInstances	Merge two user instances in the current frame into a single instance.
OpenSkeleton
RenderVideoThread	Background thread for rendering video without freezing GUI.
ReplaceVideo
SaveProjectAs
SetInstancePointLocations	Sets locations for node(s) for an instance.
SetInstancePointVisibility	Toggles visibility set for a node for an instance.
ToggleGrayscale
ToggleNegativeFrame	Mark or unmark the current frame as a negative (background) frame.
UpdateTopic	Topics so context can tell callback what was updated by the command.

Functions:

Name	Description
copy_to_clipboard	Copy a string to the system clipboard.
export_dataset_gui	Export dataset with image data and display progress GUI dialog.
get_new_version_filename	Increment version number in filenames that end in .v###.slp.
open_file	Opens file in native system file browser or registered application.
open_website	Open website in default browser.
render_video_gui	Render video with progress dialog.
reveal_file	Open the file explorer with the given file selected/revealed.

AddInstance

Bases: EditCommand

Methods:

Name	Description
create_new_instance	Create new instance.
fill_missing_nodes	Fill in missing nodes for new instance.
find_instance_to_copy_from	Find instance to copy from.
get_previous_frame_index	Returns index of previous frame.
set_visible_nodes	Sets visible nodes for new instance.

Source code in sleap/gui/commands.py

class AddInstance(EditCommand):
    topics = [UpdateTopic.frame, UpdateTopic.project_instances, UpdateTopic.suggestions]

    @classmethod
    def do_action(cls, context: CommandContext, params: dict):
        copy_instance = params.get("copy_instance", None)
        init_method = params.get("init_method", "best")
        location = params.get("location", None)
        mark_complete = params.get("mark_complete", False)
        offset = params.get("offset", 0)

        if context.state["labeled_frame"] is None:
            return

        if len(context.state["skeleton"]) == 0:
            return

        (
            copy_instance,
            from_predicted,
            from_prev_frame,
        ) = AddInstance.find_instance_to_copy_from(
            context, copy_instance=copy_instance, init_method=init_method
        )

        new_instance = AddInstance.create_new_instance(
            context=context,
            from_predicted=from_predicted,
            copy_instance=copy_instance,
            mark_complete=mark_complete,
            init_method=init_method,
            location=location,
            from_prev_frame=from_prev_frame,
            offset=offset,
        )

        # add new instance
        if new_instance not in context.state["labeled_frame"].instances:
            context.state["labeled_frame"].instances.append(new_instance)

        existing_tracks = [track.name for track in context.labels.tracks]
        if (
            new_instance.track is not None
            and new_instance.track.name not in existing_tracks
        ):
            context.labels.tracks.append(new_instance.track)

        # A frame with a real instance is not a background frame.
        context.state["labeled_frame"].is_negative = False

        if context.state["labeled_frame"] not in context.labels:
            context.labels.append(context.state["labeled_frame"])

        context.labels.update()

    @staticmethod
    def create_new_instance(
        context: CommandContext,
        from_predicted: Optional[PredictedInstance],
        copy_instance: Optional[Union[Instance, PredictedInstance]],
        mark_complete: bool,
        init_method: str,
        location: Optional[QtCore.QPoint],
        from_prev_frame: bool,
        offset: int = 0,
    ) -> Instance:
        """Create new instance."""

        # Now create the new instance
        new_instance = Instance.empty(
            skeleton=context.state["skeleton"],
            from_predicted=from_predicted,
        )

        has_missing_nodes = AddInstance.set_visible_nodes(
            context=context,
            copy_instance=copy_instance,
            new_instance=new_instance,
            mark_complete=mark_complete,
            init_method=init_method,
            location=location,
            offset=offset,
        )

        if has_missing_nodes:
            AddInstance.fill_missing_nodes(
                context=context,
                copy_instance=copy_instance,
                init_method=init_method,
                new_instance=new_instance,
                location=location,
            )

        # If we're copying a predicted instance or from another frame, copy the track
        if hasattr(copy_instance, "score") or from_prev_frame:
            copy_instance = cast(Union[PredictedInstance, Instance], copy_instance)
            new_instance.track = copy_instance.track

        return new_instance

    @staticmethod
    def fill_missing_nodes(
        context: CommandContext,
        copy_instance: Optional[Union[Instance, PredictedInstance]],
        init_method: str,
        new_instance: Instance,
        location: Optional[QtCore.QPoint],
    ):
        """Fill in missing nodes for new instance.

        Args:
            context: The command context.
            copy_instance: The instance to copy from.
            init_method: The initialization method.
            new_instance: The new instance.
            location: The location of the instance.

        Returns:
            None
        """

        # mark the node as not "visible" if we're copying from a predicted instance
        # without this node
        is_visible = copy_instance is None or (not hasattr(copy_instance, "score"))

        if init_method == "force_directed":
            AddMissingInstanceNodes.add_force_directed_nodes(
                context=context,
                instance=new_instance,
                visible=is_visible,
                center_point=location,
            )
        elif init_method == "random":
            AddMissingInstanceNodes.add_random_nodes(
                context=context, instance=new_instance, visible=is_visible
            )
        elif init_method == "template":
            AddMissingInstanceNodes.add_nodes_from_template(
                context=context,
                instance=new_instance,
                visible=is_visible,
                center_point=location,
            )
        else:
            AddMissingInstanceNodes.add_best_nodes(
                context=context, instance=new_instance, visible=is_visible
            )

    @staticmethod
    def set_visible_nodes(
        context: CommandContext,
        copy_instance: Optional[Union[Instance, PredictedInstance]],
        new_instance: Instance,
        mark_complete: bool,
        init_method: str,
        location: Optional[QtCore.QPoint] = None,
        offset: int = 0,
    ) -> bool:
        """Sets visible nodes for new instance.

        Args:
            context: The command context.
            copy_instance: The instance to copy from.
            new_instance: The new instance.
            mark_complete: Whether to mark the instance as complete.
            init_method: The initialization method.
            location: The location of the mouse click if any.
            offset: The offset to apply to all nodes.

        Returns:
            Whether the new instance has missing nodes.
        """
        if copy_instance is None:
            return True

        has_missing_nodes = False

        # Calculate scale factor for getting new x and y values.
        # Get video from context since instances don't have frame attribute
        old_video = context.state.get("video") or context.labels.videos[0]
        new_video = context.state.get("video") or context.labels.videos[0]
        old_size_width = old_video.shape[2]
        old_size_height = old_video.shape[1]
        new_size_width = new_video.shape[2]
        new_size_height = new_video.shape[1]
        scale_width = new_size_width / old_size_width
        scale_height = new_size_height / old_size_height

        # The offset is 0, except when using Ctrl + I or Add Instance button.
        offset_x = offset
        offset_y = offset

        # Using right click and context menu with option "best"
        if (init_method == "best") and (location is not None):
            reference_node = next(
                (node for node in copy_instance if not np.any(np.isnan(node["xy"]))),
                None,
            )
            reference_x, reference_y = reference_node["xy"]
            offset_x = location.x() - (reference_x * scale_width)
            offset_y = location.y() - (reference_y * scale_height)

        # Go through each node in skeleton.
        for node in context.state["skeleton"].node_names:
            # If we're copying from a skeleton that has this node.
            node_idx = context.state["skeleton"].node_names.index(node)
            if node in copy_instance.skeleton.node_names and not np.any(
                np.isnan(copy_instance.numpy()[node_idx])
            ):
                # Ensure x, y inside current frame, then copy x, y, and visible.
                # We don't want to copy a PredictedPoint or score attribute.
                point_data = copy_instance[node_idx]
                x_old, y_old = point_data["xy"]

                # Copy the instance without scale or offset if predicted
                if isinstance(copy_instance, PredictedInstance):
                    x_new = x_old
                    y_new = y_old
                else:
                    x_new = x_old * scale_width
                    y_new = y_old * scale_height

                # Apply offset if in bounds
                x_new_offset = x_new + offset_x
                y_new_offset = y_new + offset_y

                # Default visibility is same as copied instance.
                visible = point_data["visible"]

                # If the node is offset to outside the frame, mark as not visible.
                if x_new_offset < 0:
                    x_new = 0
                    visible = False
                elif x_new_offset > new_size_width:
                    x_new = new_size_width
                    visible = False
                else:
                    x_new = x_new_offset
                if y_new_offset < 0:
                    y_new = 0
                    visible = False
                elif y_new_offset > new_size_height:
                    y_new = new_size_height
                    visible = False
                else:
                    y_new = y_new_offset

                new_instance[node]["xy"] = np.array([x_new, y_new])
                new_instance[node]["visible"] = visible
                new_instance[node]["complete"] = mark_complete
                new_instance[node]["name"] = node
            else:
                has_missing_nodes = True
                # Initialize the skipped point with NaN xy and visible=False so
                # downstream `add_*_nodes` gates fire and the buffer is not
                # left holding uninitialized memory from `Instance.empty()`.
                new_instance[node]["xy"] = np.array([np.nan, np.nan])
                new_instance[node]["visible"] = False
                new_instance[node]["complete"] = False
                new_instance[node]["name"] = node

        return has_missing_nodes

    @staticmethod
    def find_instance_to_copy_from(
        context: CommandContext,
        copy_instance: Optional[Union[Instance, PredictedInstance]],
        init_method: bool,
    ) -> Tuple[
        Optional[Union[Instance, PredictedInstance]], Optional[PredictedInstance], bool
    ]:
        """Find instance to copy from.

        Args:
            context: The command context.
            copy_instance: The `Instance` to copy from.
            init_method: The initialization method.

        Returns:
            The instance to copy from, the predicted instance (if it is from a predicted
            instance, else None), and whether it's from a previous frame.
        """

        from_predicted = copy_instance
        from_prev_frame = False

        if init_method == "best" and copy_instance is None:
            selected_inst = context.state["instance"]
            if selected_inst is not None:
                # If the user has selected an instance, copy that one.
                copy_instance = selected_inst
                from_predicted = copy_instance

        if (
            init_method == "best" and copy_instance is None
        ) or init_method == "prediction":
            unused_predictions = context.state["labeled_frame"].unused_predictions
            if len(unused_predictions):
                # If there are predicted instances that don't correspond to an instance
                # in this frame, use the first predicted instance without
                # matching instance.
                copy_instance = unused_predictions[0]
                from_predicted = copy_instance

        if (
            init_method == "best" and copy_instance is None
        ) or init_method == "prior_frame":
            # Otherwise, if there are instances in previous frames,
            # copy the points from one of those instances.
            prev_idx = AddInstance.get_previous_frame_index(context)

            if prev_idx is not None:
                prev_lf = context.labels.find(
                    context.state["video"], prev_idx, return_new=True
                )[0]
                # Prefer user-corrected instances over their predicted
                # counterparts so "Copy Prior Frame" picks up edits the user
                # made in the previous frame (#1065).
                prev_instances = AddInstance._effective_prior_instances(prev_lf)
                if len(prev_instances) > len(context.state["labeled_frame"].instances):
                    # If more instances in previous frame than current, then use the
                    # first unmatched instance.
                    copy_instance = prev_instances[
                        len(context.state["labeled_frame"].instances)
                    ]
                    from_prev_frame = True
                elif init_method == "best" and (
                    context.state["labeled_frame"].instances
                ):
                    # Otherwise, if there are already instances in current frame,
                    # copy the points from the last instance added to frame.
                    copy_instance = context.state["labeled_frame"].instances[-1]
                elif len(prev_instances):
                    # Otherwise use the last instance added to previous frame.
                    copy_instance = prev_instances[-1]
                    from_prev_frame = True

        from_predicted = from_predicted if hasattr(from_predicted, "score") else None
        from_predicted = cast(Optional[PredictedInstance], from_predicted)

        return copy_instance, from_predicted, from_prev_frame

    @staticmethod
    def get_previous_frame_index(context: CommandContext) -> Optional[int]:
        """Returns index of previous frame."""
        from sleap.sleap_io_adaptors.lf_labels_utils import iterate_labeled_frames

        frames_iter = iterate_labeled_frames(
            context.labels,
            context.state["video"],
            from_frame_idx=context.state["frame_idx"],
            reverse=True,
        )

        try:
            next_idx = next(frames_iter).frame_idx
        except Exception:
            return

        return next_idx

    @staticmethod
    def _effective_prior_instances(
        prev_lf: LabeledFrame,
    ) -> List[Union[Instance, PredictedInstance]]:
        # When a user corrects a prediction the original PredictedInstance
        # stays on the frame alongside the new user Instance. Returning raw
        # `lf.instances` would let "Copy Prior Frame" land on the stale
        # prediction; prefer the user version of each animal and drop
        # predictions whose user counterpart is already present.
        return list(prev_lf.user_instances) + list(prev_lf.unused_predictions)

create_new_instance(context, from_predicted, copy_instance, mark_complete, init_method, location, from_prev_frame, offset=0) staticmethod

Create new instance.

Source code in sleap/gui/commands.py

@staticmethod
def create_new_instance(
    context: CommandContext,
    from_predicted: Optional[PredictedInstance],
    copy_instance: Optional[Union[Instance, PredictedInstance]],
    mark_complete: bool,
    init_method: str,
    location: Optional[QtCore.QPoint],
    from_prev_frame: bool,
    offset: int = 0,
) -> Instance:
    """Create new instance."""

    # Now create the new instance
    new_instance = Instance.empty(
        skeleton=context.state["skeleton"],
        from_predicted=from_predicted,
    )

    has_missing_nodes = AddInstance.set_visible_nodes(
        context=context,
        copy_instance=copy_instance,
        new_instance=new_instance,
        mark_complete=mark_complete,
        init_method=init_method,
        location=location,
        offset=offset,
    )

    if has_missing_nodes:
        AddInstance.fill_missing_nodes(
            context=context,
            copy_instance=copy_instance,
            init_method=init_method,
            new_instance=new_instance,
            location=location,
        )

    # If we're copying a predicted instance or from another frame, copy the track
    if hasattr(copy_instance, "score") or from_prev_frame:
        copy_instance = cast(Union[PredictedInstance, Instance], copy_instance)
        new_instance.track = copy_instance.track

    return new_instance

fill_missing_nodes(context, copy_instance, init_method, new_instance, location) staticmethod

Fill in missing nodes for new instance.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
copy_instance	Optional[Union[Instance, PredictedInstance]]	The instance to copy from.	required
init_method	str	The initialization method.	required
new_instance	Instance	The new instance.	required
location	Optional[QPoint]	The location of the instance.	required

Returns:

Type	Description
	None

Source code in sleap/gui/commands.py

@staticmethod
def fill_missing_nodes(
    context: CommandContext,
    copy_instance: Optional[Union[Instance, PredictedInstance]],
    init_method: str,
    new_instance: Instance,
    location: Optional[QtCore.QPoint],
):
    """Fill in missing nodes for new instance.

    Args:
        context: The command context.
        copy_instance: The instance to copy from.
        init_method: The initialization method.
        new_instance: The new instance.
        location: The location of the instance.

    Returns:
        None
    """

    # mark the node as not "visible" if we're copying from a predicted instance
    # without this node
    is_visible = copy_instance is None or (not hasattr(copy_instance, "score"))

    if init_method == "force_directed":
        AddMissingInstanceNodes.add_force_directed_nodes(
            context=context,
            instance=new_instance,
            visible=is_visible,
            center_point=location,
        )
    elif init_method == "random":
        AddMissingInstanceNodes.add_random_nodes(
            context=context, instance=new_instance, visible=is_visible
        )
    elif init_method == "template":
        AddMissingInstanceNodes.add_nodes_from_template(
            context=context,
            instance=new_instance,
            visible=is_visible,
            center_point=location,
        )
    else:
        AddMissingInstanceNodes.add_best_nodes(
            context=context, instance=new_instance, visible=is_visible
        )

find_instance_to_copy_from(context, copy_instance, init_method) staticmethod

Find instance to copy from.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
copy_instance	Optional[Union[Instance, PredictedInstance]]	The Instance to copy from.	required
init_method	bool	The initialization method.	required

Returns:

Type	Description
Tuple[Optional[Union[Instance, PredictedInstance]], Optional[PredictedInstance], bool]	The instance to copy from, the predicted instance (if it is from a predicted instance, else None), and whether it's from a previous frame.

Source code in sleap/gui/commands.py

@staticmethod
def find_instance_to_copy_from(
    context: CommandContext,
    copy_instance: Optional[Union[Instance, PredictedInstance]],
    init_method: bool,
) -> Tuple[
    Optional[Union[Instance, PredictedInstance]], Optional[PredictedInstance], bool
]:
    """Find instance to copy from.

    Args:
        context: The command context.
        copy_instance: The `Instance` to copy from.
        init_method: The initialization method.

    Returns:
        The instance to copy from, the predicted instance (if it is from a predicted
        instance, else None), and whether it's from a previous frame.
    """

    from_predicted = copy_instance
    from_prev_frame = False

    if init_method == "best" and copy_instance is None:
        selected_inst = context.state["instance"]
        if selected_inst is not None:
            # If the user has selected an instance, copy that one.
            copy_instance = selected_inst
            from_predicted = copy_instance

    if (
        init_method == "best" and copy_instance is None
    ) or init_method == "prediction":
        unused_predictions = context.state["labeled_frame"].unused_predictions
        if len(unused_predictions):
            # If there are predicted instances that don't correspond to an instance
            # in this frame, use the first predicted instance without
            # matching instance.
            copy_instance = unused_predictions[0]
            from_predicted = copy_instance

    if (
        init_method == "best" and copy_instance is None
    ) or init_method == "prior_frame":
        # Otherwise, if there are instances in previous frames,
        # copy the points from one of those instances.
        prev_idx = AddInstance.get_previous_frame_index(context)

        if prev_idx is not None:
            prev_lf = context.labels.find(
                context.state["video"], prev_idx, return_new=True
            )[0]
            # Prefer user-corrected instances over their predicted
            # counterparts so "Copy Prior Frame" picks up edits the user
            # made in the previous frame (#1065).
            prev_instances = AddInstance._effective_prior_instances(prev_lf)
            if len(prev_instances) > len(context.state["labeled_frame"].instances):
                # If more instances in previous frame than current, then use the
                # first unmatched instance.
                copy_instance = prev_instances[
                    len(context.state["labeled_frame"].instances)
                ]
                from_prev_frame = True
            elif init_method == "best" and (
                context.state["labeled_frame"].instances
            ):
                # Otherwise, if there are already instances in current frame,
                # copy the points from the last instance added to frame.
                copy_instance = context.state["labeled_frame"].instances[-1]
            elif len(prev_instances):
                # Otherwise use the last instance added to previous frame.
                copy_instance = prev_instances[-1]
                from_prev_frame = True

    from_predicted = from_predicted if hasattr(from_predicted, "score") else None
    from_predicted = cast(Optional[PredictedInstance], from_predicted)

    return copy_instance, from_predicted, from_prev_frame

get_previous_frame_index(context) staticmethod

Returns index of previous frame.

Source code in sleap/gui/commands.py

@staticmethod
def get_previous_frame_index(context: CommandContext) -> Optional[int]:
    """Returns index of previous frame."""
    from sleap.sleap_io_adaptors.lf_labels_utils import iterate_labeled_frames

    frames_iter = iterate_labeled_frames(
        context.labels,
        context.state["video"],
        from_frame_idx=context.state["frame_idx"],
        reverse=True,
    )

    try:
        next_idx = next(frames_iter).frame_idx
    except Exception:
        return

    return next_idx

set_visible_nodes(context, copy_instance, new_instance, mark_complete, init_method, location=None, offset=0) staticmethod

Sets visible nodes for new instance.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
copy_instance	Optional[Union[Instance, PredictedInstance]]	The instance to copy from.	required
new_instance	Instance	The new instance.	required
mark_complete	bool	Whether to mark the instance as complete.	required
init_method	str	The initialization method.	required
location	Optional[QPoint]	The location of the mouse click if any.	None
offset	int	The offset to apply to all nodes.	0

Returns:

Type	Description
bool	Whether the new instance has missing nodes.

Source code in sleap/gui/commands.py

@staticmethod
def set_visible_nodes(
    context: CommandContext,
    copy_instance: Optional[Union[Instance, PredictedInstance]],
    new_instance: Instance,
    mark_complete: bool,
    init_method: str,
    location: Optional[QtCore.QPoint] = None,
    offset: int = 0,
) -> bool:
    """Sets visible nodes for new instance.

    Args:
        context: The command context.
        copy_instance: The instance to copy from.
        new_instance: The new instance.
        mark_complete: Whether to mark the instance as complete.
        init_method: The initialization method.
        location: The location of the mouse click if any.
        offset: The offset to apply to all nodes.

    Returns:
        Whether the new instance has missing nodes.
    """
    if copy_instance is None:
        return True

    has_missing_nodes = False

    # Calculate scale factor for getting new x and y values.
    # Get video from context since instances don't have frame attribute
    old_video = context.state.get("video") or context.labels.videos[0]
    new_video = context.state.get("video") or context.labels.videos[0]
    old_size_width = old_video.shape[2]
    old_size_height = old_video.shape[1]
    new_size_width = new_video.shape[2]
    new_size_height = new_video.shape[1]
    scale_width = new_size_width / old_size_width
    scale_height = new_size_height / old_size_height

    # The offset is 0, except when using Ctrl + I or Add Instance button.
    offset_x = offset
    offset_y = offset

    # Using right click and context menu with option "best"
    if (init_method == "best") and (location is not None):
        reference_node = next(
            (node for node in copy_instance if not np.any(np.isnan(node["xy"]))),
            None,
        )
        reference_x, reference_y = reference_node["xy"]
        offset_x = location.x() - (reference_x * scale_width)
        offset_y = location.y() - (reference_y * scale_height)

    # Go through each node in skeleton.
    for node in context.state["skeleton"].node_names:
        # If we're copying from a skeleton that has this node.
        node_idx = context.state["skeleton"].node_names.index(node)
        if node in copy_instance.skeleton.node_names and not np.any(
            np.isnan(copy_instance.numpy()[node_idx])
        ):
            # Ensure x, y inside current frame, then copy x, y, and visible.
            # We don't want to copy a PredictedPoint or score attribute.
            point_data = copy_instance[node_idx]
            x_old, y_old = point_data["xy"]

            # Copy the instance without scale or offset if predicted
            if isinstance(copy_instance, PredictedInstance):
                x_new = x_old
                y_new = y_old
            else:
                x_new = x_old * scale_width
                y_new = y_old * scale_height

            # Apply offset if in bounds
            x_new_offset = x_new + offset_x
            y_new_offset = y_new + offset_y

            # Default visibility is same as copied instance.
            visible = point_data["visible"]

            # If the node is offset to outside the frame, mark as not visible.
            if x_new_offset < 0:
                x_new = 0
                visible = False
            elif x_new_offset > new_size_width:
                x_new = new_size_width
                visible = False
            else:
                x_new = x_new_offset
            if y_new_offset < 0:
                y_new = 0
                visible = False
            elif y_new_offset > new_size_height:
                y_new = new_size_height
                visible = False
            else:
                y_new = y_new_offset

            new_instance[node]["xy"] = np.array([x_new, y_new])
            new_instance[node]["visible"] = visible
            new_instance[node]["complete"] = mark_complete
            new_instance[node]["name"] = node
        else:
            has_missing_nodes = True
            # Initialize the skipped point with NaN xy and visible=False so
            # downstream `add_*_nodes` gates fire and the buffer is not
            # left holding uninitialized memory from `Instance.empty()`.
            new_instance[node]["xy"] = np.array([np.nan, np.nan])
            new_instance[node]["visible"] = False
            new_instance[node]["complete"] = False
            new_instance[node]["name"] = node

    return has_missing_nodes

AddMissingInstanceNodes

Bases: EditCommand

Methods:

Name	Description
get_rect_center_xy	Returns x, y at center of rect.
get_xy_in_rect	Returns random x, y coordinates within given rect.

Source code in sleap/gui/commands.py

class AddMissingInstanceNodes(EditCommand):
    topics = [UpdateTopic.frame]

    @classmethod
    def do_action(cls, context: CommandContext, params: dict):
        instance = params["instance"]
        visible = params.get("visible", False)

        cls.add_best_nodes(context, instance, visible)

    @classmethod
    def add_best_nodes(cls, context, instance, visible):
        # Try placing missing nodes using a "template" instance
        cls.add_nodes_from_template(context, instance, visible)

        # If the "template" instance has missing nodes (i.e., a node that isn't
        # labeled on any of the instances we used to generate the template),
        # then adding nodes from the template may still result in missing nodes.
        # So we'll use random placement for anything that's still missing.
        cls.add_random_nodes(context, instance, visible)

    @classmethod
    def add_random_nodes(cls, context, instance, visible):
        # TODO: Move this to Instance so we can do this on-demand
        # the rect that's currently visible in the window view
        in_view_rect = context.app.player.getVisibleRect()

        input_arrays = instance.points

        for node_name in context.state["skeleton"].node_names:
            node_idx = context.state["skeleton"].node_names.index(node_name)
            if node_name not in instance.points["name"] or np.any(
                np.isnan(instance.numpy()[node_idx])
            ):
                # pick random points within currently zoomed view
                x, y = cls.get_xy_in_rect(in_view_rect)
                # set point for node

                input_array = np.array(
                    (np.array([x, y]), visible, False, node_name),
                    dtype=[
                        ("xy", "<f8", (2,)),
                        ("visible", "bool"),
                        ("complete", "bool"),
                        ("name", "O"),
                    ],
                )
                input_arrays[node_idx] = input_array
            else:
                x, y = instance.points[node_idx]["xy"]
                # Use distinct names so we don't shadow the `visible` function
                # parameter -- otherwise a per-node visibility from this branch
                # bleeds into the if-branch on later iterations and overrides
                # the caller-requested default (which is how NaN-coord
                # predicted nodes were ending up with visible=True).
                point_visible = instance.points[node_idx]["visible"]
                point_complete = instance.points[node_idx]["complete"]
                input_arrays[node_idx] = np.array(
                    (np.array([x, y]), point_visible, point_complete, node_name),
                    dtype=[
                        ("xy", "<f8", (2,)),
                        ("visible", "bool"),
                        ("complete", "bool"),
                        ("name", "O"),
                    ],
                )
        instance.points = PointsArray.from_array(input_arrays)

    @staticmethod
    def get_xy_in_rect(rect: QtCore.QRectF):
        """Returns random x, y coordinates within given rect."""
        x = rect.x() + (rect.width() * 0.1) + (np.random.rand() * rect.width() * 0.8)
        y = rect.y() + (rect.height() * 0.1) + (np.random.rand() * rect.height() * 0.8)
        return x, y

    @staticmethod
    def get_rect_center_xy(rect: QtCore.QRectF):
        """Returns x, y at center of rect."""

    @classmethod
    def add_nodes_from_template(
        cls,
        context,
        instance,  # should be zeroes
        visible: bool = False,
        center_point: QtCore.QPoint = None,
    ):
        # Get the "template" instance
        # context.labels.get_template_instance()
        template_points = get_template_instance_points(
            context.labels, skeleton=instance.skeleton
        )

        # Align the template on to the current instance with missing points
        if not np.all(np.isnan(instance.numpy())) and not np.allclose(
            instance.numpy(), 0.0
        ):
            aligned_template = align.align_instance_points(
                source_points_array=template_points,
                target_points_array=instance.points["xy"],
            )
        else:
            template_mean = np.nanmean(template_points, axis=0)

            center_point = center_point or context.app.player.getVisibleRect().center()
            center = np.array([center_point.x(), center_point.y()])

            aligned_template = (template_points - template_mean) + center

        input_arrays = PointsArray.empty(len(instance.skeleton.nodes))
        # Make missing points from the aligned template
        for i, node in enumerate(instance.skeleton.nodes):
            if np.all(np.isnan(instance.points[i]["xy"])) or np.allclose(
                instance.points[i]["xy"], 0.0, equal_nan=True
            ):
                x, y = aligned_template[i]
                input_array = np.array(
                    [([x, y], visible, False, node.name)],
                    dtype=[
                        ("xy", "<f8", (2,)),
                        ("visible", "bool"),
                        ("complete", "bool"),
                        ("name", "O"),
                    ],
                )
                input_arrays[i] = input_array
            else:
                input_arrays[i] = instance.points[i]

        instance.points = PointsArray.from_array(input_arrays)

    @classmethod
    def add_force_directed_nodes(
        cls, context, instance, visible, center_point: QtCore.QPoint = None
    ):
        import networkx as nx

        center_point = center_point or context.app.player.getVisibleRect().center()
        center_tuple = (center_point.x(), center_point.y())

        node_positions = nx.spring_layout(
            G=to_graph(context.state["skeleton"]), center=center_tuple, scale=50
        )

        for node, pos in node_positions.items():
            # Create the input array first, then use PointsArray.from_array()
            node_name = node if isinstance(node, str) else node.name
            instance[node_name]["xy"] = np.array([pos[0], pos[1]])
            instance[node_name]["visible"] = visible
            instance[node_name]["complete"] = False
            instance[node_name]["name"] = node_name

get_rect_center_xy(rect) staticmethod

Returns x, y at center of rect.

Source code in sleap/gui/commands.py

@staticmethod
def get_rect_center_xy(rect: QtCore.QRectF):
    """Returns x, y at center of rect."""

get_xy_in_rect(rect) staticmethod

Returns random x, y coordinates within given rect.

Source code in sleap/gui/commands.py

@staticmethod
def get_xy_in_rect(rect: QtCore.QRectF):
    """Returns random x, y coordinates within given rect."""
    x = rect.x() + (rect.width() * 0.1) + (np.random.rand() * rect.width() * 0.8)
    y = rect.y() + (rect.height() * 0.1) + (np.random.rand() * rect.height() * 0.8)
    return x, y

AddUserInstancesFromPredictions

Bases: EditCommand

Methods:

Name	Description
fill_missing_predicted_nodes	Position undetected (NaN) nodes with a force-directed layout, hidden.
make_instance_from_predicted_instance	Create a user Instance from a PredictedInstance.

Source code in sleap/gui/commands.py

class AddUserInstancesFromPredictions(EditCommand):
    topics = [UpdateTopic.frame, UpdateTopic.project_instances]

    @staticmethod
    def make_instance_from_predicted_instance(
        copy_instance: PredictedInstance,
    ) -> Instance:
        """Create a user Instance from a PredictedInstance.

        Creates an empty Instance with proper PointsArray dtype, then copies
        coordinates and visibility from the prediction.

        Args:
            copy_instance: The PredictedInstance to convert.

        Returns:
            A new Instance with the same points, skeleton, and track,
            and from_predicted linking back to the original prediction.
        """
        # Create empty instance with proper PointsArray (not PredictedPointsArray)
        new_instance = Instance.empty(
            skeleton=copy_instance.skeleton,
            track=copy_instance.track,
            from_predicted=copy_instance,
        )

        # Copy point data from prediction. Predicted nodes that were not
        # detected have NaN coordinates; mark those as not visible so the
        # user instance starts in a well-defined state.
        for i, node in enumerate(copy_instance.skeleton.node_names):
            pred_point = copy_instance.points[i]
            xy_is_nan = bool(np.any(np.isnan(pred_point["xy"])))
            new_instance.points[i]["xy"] = pred_point["xy"]
            new_instance.points[i]["visible"] = (
                bool(pred_point["visible"]) and not xy_is_nan
            )
            new_instance.points[i]["complete"] = False

        return new_instance

    @staticmethod
    def fill_missing_predicted_nodes(new_instance: Instance):
        """Position undetected (NaN) nodes with a force-directed layout, hidden.

        The model leaves occluded nodes at NaN coordinates, and
        ``make_instance_from_predicted_instance`` keeps them ``visible=False``
        (correct -- the converted instance should look like the prediction). But
        a NaN coordinate renders at a default/garbage location when the user
        enables "show non-visible nodes" (``QtInstance`` still creates a node
        item for every node in that mode, positioned at its ``xy``).

        Spread the missing nodes with a force-directed (spring) layout of the
        skeleton graph, centered on the detected keypoints' centroid and scaled
        to their extent, so they sit on the animal -- spread out and grabbable --
        regardless of how many nodes the model detected, while staying
        ``visible=False``. (Template/alignment placement is unreliable when only
        a few nodes are detected -- there is no way to infer where occluded nodes
        are from a couple of visible ones -- so a force-directed layout, one of
        the brand-new-instance init options, is used for robustness.)
        Already-detected points, the track, and ``from_predicted`` are untouched.

        No GUI player is required. No-op when every node was detected, or when
        nothing was detected (no anchor for the layout center).

        Args:
            new_instance: The user ``Instance`` produced by
                ``make_instance_from_predicted_instance``; modified in place.
        """
        import networkx as nx

        xy = new_instance.points["xy"]
        missing = np.isnan(xy).any(axis=1)
        detected = ~missing
        if not missing.any() or not detected.any():
            return

        det_xy = xy[detected]
        center = det_xy.mean(axis=0)
        extent = float(np.linalg.norm(det_xy.max(axis=0) - det_xy.min(axis=0)))
        scale = max(extent / 2.0, 5.0)

        skeleton = new_instance.skeleton
        layout = nx.spring_layout(
            to_graph(skeleton), center=center, scale=scale, seed=0
        )
        pos_by_name = {
            (node if isinstance(node, str) else node.name): pos
            for node, pos in layout.items()
        }

        miss_idx = np.nonzero(missing)[0]
        fill_xy = np.array(
            [pos_by_name.get(skeleton.node_names[i], center) for i in miss_idx],
            dtype=float,
        )
        new_instance.points["xy"][missing] = fill_xy
        new_instance.points["visible"][missing] = False
        new_instance.points["complete"][missing] = False

    @classmethod
    def do_action(cls, context: CommandContext, params: dict):
        if context.state["labeled_frame"] is None:
            return

        new_instances = []
        unused_predictions = context.state["labeled_frame"].unused_predictions
        for predicted_instance in unused_predictions:
            new_instance = cls.make_instance_from_predicted_instance(predicted_instance)
            cls.fill_missing_predicted_nodes(new_instance)
            new_instances.append(new_instance)

        # Add the instances
        for new_instance in new_instances:
            if new_instance not in context.state["labeled_frame"].instances:
                context.state["labeled_frame"].instances.append(new_instance)

            existing_tracks = [track.name for track in context.labels.tracks]
            if (
                new_instance.track is not None
                and new_instance.track.name not in existing_tracks
            ):
                context.labels.tracks.append(new_instance.track)

            if context.state["labeled_frame"] not in context.labels:
                context.labels.append(context.state["labeled_frame"])

            context.labels.update()

fill_missing_predicted_nodes(new_instance) staticmethod

Position undetected (NaN) nodes with a force-directed layout, hidden.

The model leaves occluded nodes at NaN coordinates, and make_instance_from_predicted_instance keeps them visible=False (correct -- the converted instance should look like the prediction). But a NaN coordinate renders at a default/garbage location when the user enables "show non-visible nodes" (QtInstance still creates a node item for every node in that mode, positioned at its xy).

Spread the missing nodes with a force-directed (spring) layout of the skeleton graph, centered on the detected keypoints' centroid and scaled to their extent, so they sit on the animal -- spread out and grabbable -- regardless of how many nodes the model detected, while staying visible=False. (Template/alignment placement is unreliable when only a few nodes are detected -- there is no way to infer where occluded nodes are from a couple of visible ones -- so a force-directed layout, one of the brand-new-instance init options, is used for robustness.) Already-detected points, the track, and from_predicted are untouched.

No GUI player is required. No-op when every node was detected, or when nothing was detected (no anchor for the layout center).

Parameters:

Name	Type	Description	Default
new_instance	Instance	The user Instance produced by make_instance_from_predicted_instance; modified in place.	required

Source code in sleap/gui/commands.py

@staticmethod
def fill_missing_predicted_nodes(new_instance: Instance):
    """Position undetected (NaN) nodes with a force-directed layout, hidden.

    The model leaves occluded nodes at NaN coordinates, and
    ``make_instance_from_predicted_instance`` keeps them ``visible=False``
    (correct -- the converted instance should look like the prediction). But
    a NaN coordinate renders at a default/garbage location when the user
    enables "show non-visible nodes" (``QtInstance`` still creates a node
    item for every node in that mode, positioned at its ``xy``).

    Spread the missing nodes with a force-directed (spring) layout of the
    skeleton graph, centered on the detected keypoints' centroid and scaled
    to their extent, so they sit on the animal -- spread out and grabbable --
    regardless of how many nodes the model detected, while staying
    ``visible=False``. (Template/alignment placement is unreliable when only
    a few nodes are detected -- there is no way to infer where occluded nodes
    are from a couple of visible ones -- so a force-directed layout, one of
    the brand-new-instance init options, is used for robustness.)
    Already-detected points, the track, and ``from_predicted`` are untouched.

    No GUI player is required. No-op when every node was detected, or when
    nothing was detected (no anchor for the layout center).

    Args:
        new_instance: The user ``Instance`` produced by
            ``make_instance_from_predicted_instance``; modified in place.
    """
    import networkx as nx

    xy = new_instance.points["xy"]
    missing = np.isnan(xy).any(axis=1)
    detected = ~missing
    if not missing.any() or not detected.any():
        return

    det_xy = xy[detected]
    center = det_xy.mean(axis=0)
    extent = float(np.linalg.norm(det_xy.max(axis=0) - det_xy.min(axis=0)))
    scale = max(extent / 2.0, 5.0)

    skeleton = new_instance.skeleton
    layout = nx.spring_layout(
        to_graph(skeleton), center=center, scale=scale, seed=0
    )
    pos_by_name = {
        (node if isinstance(node, str) else node.name): pos
        for node, pos in layout.items()
    }

    miss_idx = np.nonzero(missing)[0]
    fill_xy = np.array(
        [pos_by_name.get(skeleton.node_names[i], center) for i in miss_idx],
        dtype=float,
    )
    new_instance.points["xy"][missing] = fill_xy
    new_instance.points["visible"][missing] = False
    new_instance.points["complete"][missing] = False

make_instance_from_predicted_instance(copy_instance) staticmethod

Create a user Instance from a PredictedInstance.

Creates an empty Instance with proper PointsArray dtype, then copies coordinates and visibility from the prediction.

Parameters:

Name	Type	Description	Default
copy_instance	PredictedInstance	The PredictedInstance to convert.	required

Returns:

Type	Description
Instance	A new Instance with the same points, skeleton, and track, and from_predicted linking back to the original prediction.

Source code in sleap/gui/commands.py

@staticmethod
def make_instance_from_predicted_instance(
    copy_instance: PredictedInstance,
) -> Instance:
    """Create a user Instance from a PredictedInstance.

    Creates an empty Instance with proper PointsArray dtype, then copies
    coordinates and visibility from the prediction.

    Args:
        copy_instance: The PredictedInstance to convert.

    Returns:
        A new Instance with the same points, skeleton, and track,
        and from_predicted linking back to the original prediction.
    """
    # Create empty instance with proper PointsArray (not PredictedPointsArray)
    new_instance = Instance.empty(
        skeleton=copy_instance.skeleton,
        track=copy_instance.track,
        from_predicted=copy_instance,
    )

    # Copy point data from prediction. Predicted nodes that were not
    # detected have NaN coordinates; mark those as not visible so the
    # user instance starts in a well-defined state.
    for i, node in enumerate(copy_instance.skeleton.node_names):
        pred_point = copy_instance.points[i]
        xy_is_nan = bool(np.any(np.isnan(pred_point["xy"])))
        new_instance.points[i]["xy"] = pred_point["xy"]
        new_instance.points[i]["visible"] = (
            bool(pred_point["visible"]) and not xy_is_nan
        )
        new_instance.points[i]["complete"] = False

    return new_instance

AddVideo

Bases: EditCommand

Methods:

Name	Description
ask	Shows gui for adding video to project.

Source code in sleap/gui/commands.py

class AddVideo(EditCommand):
    topics = [UpdateTopic.video]

    @staticmethod
    def do_action(context: CommandContext, params: dict):
        import_list = params["import_list"]

        new_videos = ImportVideos.create_videos(import_list)
        video = None
        for video in new_videos:
            # Add to labels (labels_add_video handles duplicate prevention)
            labels_add_video(context.labels, video)
            context.labels.update()
            context.changestack_push("add video")

        # Load if no video currently loaded
        if context.state["video"] is None:
            context.state["video"] = video

    @staticmethod
    def ask(context: CommandContext, params: dict) -> bool:
        """Shows gui for adding video to project."""
        params["import_list"] = ImportVideos().ask()

        return len(params["import_list"]) > 0

ask(context, params) staticmethod

Shows gui for adding video to project.

Source code in sleap/gui/commands.py

@staticmethod
def ask(context: CommandContext, params: dict) -> bool:
    """Shows gui for adding video to project."""
    params["import_list"] = ImportVideos().ask()

    return len(params["import_list"]) > 0

AppCommand

Base class for specific commands.

Note that this is not an abstract base class. For specific commands, you should override ask and/or do_action methods, or add an ask_and_do method. In many cases you'll want to override the topics and does_edits attributes. That said, these are not virtual methods/attributes and have are implemented in the base class with default behaviors (i.e., doing nothing).

You should not override execute or do_with_signal.

Attributes:

Name	Type	Description
topics	List[UpdateTopic]	List of UpdateTopic items. Override this to indicate what should be updated after command is executed.
does_edits	bool	Whether command will modify data that could be saved.

Methods:

Name	Description
ask	Method for information gathering.
do_action	Method for performing action.
do_with_signal	Wrapper to perform action and notify/track changes.
execute	Entry point for running command.

Source code in sleap/gui/commands.py

class AppCommand:
    """Base class for specific commands.

    Note that this is not an abstract base class. For specific commands, you
    should override `ask` and/or `do_action` methods, or add an `ask_and_do`
    method. In many cases you'll want to override the `topics` and `does_edits`
    attributes. That said, these are not virtual methods/attributes and have
    are implemented in the base class with default behaviors (i.e., doing
    nothing).

    You should not override `execute` or `do_with_signal`.

    Attributes:
        topics: List of `UpdateTopic` items. Override this to indicate what
            should be updated after command is executed.
        does_edits: Whether command will modify data that could be saved.
    """

    topics: List[UpdateTopic] = []
    does_edits: bool = False

    def execute(self, context: "CommandContext", params: dict = None):
        """Entry point for running command.

        This calls internal methods to gather information required for
        execution, perform the action, and notify about changes.

        Ideally, any information gathering should be performed in the `ask`
        method, and be added to the `params` dictionary which then gets
        passed to `do_action`. The `ask` method should not modify state.

        (This will make it easier to add support for undo,
        using an `undo_action` which will be given the same `params`
        dictionary.)

        If it's not possible to easily separate information gathering from
        performing the action, the child class should implement `ask_and_do`,
        which it turn should call `do_with_signal` to notify about changes.

        Args:
            context: This is the `CommandContext` in which the command will
                execute. Commands will use this to access `MainWindow`,
                `GuiState`, and `Labels`.
            params: Dictionary of any params for command.
        """
        params = params or dict()

        if hasattr(self, "ask_and_do") and callable(self.ask_and_do):
            self.ask_and_do(context, params)
        else:
            okay = self.ask(context, params)
            if okay:
                self.do_with_signal(context, params)

    @staticmethod
    def ask(context: "CommandContext", params: dict) -> bool:
        """Method for information gathering.

        Returns:
            Whether to perform action. By default returns True, but this is
            where we should return False if we prompt user for confirmation
            and they abort.
        """
        return True

    @staticmethod
    def do_action(context: "CommandContext", params: dict):
        """Method for performing action."""
        pass

    @classmethod
    def do_with_signal(cls, context: "CommandContext", params: dict):
        """Wrapper to perform action and notify/track changes.

        Don't override this method!
        """
        cls.do_action(context, params)
        if cls.topics:
            context.signal_update(cls.topics)
        if cls.does_edits:
            context.changestack_push(cls.__name__)

ask(context, params) staticmethod

Method for information gathering.

Returns:

Type	Description
bool	Whether to perform action. By default returns True, but this is where we should return False if we prompt user for confirmation and they abort.

Source code in sleap/gui/commands.py

@staticmethod
def ask(context: "CommandContext", params: dict) -> bool:
    """Method for information gathering.

    Returns:
        Whether to perform action. By default returns True, but this is
        where we should return False if we prompt user for confirmation
        and they abort.
    """
    return True

do_action(context, params) staticmethod

Method for performing action.

Source code in sleap/gui/commands.py

@staticmethod
def do_action(context: "CommandContext", params: dict):
    """Method for performing action."""
    pass

do_with_signal(context, params) classmethod

Wrapper to perform action and notify/track changes.

Don't override this method!

Source code in sleap/gui/commands.py

@classmethod
def do_with_signal(cls, context: "CommandContext", params: dict):
    """Wrapper to perform action and notify/track changes.

    Don't override this method!
    """
    cls.do_action(context, params)
    if cls.topics:
        context.signal_update(cls.topics)
    if cls.does_edits:
        context.changestack_push(cls.__name__)

execute(context, params=None)

Entry point for running command.

This calls internal methods to gather information required for execution, perform the action, and notify about changes.

Ideally, any information gathering should be performed in the ask method, and be added to the params dictionary which then gets passed to do_action. The ask method should not modify state.

(This will make it easier to add support for undo, using an undo_action which will be given the same params dictionary.)

If it's not possible to easily separate information gathering from performing the action, the child class should implement ask_and_do, which it turn should call do_with_signal to notify about changes.

Parameters:

Name	Type	Description	Default
context	'CommandContext'	This is the CommandContext in which the command will execute. Commands will use this to access MainWindow, GuiState, and Labels.	required
params	dict	Dictionary of any params for command.	None

Source code in sleap/gui/commands.py

def execute(self, context: "CommandContext", params: dict = None):
    """Entry point for running command.

    This calls internal methods to gather information required for
    execution, perform the action, and notify about changes.

    Ideally, any information gathering should be performed in the `ask`
    method, and be added to the `params` dictionary which then gets
    passed to `do_action`. The `ask` method should not modify state.

    (This will make it easier to add support for undo,
    using an `undo_action` which will be given the same `params`
    dictionary.)

    If it's not possible to easily separate information gathering from
    performing the action, the child class should implement `ask_and_do`,
    which it turn should call `do_with_signal` to notify about changes.

    Args:
        context: This is the `CommandContext` in which the command will
            execute. Commands will use this to access `MainWindow`,
            `GuiState`, and `Labels`.
        params: Dictionary of any params for command.
    """
    params = params or dict()

    if hasattr(self, "ask_and_do") and callable(self.ask_and_do):
        self.ask_and_do(context, params)
    else:
        okay = self.ask(context, params)
        if okay:
            self.do_with_signal(context, params)

CommandContext

Context within in which commands are executed.

When you create a new command, you should both create a class for the command (which inherits from CommandClass) and add a distinct method for the command in the CommandContext class. This method is what should be connected/called from other code to invoke the command.

Attributes:

Name	Type	Description
state	GuiState	The GuiState object used to store state and pass messages.
app	'MainWindow'	The MainWindow, available for commands that modify the app.
update_callback	Optional[Callable]	A callback to receive update notifications. This function should accept a list of UpdateTopic items.

Methods:

Name	Description
addCurrentFrameAsSuggestion	Add current frame as a suggestion.
addTrack	Creates new track and moves selected instance into this track.
addUserInstancesFromAllPredictions	Create user instances from all predicted instances across all frames.
addUserInstancesFromPredictions	Create user instance from a predicted instance.
addVideo	Shows gui for adding videos to project.
changestack_clear	Clears stack of changes.
changestack_push	Adds to stack of changes made by user.
changestack_savepoint	Marks that project was just saved.
clearSuggestions	Clear all suggestions.
completeInstanceNodes	Adds missing nodes to given instance.
copyInstance	Copy the selected instance to the instance clipboard.
copyInstanceTrack	Copies the selected instance's track to the track clipboard.
deleteAreaPredictions	Gui for deleting instances within some rect on frame images.
deleteClipPredictions	Deletes all predictions within selected range of video frames.
deleteDialog	Deletes using options selected in a dialog.
deleteEdge	Removes (currently selected) edge from skeleton.
deleteFrameLimitPredictions	Gui for deleting instances beyond some frame number.
deleteFramePredictions	Deletes all predictions on current frame.
deleteInstanceLimitPredictions	Gui for deleting instances beyond some number in each frame.
deleteLowScorePredictions	Gui for deleting instances below some score threshold.
deleteMultipleTracks	Delete all tracks.
deleteNode	Removes (currently selected) node from skeleton.
deletePredictions	Deletes all predicted instances in project.
deleteSelectedInstance	Deletes currently selected instance.
deleteSelectedInstanceTrack	Deletes all instances from track of currently selected instance.
deleteTrack	Delete a track and remove from all instances.
deleteUserFramePredictions	Gui for deleting predictions on frames with user instances.
execute	Execute command in this context, passing named arguments.
exportAnalysisFile	Shows gui for exporting analysis h5 file.
exportCSVFile	Shows gui for exporting analysis csv file.
exportFullPackage	Gui for exporting the dataset with any labeled frames and suggestions.
exportLabeledClip	Shows gui for exporting clip with visual annotations.
exportLabelsSubset	Exports a selected range of video frames and their corresponding labels.
exportNWB	Show gui for exporting nwb file.
exportTrainingPackage	Gui for exporting the dataset with user-labeled images and suggestions.
exportUserLabelsPackage	Gui for exporting the dataset with user-labeled images.
from_labels	Creates a command context for use independently of GUI app.
generateSuggestions	Generates suggestions using given params dictionary.
gotoFrame	Shows gui to go to frame by number.
gotoVideoAndFrame	Activates video and goes to frame.
gotoVideoAndFrameAndInstance	Activates video, goes to frame, and highlights instance.
importAnalysisFile	Imports SLEAP analysis hdf5 files.
importCoco	Imports COCO datasets.
importDLC	Imports DeepLabCut datasets.
importDLCFolder	Imports multiple DeepLabCut datasets.
importNWB	Imports NWB datasets.
lastInteractedFrame	Goes to last frame that user interacted with.
loadLabelsObject	Loads a Labels object into the GUI, replacing any currently loaded.
loadProjectFile	Loads given labels file into GUI.
mergeInstance	Merge another user instance in the frame into the selected one.
mergeProject	Starts gui for importing another dataset into currently one.
newEdge	Adds new edge to skeleton.
newInstance	Creates a new instance, copying node coordinates as appropriate.
newNode	Adds new node to skeleton.
newProject	Create a new project in a new window.
nextLabeledFrame	Goes to labeled frame after current frame.
nextSuggestedFrame	Goes to next suggested frame.
nextTrackFrame	Goes to next frame on which a track starts.
nextUserLabeledFrame	Goes to next labeled frame with user instances.
openProject	Allows user to select and then open a saved project.
openSkeleton	Shows gui for loading saved skeleton into project.
openSkeletonTemplate	Shows gui for loading saved skeleton into project.
openWebsite	Open a website from URL using the native system browser.
pasteInstance	Paste the instance from the clipboard as a new copy.
pasteInstanceTrack	Pastes the track in the clipboard to the selected instance.
prevSuggestedFrame	Goes to previous suggested frame.
prevUserLabeledFrame	Goes to previous labeled frame with user instances.
previousLabeledFrame	Goes to labeled frame prior to current frame.
removeSuggestion	Remove the selected frame from suggestions.
removeVideo	Removes selected video from project.
replaceVideo	Shows gui for replacing videos to project.
saveProject	Show gui to save project (or save as if not yet saved).
saveProjectAs	Show gui to save project as a new file.
saveSkeleton	Shows gui for saving skeleton from project.
selectToFrame	Shows gui to go to frame by number.
setInstancePointVisibility	Toggles visibility set for a node for an instance.
setInstanceTrack	Sets track for selected instance.
setNodeName	Changes name of node in skeleton.
setNodeSymmetry	Sets node symmetry in skeleton.
setPointLocations	Sets locations for node(s) for an instance.
setTrackName	Sets name for track.
showImportVideos	Show video importer GUI without the file browser.
signal_update	Calls the update callback after data has been changed.
toggleCurrentFrameNegative	Mark or unmark the current frame as a negative (background) frame.
toggleGrayscale	Toggles grayscale setting for current video.
transposeInstance	Transposes tracks for two instances.
updateEdges	Called when edges in skeleton have been changed.

Source code in sleap/gui/commands.py

@attr.s(auto_attribs=True, eq=False)
class CommandContext:
    """
    Context within in which commands are executed.

    When you create a new command, you should both create a class for the
    command (which inherits from `CommandClass`) and add a distinct method
    for the command in the `CommandContext` class. This method is what should
    be connected/called from other code to invoke the command.

    Attributes:
        state: The `GuiState` object used to store state and pass messages.
        app: The `MainWindow`, available for commands that modify the app.
        update_callback: A callback to receive update notifications.
            This function should accept a list of `UpdateTopic` items.
    """

    state: GuiState
    app: "MainWindow"

    update_callback: Optional[Callable] = None
    _change_stack: List = attr.ib(default=attr.Factory(list))

    @classmethod
    def from_labels(cls, labels: Labels) -> "CommandContext":
        """Creates a command context for use independently of GUI app."""
        state = GuiState()
        state["labels"] = labels
        app = FakeApp(labels)
        return cls(state=state, app=app)

    @property
    def labels(self) -> Labels:
        """Alias to app.labels."""
        return self.app.labels

    def signal_update(self, what: List[UpdateTopic]):
        """Calls the update callback after data has been changed."""
        if callable(self.update_callback):
            self.update_callback(what)

    def changestack_push(self, change: str = ""):
        """Adds to stack of changes made by user."""
        # Currently the change doesn't store any data, and we're only using this
        # to determine if there are unsaved changes. Eventually we could use this
        # to support undo/redo.
        self._change_stack.append(change)
        # print(len(self._change_stack))
        self.state["has_changes"] = True

    def changestack_savepoint(self):
        """Marks that project was just saved."""
        self.changestack_push("SAVE")
        self.state["has_changes"] = False

    def changestack_clear(self):
        """Clears stack of changes."""
        self._change_stack = list()
        self.state["has_changes"] = False

    @property
    def has_any_changes(self):
        return len(self._change_stack) > 0

    def execute(self, command: Type[AppCommand], **kwargs):
        """Execute command in this context, passing named arguments."""
        command().execute(context=self, params=kwargs)

    # File commands

    def newProject(self):
        """Create a new project in a new window."""
        self.execute(NewProject)

    def loadLabelsObject(self, labels: Labels, filename: Optional[str] = None):
        """Loads a `Labels` object into the GUI, replacing any currently loaded.

        Args:
            labels: The `Labels` object to load.
            filename: The filename where this file is saved, if any.

        Returns:
            None.

        """
        self.execute(LoadLabelsObject, labels=labels, filename=filename)

    def loadProjectFile(self, filename: Union[str, Labels]):
        """Loads given labels file into GUI.

        Args:
            filename: The path to the saved labels dataset or the `Labels` object.
                If None, then don't do anything.

        Returns:
            None
        """
        self.execute(LoadProjectFile, filename=filename)

    def openProject(self, filename: Optional[str] = None, first_open: bool = False):
        """Allows user to select and then open a saved project.

        Args:
            filename: Filename of the project to be opened. If None, a file browser
                dialog will prompt the user for a path.
            first_open: Whether this is the first window opened. If True,
                then the new project is loaded into the current window
                rather than a new application window.

        Returns:
            None.
        """
        self.execute(OpenProject, filename=filename, first_open=first_open)

    def importNWB(self):
        """Imports NWB datasets."""
        self.execute(ImportNWB)

    def importCoco(self):
        """Imports COCO datasets."""
        self.execute(ImportCoco)

    def importDLC(self):
        """Imports DeepLabCut datasets."""
        self.execute(ImportDeepLabCut)

    def importDLCFolder(self):
        """Imports multiple DeepLabCut datasets."""
        self.execute(ImportDeepLabCutFolder)

    def importAnalysisFile(self):
        """Imports SLEAP analysis hdf5 files."""
        self.execute(ImportAnalysisFile)

    def saveProject(self):
        """Show gui to save project (or save as if not yet saved)."""
        self.execute(SaveProject)

    def saveProjectAs(self):
        """Show gui to save project as a new file."""
        self.execute(SaveProjectAs)

    def exportAnalysisFile(self, all_videos: bool = False):
        """Shows gui for exporting analysis h5 file."""
        self.execute(ExportAnalysisFile, all_videos=all_videos, csv=False)

    def exportCSVFile(self, all_videos: bool = False):
        """Shows gui for exporting analysis csv file."""
        self.execute(ExportAnalysisFile, all_videos=all_videos, csv=True)

    def exportNWB(self):
        """Show gui for exporting nwb file."""
        self.execute(SaveProjectAs, adaptor="nwb")

    def exportLabeledClip(self):
        """Shows gui for exporting clip with visual annotations."""
        self.execute(ExportLabeledClip)

    def exportUserLabelsPackage(self):
        """Gui for exporting the dataset with user-labeled images."""
        self.execute(ExportUserLabelsPackage)

    def exportTrainingPackage(self):
        """Gui for exporting the dataset with user-labeled images and suggestions."""
        self.execute(ExportTrainingPackage)

    def exportFullPackage(self):
        """Gui for exporting the dataset with any labeled frames and suggestions."""
        self.execute(ExportFullPackage)

    # Navigation Commands

    def previousLabeledFrame(self):
        """Goes to labeled frame prior to current frame."""
        self.execute(GoPreviousLabeledFrame)

    def nextLabeledFrame(self):
        """Goes to labeled frame after current frame."""
        self.execute(GoNextLabeledFrame)

    def nextUserLabeledFrame(self):
        """Goes to next labeled frame with user instances."""
        self.execute(GoNextUserLabeledFrame)

    def prevUserLabeledFrame(self):
        """Goes to previous labeled frame with user instances."""
        self.execute(GoPrevUserLabeledFrame)

    def lastInteractedFrame(self):
        """Goes to last frame that user interacted with."""
        self.execute(GoLastInteractedFrame)

    def nextSuggestedFrame(self):
        """Goes to next suggested frame."""
        self.execute(GoNextSuggestedFrame)

    def prevSuggestedFrame(self):
        """Goes to previous suggested frame."""
        self.execute(GoPrevSuggestedFrame)

    def addCurrentFrameAsSuggestion(self):
        """Add current frame as a suggestion."""
        self.execute(AddSuggestion)

    def removeSuggestion(self):
        """Remove the selected frame from suggestions."""
        self.execute(RemoveSuggestion)

    def clearSuggestions(self):
        """Clear all suggestions."""
        self.execute(ClearSuggestions)

    def nextTrackFrame(self):
        """Goes to next frame on which a track starts."""
        self.execute(GoNextTrackFrame)

    def gotoFrame(self):
        """Shows gui to go to frame by number."""
        self.execute(GoFrameGui)

    def selectToFrame(self):
        """Shows gui to go to frame by number."""
        self.execute(SelectToFrameGui)

    def gotoVideoAndFrame(self, video: Video, frame_idx: int):
        """Activates video and goes to frame."""
        NavCommand.go_to(self, frame_idx, video)

    def gotoVideoAndFrameAndInstance(
        self, video: Video, frame_idx: int, instance_idx: int
    ):
        """Activates video, goes to frame, and highlights instance.

        This is used when navigating from the Size Distribution widget to
        highlight which specific instance was clicked.

        Args:
            video: Video to navigate to.
            frame_idx: Frame index to navigate to.
            instance_idx: Index of user instance within the frame to highlight.
        """
        NavCommand.go_to(self, frame_idx, video)

        # Look up the actual Instance object from labels
        # instance_idx is the index within user_instances (not all instances)
        instance_to_highlight = None
        lfs = self.labels.find(video, frame_idx)
        if lfs:
            lf = lfs[0]
            user_instances = lf.user_instances if hasattr(lf, "user_instances") else []
            if 0 <= instance_idx < len(user_instances):
                instance_to_highlight = user_instances[instance_idx]

        # Make the navigated instance the app-selected instance (not just a
        # player-view highlight) so anything keyed off ``state["instance"]``
        # follows it -- in particular the Label QC display modes (#2783), which
        # focus on the selected instance. Without this, navigating to a flagged
        # instance left ``state["instance"]`` unchanged, so those modes saw no
        # on-frame selection and fell back to the first instance.
        if instance_to_highlight is not None:
            self.state["instance"] = instance_to_highlight

        # Use a timer to highlight and select after the frame is redrawn
        # (state changes trigger plot() which recreates instances via overlay)
        player = getattr(self.app, "player", None)
        if player is not None and instance_to_highlight is not None:

            def _highlight_select_and_zoom():
                # Highlight the instance (cyan box)
                player.highlightNavigatedInstance(instance_to_highlight)
                # Select the instance so zoomToSelection works
                player.view.selectInstance(instance_to_highlight)
                # Zoom to selection if enabled
                if self.state.get("fit_selection", False):
                    player.zoomToSelection()

            # Small delay to ensure overlay has added instances to scene
            QtCore.QTimer.singleShot(50, _highlight_select_and_zoom)

    # Editing Commands

    def toggleGrayscale(self):
        """Toggles grayscale setting for current video."""
        self.execute(ToggleGrayscale)

    def addVideo(self):
        """Shows gui for adding videos to project."""
        self.execute(AddVideo)

    def showImportVideos(self, filenames: List[str]):
        """Show video importer GUI without the file browser."""
        self.execute(ShowImportVideos, filenames=filenames)

    def replaceVideo(self):
        """Shows gui for replacing videos to project."""
        self.execute(ReplaceVideo)

    def removeVideo(self):
        """Removes selected video from project."""
        self.execute(RemoveVideo)

    def openSkeletonTemplate(self):
        """Shows gui for loading saved skeleton into project."""
        self.execute(OpenSkeleton, template=True)

    def openSkeleton(self):
        """Shows gui for loading saved skeleton into project."""
        self.execute(OpenSkeleton)

    def saveSkeleton(self):
        """Shows gui for saving skeleton from project."""
        self.execute(SaveSkeleton)

    def newNode(self):
        """Adds new node to skeleton."""
        self.execute(NewNode)

    def deleteNode(self):
        """Removes (currently selected) node from skeleton."""
        self.execute(DeleteNode)

    def setNodeName(self, skeleton, node, name):
        """Changes name of node in skeleton."""
        self.execute(SetNodeName, skeleton=skeleton, node=node, name=name)

    def setNodeSymmetry(self, skeleton, node, symmetry: str):
        """Sets node symmetry in skeleton."""
        self.execute(SetNodeSymmetry, skeleton=skeleton, node=node, symmetry=symmetry)

    def updateEdges(self):
        """Called when edges in skeleton have been changed."""
        self.signal_update([UpdateTopic.skeleton])

    def newEdge(self, src_node, dst_node):
        """Adds new edge to skeleton."""
        self.execute(NewEdge, src_node=src_node, dst_node=dst_node)

    def deleteEdge(self):
        """Removes (currently selected) edge from skeleton."""
        self.execute(DeleteEdge)

    def deletePredictions(self):
        """Deletes all predicted instances in project."""
        self.execute(DeleteAllPredictions)

    def deleteFramePredictions(self):
        """Deletes all predictions on current frame."""
        self.execute(DeleteFramePredictions)

    def deleteClipPredictions(self):
        """Deletes all predictions within selected range of video frames."""
        self.execute(DeleteClipPredictions)

    def deleteAreaPredictions(self):
        """Gui for deleting instances within some rect on frame images."""
        self.execute(DeleteAreaPredictions)

    def deleteLowScorePredictions(self):
        """Gui for deleting instances below some score threshold."""
        self.execute(DeleteLowScorePredictions)

    def deleteInstanceLimitPredictions(self):
        """Gui for deleting instances beyond some number in each frame."""
        self.execute(DeleteInstanceLimitPredictions)

    def deleteFrameLimitPredictions(self):
        """Gui for deleting instances beyond some frame number."""
        self.execute(DeleteFrameLimitPredictions)

    def deleteUserFramePredictions(self):
        """Gui for deleting predictions on frames with user instances."""
        self.execute(DeleteUserFramePredictions)

    def completeInstanceNodes(self, instance: Instance):
        """Adds missing nodes to given instance."""
        self.execute(AddMissingInstanceNodes, instance=instance)

    def newInstance(
        self,
        copy_instance: Optional[Instance] = None,
        init_method: str = "best",
        location: Optional[QtCore.QPoint] = None,
        mark_complete: bool = False,
        offset: int = 0,
    ):
        """Creates a new instance, copying node coordinates as appropriate.

        Args:
            copy_instance: The :class:`Instance` (or
                :class:`PredictedInstance`) which we want to copy.
            init_method: Method to use for positioning nodes.
            location: The location where instance should be added (if node init
                method supports custom location).
            mark_complete: Whether to mark the instance as complete.
            offset: Offset to apply to the location if given.
        """
        self.execute(
            AddInstance,
            copy_instance=copy_instance,
            init_method=init_method,
            location=location,
            mark_complete=mark_complete,
            offset=offset,
        )

    def setPointLocations(
        self, instance: Instance, nodes_locations: Dict[Node, Tuple[int, int]]
    ):
        """Sets locations for node(s) for an instance."""
        self.execute(
            SetInstancePointLocations,
            instance=instance,
            nodes_locations=nodes_locations,
        )

    def setInstancePointVisibility(self, instance: Instance, node: Node, visible: bool):
        """Toggles visibility set for a node for an instance."""
        self.execute(
            SetInstancePointVisibility, instance=instance, node=node, visible=visible
        )

    def addUserInstancesFromPredictions(self):
        """Create user instance from a predicted instance."""
        self.execute(AddUserInstancesFromPredictions)

    def addUserInstancesFromAllPredictions(self):
        """Create user instances from all predicted instances across all frames."""
        self.execute(AddUserInstancesFromAllPredictions)

    def toggleCurrentFrameNegative(self):
        """Mark or unmark the current frame as a negative (background) frame."""
        self.execute(ToggleNegativeFrame)

    def copyInstance(self):
        """Copy the selected instance to the instance clipboard."""
        self.execute(CopyInstance)

    def pasteInstance(self):
        """Paste the instance from the clipboard as a new copy."""
        self.execute(PasteInstance)

    def deleteSelectedInstance(self):
        """Deletes currently selected instance."""
        self.execute(DeleteSelectedInstance)

    def mergeInstance(self, donor: Optional["Instance"] = None):
        """Merge another user instance in the frame into the selected one.

        The selected instance is kept (survivor) and gains the donor's labeled
        keypoints for any nodes it is missing. If `donor` is None and the frame
        has exactly two user instances, the other one is used as the donor.
        """
        self.execute(MergeInstances, donor=donor)

    def deleteSelectedInstanceTrack(self):
        """Deletes all instances from track of currently selected instance."""
        self.execute(DeleteSelectedInstanceTrack)

    def deleteDialog(self):
        """Deletes using options selected in a dialog."""
        self.execute(DeleteDialogCommand)

    def addTrack(self):
        """Creates new track and moves selected instance into this track."""
        self.execute(AddTrack)

    def setInstanceTrack(self, new_track: "Track"):
        """Sets track for selected instance."""
        self.execute(SetSelectedInstanceTrack, new_track=new_track)

    def deleteTrack(self, track: "Track"):
        """Delete a track and remove from all instances."""
        self.execute(DeleteTrack, track=track)

    def deleteMultipleTracks(self, delete_all: bool = False):
        """Delete all tracks."""
        self.execute(DeleteMultipleTracks, delete_all=delete_all)

    def copyInstanceTrack(self):
        """Copies the selected instance's track to the track clipboard."""
        self.execute(CopyInstanceTrack)

    def pasteInstanceTrack(self):
        """Pastes the track in the clipboard to the selected instance."""
        self.execute(PasteInstanceTrack)

    def setTrackName(self, track: "Track", name: str):
        """Sets name for track."""
        self.execute(SetTrackName, track=track, name=name)

    def transposeInstance(self):
        """Transposes tracks for two instances.

        If there are only two instances, then this swaps tracks.
        Otherwise, it allows user to select the instances for which we want
        to swap tracks.
        """
        self.execute(TransposeInstances)

    def mergeProject(self, filenames: Optional[List[str]] = None):
        """Starts gui for importing another dataset into currently one."""
        self.execute(MergeProject, filenames=filenames)

    def generateSuggestions(self, params: Dict):
        """Generates suggestions using given params dictionary."""
        self.execute(GenerateSuggestions, **params)

    def openWebsite(self, url):
        """Open a website from URL using the native system browser."""
        self.execute(OpenWebsite, url=url)

    def exportLabelsSubset(
        self, as_package: bool = False, open_new_project: bool = True
    ):
        """Exports a selected range of video frames and their corresponding labels.

        Args:
            as_package: Whether to export as a package.
            open_new_project: Whether to open the exported labels in a new project GUI.
        """
        self.execute(
            ExportLabelsSubset, as_package=as_package, open_new_project=open_new_project
        )

labels property

Alias to app.labels.

addCurrentFrameAsSuggestion()

Add current frame as a suggestion.

Source code in sleap/gui/commands.py

def addCurrentFrameAsSuggestion(self):
    """Add current frame as a suggestion."""
    self.execute(AddSuggestion)

addTrack()

Creates new track and moves selected instance into this track.

Source code in sleap/gui/commands.py

def addTrack(self):
    """Creates new track and moves selected instance into this track."""
    self.execute(AddTrack)

addUserInstancesFromAllPredictions()

Create user instances from all predicted instances across all frames.

Source code in sleap/gui/commands.py

def addUserInstancesFromAllPredictions(self):
    """Create user instances from all predicted instances across all frames."""
    self.execute(AddUserInstancesFromAllPredictions)

addUserInstancesFromPredictions()

Create user instance from a predicted instance.

Source code in sleap/gui/commands.py

def addUserInstancesFromPredictions(self):
    """Create user instance from a predicted instance."""
    self.execute(AddUserInstancesFromPredictions)

addVideo()

Shows gui for adding videos to project.

Source code in sleap/gui/commands.py

def addVideo(self):
    """Shows gui for adding videos to project."""
    self.execute(AddVideo)

changestack_clear()

Clears stack of changes.

Source code in sleap/gui/commands.py

def changestack_clear(self):
    """Clears stack of changes."""
    self._change_stack = list()
    self.state["has_changes"] = False

changestack_push(change='')

Adds to stack of changes made by user.

Source code in sleap/gui/commands.py

def changestack_push(self, change: str = ""):
    """Adds to stack of changes made by user."""
    # Currently the change doesn't store any data, and we're only using this
    # to determine if there are unsaved changes. Eventually we could use this
    # to support undo/redo.
    self._change_stack.append(change)
    # print(len(self._change_stack))
    self.state["has_changes"] = True

changestack_savepoint()

Marks that project was just saved.

Source code in sleap/gui/commands.py

def changestack_savepoint(self):
    """Marks that project was just saved."""
    self.changestack_push("SAVE")
    self.state["has_changes"] = False

clearSuggestions()

Clear all suggestions.

Source code in sleap/gui/commands.py

def clearSuggestions(self):
    """Clear all suggestions."""
    self.execute(ClearSuggestions)

completeInstanceNodes(instance)

Adds missing nodes to given instance.

Source code in sleap/gui/commands.py

def completeInstanceNodes(self, instance: Instance):
    """Adds missing nodes to given instance."""
    self.execute(AddMissingInstanceNodes, instance=instance)

copyInstance()

Copy the selected instance to the instance clipboard.

Source code in sleap/gui/commands.py

def copyInstance(self):
    """Copy the selected instance to the instance clipboard."""
    self.execute(CopyInstance)

copyInstanceTrack()

Copies the selected instance's track to the track clipboard.

Source code in sleap/gui/commands.py

def copyInstanceTrack(self):
    """Copies the selected instance's track to the track clipboard."""
    self.execute(CopyInstanceTrack)

deleteAreaPredictions()

Gui for deleting instances within some rect on frame images.

Source code in sleap/gui/commands.py

def deleteAreaPredictions(self):
    """Gui for deleting instances within some rect on frame images."""
    self.execute(DeleteAreaPredictions)

deleteClipPredictions()

Deletes all predictions within selected range of video frames.

Source code in sleap/gui/commands.py

def deleteClipPredictions(self):
    """Deletes all predictions within selected range of video frames."""
    self.execute(DeleteClipPredictions)

deleteDialog()

Deletes using options selected in a dialog.

Source code in sleap/gui/commands.py

def deleteDialog(self):
    """Deletes using options selected in a dialog."""
    self.execute(DeleteDialogCommand)

deleteEdge()

Removes (currently selected) edge from skeleton.

Source code in sleap/gui/commands.py

def deleteEdge(self):
    """Removes (currently selected) edge from skeleton."""
    self.execute(DeleteEdge)

deleteFrameLimitPredictions()

Gui for deleting instances beyond some frame number.

Source code in sleap/gui/commands.py

def deleteFrameLimitPredictions(self):
    """Gui for deleting instances beyond some frame number."""
    self.execute(DeleteFrameLimitPredictions)

deleteFramePredictions()

Deletes all predictions on current frame.

Source code in sleap/gui/commands.py

def deleteFramePredictions(self):
    """Deletes all predictions on current frame."""
    self.execute(DeleteFramePredictions)

deleteInstanceLimitPredictions()

Gui for deleting instances beyond some number in each frame.

Source code in sleap/gui/commands.py

def deleteInstanceLimitPredictions(self):
    """Gui for deleting instances beyond some number in each frame."""
    self.execute(DeleteInstanceLimitPredictions)

deleteLowScorePredictions()

Gui for deleting instances below some score threshold.

Source code in sleap/gui/commands.py

def deleteLowScorePredictions(self):
    """Gui for deleting instances below some score threshold."""
    self.execute(DeleteLowScorePredictions)

deleteMultipleTracks(delete_all=False)

Delete all tracks.

Source code in sleap/gui/commands.py

def deleteMultipleTracks(self, delete_all: bool = False):
    """Delete all tracks."""
    self.execute(DeleteMultipleTracks, delete_all=delete_all)

deleteNode()

Removes (currently selected) node from skeleton.

Source code in sleap/gui/commands.py

def deleteNode(self):
    """Removes (currently selected) node from skeleton."""
    self.execute(DeleteNode)

deletePredictions()

Deletes all predicted instances in project.

Source code in sleap/gui/commands.py

def deletePredictions(self):
    """Deletes all predicted instances in project."""
    self.execute(DeleteAllPredictions)

deleteSelectedInstance()

Deletes currently selected instance.

Source code in sleap/gui/commands.py

def deleteSelectedInstance(self):
    """Deletes currently selected instance."""
    self.execute(DeleteSelectedInstance)

deleteSelectedInstanceTrack()

Deletes all instances from track of currently selected instance.

Source code in sleap/gui/commands.py

def deleteSelectedInstanceTrack(self):
    """Deletes all instances from track of currently selected instance."""
    self.execute(DeleteSelectedInstanceTrack)

deleteTrack(track)

Delete a track and remove from all instances.

Source code in sleap/gui/commands.py

def deleteTrack(self, track: "Track"):
    """Delete a track and remove from all instances."""
    self.execute(DeleteTrack, track=track)

deleteUserFramePredictions()

Gui for deleting predictions on frames with user instances.

Source code in sleap/gui/commands.py

def deleteUserFramePredictions(self):
    """Gui for deleting predictions on frames with user instances."""
    self.execute(DeleteUserFramePredictions)

execute(command, **kwargs)

Execute command in this context, passing named arguments.

Source code in sleap/gui/commands.py

def execute(self, command: Type[AppCommand], **kwargs):
    """Execute command in this context, passing named arguments."""
    command().execute(context=self, params=kwargs)

exportAnalysisFile(all_videos=False)

Shows gui for exporting analysis h5 file.

Source code in sleap/gui/commands.py

def exportAnalysisFile(self, all_videos: bool = False):
    """Shows gui for exporting analysis h5 file."""
    self.execute(ExportAnalysisFile, all_videos=all_videos, csv=False)

exportCSVFile(all_videos=False)

Shows gui for exporting analysis csv file.

Source code in sleap/gui/commands.py

def exportCSVFile(self, all_videos: bool = False):
    """Shows gui for exporting analysis csv file."""
    self.execute(ExportAnalysisFile, all_videos=all_videos, csv=True)

exportFullPackage()

Gui for exporting the dataset with any labeled frames and suggestions.

Source code in sleap/gui/commands.py

def exportFullPackage(self):
    """Gui for exporting the dataset with any labeled frames and suggestions."""
    self.execute(ExportFullPackage)

exportLabeledClip()

Shows gui for exporting clip with visual annotations.

Source code in sleap/gui/commands.py

def exportLabeledClip(self):
    """Shows gui for exporting clip with visual annotations."""
    self.execute(ExportLabeledClip)

exportLabelsSubset(as_package=False, open_new_project=True)

Exports a selected range of video frames and their corresponding labels.

Parameters:

Name	Type	Description	Default
as_package	bool	Whether to export as a package.	False
open_new_project	bool	Whether to open the exported labels in a new project GUI.	True

Source code in sleap/gui/commands.py

def exportLabelsSubset(
    self, as_package: bool = False, open_new_project: bool = True
):
    """Exports a selected range of video frames and their corresponding labels.

    Args:
        as_package: Whether to export as a package.
        open_new_project: Whether to open the exported labels in a new project GUI.
    """
    self.execute(
        ExportLabelsSubset, as_package=as_package, open_new_project=open_new_project
    )

exportNWB()

Show gui for exporting nwb file.

Source code in sleap/gui/commands.py

def exportNWB(self):
    """Show gui for exporting nwb file."""
    self.execute(SaveProjectAs, adaptor="nwb")

exportTrainingPackage()

Gui for exporting the dataset with user-labeled images and suggestions.

Source code in sleap/gui/commands.py

def exportTrainingPackage(self):
    """Gui for exporting the dataset with user-labeled images and suggestions."""
    self.execute(ExportTrainingPackage)

exportUserLabelsPackage()

Gui for exporting the dataset with user-labeled images.

Source code in sleap/gui/commands.py

def exportUserLabelsPackage(self):
    """Gui for exporting the dataset with user-labeled images."""
    self.execute(ExportUserLabelsPackage)

from_labels(labels) classmethod

Creates a command context for use independently of GUI app.

Source code in sleap/gui/commands.py

@classmethod
def from_labels(cls, labels: Labels) -> "CommandContext":
    """Creates a command context for use independently of GUI app."""
    state = GuiState()
    state["labels"] = labels
    app = FakeApp(labels)
    return cls(state=state, app=app)

generateSuggestions(params)

Generates suggestions using given params dictionary.

Source code in sleap/gui/commands.py

def generateSuggestions(self, params: Dict):
    """Generates suggestions using given params dictionary."""
    self.execute(GenerateSuggestions, **params)

gotoFrame()

Shows gui to go to frame by number.

Source code in sleap/gui/commands.py

def gotoFrame(self):
    """Shows gui to go to frame by number."""
    self.execute(GoFrameGui)

gotoVideoAndFrame(video, frame_idx)

Activates video and goes to frame.

Source code in sleap/gui/commands.py

def gotoVideoAndFrame(self, video: Video, frame_idx: int):
    """Activates video and goes to frame."""
    NavCommand.go_to(self, frame_idx, video)

gotoVideoAndFrameAndInstance(video, frame_idx, instance_idx)

Activates video, goes to frame, and highlights instance.

This is used when navigating from the Size Distribution widget to highlight which specific instance was clicked.

Parameters:

Name	Type	Description	Default
video	Video	Video to navigate to.	required
frame_idx	int	Frame index to navigate to.	required
instance_idx	int	Index of user instance within the frame to highlight.	required

Source code in sleap/gui/commands.py

def gotoVideoAndFrameAndInstance(
    self, video: Video, frame_idx: int, instance_idx: int
):
    """Activates video, goes to frame, and highlights instance.

    This is used when navigating from the Size Distribution widget to
    highlight which specific instance was clicked.

    Args:
        video: Video to navigate to.
        frame_idx: Frame index to navigate to.
        instance_idx: Index of user instance within the frame to highlight.
    """
    NavCommand.go_to(self, frame_idx, video)

    # Look up the actual Instance object from labels
    # instance_idx is the index within user_instances (not all instances)
    instance_to_highlight = None
    lfs = self.labels.find(video, frame_idx)
    if lfs:
        lf = lfs[0]
        user_instances = lf.user_instances if hasattr(lf, "user_instances") else []
        if 0 <= instance_idx < len(user_instances):
            instance_to_highlight = user_instances[instance_idx]

    # Make the navigated instance the app-selected instance (not just a
    # player-view highlight) so anything keyed off ``state["instance"]``
    # follows it -- in particular the Label QC display modes (#2783), which
    # focus on the selected instance. Without this, navigating to a flagged
    # instance left ``state["instance"]`` unchanged, so those modes saw no
    # on-frame selection and fell back to the first instance.
    if instance_to_highlight is not None:
        self.state["instance"] = instance_to_highlight

    # Use a timer to highlight and select after the frame is redrawn
    # (state changes trigger plot() which recreates instances via overlay)
    player = getattr(self.app, "player", None)
    if player is not None and instance_to_highlight is not None:

        def _highlight_select_and_zoom():
            # Highlight the instance (cyan box)
            player.highlightNavigatedInstance(instance_to_highlight)
            # Select the instance so zoomToSelection works
            player.view.selectInstance(instance_to_highlight)
            # Zoom to selection if enabled
            if self.state.get("fit_selection", False):
                player.zoomToSelection()

        # Small delay to ensure overlay has added instances to scene
        QtCore.QTimer.singleShot(50, _highlight_select_and_zoom)

importAnalysisFile()

Imports SLEAP analysis hdf5 files.

Source code in sleap/gui/commands.py

def importAnalysisFile(self):
    """Imports SLEAP analysis hdf5 files."""
    self.execute(ImportAnalysisFile)

importCoco()

Imports COCO datasets.

Source code in sleap/gui/commands.py

def importCoco(self):
    """Imports COCO datasets."""
    self.execute(ImportCoco)

importDLC()

Imports DeepLabCut datasets.

Source code in sleap/gui/commands.py

def importDLC(self):
    """Imports DeepLabCut datasets."""
    self.execute(ImportDeepLabCut)

importDLCFolder()

Imports multiple DeepLabCut datasets.

Source code in sleap/gui/commands.py

def importDLCFolder(self):
    """Imports multiple DeepLabCut datasets."""
    self.execute(ImportDeepLabCutFolder)

importNWB()

Imports NWB datasets.

Source code in sleap/gui/commands.py

def importNWB(self):
    """Imports NWB datasets."""
    self.execute(ImportNWB)

lastInteractedFrame()

Goes to last frame that user interacted with.

Source code in sleap/gui/commands.py

def lastInteractedFrame(self):
    """Goes to last frame that user interacted with."""
    self.execute(GoLastInteractedFrame)

loadLabelsObject(labels, filename=None)

Loads a Labels object into the GUI, replacing any currently loaded.

Parameters:

Name	Type	Description	Default
labels	Labels	The Labels object to load.	required
filename	Optional[str]	The filename where this file is saved, if any.	None

Returns:

Type	Description
	None.

Source code in sleap/gui/commands.py

def loadLabelsObject(self, labels: Labels, filename: Optional[str] = None):
    """Loads a `Labels` object into the GUI, replacing any currently loaded.

    Args:
        labels: The `Labels` object to load.
        filename: The filename where this file is saved, if any.

    Returns:
        None.

    """
    self.execute(LoadLabelsObject, labels=labels, filename=filename)

loadProjectFile(filename)

Loads given labels file into GUI.

Parameters:

Name	Type	Description	Default
filename	Union[str, Labels]	The path to the saved labels dataset or the Labels object. If None, then don't do anything.	required

Returns:

Type	Description
	None

Source code in sleap/gui/commands.py

def loadProjectFile(self, filename: Union[str, Labels]):
    """Loads given labels file into GUI.

    Args:
        filename: The path to the saved labels dataset or the `Labels` object.
            If None, then don't do anything.

    Returns:
        None
    """
    self.execute(LoadProjectFile, filename=filename)

mergeInstance(donor=None)

Merge another user instance in the frame into the selected one.

The selected instance is kept (survivor) and gains the donor's labeled keypoints for any nodes it is missing. If donor is None and the frame has exactly two user instances, the other one is used as the donor.

Source code in sleap/gui/commands.py

def mergeInstance(self, donor: Optional["Instance"] = None):
    """Merge another user instance in the frame into the selected one.

    The selected instance is kept (survivor) and gains the donor's labeled
    keypoints for any nodes it is missing. If `donor` is None and the frame
    has exactly two user instances, the other one is used as the donor.
    """
    self.execute(MergeInstances, donor=donor)

mergeProject(filenames=None)

Starts gui for importing another dataset into currently one.

Source code in sleap/gui/commands.py

def mergeProject(self, filenames: Optional[List[str]] = None):
    """Starts gui for importing another dataset into currently one."""
    self.execute(MergeProject, filenames=filenames)

newEdge(src_node, dst_node)

Adds new edge to skeleton.

Source code in sleap/gui/commands.py

def newEdge(self, src_node, dst_node):
    """Adds new edge to skeleton."""
    self.execute(NewEdge, src_node=src_node, dst_node=dst_node)

newInstance(copy_instance=None, init_method='best', location=None, mark_complete=False, offset=0)

Creates a new instance, copying node coordinates as appropriate.

Parameters:

Name	Type	Description	Default
copy_instance	Optional[Instance]	The :class:Instance (or :class:PredictedInstance) which we want to copy.	None
init_method	str	Method to use for positioning nodes.	'best'
location	Optional[QPoint]	The location where instance should be added (if node init method supports custom location).	None
mark_complete	bool	Whether to mark the instance as complete.	False
offset	int	Offset to apply to the location if given.	0

Source code in sleap/gui/commands.py

def newInstance(
    self,
    copy_instance: Optional[Instance] = None,
    init_method: str = "best",
    location: Optional[QtCore.QPoint] = None,
    mark_complete: bool = False,
    offset: int = 0,
):
    """Creates a new instance, copying node coordinates as appropriate.

    Args:
        copy_instance: The :class:`Instance` (or
            :class:`PredictedInstance`) which we want to copy.
        init_method: Method to use for positioning nodes.
        location: The location where instance should be added (if node init
            method supports custom location).
        mark_complete: Whether to mark the instance as complete.
        offset: Offset to apply to the location if given.
    """
    self.execute(
        AddInstance,
        copy_instance=copy_instance,
        init_method=init_method,
        location=location,
        mark_complete=mark_complete,
        offset=offset,
    )

newNode()

Adds new node to skeleton.

Source code in sleap/gui/commands.py

def newNode(self):
    """Adds new node to skeleton."""
    self.execute(NewNode)

newProject()

Create a new project in a new window.

Source code in sleap/gui/commands.py

def newProject(self):
    """Create a new project in a new window."""
    self.execute(NewProject)

nextLabeledFrame()

Goes to labeled frame after current frame.

Source code in sleap/gui/commands.py

def nextLabeledFrame(self):
    """Goes to labeled frame after current frame."""
    self.execute(GoNextLabeledFrame)

nextSuggestedFrame()

Goes to next suggested frame.

Source code in sleap/gui/commands.py

def nextSuggestedFrame(self):
    """Goes to next suggested frame."""
    self.execute(GoNextSuggestedFrame)

nextTrackFrame()

Goes to next frame on which a track starts.

Source code in sleap/gui/commands.py

def nextTrackFrame(self):
    """Goes to next frame on which a track starts."""
    self.execute(GoNextTrackFrame)

nextUserLabeledFrame()

Goes to next labeled frame with user instances.

Source code in sleap/gui/commands.py

def nextUserLabeledFrame(self):
    """Goes to next labeled frame with user instances."""
    self.execute(GoNextUserLabeledFrame)

openProject(filename=None, first_open=False)

Allows user to select and then open a saved project.

Parameters:

Name	Type	Description	Default
filename	Optional[str]	Filename of the project to be opened. If None, a file browser dialog will prompt the user for a path.	None
first_open	bool	Whether this is the first window opened. If True, then the new project is loaded into the current window rather than a new application window.	False

Returns:

Type	Description
	None.

Source code in sleap/gui/commands.py

def openProject(self, filename: Optional[str] = None, first_open: bool = False):
    """Allows user to select and then open a saved project.

    Args:
        filename: Filename of the project to be opened. If None, a file browser
            dialog will prompt the user for a path.
        first_open: Whether this is the first window opened. If True,
            then the new project is loaded into the current window
            rather than a new application window.

    Returns:
        None.
    """
    self.execute(OpenProject, filename=filename, first_open=first_open)

openSkeleton()

Shows gui for loading saved skeleton into project.

Source code in sleap/gui/commands.py

def openSkeleton(self):
    """Shows gui for loading saved skeleton into project."""
    self.execute(OpenSkeleton)

openSkeletonTemplate()

Shows gui for loading saved skeleton into project.

Source code in sleap/gui/commands.py

def openSkeletonTemplate(self):
    """Shows gui for loading saved skeleton into project."""
    self.execute(OpenSkeleton, template=True)

openWebsite(url)

Open a website from URL using the native system browser.

Source code in sleap/gui/commands.py

def openWebsite(self, url):
    """Open a website from URL using the native system browser."""
    self.execute(OpenWebsite, url=url)

pasteInstance()

Paste the instance from the clipboard as a new copy.

Source code in sleap/gui/commands.py

def pasteInstance(self):
    """Paste the instance from the clipboard as a new copy."""
    self.execute(PasteInstance)

pasteInstanceTrack()

Pastes the track in the clipboard to the selected instance.

Source code in sleap/gui/commands.py

def pasteInstanceTrack(self):
    """Pastes the track in the clipboard to the selected instance."""
    self.execute(PasteInstanceTrack)

prevSuggestedFrame()

Goes to previous suggested frame.

Source code in sleap/gui/commands.py

def prevSuggestedFrame(self):
    """Goes to previous suggested frame."""
    self.execute(GoPrevSuggestedFrame)

prevUserLabeledFrame()

Goes to previous labeled frame with user instances.

Source code in sleap/gui/commands.py

def prevUserLabeledFrame(self):
    """Goes to previous labeled frame with user instances."""
    self.execute(GoPrevUserLabeledFrame)

previousLabeledFrame()

Goes to labeled frame prior to current frame.

Source code in sleap/gui/commands.py

def previousLabeledFrame(self):
    """Goes to labeled frame prior to current frame."""
    self.execute(GoPreviousLabeledFrame)

removeSuggestion()

Remove the selected frame from suggestions.

Source code in sleap/gui/commands.py

def removeSuggestion(self):
    """Remove the selected frame from suggestions."""
    self.execute(RemoveSuggestion)

removeVideo()

Removes selected video from project.

Source code in sleap/gui/commands.py

def removeVideo(self):
    """Removes selected video from project."""
    self.execute(RemoveVideo)

replaceVideo()

Shows gui for replacing videos to project.

Source code in sleap/gui/commands.py

def replaceVideo(self):
    """Shows gui for replacing videos to project."""
    self.execute(ReplaceVideo)

saveProject()

Show gui to save project (or save as if not yet saved).

Source code in sleap/gui/commands.py

def saveProject(self):
    """Show gui to save project (or save as if not yet saved)."""
    self.execute(SaveProject)

saveProjectAs()

Show gui to save project as a new file.

Source code in sleap/gui/commands.py

def saveProjectAs(self):
    """Show gui to save project as a new file."""
    self.execute(SaveProjectAs)

saveSkeleton()

Shows gui for saving skeleton from project.

Source code in sleap/gui/commands.py

def saveSkeleton(self):
    """Shows gui for saving skeleton from project."""
    self.execute(SaveSkeleton)

selectToFrame()

Shows gui to go to frame by number.

Source code in sleap/gui/commands.py

def selectToFrame(self):
    """Shows gui to go to frame by number."""
    self.execute(SelectToFrameGui)

setInstancePointVisibility(instance, node, visible)

Toggles visibility set for a node for an instance.

Source code in sleap/gui/commands.py

def setInstancePointVisibility(self, instance: Instance, node: Node, visible: bool):
    """Toggles visibility set for a node for an instance."""
    self.execute(
        SetInstancePointVisibility, instance=instance, node=node, visible=visible
    )

setInstanceTrack(new_track)

Sets track for selected instance.

Source code in sleap/gui/commands.py

def setInstanceTrack(self, new_track: "Track"):
    """Sets track for selected instance."""
    self.execute(SetSelectedInstanceTrack, new_track=new_track)

setNodeName(skeleton, node, name)

Changes name of node in skeleton.

Source code in sleap/gui/commands.py

def setNodeName(self, skeleton, node, name):
    """Changes name of node in skeleton."""
    self.execute(SetNodeName, skeleton=skeleton, node=node, name=name)

setNodeSymmetry(skeleton, node, symmetry)

Sets node symmetry in skeleton.

Source code in sleap/gui/commands.py

def setNodeSymmetry(self, skeleton, node, symmetry: str):
    """Sets node symmetry in skeleton."""
    self.execute(SetNodeSymmetry, skeleton=skeleton, node=node, symmetry=symmetry)

setPointLocations(instance, nodes_locations)

Sets locations for node(s) for an instance.

Source code in sleap/gui/commands.py

def setPointLocations(
    self, instance: Instance, nodes_locations: Dict[Node, Tuple[int, int]]
):
    """Sets locations for node(s) for an instance."""
    self.execute(
        SetInstancePointLocations,
        instance=instance,
        nodes_locations=nodes_locations,
    )

setTrackName(track, name)

Sets name for track.

Source code in sleap/gui/commands.py

def setTrackName(self, track: "Track", name: str):
    """Sets name for track."""
    self.execute(SetTrackName, track=track, name=name)

showImportVideos(filenames)

Show video importer GUI without the file browser.

Source code in sleap/gui/commands.py

def showImportVideos(self, filenames: List[str]):
    """Show video importer GUI without the file browser."""
    self.execute(ShowImportVideos, filenames=filenames)

signal_update(what)

Calls the update callback after data has been changed.

Source code in sleap/gui/commands.py

def signal_update(self, what: List[UpdateTopic]):
    """Calls the update callback after data has been changed."""
    if callable(self.update_callback):
        self.update_callback(what)

toggleCurrentFrameNegative()

Mark or unmark the current frame as a negative (background) frame.

Source code in sleap/gui/commands.py

def toggleCurrentFrameNegative(self):
    """Mark or unmark the current frame as a negative (background) frame."""
    self.execute(ToggleNegativeFrame)

toggleGrayscale()

Toggles grayscale setting for current video.

Source code in sleap/gui/commands.py

def toggleGrayscale(self):
    """Toggles grayscale setting for current video."""
    self.execute(ToggleGrayscale)

transposeInstance()

Transposes tracks for two instances.

If there are only two instances, then this swaps tracks. Otherwise, it allows user to select the instances for which we want to swap tracks.

Source code in sleap/gui/commands.py

def transposeInstance(self):
    """Transposes tracks for two instances.

    If there are only two instances, then this swaps tracks.
    Otherwise, it allows user to select the instances for which we want
    to swap tracks.
    """
    self.execute(TransposeInstances)

updateEdges()

Called when edges in skeleton have been changed.

Source code in sleap/gui/commands.py

def updateEdges(self):
    """Called when edges in skeleton have been changed."""
    self.signal_update([UpdateTopic.skeleton])

DeleteFrameLimitPredictions

Bases: InstanceDeleteCommand

Methods:

Name	Description
get_frame_instance_list	Called from the parent InstanceDeleteCommand.ask method.

Source code in sleap/gui/commands.py

class DeleteFrameLimitPredictions(InstanceDeleteCommand):
    @staticmethod
    def get_frame_instance_list(context: CommandContext, params: Dict):
        """Called from the parent `InstanceDeleteCommand.ask` method.

        Returns:
            List of instances to be deleted.
        """
        instances = []
        # Select the instances to be deleted
        for lf in context.labels.labeled_frames:
            if lf.frame_idx < (params["min_frame_idx"] - 1) or lf.frame_idx > (
                params["max_frame_idx"] - 1
            ):
                instances.extend([(lf, inst) for inst in lf.instances])
        return instances

    @classmethod
    def ask(cls, context: CommandContext, params: Dict) -> bool:
        current_video = context.state["video"]
        dialog = FrameRangeDialog(
            title="Delete Predictions Outside Frame Range",
            max_frame_idx=len(current_video),
        )
        results = dialog.get_results()
        if results:
            params["min_frame_idx"] = results["min_frame_idx"]
            params["max_frame_idx"] = results["max_frame_idx"]
            return super().ask(context, params)

get_frame_instance_list(context, params) staticmethod

Called from the parent InstanceDeleteCommand.ask method.

Returns:

Type	Description
	List of instances to be deleted.

Source code in sleap/gui/commands.py

@staticmethod
def get_frame_instance_list(context: CommandContext, params: Dict):
    """Called from the parent `InstanceDeleteCommand.ask` method.

    Returns:
        List of instances to be deleted.
    """
    instances = []
    # Select the instances to be deleted
    for lf in context.labels.labeled_frames:
        if lf.frame_idx < (params["min_frame_idx"] - 1) or lf.frame_idx > (
            params["max_frame_idx"] - 1
        ):
            instances.extend([(lf, inst) for inst in lf.instances])
    return instances

DeleteMultipleTracks

Bases: EditCommand

Methods:

Name	Description
do_action	Delete either all tracks or just unused tracks.

Source code in sleap/gui/commands.py

class DeleteMultipleTracks(EditCommand):
    topics = [UpdateTopic.tracks]

    @staticmethod
    def do_action(context: CommandContext, params: dict):
        """Delete either all tracks or just unused tracks.

        Args:
            context: The command context.
            params: The command parameters.
                delete_all: If True, delete all tracks. If False, delete only
                    unused tracks.
        """
        delete_all: bool = params["delete_all"]
        if delete_all:
            remove_all_tracks(context.labels)
        else:
            remove_unused_tracks(context.labels)

do_action(context, params) staticmethod

Delete either all tracks or just unused tracks.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	The command parameters. delete_all: If True, delete all tracks. If False, delete only unused tracks.	required

Source code in sleap/gui/commands.py

@staticmethod
def do_action(context: CommandContext, params: dict):
    """Delete either all tracks or just unused tracks.

    Args:
        context: The command context.
        params: The command parameters.
            delete_all: If True, delete all tracks. If False, delete only
                unused tracks.
    """
    delete_all: bool = params["delete_all"]
    if delete_all:
        remove_all_tracks(context.labels)
    else:
        remove_unused_tracks(context.labels)

DeleteUserFramePredictions

Bases: InstanceDeleteCommand

Delete predictions on frames that have user instances.

This command cleans up predictions that were merged into frames that already have user labels, which causes both to be displayed in the GUI (confusing UX).

Two modes are supported: - Unlinked only (default): Delete predictions not linked via any user instance's from_predicted attribute. These are the "orphan" predictions causing duplicates. - All predictions: Delete all predictions on user-labeled frames.

Source code in sleap/gui/commands.py

class DeleteUserFramePredictions(InstanceDeleteCommand):
    """Delete predictions on frames that have user instances.

    This command cleans up predictions that were merged into frames that already
    have user labels, which causes both to be displayed in the GUI (confusing UX).

    Two modes are supported:
    - Unlinked only (default): Delete predictions not linked via any user instance's
      `from_predicted` attribute. These are the "orphan" predictions causing duplicates.
    - All predictions: Delete all predictions on user-labeled frames.
    """

    @staticmethod
    def get_frame_instance_list(context: CommandContext, params: dict):
        video = (
            context.state["video"] if params.get("current_video_only", True) else None
        )
        unlinked_only = params.get("unlinked_only", True)

        return get_predictions_on_user_frames(
            labels=context.labels,
            video=video,
            unlinked_only=unlinked_only,
        )

    @classmethod
    def ask(cls, context: CommandContext, params: dict) -> bool:
        from sleap.gui.dialogs.delete import DeleteUserFramePredictionsDialog

        dialog = DeleteUserFramePredictionsDialog(context)
        if not dialog.exec_():
            return False

        params["current_video_only"] = dialog.current_video_only
        params["unlinked_only"] = dialog.unlinked_only

        lf_inst_list = cls.get_frame_instance_list(context, params)
        params["lf_instance_list"] = lf_inst_list

        if len(lf_inst_list) == 0:
            QtWidgets.QMessageBox.information(
                context.app,
                "No predictions to delete",
                "No predictions found on user-labeled frames matching the criteria.",
            )
            return False

        return cls._confirm_deletion(context, lf_inst_list)

EditCommand

Bases: AppCommand

Class for commands which change data in project.

Source code in sleap/gui/commands.py

class EditCommand(AppCommand):
    """Class for commands which change data in project."""

    does_edits = True

ExportLabeledClip

Bases: AppCommand

Export a labeled video clip with skeleton overlay.

Uses sleap-io's rendering API for high-quality video export with real-time preview capabilities.

Methods:

Name	Description
ask	Show the render dialog and collect export parameters.
do_action	Export the labeled video clip.
write_new_video	Write annotated video using sleap-io rendering.

Source code in sleap/gui/commands.py

class ExportLabeledClip(AppCommand):
    """Export a labeled video clip with skeleton overlay.

    Uses sleap-io's rendering API for high-quality video export with
    real-time preview capabilities.
    """

    @classmethod
    def ask(cls, context: CommandContext, params: dict) -> bool:
        """Show the render dialog and collect export parameters.

        Args:
            context: The command context.
            params: Dictionary to store collected parameters.

        Returns:
            True if user confirmed, False if cancelled.
        """
        from sleap.gui.dialogs.render_clip import RenderClipDialog

        labels = context.state["labels"]
        video = context.state["video"]
        frame_idx = context.state.get("frame_idx", None)

        # Get frame range if a clip is selected in main window
        frame_range = None
        if context.state["has_frame_range"]:
            frame_range = tuple(context.state["frame_range"])

        dialog = RenderClipDialog(
            labels=labels,
            video=video,
            current_frame=frame_idx,
            frame_range=frame_range,
            parent=context.app,
        )

        if not dialog.exec_():
            return False

        # Collect parameters from dialog
        params["video_filename"] = dialog.get_output_path()
        params["frame_indices"] = dialog.get_frame_indices()
        # Capture the dialog's selected video — it may differ from the main
        # window's selection when the user picks a different source in the
        # multi-video selector.
        params["video"] = dialog.video
        export_params = dialog.get_export_params()

        # Map dialog params to render params
        params["fps"] = export_params.get("fps", 30)
        params["crf"] = export_params.get("crf", 23)
        params["scale"] = export_params.get("scale", 1.0)
        params["color_by"] = export_params.get("color_by", "track")
        params["palette"] = export_params.get("palette", "tableau10")
        params["marker_shape"] = export_params.get("marker_shape", "circle")
        params["marker_size"] = export_params.get("marker_size", 4.0)
        params["line_width"] = export_params.get("line_width", 2.0)
        params["alpha"] = export_params.get("alpha", 1.0)
        params["show_nodes"] = export_params.get("show_nodes", True)
        params["show_edges"] = export_params.get("show_edges", True)
        params["background"] = export_params.get("background")
        params["open_when_done"] = export_params.get("open_when_done", True)
        params["include_unlabeled"] = export_params.get("include_unlabeled", False)
        params["start"] = export_params.get("start")
        params["end"] = export_params.get("end")

        # Motion trail params are only present in export_params when the user
        # enabled trails; copy through whatever is there.
        for key in (
            "show_trails",
            "trail_length",
            "trail_node",
            "trail_width",
            "trail_alpha_fade",
            "trail_alpha",
            "trail_color",
        ):
            if key in export_params:
                params[key] = export_params[key]

        return True

    @classmethod
    def do_action(cls, context: CommandContext, params: dict):
        """Export the labeled video clip.

        Args:
            context: The command context.
            params: Export parameters from ask().
        """
        labels = context.state["labels"]
        video = params.get("video", context.state["video"])

        # Build render parameters
        render_params = {
            "fps": params.get("fps", 30),
            "crf": params.get("crf", 23),
            "scale": params.get("scale", 1.0),
            "color_by": params.get("color_by", "track"),
            "palette": params.get("palette", "tableau10"),
            "marker_shape": params.get("marker_shape", "circle"),
            "marker_size": params.get("marker_size", 4.0),
            "line_width": params.get("line_width", 2.0),
            "alpha": params.get("alpha", 1.0),
            "show_nodes": params.get("show_nodes", True),
            "show_edges": params.get("show_edges", True),
        }

        # Add background if not "video"
        if params.get("background"):
            render_params["background"] = params["background"]

        # Motion trails. Only forward when enabled so the default render path is
        # untouched. trail_color / trail_alpha_fade may legitimately be falsy,
        # so guard on presence rather than truthiness once trails are on.
        if params.get("show_trails"):
            render_params["show_trails"] = True
            for key in (
                "trail_length",
                "trail_node",
                "trail_width",
                "trail_alpha_fade",
                "trail_alpha",
                "trail_color",
            ):
                if key in params:
                    render_params[key] = params[key]

        # When the user opts in to include unlabeled frames, hand sleap-io the
        # full range instead of a labeled-only frame_inds list — otherwise the
        # explicit frame_inds would restrict output back to labeled frames.
        include_unlabeled = params.get("include_unlabeled", False)
        if include_unlabeled:
            render_params["include_unlabeled"] = True
            if params.get("start") is not None:
                render_params["start"] = params["start"]
            if params.get("end") is not None:
                render_params["end"] = params["end"]
            frame_inds = None
        else:
            frame_inds = params.get("frame_indices")

        # Render with progress dialog (non-blocking)
        render_video_gui(
            labels=labels,
            filename=params["video_filename"],
            video=video,
            frame_inds=frame_inds,
            render_params=render_params,
            open_when_done=params.get("open_when_done", True),
        )

    @classmethod
    def write_new_video(cls, context: CommandContext, params: dict):
        """Write annotated video using sleap-io rendering.

        .. deprecated::
            This method is deprecated. Use `render_video_gui()` for GUI rendering
            with progress dialog, or call `sleap_io.render_video()` directly for
            programmatic use.

        Args:
            context: The command context.
            params: The parameters for the export.
        """
        import warnings

        import sleap_io as sio

        warnings.warn(
            "ExportLabeledClip.write_new_video() is deprecated. "
            "Use render_video_gui() or sleap_io.render_video() directly.",
            DeprecationWarning,
            stacklevel=2,
        )

        labels = context.state["labels"]
        video = context.state["video"]

        # Build render parameters
        render_params = {
            "fps": params.get("fps", 30),
            "crf": params.get("crf", 23),
            "scale": params.get("scale", 1.0),
            "color_by": params.get("color_by", "track"),
            "palette": params.get("palette", "tableau10"),
            "marker_shape": params.get("marker_shape", "circle"),
            "marker_size": params.get("marker_size", 4.0),
            "line_width": params.get("line_width", 2.0),
            "alpha": params.get("alpha", 1.0),
            "show_nodes": params.get("show_nodes", True),
            "show_edges": params.get("show_edges", True),
        }

        # Add background if not "video"
        if params.get("background"):
            render_params["background"] = params["background"]

        # Get frame indices
        frame_inds = params.get("frame_indices", None)

        # Render video using sleap-io
        sio.render_video(
            labels,
            params["video_filename"],
            video=video,
            frame_inds=frame_inds,
            show_progress=True,
            **render_params,
        )

ask(context, params) classmethod

Show the render dialog and collect export parameters.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	Dictionary to store collected parameters.	required

Returns:

Type	Description
bool	True if user confirmed, False if cancelled.

Source code in sleap/gui/commands.py

@classmethod
def ask(cls, context: CommandContext, params: dict) -> bool:
    """Show the render dialog and collect export parameters.

    Args:
        context: The command context.
        params: Dictionary to store collected parameters.

    Returns:
        True if user confirmed, False if cancelled.
    """
    from sleap.gui.dialogs.render_clip import RenderClipDialog

    labels = context.state["labels"]
    video = context.state["video"]
    frame_idx = context.state.get("frame_idx", None)

    # Get frame range if a clip is selected in main window
    frame_range = None
    if context.state["has_frame_range"]:
        frame_range = tuple(context.state["frame_range"])

    dialog = RenderClipDialog(
        labels=labels,
        video=video,
        current_frame=frame_idx,
        frame_range=frame_range,
        parent=context.app,
    )

    if not dialog.exec_():
        return False

    # Collect parameters from dialog
    params["video_filename"] = dialog.get_output_path()
    params["frame_indices"] = dialog.get_frame_indices()
    # Capture the dialog's selected video — it may differ from the main
    # window's selection when the user picks a different source in the
    # multi-video selector.
    params["video"] = dialog.video
    export_params = dialog.get_export_params()

    # Map dialog params to render params
    params["fps"] = export_params.get("fps", 30)
    params["crf"] = export_params.get("crf", 23)
    params["scale"] = export_params.get("scale", 1.0)
    params["color_by"] = export_params.get("color_by", "track")
    params["palette"] = export_params.get("palette", "tableau10")
    params["marker_shape"] = export_params.get("marker_shape", "circle")
    params["marker_size"] = export_params.get("marker_size", 4.0)
    params["line_width"] = export_params.get("line_width", 2.0)
    params["alpha"] = export_params.get("alpha", 1.0)
    params["show_nodes"] = export_params.get("show_nodes", True)
    params["show_edges"] = export_params.get("show_edges", True)
    params["background"] = export_params.get("background")
    params["open_when_done"] = export_params.get("open_when_done", True)
    params["include_unlabeled"] = export_params.get("include_unlabeled", False)
    params["start"] = export_params.get("start")
    params["end"] = export_params.get("end")

    # Motion trail params are only present in export_params when the user
    # enabled trails; copy through whatever is there.
    for key in (
        "show_trails",
        "trail_length",
        "trail_node",
        "trail_width",
        "trail_alpha_fade",
        "trail_alpha",
        "trail_color",
    ):
        if key in export_params:
            params[key] = export_params[key]

    return True

do_action(context, params) classmethod

Export the labeled video clip.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	Export parameters from ask().	required

Source code in sleap/gui/commands.py

@classmethod
def do_action(cls, context: CommandContext, params: dict):
    """Export the labeled video clip.

    Args:
        context: The command context.
        params: Export parameters from ask().
    """
    labels = context.state["labels"]
    video = params.get("video", context.state["video"])

    # Build render parameters
    render_params = {
        "fps": params.get("fps", 30),
        "crf": params.get("crf", 23),
        "scale": params.get("scale", 1.0),
        "color_by": params.get("color_by", "track"),
        "palette": params.get("palette", "tableau10"),
        "marker_shape": params.get("marker_shape", "circle"),
        "marker_size": params.get("marker_size", 4.0),
        "line_width": params.get("line_width", 2.0),
        "alpha": params.get("alpha", 1.0),
        "show_nodes": params.get("show_nodes", True),
        "show_edges": params.get("show_edges", True),
    }

    # Add background if not "video"
    if params.get("background"):
        render_params["background"] = params["background"]

    # Motion trails. Only forward when enabled so the default render path is
    # untouched. trail_color / trail_alpha_fade may legitimately be falsy,
    # so guard on presence rather than truthiness once trails are on.
    if params.get("show_trails"):
        render_params["show_trails"] = True
        for key in (
            "trail_length",
            "trail_node",
            "trail_width",
            "trail_alpha_fade",
            "trail_alpha",
            "trail_color",
        ):
            if key in params:
                render_params[key] = params[key]

    # When the user opts in to include unlabeled frames, hand sleap-io the
    # full range instead of a labeled-only frame_inds list — otherwise the
    # explicit frame_inds would restrict output back to labeled frames.
    include_unlabeled = params.get("include_unlabeled", False)
    if include_unlabeled:
        render_params["include_unlabeled"] = True
        if params.get("start") is not None:
            render_params["start"] = params["start"]
        if params.get("end") is not None:
            render_params["end"] = params["end"]
        frame_inds = None
    else:
        frame_inds = params.get("frame_indices")

    # Render with progress dialog (non-blocking)
    render_video_gui(
        labels=labels,
        filename=params["video_filename"],
        video=video,
        frame_inds=frame_inds,
        render_params=render_params,
        open_when_done=params.get("open_when_done", True),
    )

write_new_video(context, params) classmethod

Write annotated video using sleap-io rendering.

.. deprecated:: This method is deprecated. Use render_video_gui() for GUI rendering with progress dialog, or call sleap_io.render_video() directly for programmatic use.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	The parameters for the export.	required

Source code in sleap/gui/commands.py

@classmethod
def write_new_video(cls, context: CommandContext, params: dict):
    """Write annotated video using sleap-io rendering.

    .. deprecated::
        This method is deprecated. Use `render_video_gui()` for GUI rendering
        with progress dialog, or call `sleap_io.render_video()` directly for
        programmatic use.

    Args:
        context: The command context.
        params: The parameters for the export.
    """
    import warnings

    import sleap_io as sio

    warnings.warn(
        "ExportLabeledClip.write_new_video() is deprecated. "
        "Use render_video_gui() or sleap_io.render_video() directly.",
        DeprecationWarning,
        stacklevel=2,
    )

    labels = context.state["labels"]
    video = context.state["video"]

    # Build render parameters
    render_params = {
        "fps": params.get("fps", 30),
        "crf": params.get("crf", 23),
        "scale": params.get("scale", 1.0),
        "color_by": params.get("color_by", "track"),
        "palette": params.get("palette", "tableau10"),
        "marker_shape": params.get("marker_shape", "circle"),
        "marker_size": params.get("marker_size", 4.0),
        "line_width": params.get("line_width", 2.0),
        "alpha": params.get("alpha", 1.0),
        "show_nodes": params.get("show_nodes", True),
        "show_edges": params.get("show_edges", True),
    }

    # Add background if not "video"
    if params.get("background"):
        render_params["background"] = params["background"]

    # Get frame indices
    frame_inds = params.get("frame_indices", None)

    # Render video using sleap-io
    sio.render_video(
        labels,
        params["video_filename"],
        video=video,
        frame_inds=frame_inds,
        show_progress=True,
        **render_params,
    )

ExportLabelsSubset

Bases: ExportFullPackage

Export a subset of labels to a new file with either images or a trimmed video.

This command subclasses ExportFullPackage, but uses also uses methods from ExportVideoClip to provide functionality for exporting a subset of labels to a new file with either images or a trimmed video. It allows the user to specify the labels to export and the format of the output file.

Methods:

Name	Description
get_labels_subset_unshifted	Get the labels subset for the export.
get_lfs_subset	Get the labeled frames subset for the export.
get_or_create_video_subset	Get the video subset for the export.
get_suggestions_subset	Get the suggestions subset for the labels.

Source code in sleap/gui/commands.py

class ExportLabelsSubset(ExportFullPackage):
    """Export a subset of labels to a new file with either images or a trimmed video.

    This command subclasses `ExportFullPackage`, but uses also uses methods from
    `ExportVideoClip` to provide functionality for exporting a subset of labels to a new
    file with either images or a trimmed video. It allows the user to specify the labels
    to export and the format of the output file.
    """

    @classmethod
    def ask(cls, context: CommandContext, params: dict) -> bool:
        # Ask for the labels subset to export.
        if not super().ask(context=context, params=params):
            return False

        # If we are exporting as a pkg.slp, then we just need the frame range.
        # Not interested in opening the video.
        if params.get("as_package", False):
            ExportVideoClip.get_frame_range_params(context=context, params=params)
        # Otherwise, exporting as slp and need to get video clip parameters.
        elif not ExportVideoClip.ask(context=context, params=params):
            return False

        return True

    @classmethod
    def do_action(cls, context: CommandContext, params: dict):
        # Get the video subset for the export.
        video_subset = cls.get_or_create_video_subset(context=context, params=params)

        # Get the (unshifted) labels subset for the export.
        labels_subset_unshifted: Labels = cls.get_labels_subset_unshifted(
            context=context, params=params
        )

        # Get the shifted and updated labels frames subset for the export.
        lfs_subset = cls.get_lfs_subset(
            labels_subset_unshifted=labels_subset_unshifted,
            video_subset=video_subset,
            params=params,
        )

        # Also need to update anything that references the video or frame index.
        suggestions_subset = cls.get_suggestions_subset(
            labels_subset_unshifted=labels_subset_unshifted,
            video_subset=video_subset,
            params=params,
        )

        # Create the labels subset for the export.
        labels_subset = Labels(
            labeled_frames=lfs_subset,
            videos=[video_subset],
            skeletons=labels_subset_unshifted.skeletons,
            tracks=labels_subset_unshifted.tracks,
            suggestions=suggestions_subset,
            provenance=labels_subset_unshifted.provenance,
        )

        # Save the labels subset to a new file.
        params["labels"] = labels_subset
        super().do_action(context=context, params=params)

        # Now let's open the new file.
        if params.get("open_new_project", False):
            OpenProject.do_action(context=context, params=params)

    @classmethod
    def get_or_create_video_subset(cls, context: CommandContext, params: dict) -> Video:
        """Get the video subset for the export.

        Args:
            context: The command context.
            params: The parameters for the export.

        Returns:
            Video: The video subset for the export.
        """
        # Get variables from params and context.
        as_package = params.get("as_package", False)
        frames = params["frames"]
        end_frame_idx = frames[-1]  # 0-indexed
        video: Video = context.state["video"]
        n_frames = len(video)
        # Initialize video subset.
        video_subset = video

        # If the user selected the entire video, then do not create a new video.
        if (end_frame_idx < n_frames - 1) and not as_package:
            # Do not open the video when done.
            open_when_done = params.get("open_when_done", False)
            params["open_when_done"] = False

            # Export the video clip using the parameters provided.
            ExportVideoClip.do_action(context=context, params=params)
            video_subset_filename = params["video_filename"]
            video_subset = Video.from_filename(filename=video_subset_filename)

            # Reset the open_when_done parameter. Not currently used, but maybe we
            # should use this for opening the new project.
            params["open_when_done"] = open_when_done

        return video_subset

    @classmethod
    def get_labels_subset_unshifted(
        cls, context: CommandContext, params: dict
    ) -> Labels:
        """Get the labels subset for the export.

        Args:
            context: The command context.
            params: The parameters for the export.

        Returns:
            Labels: The labels subset for the export.
        """
        # Get variables from params.
        video: Video = context.state["video"]
        frames: range = params["frames"]

        # Get subset of labels to export
        labels: Labels = context.state["labels"]
        frames_in_labels = [(video, frame) for frame in frames]
        labels_subset_unshifted: Labels = labels.extract(
            inds=frames_in_labels, copy=True
        )
        return labels_subset_unshifted

    @classmethod
    def get_lfs_subset(
        cls, labels_subset_unshifted: Labels, video_subset: Video, params: dict
    ) -> list[LabeledFrame]:
        """Get the labeled frames subset for the export.

        Args:
            labels_subset_unshifted: The labels subset to export.
            video_subset: The video subset to export.
            params: The parameters for the export.

        Returns:
            list[LabeledFrame]: The labeled frames subset for the export.
        """
        # Get variables from params.
        as_package = params.get("as_package", False)
        frames: range = params["frames"]
        start_frame_idx = frames[0]  # 0-indexed

        # Update the video and frame indices of the labels.
        lfs_subset = labels_subset_unshifted.labeled_frames if as_package else []
        for lf in labels_subset_unshifted.labeled_frames:
            # Use the new video for the subset (need to do this even if video is same,
            # otherwise, fails in Labels __init__ when updating cache).
            lf.video = video_subset

            if not as_package:
                # Shift the frame index to match the new video
                lf.frame_idx -= start_frame_idx

                # Add the labeled frame to the subset
                lfs_subset.append(lf)

        return lfs_subset

    @classmethod
    def get_suggestions_subset(
        cls,
        labels_subset_unshifted: Labels,
        video_subset: Video,
        params: dict,
    ) -> list[SuggestionFrame]:
        """Get the suggestions subset for the labels.

        Args:
            labels_subset_unshifted: The labels subset to export.
            video_subset: The video subset to export.

        Returns:
            list[SuggestionFrame]: The suggestions subset for the labels.
        """
        # Get variables from params.
        as_package = params.get("as_package", False)
        frames = params["frames"]
        start_frame_idx = frames[0]  # 0-indexed
        end_frame_idx = frames[-1]

        # Get the suggestions subset for the labels.
        suggestions_subset = []
        for suggestion in labels_subset_unshifted.suggestions:
            suggestion.video = video_subset

            if (
                suggestion.frame_idx >= start_frame_idx
                and suggestion.frame_idx < end_frame_idx
            ):
                # Shift the frame index to match the new video if not a package.
                if not as_package:
                    suggestion.frame_idx -= start_frame_idx

                suggestions_subset.append(suggestion)

        return suggestions_subset

get_labels_subset_unshifted(context, params) classmethod

Get the labels subset for the export.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	The parameters for the export.	required

Returns:

Name	Type	Description
Labels	Labels	The labels subset for the export.

Source code in sleap/gui/commands.py

@classmethod
def get_labels_subset_unshifted(
    cls, context: CommandContext, params: dict
) -> Labels:
    """Get the labels subset for the export.

    Args:
        context: The command context.
        params: The parameters for the export.

    Returns:
        Labels: The labels subset for the export.
    """
    # Get variables from params.
    video: Video = context.state["video"]
    frames: range = params["frames"]

    # Get subset of labels to export
    labels: Labels = context.state["labels"]
    frames_in_labels = [(video, frame) for frame in frames]
    labels_subset_unshifted: Labels = labels.extract(
        inds=frames_in_labels, copy=True
    )
    return labels_subset_unshifted

get_lfs_subset(labels_subset_unshifted, video_subset, params) classmethod

Get the labeled frames subset for the export.

Parameters:

Name	Type	Description	Default
labels_subset_unshifted	Labels	The labels subset to export.	required
video_subset	Video	The video subset to export.	required
params	dict	The parameters for the export.	required

Returns:

Type	Description
list[LabeledFrame]	list[LabeledFrame]: The labeled frames subset for the export.

Source code in sleap/gui/commands.py

@classmethod
def get_lfs_subset(
    cls, labels_subset_unshifted: Labels, video_subset: Video, params: dict
) -> list[LabeledFrame]:
    """Get the labeled frames subset for the export.

    Args:
        labels_subset_unshifted: The labels subset to export.
        video_subset: The video subset to export.
        params: The parameters for the export.

    Returns:
        list[LabeledFrame]: The labeled frames subset for the export.
    """
    # Get variables from params.
    as_package = params.get("as_package", False)
    frames: range = params["frames"]
    start_frame_idx = frames[0]  # 0-indexed

    # Update the video and frame indices of the labels.
    lfs_subset = labels_subset_unshifted.labeled_frames if as_package else []
    for lf in labels_subset_unshifted.labeled_frames:
        # Use the new video for the subset (need to do this even if video is same,
        # otherwise, fails in Labels __init__ when updating cache).
        lf.video = video_subset

        if not as_package:
            # Shift the frame index to match the new video
            lf.frame_idx -= start_frame_idx

            # Add the labeled frame to the subset
            lfs_subset.append(lf)

    return lfs_subset

get_or_create_video_subset(context, params) classmethod

Get the video subset for the export.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	The parameters for the export.	required

Returns:

Name	Type	Description
Video	Video	The video subset for the export.

Source code in sleap/gui/commands.py

@classmethod
def get_or_create_video_subset(cls, context: CommandContext, params: dict) -> Video:
    """Get the video subset for the export.

    Args:
        context: The command context.
        params: The parameters for the export.

    Returns:
        Video: The video subset for the export.
    """
    # Get variables from params and context.
    as_package = params.get("as_package", False)
    frames = params["frames"]
    end_frame_idx = frames[-1]  # 0-indexed
    video: Video = context.state["video"]
    n_frames = len(video)
    # Initialize video subset.
    video_subset = video

    # If the user selected the entire video, then do not create a new video.
    if (end_frame_idx < n_frames - 1) and not as_package:
        # Do not open the video when done.
        open_when_done = params.get("open_when_done", False)
        params["open_when_done"] = False

        # Export the video clip using the parameters provided.
        ExportVideoClip.do_action(context=context, params=params)
        video_subset_filename = params["video_filename"]
        video_subset = Video.from_filename(filename=video_subset_filename)

        # Reset the open_when_done parameter. Not currently used, but maybe we
        # should use this for opening the new project.
        params["open_when_done"] = open_when_done

    return video_subset

get_suggestions_subset(labels_subset_unshifted, video_subset, params) classmethod

Get the suggestions subset for the labels.

Parameters:

Name	Type	Description	Default
labels_subset_unshifted	Labels	The labels subset to export.	required
video_subset	Video	The video subset to export.	required

Returns:

Type	Description
list[SuggestionFrame]	list[SuggestionFrame]: The suggestions subset for the labels.

Source code in sleap/gui/commands.py

@classmethod
def get_suggestions_subset(
    cls,
    labels_subset_unshifted: Labels,
    video_subset: Video,
    params: dict,
) -> list[SuggestionFrame]:
    """Get the suggestions subset for the labels.

    Args:
        labels_subset_unshifted: The labels subset to export.
        video_subset: The video subset to export.

    Returns:
        list[SuggestionFrame]: The suggestions subset for the labels.
    """
    # Get variables from params.
    as_package = params.get("as_package", False)
    frames = params["frames"]
    start_frame_idx = frames[0]  # 0-indexed
    end_frame_idx = frames[-1]

    # Get the suggestions subset for the labels.
    suggestions_subset = []
    for suggestion in labels_subset_unshifted.suggestions:
        suggestion.video = video_subset

        if (
            suggestion.frame_idx >= start_frame_idx
            and suggestion.frame_idx < end_frame_idx
        ):
            # Shift the frame index to match the new video if not a package.
            if not as_package:
                suggestion.frame_idx -= start_frame_idx

            suggestions_subset.append(suggestion)

    return suggestions_subset

ExportPackageThread

Bases: QThread

Background thread for exporting labels package without freezing GUI.

Methods:

Name	Description
cancel	Request cancellation of the export.
run	Run the export in background thread.

Source code in sleap/gui/commands.py

class ExportPackageThread(QtCore.QThread):
    """Background thread for exporting labels package without freezing GUI."""

    progress = QtCore.Signal(int, int)  # (current, total)
    finished = QtCore.Signal(str)  # filename
    error = QtCore.Signal(str)  # error message
    cancelled = QtCore.Signal()

    def __init__(
        self,
        labels: Labels,
        filename: str,
        embed_option: str,
        parent=None,
    ):
        super().__init__(parent)
        self.labels = labels
        self.filename = filename
        self.embed_option = embed_option
        self._cancelled = False

    def cancel(self):
        """Request cancellation of the export."""
        self._cancelled = True

    def _needs_temp_file(self) -> bool:
        """Check if we need to use a temp file to avoid overwriting source.

        Returns True if any video in the labels references the output filename,
        which would cause errors if we delete the file before reading frames.
        """
        output_path = Path(self.filename).resolve()
        if not output_path.exists():
            return False

        for video in self.labels.videos:
            video_path = Path(video.filename).resolve()
            if video_path == output_path:
                return True
        return False

    def run(self):
        """Run the export in background thread."""

        def on_progress(current, total):
            self.progress.emit(current, total)
            return not self._cancelled

        # Check if we need to use a temp file to avoid overwriting source
        use_temp = self._needs_temp_file()
        if use_temp:
            # Write to temp file first, then rename
            temp_filename = self.filename + ".tmp"
            export_target = temp_filename
        else:
            export_target = self.filename

        # Deep copy labels to avoid mutation by sleap-io's embed_frames().
        # sleap-io replaces video references in-place with embedded versions,
        # which would break subsequent exports from the same Labels object.
        labels_copy = deepcopy(self.labels)

        try:
            save_file(
                labels_copy,
                export_target,
                format="slp",
                embed=self.embed_option,
                progress_callback=on_progress,
            )

            if self._cancelled:
                # Clean up on cancellation
                if Path(export_target).exists():
                    os.remove(export_target)
                self.cancelled.emit()
                return

            # If we used a temp file, replace the original
            if use_temp:
                if Path(self.filename).exists():
                    os.remove(self.filename)
                os.rename(export_target, self.filename)

            self.finished.emit(self.filename)

        except Exception as e:
            # Clean up temp file if it exists
            if use_temp and Path(export_target).exists():
                os.remove(export_target)

            # Check if this was a cancellation
            is_cancelled = (
                (ExportCancelled is not None and isinstance(e, ExportCancelled))
                or "cancel" in str(e).lower()
                or self._cancelled
            )
            if is_cancelled:
                # Clean up partial file
                if Path(self.filename).exists():
                    os.remove(self.filename)
                self.cancelled.emit()
            else:
                self.error.emit(str(e))

cancel()

Request cancellation of the export.

Source code in sleap/gui/commands.py

def cancel(self):
    """Request cancellation of the export."""
    self._cancelled = True

run()

Run the export in background thread.

Source code in sleap/gui/commands.py

def run(self):
    """Run the export in background thread."""

    def on_progress(current, total):
        self.progress.emit(current, total)
        return not self._cancelled

    # Check if we need to use a temp file to avoid overwriting source
    use_temp = self._needs_temp_file()
    if use_temp:
        # Write to temp file first, then rename
        temp_filename = self.filename + ".tmp"
        export_target = temp_filename
    else:
        export_target = self.filename

    # Deep copy labels to avoid mutation by sleap-io's embed_frames().
    # sleap-io replaces video references in-place with embedded versions,
    # which would break subsequent exports from the same Labels object.
    labels_copy = deepcopy(self.labels)

    try:
        save_file(
            labels_copy,
            export_target,
            format="slp",
            embed=self.embed_option,
            progress_callback=on_progress,
        )

        if self._cancelled:
            # Clean up on cancellation
            if Path(export_target).exists():
                os.remove(export_target)
            self.cancelled.emit()
            return

        # If we used a temp file, replace the original
        if use_temp:
            if Path(self.filename).exists():
                os.remove(self.filename)
            os.rename(export_target, self.filename)

        self.finished.emit(self.filename)

    except Exception as e:
        # Clean up temp file if it exists
        if use_temp and Path(export_target).exists():
            os.remove(export_target)

        # Check if this was a cancellation
        is_cancelled = (
            (ExportCancelled is not None and isinstance(e, ExportCancelled))
            or "cancel" in str(e).lower()
            or self._cancelled
        )
        if is_cancelled:
            # Clean up partial file
            if Path(self.filename).exists():
                os.remove(self.filename)
            self.cancelled.emit()
        else:
            self.error.emit(str(e))

ExportVideoClip

Bases: AppCommand

Base class for exporting video clips.

The ask method provides all functionality to gather parameters from the export dialog.

Methods:

Name	Description
ask	Ask the user for parameters to export a video clip.
do_action	Export video clip using the parameters provided.
get_export_options	Get export options from the user.
get_frame_range_params	Get frame range parameters.
get_video_augmentation_params	Get video augmentation parameters.
get_video_markup_params	Get video markup parameters.
get_video_save_params	Get video save parameters.
write_new_video	Write a new video using the parameters provided.

Source code in sleap/gui/commands.py

class ExportVideoClip(AppCommand):
    """Base class for exporting video clips.

    The ask method provides all functionality to gather parameters from the export
    dialog.
    """

    @classmethod
    def ask(cls, context: CommandContext, params: dict) -> bool:
        """Ask the user for parameters to export a video clip.

        Args:
            context: The command context.
            params: The parameters for the export.

        Returns:
            bool: True if the user provided valid parameters, False otherwise.
        """
        # Open export dialog.
        export_options = cls.get_export_options(context, params)
        if export_options is None:  # User hit cancel.
            return False

        # If we had a pop-up dialog, then we can also show GUI progress.
        params["gui_progress"] = True

        # Get video save parameters.
        params = cls.get_video_save_params(params, export_options)

        # Get frame range parameters.
        params = cls.get_frame_range_params(context, params)

        # Get video augmentation parameters.
        params = cls.get_video_augmentation_params(context, params, export_options)

        # Get video markup parameters.
        params = cls.get_video_markup_params(context, params, export_options)

        return True

    @classmethod
    def do_action(cls, context: CommandContext, params: dict):
        """Export video clip using the parameters provided.

        Args:
            context: The command context.
            params: The parameters for the export.
        """
        # Write the new video using the parameters provided.
        cls.write_new_video(context, params)

        # Open the file using default video playing app
        if params["open_when_done"]:
            open_file(params["video_filename"])

    @classmethod
    def write_new_video(
        cls,
        context: CommandContext,
        params: dict,
    ) -> None:
        """Write a new video using the parameters provided.

        Args:
            context: The command context.
            params: The parameters for the export.
        """
        # write_video(
        #     filename=params["video_filename"],
        #     video=context.state["video"],
        #     frames=list(params["frames"]),
        #     fps=params["fps"],
        #     scale=params["scale"],
        #     background=params["background"],
        #     gui_progress=params["gui_progress"],
        # )
        save_video(
            frames=[
                context.state["video"][frame_idx] for frame_idx in params["frames"]
            ],
            filename=params["video_filename"],
            fps=params["fps"],
        )

    @classmethod
    def get_export_options(cls, context: CommandContext, params: dict) -> dict | None:
        """Get export options from the user.

        Args:
            context: The command context.
            params: The parameters for the export.

        Returns:
            dict: The export options.
        """
        from sleap.gui.dialogs.export_clip import ExportClipDialog

        form_name = params.get("form_name", "video_clip_form")
        dialog = ExportClipDialog(form_name=form_name)

        # Set default fps from video (if video has fps attribute)
        dialog.form_widget.set_form_data(
            dict(fps=getattr(context.state["video"], "fps", 30))
        )

        # Show modal dialog and get form results
        export_options = dialog.get_results()

        # Check if user hit cancel
        if export_options is None:
            return False

        default_out_basename = params.get("filename", context.state["filename"])

        # For OpenCV we default to avi since the bundled ffmpeg
        # makes mp4's that most programs can't open (VLC can).
        default_out_filename = default_out_basename + ".avi"

        if can_use_ffmpeg():
            default_out_filename = default_out_basename + ".mp4"

        # Ask where user wants to save video file
        filename, _ = FileDialog.save(
            context.app,
            caption="Save Video As...",
            dir=default_out_filename,
            filter="Video (*.avi *.mp4)",
        )

        # Check if user hit cancel
        if len(filename) == 0:
            return None

        export_options["video_filename"] = filename
        return export_options

    @classmethod
    def get_video_save_params(cls, params: dict, export_options: dict) -> dict:
        """Get video save parameters.

        Args:
            params: The parameters for the export.
            export_options: The export options.

        Side Effects:
            Sets "video_filename", "fps", and "open_when_done" in params.

        Returns:
            dict: Containing the video save parameters (in addition to other params).
        """
        params["video_filename"] = export_options["video_filename"]
        params["fps"] = export_options["fps"]
        params["open_when_done"] = export_options["open_when_done"]
        return params

    @classmethod
    def get_frame_range_params(cls, context: CommandContext, params: dict) -> dict:
        """Get frame range parameters.

        Args:
            context: The command context.
            params: The parameters for the export.

        Side Effects:
            Sets "frames" in params.

        Returns:
            dict: Containing the frame range parameters (in addition to other params).
        """
        # If user selected a clip, use that; otherwise include all frames.
        if context.state["has_frame_range"]:
            params["frames"] = range(*context.state["frame_range"])
        else:
            params["frames"] = range(len(context.state["video"]))

        return params

    @classmethod
    def get_video_augmentation_params(
        cls, context: CommandContext, params: dict, export_options: dict
    ) -> dict:
        """Get video augmentation parameters.

        Args:
            context: The command context.
            params: The parameters for the export.
            export_options: The export options.

        Side Effects:
            Sets "scale", "background", and "crop" in params.

        Returns:
            dict: Containing the video augmentation parameters (in addition to other
                params).
        """
        params["scale"] = export_options.get("scale", 1.0)
        params["background"] = export_options.get("background", None)
        params["crop"] = None

        export_options_crop = export_options.get("crop", None)
        if export_options_crop is None:
            return params

        # Determine crop size relative to original size and scale
        # (crop size should be *final* output size, thus already scaled).
        video = context.state["video"]
        img_h, img_w = video.shape[1:3]
        w = int(img_w * params["scale"])
        h = int(img_h * params["scale"])
        if export_options_crop == "Half":
            params["crop"] = (w // 2, h // 2)
        elif export_options_crop == "Quarter":
            params["crop"] = (w // 4, h // 4)

        return params

    @classmethod
    def get_video_markup_params(
        cls, context: CommandContext, params: dict, export_options: dict
    ) -> dict:
        """Get video markup parameters.

        Args:
            context: The command context.
            params: The parameters for the export.
            export_options: The export options.

        Side Effects:
            Sets "color_manager", "show edges", "edge_is_wedge", and "marker size" in
            params.

        Returns:
            dict: Containing the video markup parameters (in addition to other params).
        """
        if export_options.get("use_gui_visuals", False):
            params["color_manager"] = context.app.color_manager
        else:
            params["color_manager"] = None

        params["show edges"] = context.state.get("show edges", default=True)
        params["edge_is_wedge"] = (
            context.state.get("edge style", default="").lower() == "wedge"
        )

        params["marker size"] = context.state.get("marker size", default=4)
        return params

ask(context, params) classmethod

Ask the user for parameters to export a video clip.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	The parameters for the export.	required

Returns:

Name	Type	Description
bool	bool	True if the user provided valid parameters, False otherwise.

Source code in sleap/gui/commands.py

@classmethod
def ask(cls, context: CommandContext, params: dict) -> bool:
    """Ask the user for parameters to export a video clip.

    Args:
        context: The command context.
        params: The parameters for the export.

    Returns:
        bool: True if the user provided valid parameters, False otherwise.
    """
    # Open export dialog.
    export_options = cls.get_export_options(context, params)
    if export_options is None:  # User hit cancel.
        return False

    # If we had a pop-up dialog, then we can also show GUI progress.
    params["gui_progress"] = True

    # Get video save parameters.
    params = cls.get_video_save_params(params, export_options)

    # Get frame range parameters.
    params = cls.get_frame_range_params(context, params)

    # Get video augmentation parameters.
    params = cls.get_video_augmentation_params(context, params, export_options)

    # Get video markup parameters.
    params = cls.get_video_markup_params(context, params, export_options)

    return True

do_action(context, params) classmethod

Export video clip using the parameters provided.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	The parameters for the export.	required

Source code in sleap/gui/commands.py

@classmethod
def do_action(cls, context: CommandContext, params: dict):
    """Export video clip using the parameters provided.

    Args:
        context: The command context.
        params: The parameters for the export.
    """
    # Write the new video using the parameters provided.
    cls.write_new_video(context, params)

    # Open the file using default video playing app
    if params["open_when_done"]:
        open_file(params["video_filename"])

get_export_options(context, params) classmethod

Get export options from the user.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	The parameters for the export.	required

Returns:

Name	Type	Description
dict	dict | None	The export options.

Source code in sleap/gui/commands.py

@classmethod
def get_export_options(cls, context: CommandContext, params: dict) -> dict | None:
    """Get export options from the user.

    Args:
        context: The command context.
        params: The parameters for the export.

    Returns:
        dict: The export options.
    """
    from sleap.gui.dialogs.export_clip import ExportClipDialog

    form_name = params.get("form_name", "video_clip_form")
    dialog = ExportClipDialog(form_name=form_name)

    # Set default fps from video (if video has fps attribute)
    dialog.form_widget.set_form_data(
        dict(fps=getattr(context.state["video"], "fps", 30))
    )

    # Show modal dialog and get form results
    export_options = dialog.get_results()

    # Check if user hit cancel
    if export_options is None:
        return False

    default_out_basename = params.get("filename", context.state["filename"])

    # For OpenCV we default to avi since the bundled ffmpeg
    # makes mp4's that most programs can't open (VLC can).
    default_out_filename = default_out_basename + ".avi"

    if can_use_ffmpeg():
        default_out_filename = default_out_basename + ".mp4"

    # Ask where user wants to save video file
    filename, _ = FileDialog.save(
        context.app,
        caption="Save Video As...",
        dir=default_out_filename,
        filter="Video (*.avi *.mp4)",
    )

    # Check if user hit cancel
    if len(filename) == 0:
        return None

    export_options["video_filename"] = filename
    return export_options

get_frame_range_params(context, params) classmethod

Get frame range parameters.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	The parameters for the export.	required

Side Effects

Sets "frames" in params.

Returns:

Name	Type	Description
dict	dict	Containing the frame range parameters (in addition to other params).

Source code in sleap/gui/commands.py

@classmethod
def get_frame_range_params(cls, context: CommandContext, params: dict) -> dict:
    """Get frame range parameters.

    Args:
        context: The command context.
        params: The parameters for the export.

    Side Effects:
        Sets "frames" in params.

    Returns:
        dict: Containing the frame range parameters (in addition to other params).
    """
    # If user selected a clip, use that; otherwise include all frames.
    if context.state["has_frame_range"]:
        params["frames"] = range(*context.state["frame_range"])
    else:
        params["frames"] = range(len(context.state["video"]))

    return params

get_video_augmentation_params(context, params, export_options) classmethod

Get video augmentation parameters.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	The parameters for the export.	required
export_options	dict	The export options.	required

Side Effects

Sets "scale", "background", and "crop" in params.

Returns:

Name	Type	Description
dict	dict	Containing the video augmentation parameters (in addition to other params).

Source code in sleap/gui/commands.py

@classmethod
def get_video_augmentation_params(
    cls, context: CommandContext, params: dict, export_options: dict
) -> dict:
    """Get video augmentation parameters.

    Args:
        context: The command context.
        params: The parameters for the export.
        export_options: The export options.

    Side Effects:
        Sets "scale", "background", and "crop" in params.

    Returns:
        dict: Containing the video augmentation parameters (in addition to other
            params).
    """
    params["scale"] = export_options.get("scale", 1.0)
    params["background"] = export_options.get("background", None)
    params["crop"] = None

    export_options_crop = export_options.get("crop", None)
    if export_options_crop is None:
        return params

    # Determine crop size relative to original size and scale
    # (crop size should be *final* output size, thus already scaled).
    video = context.state["video"]
    img_h, img_w = video.shape[1:3]
    w = int(img_w * params["scale"])
    h = int(img_h * params["scale"])
    if export_options_crop == "Half":
        params["crop"] = (w // 2, h // 2)
    elif export_options_crop == "Quarter":
        params["crop"] = (w // 4, h // 4)

    return params

get_video_markup_params(context, params, export_options) classmethod

Get video markup parameters.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	The parameters for the export.	required
export_options	dict	The export options.	required

Side Effects

Sets "color_manager", "show edges", "edge_is_wedge", and "marker size" in params.

Returns:

Name	Type	Description
dict	dict	Containing the video markup parameters (in addition to other params).

Source code in sleap/gui/commands.py

@classmethod
def get_video_markup_params(
    cls, context: CommandContext, params: dict, export_options: dict
) -> dict:
    """Get video markup parameters.

    Args:
        context: The command context.
        params: The parameters for the export.
        export_options: The export options.

    Side Effects:
        Sets "color_manager", "show edges", "edge_is_wedge", and "marker size" in
        params.

    Returns:
        dict: Containing the video markup parameters (in addition to other params).
    """
    if export_options.get("use_gui_visuals", False):
        params["color_manager"] = context.app.color_manager
    else:
        params["color_manager"] = None

    params["show edges"] = context.state.get("show edges", default=True)
    params["edge_is_wedge"] = (
        context.state.get("edge style", default="").lower() == "wedge"
    )

    params["marker size"] = context.state.get("marker size", default=4)
    return params

get_video_save_params(params, export_options) classmethod

Get video save parameters.

Parameters:

Name	Type	Description	Default
params	dict	The parameters for the export.	required
export_options	dict	The export options.	required

Side Effects

Sets "video_filename", "fps", and "open_when_done" in params.

Returns:

Name	Type	Description
dict	dict	Containing the video save parameters (in addition to other params).

Source code in sleap/gui/commands.py

@classmethod
def get_video_save_params(cls, params: dict, export_options: dict) -> dict:
    """Get video save parameters.

    Args:
        params: The parameters for the export.
        export_options: The export options.

    Side Effects:
        Sets "video_filename", "fps", and "open_when_done" in params.

    Returns:
        dict: Containing the video save parameters (in addition to other params).
    """
    params["video_filename"] = export_options["video_filename"]
    params["fps"] = export_options["fps"]
    params["open_when_done"] = export_options["open_when_done"]
    return params

write_new_video(context, params) classmethod

Write a new video using the parameters provided.

Parameters:

Name	Type	Description	Default
context	CommandContext	The command context.	required
params	dict	The parameters for the export.	required

Source code in sleap/gui/commands.py

@classmethod
def write_new_video(
    cls,
    context: CommandContext,
    params: dict,
) -> None:
    """Write a new video using the parameters provided.

    Args:
        context: The command context.
        params: The parameters for the export.
    """
    # write_video(
    #     filename=params["video_filename"],
    #     video=context.state["video"],
    #     frames=list(params["frames"]),
    #     fps=params["fps"],
    #     scale=params["scale"],
    #     background=params["background"],
    #     gui_progress=params["gui_progress"],
    # )
    save_video(
        frames=[
            context.state["video"][frame_idx] for frame_idx in params["frames"]
        ],
        filename=params["video_filename"],
        fps=params["fps"],
    )

FakeApp

Use if you want to execute commands independently of the GUI app.

Source code in sleap/gui/commands.py

@attr.s(auto_attribs=True)
class FakeApp:
    """Use if you want to execute commands independently of the GUI app."""

    labels: Labels

GenerateSuggestionsThread

Bases: QThread

Background thread for generating frame suggestions without freezing GUI.

Source code in sleap/gui/commands.py

class GenerateSuggestionsThread(QtCore.QThread):
    """Background thread for generating frame suggestions without freezing GUI."""

    finished = QtCore.Signal(list)
    error = QtCore.Signal(str)

    def __init__(self, labels, params, parent=None):
        super().__init__(parent)
        self.labels = labels
        self.params = params

    def run(self):
        try:
            suggestions = VideoFrameSuggestions.suggest(
                labels=self.labels, params=self.params
            )
            self.finished.emit(suggestions)
        except Exception as e:
            self.error.emit(str(e))

GoIteratorCommand

Bases: AppCommand

Source code in sleap/gui/commands.py

class GoIteratorCommand(AppCommand):
    @staticmethod
    def _plot_if_next(context, frame_iterator: Iterator) -> bool:
        """Plots next frame (if there is one) from iterator.

        Arguments:
            frame_iterator: The iterator from which we'll try to get next
            :class:`LabeledFrame`.

        Returns:
            True if we went to next frame.
        """
        try:
            next_lf = next(frame_iterator)
        except StopIteration:
            return False

        context.state["frame_idx"] = next_lf.frame_idx
        return True

    @staticmethod
    def _get_frame_iterator(context: CommandContext):
        raise NotImplementedError("Call to virtual method.")

    @classmethod
    def do_action(cls, context: CommandContext, params: dict):
        frames = cls._get_frame_iterator(context)
        cls._plot_if_next(context, frames)

InstanceDeleteCommand

Bases: EditCommand

Source code in sleap/gui/commands.py

class InstanceDeleteCommand(EditCommand):
    topics = [UpdateTopic.project_instances]

    @staticmethod
    def get_frame_instance_list(context: CommandContext, params: dict):
        raise NotImplementedError("Call to virtual method.")

    @staticmethod
    def _confirm_deletion(context: CommandContext, lf_inst_list: List) -> bool:
        """Helper function to confirm before deleting instances.

        Args:
            lf_inst_list: A list of (labeled frame, instance) tuples.
        """

        title = "Deleting instances"
        message = (
            f"There are {len(lf_inst_list)} instances which would be deleted. "
            f"Are you sure you want to delete these?"
        )

        # Confirm that we want to delete
        resp = QtWidgets.QMessageBox.critical(
            context.app,
            title,
            message,
            QtWidgets.QMessageBox.Yes,
            QtWidgets.QMessageBox.No,
        )

        if resp == QtWidgets.QMessageBox.No:
            return False

        return True

    @staticmethod
    def _do_deletion(context: CommandContext, lf_inst_list: List[int]):
        # Delete the instances
        lfs_to_remove = []
        for lf, inst in lf_inst_list:
            remove_instance(context.labels, instance=inst, lf=lf)
            if context.state["instance"] == inst:
                context.state["instance"] = None
            if len(lf.instances) == 0:
                lfs_to_remove.append(lf)

        remove_frames(context.labels, lfs_to_remove)

        # # Update caches since we skipped doing this after each deletion
        # context.labels.update_cache()

        # Update visuals
        context.changestack_push("delete instances")

    @classmethod
    def do_action(cls, context: CommandContext, params: dict):
        cls._do_deletion(context, params["lf_instance_list"])

    @classmethod
    def ask(cls, context: CommandContext, params: dict) -> bool:
        lf_inst_list = cls.get_frame_instance_list(context, params)
        params["lf_instance_list"] = lf_inst_list

        return cls._confirm_deletion(context, lf_inst_list)

LoadLabelsObject

Bases: AppCommand

Methods:

Name	Description
do_action	Loads a Labels object into the GUI, replacing any currently loaded.

Source code in sleap/gui/commands.py

class LoadLabelsObject(AppCommand):
    @staticmethod
    def do_action(context: "CommandContext", params: dict):
        """Loads a `Labels` object into the GUI, replacing any currently loaded.

        Args:
            labels: The `Labels` object to load.
            filename: The filename where this file is saved, if any.

        Returns:
            None.
        """
        filename = params.get("filename", None)  # If called with just a Labels object
        labels: Labels = params["labels"]

        context.state["labels"] = labels
        context.state["filename"] = filename

        context.changestack_clear()
        context.app.color_manager.labels = context.labels
        context.app.color_manager.set_palette(context.state["palette"])

        context.app._load_overlays()

        if len(labels.skeletons):
            context.state["skeleton"] = labels.skeletons[0]

        # Load first video
        if len(labels.videos):
            context.state["video"] = labels.videos[0]

        context.state["project_loaded"] = True
        context.state["has_changes"] = params.get("changed_on_load", False) or (
            filename is None
        )

        # This is not listed as an edit command since we want a clean changestack
        context.app.on_data_update([UpdateTopic.project, UpdateTopic.all])

do_action(context, params) staticmethod

Loads a Labels object into the GUI, replacing any currently loaded.

Parameters:

Name	Type	Description	Default
labels		The Labels object to load.	required
filename		The filename where this file is saved, if any.	required

Returns:

Type	Description
	None.

Source code in sleap/gui/commands.py

@staticmethod
def do_action(context: "CommandContext", params: dict):
    """Loads a `Labels` object into the GUI, replacing any currently loaded.

    Args:
        labels: The `Labels` object to load.
        filename: The filename where this file is saved, if any.

    Returns:
        None.
    """
    filename = params.get("filename", None)  # If called with just a Labels object
    labels: Labels = params["labels"]

    context.state["labels"] = labels
    context.state["filename"] = filename

    context.changestack_clear()
    context.app.color_manager.labels = context.labels
    context.app.color_manager.set_palette(context.state["palette"])

    context.app._load_overlays()

    if len(labels.skeletons):
        context.state["skeleton"] = labels.skeletons[0]

    # Load first video
    if len(labels.videos):
        context.state["video"] = labels.videos[0]

    context.state["project_loaded"] = True
    context.state["has_changes"] = params.get("changed_on_load", False) or (
        filename is None
    )

    # This is not listed as an edit command since we want a clean changestack
    context.app.on_data_update([UpdateTopic.project, UpdateTopic.all])

MergeInstances

Bases: EditCommand

Merge two user instances in the current frame into a single instance.

The currently selected instance (context.state["instance"]) is the survivor. The instance to merge into it is the donor, taken from params["donor"]; if no donor is given and the frame has exactly two user instances, the other one is used automatically.

For every skeleton node, if the survivor's node is missing (NaN coordinates or not visible) and the donor's node is labeled/visible, the donor's xy/visible/complete values are copied onto the survivor. This lets a "front keypoints" instance and a "back keypoints" instance be combined into one. The survivor keeps its own track.

Conflict policy: if BOTH the survivor and the donor have a node labeled/visible, the survivor's value is kept (the donor's value for that node is discarded).

Scope/behavior decisions: - Only user Instances participate. PredictedInstances are never chosen as survivor or donor and are left untouched on the frame. - If there are fewer than two user instances, no donor can be resolved, the survivor is not a user Instance, or required state is missing, this is a no-op (with a status message when running in the GUI). - After merging, the donor is removed from the frame by identity and labels.update() is called. There is no dedicated undo (matching DeleteSelectedInstance/PasteInstance); EditCommand only flags the project as having unsaved changes.

Source code in sleap/gui/commands.py

class MergeInstances(EditCommand):
    """Merge two user instances in the current frame into a single instance.

    The currently selected instance (``context.state["instance"]``) is the
    *survivor*. The instance to merge into it is the *donor*, taken from
    ``params["donor"]``; if no donor is given and the frame has exactly two
    user instances, the other one is used automatically.

    For every skeleton node, if the survivor's node is missing (NaN coordinates
    or not visible) and the donor's node is labeled/visible, the donor's
    ``xy``/``visible``/``complete`` values are copied onto the survivor. This
    lets a "front keypoints" instance and a "back keypoints" instance be
    combined into one. The survivor keeps its own track.

    Conflict policy: if BOTH the survivor and the donor have a node
    labeled/visible, the survivor's value is kept (the donor's value for that
    node is discarded).

    Scope/behavior decisions:
        - Only user ``Instance``s participate. ``PredictedInstance``s are never
          chosen as survivor or donor and are left untouched on the frame.
        - If there are fewer than two user instances, no donor can be resolved,
          the survivor is not a user ``Instance``, or required state is
          missing, this is a no-op (with a status message when running in the
          GUI).
        - After merging, the donor is removed from the frame *by identity* and
          ``labels.update()`` is called. There is no dedicated undo (matching
          ``DeleteSelectedInstance``/``PasteInstance``); ``EditCommand`` only
          flags the project as having unsaved changes.
    """

    topics = [UpdateTopic.frame, UpdateTopic.project_instances]

    @staticmethod
    def _status(context: "CommandContext", message: str):
        """Post a status message if the app supports it (no-op when headless)."""
        if hasattr(context.app, "updateStatusMessage"):
            context.app.updateStatusMessage(message)

    @staticmethod
    def do_action(context: "CommandContext", params: dict):
        survivor = context.state["instance"]
        frame = context.state["labeled_frame"]
        skeleton = context.state["skeleton"]
        donor = params.get("donor", None)
        if donor is None:
            # Donor picked by shift/ctrl-selecting a second instance in the list
            # (first-selected is the survivor, second is the donor).
            donor = context.state.get("merge_partner", default=None)

        if survivor is None or frame is None or skeleton is None:
            return

        # Only user instances can be merged (skip PredictedInstance).
        if type(survivor) is not Instance:
            MergeInstances._status(
                context, "Merge Instance: select a user instance first."
            )
            return

        user_instances = frame.user_instances
        if len(user_instances) < 2:
            MergeInstances._status(
                context,
                "Merge Instance: need at least two user instances in the frame.",
            )
            return

        # Fast path: exactly two user instances -> donor is the other one.
        if donor is None and len(user_instances) == 2:
            donor = next(inst for inst in user_instances if inst is not survivor)

        if donor is None or donor is survivor or type(donor) is not Instance:
            MergeInstances._status(
                context, "Merge Instance: no valid instance to merge."
            )
            return

        # Guard against mismatched skeletons (all instances in a frame normally
        # share the project skeleton, but be safe).
        if not survivor.skeleton.matches(donor.skeleton):
            MergeInstances._status(
                context, "Merge Instance: instances have different skeletons."
            )
            return

        for node in skeleton.node_names:
            s_pt = survivor[node]
            d_pt = donor[node]
            survivor_missing = bool(np.isnan(s_pt["xy"]).any()) or not bool(
                s_pt["visible"]
            )
            donor_labeled = (not bool(np.isnan(d_pt["xy"]).any())) and bool(
                d_pt["visible"]
            )
            # Conflict policy: only fill nodes the survivor is missing; nodes
            # the survivor already has are kept as-is.
            if survivor_missing and donor_labeled:
                s_pt["xy"][0] = d_pt["xy"][0]
                s_pt["xy"][1] = d_pt["xy"][1]
                s_pt["visible"] = d_pt["visible"]
                s_pt["complete"] = d_pt["complete"]

        # Remove the donor *by identity* and persist. We must not use pose/track
        # matching here (e.g. ``remove_instance``): after the merge the survivor
        # can become pose-identical to the donor (when the donor's labeled nodes
        # are a superset of the survivor's), so for untracked or same-track
        # instances a pose-based search could remove the survivor instead. An
        # ``is``-based filter is unambiguous regardless of ``Instance.__eq__``.
        frame.instances[:] = [inst for inst in frame.instances if inst is not donor]
        context.labels.update()

        # Keep the survivor selected; clear the donor selection.
        context.state["instance"] = survivor
        context.state["merge_partner"] = None

OpenSkeleton

Bases: EditCommand

Methods:

Name	Description
do_action	Replace skeleton with new skeleton.
get_template_skeleton_filename	Helper function to get the template skeleton filename from dropdown.

Source code in sleap/gui/commands.py

class OpenSkeleton(EditCommand):
    topics = [UpdateTopic.skeleton]

    @staticmethod
    def load_skeleton(filename: str):
        from sleap_io.io.skeleton import SkeletonDecoder
        import simplejson as json

        with open(filename, "r") as f:
            skeleton_data = json.load(f)
            skeleton_data = (
                skeleton_data["nx_graph"]
                if "nx_graph" in skeleton_data
                else skeleton_data
            )
        skel = SkeletonDecoder().decode(data=skeleton_data)
        skel = skel[0] if isinstance(skel, list) else skel
        return skel

    @staticmethod
    def compare_skeletons(
        skeleton: Skeleton, new_skeleton: Skeleton
    ) -> Tuple[List[str], List[str], List[str]]:
        delete_nodes = []
        add_nodes = []
        if skeleton.node_names != new_skeleton.node_names:
            # Compare skeletons
            base_nodes = skeleton.node_names
            new_nodes = new_skeleton.node_names
            delete_nodes = [node for node in base_nodes if node not in new_nodes]
            add_nodes = [node for node in new_nodes if node not in base_nodes]

        # We want to run this even if the skeletons are the same
        rename_nodes = [
            node for node in skeleton.node_names if node not in delete_nodes
        ]

        return rename_nodes, delete_nodes, add_nodes

    @staticmethod
    def delete_extra_skeletons(labels: Labels):
        if len(labels.skeletons) > 1:
            skeletons_used = list(
                set(
                    [
                        inst.skeleton
                        for lf in labels.labeled_frames
                        for inst in lf.instances
                    ]
                )
            )
            try:
                assert len(skeletons_used) == 1
            except AssertionError:
                raise ValueError("Too many skeletons used in project.")

            labels.skeletons = skeletons_used

    @staticmethod
    def get_template_skeleton_filename(context: CommandContext) -> str:
        """Helper function to get the template skeleton filename from dropdown.

        Args:
            context: The `CommandContext`.

        Returns:
            Path to the template skeleton shipped with SLEAP.
        """

        template = context.app.skeleton_dock.skeleton_templates.currentText()
        filename = get_package_file(f"skeletons/{template}.json")
        return filename

    @staticmethod
    def ask(context: CommandContext, params: dict) -> bool:
        filters = ["JSON skeleton (*.json)", "HDF5 skeleton (*.h5 *.hdf5)"]
        # Check whether to load from file or preset
        if params.get("template", False):
            # Get selected template from dropdown
            filename = OpenSkeleton.get_template_skeleton_filename(context)
        else:
            filename, selected_filter = FileDialog.open(
                context.app,
                dir=None,
                caption="Open skeleton...",
                filter=";;".join(filters),
            )

        if len(filename) == 0:
            return False

        okay = True
        if len(context.labels.skeletons) > 0:
            # Ask user permission to merge skeletons
            okay = False
            skeleton: Skeleton = context.labels.skeleton  # Assumes single skeleton

            # Load new skeleton and compare
            new_skeleton = OpenSkeleton.load_skeleton(filename)
            (rename_nodes, delete_nodes, add_nodes) = OpenSkeleton.compare_skeletons(
                skeleton, new_skeleton
            )

            if (len(delete_nodes) > 0) or (len(add_nodes) > 0):
                # Allow user to link mismatched nodes
                query = ReplaceSkeletonTableDialog(
                    rename_nodes=rename_nodes,
                    delete_nodes=delete_nodes,
                    add_nodes=add_nodes,
                )
                query.exec_()

                # Give the okay to add/delete nodes
                linked_nodes: Optional[Dict[str, str]] = query.result()
                if linked_nodes is not None:
                    delete_nodes = list(set(delete_nodes) - set(linked_nodes.values()))
                    add_nodes = list(set(add_nodes) - set(linked_nodes.keys()))
                    params["linked_nodes"] = linked_nodes
                    okay = True

            params["delete_nodes"] = delete_nodes
            params["add_nodes"] = add_nodes

        params["filename"] = filename
        return okay

    @staticmethod
    def do_action(context: CommandContext, params: dict):
        """Replace skeleton with new skeleton.

        Note that we modify the existing skeleton in-place to essentially match the new
        skeleton. However, we cannot rename the skeleton since `Skeleton.name` is used
        for hashing (see `Skeleton.name` setter).

        Args:
            context: CommandContext
            params: dict
                filename: str
                delete_nodes: List[str]
                add_nodes: List[str]
                linked_nodes: Dict[str, str]

        Returns:
            None
        """

        # TODO (LM): This is a hack to get around the fact that we do some dangerous
        # in-place operations on the skeleton. We should fix this.
        def try_and_skip_if_error(func, *args, **kwargs):
            """This is a helper function to try and skip if there is an error."""
            try:
                func(*args, **kwargs)
            except Exception as e:
                tb_str = traceback.format_exception(
                    type(e), value=e, tb=e.__traceback__
                )
                logger.warning(
                    f"Recieved the following error while replacing skeleton:\n"
                    f"{''.join(tb_str)}"
                )

        # Load new skeleton
        filename = params["filename"]
        new_skeleton = OpenSkeleton.load_skeleton(filename)

        # Description and preview image only used for template skeletons
        # new_skeleton.description = None
        # new_skeleton.preview_image = None
        # context.state["skeleton_description"] = new_skeleton.description
        # context.state["skeleton_preview_image"] = new_skeleton.preview_image

        # Case 1: No skeleton exists in project
        if len(context.labels.skeletons) == 0:
            context.state["skeleton"] = new_skeleton
            context.labels.skeletons.append(context.state["skeleton"])
            return

        # Case 2: Skeleton(s) already exist(s) in project

        # Delete extra skeletons in project
        OpenSkeleton.delete_extra_skeletons(context.labels)
        skeleton = context.labels.skeleton  # Assume single skeleton

        if "delete_nodes" in params.keys():
            # We already compared skeletons in ask() method
            delete_nodes: List[str] = params["delete_nodes"]
            add_nodes: List[str] = params["add_nodes"]
        else:
            # Otherwise, load new skeleton and compare
            (rename_nodes, delete_nodes, add_nodes) = OpenSkeleton.compare_skeletons(
                skeleton, new_skeleton
            )

        # Delete pre-existing symmetry
        for symmetry in skeleton.symmetries:
            # In sleap-io, symmetry.nodes is a set, not a list
            nodes_list = list(symmetry.nodes)
            delete_symmetry(skeleton, nodes_list[0].name, nodes_list[1].name)

        # Link mismatched nodes
        if "linked_nodes" in params.keys():
            linked_nodes = params["linked_nodes"]
            for new_name, old_name in linked_nodes.items():
                try_and_skip_if_error(skeleton.rename_node, old_name, new_name)

        # Delete nodes from skeleton that are not in new skeleton
        for node in delete_nodes:
            try_and_skip_if_error(skeleton.remove_node, node)

        # Add nodes that only exist in the new skeleton
        for node in add_nodes:
            try_and_skip_if_error(skeleton.add_node, node)

        # Add edges
        skeleton.edges = []
        for src, dest in new_skeleton.edges:
            try_and_skip_if_error(skeleton.add_edge, src.name, dest.name)

        # Add new symmetry
        for src, dst in new_skeleton.symmetries:
            try_and_skip_if_error(skeleton.add_symmetry, src.name, dst.name)

        # Set state of context
        context.state["skeleton"] = skeleton

do_action(context, params) staticmethod

Replace skeleton with new skeleton.

Note that we modify the existing skeleton in-place to essentially match the new skeleton. However, we cannot rename the skeleton since Skeleton.name is used for hashing (see Skeleton.name setter).

Parameters:

Name	Type	Description	Default
context	CommandContext	CommandContext	required
params	dict	dict filename: str delete_nodes: List[str] add_nodes: List[str] linked_nodes: Dict[str, str]	required

Returns:

Type	Description
	None

Source code in sleap/gui/commands.py

@staticmethod
def do_action(context: CommandContext, params: dict):
    """Replace skeleton with new skeleton.

    Note that we modify the existing skeleton in-place to essentially match the new
    skeleton. However, we cannot rename the skeleton since `Skeleton.name` is used
    for hashing (see `Skeleton.name` setter).

    Args:
        context: CommandContext
        params: dict
            filename: str
            delete_nodes: List[str]
            add_nodes: List[str]
            linked_nodes: Dict[str, str]

    Returns:
        None
    """

    # TODO (LM): This is a hack to get around the fact that we do some dangerous
    # in-place operations on the skeleton. We should fix this.
    def try_and_skip_if_error(func, *args, **kwargs):
        """This is a helper function to try and skip if there is an error."""
        try:
            func(*args, **kwargs)
        except Exception as e:
            tb_str = traceback.format_exception(
                type(e), value=e, tb=e.__traceback__
            )
            logger.warning(
                f"Recieved the following error while replacing skeleton:\n"
                f"{''.join(tb_str)}"
            )

    # Load new skeleton
    filename = params["filename"]
    new_skeleton = OpenSkeleton.load_skeleton(filename)

    # Description and preview image only used for template skeletons
    # new_skeleton.description = None
    # new_skeleton.preview_image = None
    # context.state["skeleton_description"] = new_skeleton.description
    # context.state["skeleton_preview_image"] = new_skeleton.preview_image

    # Case 1: No skeleton exists in project
    if len(context.labels.skeletons) == 0:
        context.state["skeleton"] = new_skeleton
        context.labels.skeletons.append(context.state["skeleton"])
        return

    # Case 2: Skeleton(s) already exist(s) in project

    # Delete extra skeletons in project
    OpenSkeleton.delete_extra_skeletons(context.labels)
    skeleton = context.labels.skeleton  # Assume single skeleton

    if "delete_nodes" in params.keys():
        # We already compared skeletons in ask() method
        delete_nodes: List[str] = params["delete_nodes"]
        add_nodes: List[str] = params["add_nodes"]
    else:
        # Otherwise, load new skeleton and compare
        (rename_nodes, delete_nodes, add_nodes) = OpenSkeleton.compare_skeletons(
            skeleton, new_skeleton
        )

    # Delete pre-existing symmetry
    for symmetry in skeleton.symmetries:
        # In sleap-io, symmetry.nodes is a set, not a list
        nodes_list = list(symmetry.nodes)
        delete_symmetry(skeleton, nodes_list[0].name, nodes_list[1].name)

    # Link mismatched nodes
    if "linked_nodes" in params.keys():
        linked_nodes = params["linked_nodes"]
        for new_name, old_name in linked_nodes.items():
            try_and_skip_if_error(skeleton.rename_node, old_name, new_name)

    # Delete nodes from skeleton that are not in new skeleton
    for node in delete_nodes:
        try_and_skip_if_error(skeleton.remove_node, node)

    # Add nodes that only exist in the new skeleton
    for node in add_nodes:
        try_and_skip_if_error(skeleton.add_node, node)

    # Add edges
    skeleton.edges = []
    for src, dest in new_skeleton.edges:
        try_and_skip_if_error(skeleton.add_edge, src.name, dest.name)

    # Add new symmetry
    for src, dst in new_skeleton.symmetries:
        try_and_skip_if_error(skeleton.add_symmetry, src.name, dst.name)

    # Set state of context
    context.state["skeleton"] = skeleton

get_template_skeleton_filename(context) staticmethod

Helper function to get the template skeleton filename from dropdown.

Parameters:

Name	Type	Description	Default
context	CommandContext	The CommandContext.	required

Returns:

Type	Description
str	Path to the template skeleton shipped with SLEAP.

Source code in sleap/gui/commands.py

@staticmethod
def get_template_skeleton_filename(context: CommandContext) -> str:
    """Helper function to get the template skeleton filename from dropdown.

    Args:
        context: The `CommandContext`.

    Returns:
        Path to the template skeleton shipped with SLEAP.
    """

    template = context.app.skeleton_dock.skeleton_templates.currentText()
    filename = get_package_file(f"skeletons/{template}.json")
    return filename

RenderVideoThread

Bases: QThread

Background thread for rendering video without freezing GUI.

Uses sleap-io's render_video() with progress_callback for non-blocking rendering.

Methods:

Name	Description
__init__	Initialize the render video thread.
cancel	Request cancellation of the render.
run	Run the render in background thread.

Source code in sleap/gui/commands.py

class RenderVideoThread(QtCore.QThread):
    """Background thread for rendering video without freezing GUI.

    Uses sleap-io's render_video() with progress_callback for non-blocking rendering.
    """

    progress = QtCore.Signal(int, int)  # (current, total)
    finished = QtCore.Signal(str)  # output filename
    error = QtCore.Signal(str)  # error message
    cancelled = QtCore.Signal()

    def __init__(
        self,
        labels,
        filename: str,
        video,
        frame_inds: list[int] | None,
        render_params: dict,
        parent=None,
    ):
        """Initialize the render video thread.

        Args:
            labels: Labels object to render.
            filename: Output video path.
            video: Video to render from.
            frame_inds: Frame indices to render (None = all labeled).
            render_params: Dict of rendering parameters for sio.render_video().
            parent: Parent QObject.
        """
        super().__init__(parent)
        self.labels = labels
        self.filename = filename
        self.video = video
        self.frame_inds = frame_inds
        self.render_params = render_params
        self._cancelled = False

    def cancel(self):
        """Request cancellation of the render."""
        self._cancelled = True

    def run(self):
        """Run the render in background thread."""
        import sleap_io as sio

        def on_progress(current, total):
            """Progress callback for sio.render_video()."""
            self.progress.emit(current, total)
            # Return False to cancel rendering
            return not self._cancelled

        try:
            sio.render_video(
                self.labels,
                self.filename,
                video=self.video,
                frame_inds=self.frame_inds,
                progress_callback=on_progress,
                show_progress=False,  # We handle progress ourselves
                **self.render_params,
            )

            if self._cancelled:
                # Clean up partial file on cancellation
                if Path(self.filename).exists():
                    os.remove(self.filename)
                self.cancelled.emit()
                return

            self.finished.emit(self.filename)

        except Exception as e:
            # Check if this was a cancellation
            is_cancelled = "cancel" in str(e).lower() or self._cancelled
            if is_cancelled:
                # Clean up partial file
                if Path(self.filename).exists():
                    os.remove(self.filename)
                self.cancelled.emit()
            else:
                self.error.emit(str(e))

__init__(labels, filename, video, frame_inds, render_params, parent=None)

Initialize the render video thread.

Parameters:

Name	Type	Description	Default
labels		Labels object to render.	required
filename	str	Output video path.	required
video		Video to render from.	required
frame_inds	list[int] | None	Frame indices to render (None = all labeled).	required
render_params	dict	Dict of rendering parameters for sio.render_video().	required
parent		Parent QObject.	None

Source code in sleap/gui/commands.py

def __init__(
    self,
    labels,
    filename: str,
    video,
    frame_inds: list[int] | None,
    render_params: dict,
    parent=None,
):
    """Initialize the render video thread.

    Args:
        labels: Labels object to render.
        filename: Output video path.
        video: Video to render from.
        frame_inds: Frame indices to render (None = all labeled).
        render_params: Dict of rendering parameters for sio.render_video().
        parent: Parent QObject.
    """
    super().__init__(parent)
    self.labels = labels
    self.filename = filename
    self.video = video
    self.frame_inds = frame_inds
    self.render_params = render_params
    self._cancelled = False

cancel()

Request cancellation of the render.

Source code in sleap/gui/commands.py

def cancel(self):
    """Request cancellation of the render."""
    self._cancelled = True

run()

Run the render in background thread.

Source code in sleap/gui/commands.py

def run(self):
    """Run the render in background thread."""
    import sleap_io as sio

    def on_progress(current, total):
        """Progress callback for sio.render_video()."""
        self.progress.emit(current, total)
        # Return False to cancel rendering
        return not self._cancelled

    try:
        sio.render_video(
            self.labels,
            self.filename,
            video=self.video,
            frame_inds=self.frame_inds,
            progress_callback=on_progress,
            show_progress=False,  # We handle progress ourselves
            **self.render_params,
        )

        if self._cancelled:
            # Clean up partial file on cancellation
            if Path(self.filename).exists():
                os.remove(self.filename)
            self.cancelled.emit()
            return

        self.finished.emit(self.filename)

    except Exception as e:
        # Check if this was a cancellation
        is_cancelled = "cancel" in str(e).lower() or self._cancelled
        if is_cancelled:
            # Clean up partial file
            if Path(self.filename).exists():
                os.remove(self.filename)
            self.cancelled.emit()
        else:
            self.error.emit(str(e))

ReplaceVideo

Bases: EditCommand

Methods:

Name	Description
ask	Shows gui for replacing videos in project.

Source code in sleap/gui/commands.py

class ReplaceVideo(EditCommand):
    topics = [UpdateTopic.video, UpdateTopic.frame]

    @staticmethod
    def do_action(context: CommandContext, params: dict) -> bool:
        import_list = params["import_list"]

        for import_item, video in import_list:
            import_params = import_item["params"]

            # TODO: Will need to create a new backend if import has different extension.
            # ImageVideo backends return a list[str] for filename; use the first path
            # as the representative name for the extension check.
            video_filename = (
                video.filename[0]
                if isinstance(video.filename, list)
                else video.filename
            )
            if Path(video_filename).suffix != Path(import_params["filename"]).suffix:
                raise TypeError(
                    "Importing videos with different extensions is not supported."
                )
            # video.backend.reset(**import_params) potential breaking change
            video_util_reset(video, **import_params)

            # Remove frames in video past last frame index
            last_vid_frame = get_last_frame_idx(video)
            lfs: List[LabeledFrame] = list(context.labels.find(video))
            if lfs is not None:
                lfs = [lf for lf in lfs if lf.frame_idx > last_vid_frame]
                remove_frames(context.labels, lfs)

            # Update seekbar and video length through callbacks
            context.state.emit("video")

    @staticmethod
    def ask(context: CommandContext, params: dict) -> bool:
        """Shows gui for replacing videos in project."""

        def _get_truncation_message(truncation_messages, path, video):
            reader = cv2.VideoCapture(path)
            last_vid_frame = int(reader.get(cv2.CAP_PROP_FRAME_COUNT))
            lfs: List[LabeledFrame] = list(context.labels.find(video))
            if lfs is not None:
                lfs.sort(key=lambda lf: lf.frame_idx)
                last_lf_frame = lfs[-1].frame_idx
                lfs = [lf for lf in lfs if lf.frame_idx > last_vid_frame]

                # Message to warn users that labels will be removed if proceed
                if last_lf_frame > last_vid_frame:
                    # ImageVideo backends return a list[str] for filename; use the
                    # first path as the representative name for display.
                    cur_fn = (
                        video.filename[0]
                        if isinstance(video.filename, list)
                        else video.filename
                    )
                    cur_name = Path(cur_fn).name
                    message = (
                        "<p><strong>Warning:</strong> Replacing this video will "
                        f"remove {len(lfs)} labeled frames.</p>"
                        f"<p><em>Current video</em>: <b>{cur_name}</b>"
                        f" (last label at frame {last_lf_frame})<br>"
                        f"<em>Replacement video</em>: <b>{Path(path).name}"
                        f"</b> ({last_vid_frame} frames)</p>"
                    )
                    # Assumes that a project won't import the same video multiple times
                    truncation_messages[path] = message

            return truncation_messages

        # Warn user: newly added labels will be discarded if project is not saved
        if not context.state["filename"] or context.state["has_changes"]:
            QtWidgets.QMessageBox(
                text=("You have unsaved changes. Please save before replacing videos.")
            ).exec_()
            return False

        # Select the videos we want to swap.
        # ImageVideo backends return a list[str] for filename; use the first path
        # so MissingFilesDialog can treat each entry as a single file path.
        old_paths = [
            video.filename[0] if isinstance(video.filename, list) else video.filename
            for video in context.labels.videos
        ]
        paths = list(old_paths)
        okay = MissingFilesDialog(filenames=paths, replace=True).exec_()
        if not okay:
            return False

        # Only return an import list for videos we swap
        new_paths = [
            (path, video_idx)
            for video_idx, (path, old_path) in enumerate(zip(paths, old_paths))
            if path != old_path
        ]

        new_paths = []
        old_videos = dict()
        all_videos = context.labels.videos
        truncation_messages = dict()
        for video_idx, (path, old_path) in enumerate(zip(paths, old_paths)):
            if path != old_path:
                new_paths.append(path)
                old_videos[path] = all_videos[video_idx]
                truncation_messages = _get_truncation_message(
                    truncation_messages, path, video=all_videos[video_idx]
                )

        import_list = ImportVideos().ask(
            filenames=new_paths, messages=truncation_messages
        )
        # Remove videos that no longer correlate to filenames.
        old_videos_to_replace = [
            old_videos[imp["params"]["filename"]] for imp in import_list
        ]
        params["import_list"] = zip(import_list, old_videos_to_replace)

        return len(import_list) > 0

ask(context, params) staticmethod

Shows gui for replacing videos in project.

Source code in sleap/gui/commands.py

@staticmethod
def ask(context: CommandContext, params: dict) -> bool:
    """Shows gui for replacing videos in project."""

    def _get_truncation_message(truncation_messages, path, video):
        reader = cv2.VideoCapture(path)
        last_vid_frame = int(reader.get(cv2.CAP_PROP_FRAME_COUNT))
        lfs: List[LabeledFrame] = list(context.labels.find(video))
        if lfs is not None:
            lfs.sort(key=lambda lf: lf.frame_idx)
            last_lf_frame = lfs[-1].frame_idx
            lfs = [lf for lf in lfs if lf.frame_idx > last_vid_frame]

            # Message to warn users that labels will be removed if proceed
            if last_lf_frame > last_vid_frame:
                # ImageVideo backends return a list[str] for filename; use the
                # first path as the representative name for display.
                cur_fn = (
                    video.filename[0]
                    if isinstance(video.filename, list)
                    else video.filename
                )
                cur_name = Path(cur_fn).name
                message = (
                    "<p><strong>Warning:</strong> Replacing this video will "
                    f"remove {len(lfs)} labeled frames.</p>"
                    f"<p><em>Current video</em>: <b>{cur_name}</b>"
                    f" (last label at frame {last_lf_frame})<br>"
                    f"<em>Replacement video</em>: <b>{Path(path).name}"
                    f"</b> ({last_vid_frame} frames)</p>"
                )
                # Assumes that a project won't import the same video multiple times
                truncation_messages[path] = message

        return truncation_messages

    # Warn user: newly added labels will be discarded if project is not saved
    if not context.state["filename"] or context.state["has_changes"]:
        QtWidgets.QMessageBox(
            text=("You have unsaved changes. Please save before replacing videos.")
        ).exec_()
        return False

    # Select the videos we want to swap.
    # ImageVideo backends return a list[str] for filename; use the first path
    # so MissingFilesDialog can treat each entry as a single file path.
    old_paths = [
        video.filename[0] if isinstance(video.filename, list) else video.filename
        for video in context.labels.videos
    ]
    paths = list(old_paths)
    okay = MissingFilesDialog(filenames=paths, replace=True).exec_()
    if not okay:
        return False

    # Only return an import list for videos we swap
    new_paths = [
        (path, video_idx)
        for video_idx, (path, old_path) in enumerate(zip(paths, old_paths))
        if path != old_path
    ]

    new_paths = []
    old_videos = dict()
    all_videos = context.labels.videos
    truncation_messages = dict()
    for video_idx, (path, old_path) in enumerate(zip(paths, old_paths)):
        if path != old_path:
            new_paths.append(path)
            old_videos[path] = all_videos[video_idx]
            truncation_messages = _get_truncation_message(
                truncation_messages, path, video=all_videos[video_idx]
            )

    import_list = ImportVideos().ask(
        filenames=new_paths, messages=truncation_messages
    )
    # Remove videos that no longer correlate to filenames.
    old_videos_to_replace = [
        old_videos[imp["params"]["filename"]] for imp in import_list
    ]
    params["import_list"] = zip(import_list, old_videos_to_replace)

    return len(import_list) > 0

SaveProjectAs

Bases: AppCommand

Source code in sleap/gui/commands.py

class SaveProjectAs(AppCommand):
    @staticmethod
    def _try_save(context, labels: Labels, filename: str):
        """Helper function which attempts save and handles errors."""
        import sleap_io as sio

        success = False
        try:
            extension = (PurePath(filename).suffix)[1:]
            extension = None if (extension == "slp") else extension
            if extension == "nwb":
                sio.save_nwb(labels=labels, filename=filename)
            else:
                save_file(labels=labels, filename=filename, format=extension)
            success = True
            # Mark savepoint in change stack
            context.changestack_savepoint()

        except Exception as e:
            message = (
                f"An error occured when attempting to save:\n {e}\n\n"
                "Try saving your project with a different filename or in a different "
                "format."
            )
            QtWidgets.QMessageBox(text=message).exec_()

        # Redraw. Not sure why, but sometimes we need to do this.
        context.app.plotFrame()

        return success

    @classmethod
    def do_action(cls, context: CommandContext, params: dict):
        if cls._try_save(context, context.state["labels"], params["filename"]):
            # If save was successful
            context.state["filename"] = params["filename"]

    @staticmethod
    def ask(context: CommandContext, params: dict) -> bool:
        default_name = context.state["filename"] or "labels.v000.slp"
        if "adaptor" in params:
            adaptor: Adaptor = params["adaptor"]
            if adaptor == "nwb":
                default_name += ".nwb"
                filters = ["(*.nwb)"]
                filters[0] = f"NWB {filters[0]}"
        else:
            filters = ["SLEAP labels dataset (*.slp)"]
            if default_name:
                default_name = get_new_version_filename(default_name)

        filename, selected_filter = FileDialog.save(
            context.app,
            caption="Save As...",
            dir=default_name,
            filter=";;".join(filters),
        )

        if len(filename) == 0:
            return False

        params["filename"] = filename
        return True

SetInstancePointLocations

Bases: EditCommand

Sets locations for node(s) for an instance.

Note: It's important that this command does not update the visual scene, since this would redraw the frame and create new visual objects. The calling code is responsible for updating the visual scene.

Parameters:

Name	Type	Description	Default
instance		The instance	required
nodes_locations		A dictionary of data to set	required

Source code in sleap/gui/commands.py

class SetInstancePointLocations(EditCommand):
    """Sets locations for node(s) for an instance.

    Note: It's important that this command does *not* update the visual
    scene, since this would redraw the frame and create new visual objects.
    The calling code is responsible for updating the visual scene.

    Params:
        instance: The instance
        nodes_locations: A dictionary of data to set
        * keys are nodes (or node names)
        * values are (x, y) coordinate tuples.
    """

    topics = []

    @classmethod
    def do_action(cls, context: "CommandContext", params: dict):
        instance = params["instance"]
        nodes_locations = params["nodes_locations"]

        for node, (x, y) in nodes_locations.items():
            if node in instance.skeleton.node_names:
                instance[node]["xy"] = np.array([x, y])

SetInstancePointVisibility

Bases: EditCommand

Toggles visibility set for a node for an instance.

Note: It's important that this command does not update the visual scene, since this would redraw the frame and create new visual objects. The calling code is responsible for updating the visual scene.

Parameters:

Name	Type	Description	Default
instance		The instance	required
node		The Node (or name string)	required
visible		Whether to set or clear visibility for node	required

Source code in sleap/gui/commands.py

class SetInstancePointVisibility(EditCommand):
    """Toggles visibility set for a node for an instance.

    Note: It's important that this command does *not* update the visual
    scene, since this would redraw the frame and create new visual objects.
    The calling code is responsible for updating the visual scene.

    Params:
        instance: The instance
        node: The `Node` (or name string)
        visible: Whether to set or clear visibility for node
    """

    topics = []

    @classmethod
    def do_action(cls, context: "CommandContext", params: dict):
        instance = params["instance"]
        node = params["node"]
        visible = params["visible"]

        node_name = node if isinstance(node, str) else node.name
        instance[node_name]["visible"] = visible

ToggleGrayscale

Bases: EditCommand

Methods:

Name	Description
do_action	Reset the video backend.

Source code in sleap/gui/commands.py

class ToggleGrayscale(EditCommand):
    topics = [UpdateTopic.video, UpdateTopic.frame]

    @staticmethod
    def do_action(context: CommandContext, params: dict):
        """Reset the video backend."""

        def try_to_read_grayscale(video: Video):
            try:
                return video.grayscale
            except Exception:
                return None

        # Check that current video is set
        if len(context.labels.videos) == 0:
            raise ValueError("No videos detected in `Labels`.")

        # Intuitively find the "first" video that supports grayscale
        grayscale = try_to_read_grayscale(context.state["video"])
        if grayscale is None:
            for video in context.labels.videos:
                grayscale = try_to_read_grayscale(video)
                if grayscale is not None:
                    break

        if grayscale is None:
            raise ValueError("No videos support grayscale.")

        for idx, video in enumerate(context.labels.videos):
            try:
                # video.backend.reset(grayscale=(not grayscale))
                video_util_reset(video, grayscale=(not grayscale))
            except Exception:
                print(
                    f"This video type {type(video.backend)} for video at index {idx} "
                    f"does not support grayscale yet."
                )

do_action(context, params) staticmethod

Reset the video backend.

Source code in sleap/gui/commands.py

@staticmethod
def do_action(context: CommandContext, params: dict):
    """Reset the video backend."""

    def try_to_read_grayscale(video: Video):
        try:
            return video.grayscale
        except Exception:
            return None

    # Check that current video is set
    if len(context.labels.videos) == 0:
        raise ValueError("No videos detected in `Labels`.")

    # Intuitively find the "first" video that supports grayscale
    grayscale = try_to_read_grayscale(context.state["video"])
    if grayscale is None:
        for video in context.labels.videos:
            grayscale = try_to_read_grayscale(video)
            if grayscale is not None:
                break

    if grayscale is None:
        raise ValueError("No videos support grayscale.")

    for idx, video in enumerate(context.labels.videos):
        try:
            # video.backend.reset(grayscale=(not grayscale))
            video_util_reset(video, grayscale=(not grayscale))
        except Exception:
            print(
                f"This video type {type(video.backend)} for video at index {idx} "
                f"does not support grayscale yet."
            )

ToggleNegativeFrame

Bases: EditCommand

Mark or unmark the current frame as a negative (background) frame.

A negative frame is explicitly marked as containing no animals. It is used as a background training example so the model learns to predict nothing on empty frames, which reduces false positives.

Source code in sleap/gui/commands.py

class ToggleNegativeFrame(EditCommand):
    """Mark or unmark the current frame as a negative (background) frame.

    A negative frame is explicitly marked as containing no animals. It is used
    as a background training example so the model learns to predict nothing on
    empty frames, which reduces false positives.
    """

    topics = [UpdateTopic.frame]

    @staticmethod
    def ask(context: CommandContext, params: dict) -> bool:
        lf = context.state["labeled_frame"]
        if lf is None:
            return False

        params["was_negative"] = bool(lf.is_negative)

        # Unmarking never needs confirmation.
        if lf.is_negative:
            return True

        # Marking a frame that has instances destroys them, so confirm first.
        n = len(lf.instances)
        if n > 0:
            frame_number = (context.state["frame_idx"] or 0) + 1
            response = QtWidgets.QMessageBox.warning(
                context.app,
                "Mark frame as negative",
                f"Frame {frame_number} has {n} instance(s). Marking it as a "
                f"negative (background) frame will remove them.\n\nContinue?",
                QtWidgets.QMessageBox.Yes | QtWidgets.QMessageBox.No,
                QtWidgets.QMessageBox.No,
            )
            if response != QtWidgets.QMessageBox.Yes:
                return False

        return True

    @classmethod
    def do_action(cls, context: CommandContext, params: dict):
        lf = context.state["labeled_frame"]
        if lf is None:
            return

        if params["was_negative"]:
            # Unmark the frame.
            lf.is_negative = False
            # Drop the now-empty frame so it does not linger as an orphan that
            # `clean()` / training splits would silently discard.
            if len(lf.instances) == 0 and lf in context.labels:
                context.labels.labeled_frames.remove(lf)
        else:
            # Mark the frame: clear any instances and flag it.
            lf.instances = []
            lf.is_negative = True
            # The current frame is often a detached `LabeledFrame` (created by
            # `Labels.find(..., return_new=True)`); attach it or the flag is
            # lost on the next replot/save.
            if lf not in context.labels:
                context.labels.append(lf)

        context.labels.update()

UpdateTopic

Bases: Enum

Topics so context can tell callback what was updated by the command.

Source code in sleap/gui/commands.py

class UpdateTopic(Enum):
    """Topics so context can tell callback what was updated by the command."""

    all = 1
    video = 2
    skeleton = 3
    labels = 4
    on_frame = 5
    suggestions = 6
    tracks = 7
    frame = 8
    project = 9
    project_instances = 10

copy_to_clipboard(text)

Copy a string to the system clipboard. Args: text: String to copy to clipboard.

Source code in sleap/gui/commands.py

def copy_to_clipboard(text: str):
    """Copy a string to the system clipboard.
    Args:
        text: String to copy to clipboard.
    """
    clipboard = QtWidgets.QApplication.clipboard()
    clipboard.clear(mode=clipboard.Clipboard)
    clipboard.setText(text, mode=clipboard.Clipboard)

export_dataset_gui(labels, filename, all_labeled=False, suggested=False, verbose=True, as_package=True)

Export dataset with image data and display progress GUI dialog.

Parameters:

Name	Type	Description	Default
labels	Labels	sleap.Labels dataset to export.	required
filename	str	Output filename. Should end in .pkg.slp.	required
all_labeled	bool	If True, export all labeled frames, including frames with no user instances. Defaults to False.	False
suggested	bool	If True, include image data for suggested frames. Defaults to False.	False
verbose	bool	If True, display progress dialog. Defaults to True.	True
as_package	bool	If True, save as a package (saves image data instead of referencing video). Defaults to True.	True

Returns:

Type	Description
str	The filename if successful, "canceled" if canceled by user.

Source code in sleap/gui/commands.py

def export_dataset_gui(
    labels: Labels,
    filename: str,
    all_labeled: bool = False,
    suggested: bool = False,
    verbose: bool = True,
    as_package: bool = True,
) -> str:
    """Export dataset with image data and display progress GUI dialog.

    Args:
        labels: `sleap.Labels` dataset to export.
        filename: Output filename. Should end in `.pkg.slp`.
        all_labeled: If `True`, export all labeled frames, including frames with no user
            instances. Defaults to `False`.
        suggested: If `True`, include image data for suggested frames. Defaults to
            `False`.
        verbose: If `True`, display progress dialog. Defaults to `True`.
        as_package: If `True`, save as a package (saves image data instead of
            referencing video). Defaults to `True`.

    Returns:
        The filename if successful, "canceled" if canceled by user.
    """
    embed_option = "all" if all_labeled else "user+suggestions" if suggested else "user"

    if not verbose:
        # Non-verbose mode: run synchronously without GUI
        save_file(
            labels,
            filename,
            format="slp",
            embed=embed_option if as_package else False,
        )
        return filename

    # Create progress dialog
    win = QtWidgets.QProgressDialog(
        "Exporting dataset with frame images...", "Cancel", 0, 1
    )
    win.setWindowModality(QtCore.Qt.WindowModal)
    win.setMinimumDuration(0)
    win.setAutoClose(False)
    win.setAutoReset(False)
    win.show()
    QtWidgets.QApplication.instance().processEvents()

    # Track result
    result = {"status": None, "filename": None, "error": None}

    # Create worker thread
    worker = ExportPackageThread(
        labels=labels,
        filename=filename,
        embed_option=embed_option if as_package else False,
    )

    def on_progress(current, total):
        win.setMaximum(total)
        win.setValue(current)
        win.setLabelText(
            f"Exporting dataset with frame images...<br>{current}/{total} "
            f"(<b>{(current / total) * 100:.1f}%</b>)"
        )

    def on_finished(fname):
        result["status"] = "finished"
        result["filename"] = fname

    def on_cancelled():
        result["status"] = "canceled"

    def on_error(msg):
        result["status"] = "error"
        result["error"] = msg

    # Connect signals
    worker.progress.connect(on_progress)
    worker.finished.connect(on_finished)
    worker.cancelled.connect(on_cancelled)
    worker.error.connect(on_error)

    # Handle cancel button
    win.canceled.connect(worker.cancel)

    # Start the worker
    worker.start()

    # Process events while worker is running (keeps GUI responsive)
    while worker.isRunning():
        QtWidgets.QApplication.instance().processEvents()
        worker.wait(10)  # Wait up to 10ms

    # Ensure thread is fully terminated
    worker.wait()

    # Process any remaining events (including final signals from worker)
    QtWidgets.QApplication.instance().processEvents()

    # Clean up: disconnect signals and delete worker to prevent dangling references
    worker.progress.disconnect()
    worker.finished.disconnect()
    worker.cancelled.disconnect()
    worker.error.disconnect()
    worker.deleteLater()

    win.close()

    # Handle result
    if result["status"] == "finished":
        _show_export_complete_dialog(result["filename"])
        return result["filename"]
    elif result["status"] == "canceled":
        return "canceled"
    elif result["status"] == "error":
        QtWidgets.QMessageBox.critical(
            None,
            "Export Error",
            f"Failed to export labels package:\n{result['error']}",
        )
        raise RuntimeError(result["error"])

    return filename

get_new_version_filename(filename)

Increment version number in filenames that end in .v###.slp.

Source code in sleap/gui/commands.py

def get_new_version_filename(filename: str) -> str:
    """Increment version number in filenames that end in `.v###.slp`."""
    p = PurePath(filename)

    match = re.match(".*\\.v(\\d+)\\.slp", filename)
    if match is not None:
        old_ver = match.group(1)
        new_ver = str(int(old_ver) + 1).zfill(len(old_ver))
        filename = filename.replace(f".v{old_ver}.slp", f".v{new_ver}.slp")
        filename = str(PurePath(filename))
    else:
        filename = str(p.with_name(f"{p.stem} copy{p.suffix}"))

    return filename

open_file(filename)

Opens file in native system file browser or registered application.

Parameters:

Name	Type	Description	Default
filename	str	Path to file or folder.	required

Notes

Source code in sleap/gui/commands.py

def open_file(filename: str):
    """Opens file in native system file browser or registered application.

    Args:
        filename: Path to file or folder.

    Notes:
        Source: https://stackoverflow.com/a/16204023
    """
    if sys.platform == "win32":
        os.startfile(filename)
    else:
        opener = "open" if sys.platform == "darwin" else "xdg-open"
        subprocess.call([opener, filename])

open_website(url)

Open website in default browser.

Parameters:

Name	Type	Description	Default
url	str	URL to open.	required

Source code in sleap/gui/commands.py

def open_website(url: str):
    """Open website in default browser.

    Args:
        url: URL to open.
    """
    QtGui.QDesktopServices.openUrl(QtCore.QUrl(url))

render_video_gui(labels, filename, video, frame_inds, render_params, open_when_done=True)

Render video with progress dialog.

Parameters:

Name	Type	Description	Default
labels		Labels object to render.	required
filename	str	Output video path.	required
video		Video to render from.	required
frame_inds	list[int] | None	Frame indices to render (None = all labeled).	required
render_params	dict	Dict of rendering parameters for sio.render_video().	required
open_when_done	bool	If True, open video after rendering.	True

Returns:

Type	Description
str	The filename if successful, "canceled" if canceled by user.

Source code in sleap/gui/commands.py

def render_video_gui(
    labels,
    filename: str,
    video,
    frame_inds: list[int] | None,
    render_params: dict,
    open_when_done: bool = True,
) -> str:
    """Render video with progress dialog.

    Args:
        labels: Labels object to render.
        filename: Output video path.
        video: Video to render from.
        frame_inds: Frame indices to render (None = all labeled).
        render_params: Dict of rendering parameters for sio.render_video().
        open_when_done: If True, open video after rendering.

    Returns:
        The filename if successful, "canceled" if canceled by user.
    """
    # Hide predictions that were already converted into user instances so they
    # aren't rendered as ghost skeletons alongside their user counterparts.
    labels = _labels_with_visible_instances(labels, video)

    # Calculate total frames for progress. When the caller asked for unlabeled
    # frames to be included we can't infer the count from labeled frames; try
    # the video shape, then fall back to the labeled-frame count as a starting
    # estimate (the progress callback corrects ``total`` on its first tick).
    if frame_inds is not None:
        total_frames = len(frame_inds)
    elif render_params.get("include_unlabeled"):
        start = render_params.get("start")
        end = render_params.get("end")
        if start is not None and end is not None:
            total_frames = max(end - start, 0)
        else:
            video_shape = getattr(video, "shape", None)
            total_frames = int(video_shape[0]) if video_shape is not None else 0
    else:
        total_frames = len(
            [lf for lf in labels.labeled_frames if video is None or lf.video == video]
        )

    # Create progress dialog
    win = QtWidgets.QProgressDialog(
        f"Rendering video...<br>0/{total_frames} frames", "Cancel", 0, total_frames
    )
    win.setWindowTitle("Rendering Video")
    win.setWindowModality(QtCore.Qt.WindowModal)
    win.setMinimumDuration(0)
    win.setAutoClose(False)
    win.setAutoReset(False)
    win.setMinimumWidth(350)
    win.show()
    QtWidgets.QApplication.instance().processEvents()

    # Track result
    result = {"status": None, "filename": None, "error": None}

    # Create worker thread
    worker = RenderVideoThread(
        labels=labels,
        filename=filename,
        video=video,
        frame_inds=frame_inds,
        render_params=render_params,
    )

    def on_progress(current, total):
        win.setMaximum(total)
        win.setValue(current)
        pct = (current / total) * 100 if total > 0 else 0
        win.setLabelText(
            f"Rendering video...<br>{current}/{total} frames (<b>{pct:.1f}%</b>)"
        )

    def on_finished(fname):
        result["status"] = "finished"
        result["filename"] = fname

    def on_cancelled():
        result["status"] = "canceled"

    def on_error(msg):
        result["status"] = "error"
        result["error"] = msg

    # Connect signals
    worker.progress.connect(on_progress)
    worker.finished.connect(on_finished)
    worker.cancelled.connect(on_cancelled)
    worker.error.connect(on_error)

    # Handle cancel button
    win.canceled.connect(worker.cancel)

    # Start the worker
    worker.start()

    # Process events while worker is running (keeps GUI responsive)
    while worker.isRunning():
        QtWidgets.QApplication.instance().processEvents()
        worker.wait(10)  # Wait up to 10ms

    # Ensure thread is fully terminated
    worker.wait()

    # Process any remaining events (including final signals from worker)
    QtWidgets.QApplication.instance().processEvents()

    # Clean up: disconnect signals and delete worker
    worker.progress.disconnect()
    worker.finished.disconnect()
    worker.cancelled.disconnect()
    worker.error.disconnect()
    worker.deleteLater()

    win.close()

    # Handle result
    if result["status"] == "finished":
        if open_when_done:
            open_file(result["filename"])
        return result["filename"]
    elif result["status"] == "canceled":
        return "canceled"
    elif result["status"] == "error":
        QtWidgets.QMessageBox.critical(
            None,
            "Render Error",
            f"Failed to render video:\n{result['error']}",
        )
        raise RuntimeError(result["error"])

    return filename

reveal_file(filepath)

Open the file explorer with the given file selected/revealed.

Similar to open_file() but reveals the file in its containing folder rather than opening it with the default application.

Parameters:

Name	Type	Description	Default
filepath	str	The path to the file to reveal.	required

Source code in sleap/gui/commands.py

def reveal_file(filepath: str):
    """Open the file explorer with the given file selected/revealed.

    Similar to `open_file()` but reveals the file in its containing folder
    rather than opening it with the default application.

    Args:
        filepath: The path to the file to reveal.
    """
    filepath = Path(filepath).resolve()

    if sys.platform == "win32":
        # Windows: use explorer /select, to highlight the file
        # Note: the comma after /select is required
        subprocess.Popen(["explorer", "/select,", str(filepath)])
    elif sys.platform == "darwin":
        # macOS: use open -R to reveal in Finder
        subprocess.Popen(["open", "-R", str(filepath)])
    else:
        # Linux: xdg-open doesn't support file selection, open parent folder
        subprocess.Popen(["xdg-open", str(filepath.parent)])