Labeling Instances¶

An instance is one animal's pose on one frame: a position (and a visible/not-visible flag) for each node in the project's skeleton.

Adding an instance¶

How	What it does
`Cmd`+`I` / `Ctrl`+`I`	Add an instance using the current placement method
Labels ▸ Add Instance	Same, from the menu
Right-click ▸ Add Instance	Pick the placement method for this one instance
`Ctrl`-drag a node of an existing user instance	Clone it, pose and all (`Ctrl` on macOS too, not `Cmd`)

Placement methods¶

Labels ▸ Instance Placement Method decides the starting pose of a new instance. Getting this right saves a lot of dragging.

Method	Starting pose
Best	Centered template, offset to avoid overlapping existing instances (default)
Template	The skeleton's stored template pose, unmodified
Force Directed	Centered, then iteratively pushed away from existing instances
Random	Random node positions
Copy Prior Frame	The pose from the previous labeled frame
Copy Predictions	The predicted instance already on this frame

Once you have a model, Copy Predictions turns labeling into correction.

Editing¶

Drag a node to move it. Clicking or dragging a node marks it complete (green).
Mark a whole instance complete: Shift-click any of its nodes, as in SLEAP.
Move the whole pose: hold Alt and drag any node, or press Shift+A to select every node of the selected instance, then drag one of them.
Rotate the selected instance: hold Alt and scroll.
Select several nodes: Alt+Shift-click a node to add it to the selection, or remove it; drag on empty canvas to draw a selection box (hold Shift to add to the selection).
Add missing nodes: double-click a user instance to give the nodes it's missing a position (for example after adding a node to the skeleton). They're placed from your other labeled instances, as non-visible nodes to drag into place, as in SLEAP.
Merge two instances: when one animal ended up as two partial instances, select the one to keep and choose Labels ▸ Merge Instance (Shift+M). It takes the other instance's nodes for any the selected one is missing, then removes the other. With more than two user instances on the frame, pick the one to merge in: right-click ▸ Merge Instance with, or Cmd/Ctrl-click a second row in the Instances panel (the first row picked is kept).
Right-click an instance's body, or empty canvas, for the context menu: add, copy, paste, delete or merge instances, assign a track, and mark the frame negative. Right-clicking a single node flips its visibility instead.
Delete or Backspace deletes the selected instance when all of its visible nodes are selected.
Node placement mode (Shift+N, or View ▸ Node Placement Mode) is for clicking nodes down one at a time rather than dragging a pre-posed template. Click to place the current node, Tab / Shift+Tab to pick another, and Esc to leave.

Visibility¶

Nodes that are genuinely occluded should be marked not visible rather than parked somewhere plausible — a guessed point is training signal that says the part is there, which it isn't.

To mark a node non-visible, right-click it, or press V with the pointer over it. Do the same again to make it visible.
With several nodes selected, V sets them all to the same state: visible, unless more than half of them already are, in which case all become non-visible.
Shift+V toggles View ▸ Show Non-Visible Nodes: whether non-visible nodes are drawn at all.

View ▸ Display controls how much of the hidden geometry you see:

Mode	Shows
Manual	Whatever you toggled by hand
Only selected (with hidden points)	Just the selected instance, hidden points included
All instances, visible points only	Every instance, visible points only
All visible + selected hidden points	Everything, plus the selected instance's hidden points

Selecting¶

Action	Shortcut
Select next instance	`
Select next / previous instance and zoom to it	`Shift`+`Down` / `Shift`+`Up`
Clear selection	`Esc`

Clicking an instance on the canvas selects it; the Instances panel lists the current frame's instances with their track, type, and score.

Copy and paste¶

Action	Shortcut
Copy instance	`Cmd`+`C` / `Ctrl`+`C`
Paste instance	`Cmd`+`V` / `Ctrl`+`V`
Copy instance track	`Cmd`+`Shift`+`C` / `Ctrl`+`Shift`+`C`
Paste instance track	`Cmd`+`Shift`+`V` / `Ctrl`+`Shift`+`V`

Copying a track copies the identity assignment rather than the pose — see Tracks.

Deleting¶

Action	Shortcut
Delete selected instance	`Cmd`+`Backspace` / `Ctrl`+`Backspace`
Delete instance and its track	`Cmd`+`Shift`+`Backspace` / `Ctrl`+`Shift`+`Backspace`
Delete predictions in a dragged area	`Cmd`+`K` / `Ctrl`+`K`

The Labels menu has the bulk options:

Menu item	Deletes
Delete Predictions on Current Frame	Every prediction on this frame
Delete Predictions…	Predictions matching one filter: score threshold, frame range, on user-labeled frames, max instances per frame, track, or instance type
Delete Predictions from Area… (`Cmd`+`K` / `Ctrl`+`K`)	Predictions inside a rectangle you drag
Delete All Predictions…	Every prediction in the project, after a confirm

Working with predictions¶

Predicted instances are drawn distinctly from user labels (View ▸ Color Predicted Instances changes how). They are suggestions until you accept them.

Action	How
Accept one prediction	Double-click it; hold `Shift` to mark every node complete too
Accept all on this frame	`Cmd`+`Shift`+`A` / `Ctrl`+`Shift`+`A`, or Labels ▸ Accept All Predictions on Current Frame
Accept all in the project	Labels ▸ Accept All Predictions

Accepting converts a PredictedInstance into a user-labeled Instance — which is what training actually consumes.

Negative frames¶

Labels ▸ Mark Frame as Negative (N, or right-click the video) records that a frame genuinely contains no animals. Marking a frame that still has instances asks first, then removes them (undo brings them back), and adding an instance to a negative frame unmarks it. A negative frame shows a red border with a "Negative Frame" label on the video and a red tick on the seekbar, and it counts toward the status bar's labeled total, e.g. "Labeled: 6 (2 negative frames)".

Why mark them? A model only ever trained on frames with animals can "see" animals in empty frames: a shadow, bedding, an empty corner. Negative frames are examples of what nothing looks like, which teaches a model not to detect animals there.

A negative frame is not the same as an empty frame. An empty frame is one where you deleted every instance: it says nothing, and training skips it. A negative frame is a deliberate statement that there are no animals. That's why marking one asks before removing instances: marking a frame with an animal on it would teach the model the wrong thing.

Training doesn't use negative frames yet

sleap-nn can train on negative frames, but only when its use_negative_frames setting is on, and it's off by default. The Training panel doesn't turn it on yet, so marking frames negative records them in the project (and in the Label Quality Check) but doesn't change training today.

Undo¶

Every edit goes through a command with a frame-level snapshot, so Cmd+Z / Ctrl+Z and Cmd+Shift+Z / Ctrl+Shift+Z work across the whole editing surface — not just node drags.

Hints¶

Labels ▸ Show Hints During Labeling puts contextual tips on screen as you work. Help ▸ Labeling Tips… opens the full list any time.