Your First Labels¶

This walks the full loop that most SLEAP projects run: label a handful of frames, train a small model, correct what it gets wrong, and retrain. It mirrors the app's built-in Start Tutorial, which highlights each control as you go — read this first if you'd like to know why each step is there.

1. Create the project¶

File ▸ New Project…, then add your video: drag it onto the dropzone or click the dropzone to browse. To follow along with the tutorial's data, click Use sample video instead — it downloads mice.mp4. Then click Create Project.

Save immediately (Cmd+S / Ctrl+S) so the project has a .slp file to write into. The save dialog suggests labels.v001.slp.

2. Define a skeleton¶

A skeleton is the set of body parts (nodes) and the connections between them (edges) that every instance in the project shares.

Either pick a template in the New Project dialog, or build one on the frame:

1. Open the Skeleton panel and click Draw skeleton on frame.
2. Click to place each node on the animal.
3. Double-click a node to rename it to something meaningful (head, torso, tailbase) — nodes start out named node_0, node_1, …
4. Click Next: Connect edges → and drag a stroke through the nodes to connect them into edges.
5. Click Done. The app asks whether to create an instance on this frame from your layout — click Create instance to start labeling right away, or Not now.

Renaming on the frame works while you're placing nodes. After that, double-click a node's name in the Skeleton panel instead.

Three or four well-chosen nodes are plenty to start. See Skeletons.

3. Generate suggestions¶

Open the Suggestions panel, leave the method on Stride with 20 per video, and click Generate. You now have 20 frames spread across the video instead of 20 nearly identical neighbors.

Move between them with Space and Shift+Space.

4. Label¶

On each suggested frame, place one instance per animal and drag every visible node into place.

• Add instance — Cmd+I / Ctrl+I, or right-click ▸ Add Instance
• Clone an existing instance — hold Ctrl and drag one of its nodes (Ctrl on macOS too, not Cmd)
• Delete — Cmd+Backspace / Ctrl+Backspace
• Don't guess occluded parts — mark them non-visible instead

Labels ▸ Instance Placement Method controls where a new instance starts out:

Once a model exists, Copy Prior Frame and Copy Predictions turn labeling into nudging rather than placing.

Save when you're done with a frame.

5. Check your labels before training¶

Before you spend GPU time, open Analyze ▸ Label Quality Check… and click Run checks. It flags:

• duplicate instances stacked on the same animal
• frames with fewer instances than the project's typical count
• instances with almost no visible nodes
• points outside the image
• left/right swaps, inferred from your skeleton's symmetries
• chain-order problems, where a limb or body axis is labeled out of order

Each finding jumps you to the frame and instance. Fixing these is much cheaper than training on them.

Also run Analyze ▸ Instance Size Distribution — it tells you how large your animals actually are in pixels, which is what you need to choose a sensible crop size for a top-down model.

6. Train¶

Open the Training panel.

1. Make sure the Python backend is available — see Environment setup, or connect to a remote worker if you have no local GPU.
2. Pick a model type. Top-Down is a good default for multiple animals: it finds an anchor part, crops around it, and predicts the rest of the pose inside the crop.
3. Set the Anchor Part to a central, reliably visible node (torso, not tail_tip).
4. Set Epochs low — 5 is enough for a first end-to-end pass.
5. Click Start Training.

While it runs, open the loss viewer to watch curves live, or the log terminal for raw output. See Training.

7. Correct the predictions¶

When training finishes, predictions appear on the frames it ran on.

• Double-click a predicted instance to accept it as a user label
• Cmd+Shift+A / Ctrl+Shift+A accepts all predictions on the frame
• Drag any points that are off

Correcting predictions is far faster than labeling from scratch, which is the whole point of the loop.

8. Retrain¶

Back in the Training panel, click Train Again. This time:

• raise Epochs — the built-in tutorial uses 50; a real project usually wants more
• keep the same anchor part
• set Post-Training Inference Target before you start — the field is disabled once training is running

Repeat until predictions stop needing corrections. Then run inference across the whole video and move on to tracking.

Where to go next¶