Tracks & Identities¶
LUC3D provides two complementary systems for tracking individuals across frames and camera views: Tracks and Identities.
Concepts¶
Tracks¶
A Track is a label representing a persistent individual across frames (e.g., "mouse_1", "mouse_2"). Tracks are what SLEAP files carry, and are used to:
- Follow the same animal/person through time within one camera
- Color-code instances consistently
- Batch operations like "Group by Track & Triangulate All"
Identities¶
An Identity is a per-frame assignment that maps instances to unique individuals. Identities are what the cross-view tracker assigns, and are used for:
- Cross-view correspondence (same identity = same individual)
- Auto-grouping instances across cameras
- Distinguishing multiple animals in the same frame
Instance Groups¶
An Instance Group links instances across multiple camera views that represent the same individual at the same frame. Groups are required for triangulation.
Tracks and identities are per-session
In a multi-session project, each session owns its own tracks and identities — renaming or deleting a track or identity in one session does not affect the others. The skeleton is the only thing shared across all sessions. Identity is stored per-frame, so an instance can hold different identities in different frames (and can explicitly have no identity).
Managing Tracks¶
The Tracks menu holds the track and identity commands:
| Menu item | Action |
|---|---|
| New Track... | Create a track with a custom name |
| Rename Track... | Change a track's display name |
| Delete Track... | Remove the track; its instances become trackless and any groups using it are dissolved |
| Swap Tracks... | Swap two tracks over a frame range (0 = whole session) |
Assign a Track¶
- Select an instance (grouped or not) and press Shift+1 through Shift+9. If another instance in that camera already has the track, the two tracks are swapped and the swap propagates forward in that camera
- Or pick a track in the Track dropdown of the Instances tab (it also offers + New Track)
Managing Identities¶
| Menu item | Action |
|---|---|
| New Identity... | Create an identity with a custom name |
| Rename Identity... | Rename an identity |
| Delete Identity... | Remove it; groups using it are dissolved |
Assign an Identity¶
- Select a group or an ungrouped instance and press 1 through 9
- Or use the Identity dropdown in the Instances tab
Identity switches propagate forward
Assigning an identity that another animal already holds swaps the two identities from the current frame to the end of the timeline. On a group the swap applies in every camera; on an ungrouped instance it applies to that camera only. This is how you fix a tracker identity swap: find the first wrong frame, select the animal, press the correct number.
Color Modes¶
The toolbar Color: Tracks / ID toggle controls how instances, the timeline, and the 3D viewport are colored:
| Mode | Behavior |
|---|---|
| Tracks | Each track gets a distinct color (default) |
| ID | Each identity gets a distinct color (selected automatically after Propagate Tracks → IDs) |
Grouping Instances Across Views¶
Creating Groups (Assignment Mode)¶
- Click an ungrouped instance in one camera view — this selects it and enters assignment mode. A toast shows "Instances Selected: 1/N"
- Click the instances in the other camera views that show the same individual
- Press Shift+G, click the toolbar Group button, or click Group in the toast (Enter)
The linked instances form an Instance Group and can now be triangulated.
Automatic grouping
Rather than group by hand, run Track Frame (Shift+T), Track Frame Range…, or Track All (Ctrl+Shift+T) to have the cross-view tracker group instances and assign identities automatically.
Editing Groups¶
- Select a grouped instance
- Click Edit Group in the toolbar — a toast shows the current member count
- Click instances to add or remove them from the group
- Click Continue (Enter) to confirm or Cancel (Esc). Confirming with a single member dissolves the group
Ungrouping¶
- Select a grouped instance and press Shift+U, use Edit → Unlink Group, click the toolbar Group button, or right-click the group's row in the Instances tab and choose Unlink Group
- Members return to the ungrouped pool but keep their track and identity, so their name pills stay visible on the canvas. Predicted members of a mixed group are promoted to user instances
Auto-Grouping¶
LUC3D can automatically group instances across views based on track or identity assignments:
- Edit → Group by Track & Triangulate All — Opens a dialog to choose tracks and cameras, groups instances sharing the same track across cameras, then triangulates all frames
- Edit → Group by Identity & Triangulate All — Groups instances sharing the same identity, then triangulates
Triangulating (this frame or all frames) also builds groups from identities on the fly, so after Track All you can triangulate directly.
Tip
Auto-grouping by track assumes track numbers correspond across cameras. That holds for tracks produced by Propagate IDs → Tracks, but not for independently tracked per-camera .slp files.
Propagating Between Tracks and Identities¶
The tracker assigns identities; SLEAP exports carry tracks. Two menu commands convert one into the other across the whole session:
- Tracks → Propagate IDs → Tracks — rewrites each instance's track so its track is its identity, reading the per-frame identity map first. Instances with no identity become trackless. Run this after tracking and before exporting
.slpfiles. - Tracks → Propagate Tracks → IDs — turns each track into an identity (
id_<n>), stamping the per-frame identity for every instance on that track, marks the session's tracks as trusted, and switches the color mode to ID.
Warning
Propagating Tracks → IDs assumes track numbers correspond across cameras — true for cross-view-tracked or otherwise trusted tracks, but not for independently tracked per-camera .slp files.
Within any single frame, no two groups may share the same identity. If a manual assignment would collide, LUC3D swaps the identities to keep them unique.
Node Trails¶
Tracks → Node Trails draws each node's recent path (Off, 10, 50, 100, 250, or 500 frames) in the camera views and the 3D viewport — useful for spotting identity swaps.
Timeline¶
The timeline at the bottom of the screen visualizes track and identity occupancy across frames:
- Tracks mode — Shows colored bars for each track
- IDs mode — Shows colored bars for each identity
- Both mode — Displays tracks and identities simultaneously
Click to jump to a frame, scroll to zoom the time axis, and middle- or right-drag to pan. Hide rows you don't need from the Visibility ▸ Timeline toggles. See Keyboard Shortcuts for the full gesture list.