Skip to content

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)

  1. Click an ungrouped instance in one camera view — this selects it and enters assignment mode. A toast shows "Instances Selected: 1/N"
  2. Click the instances in the other camera views that show the same individual
  3. 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

  1. Select a grouped instance
  2. Click Edit Group in the toolbar — a toast shows the current member count
  3. Click instances to add or remove them from the group
  4. 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 .slp files.
  • 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.