Tracks & Identities¶

LUC3D provides two complementary systems for tracking individuals across frames and camera views: Tracks and Identities.

Concepts¶

Tracks¶

A Track is a global label representing a persistent individual across frames (e.g., "mouse_1", "mouse_2"). Tracks are used to:

Follow the same animal/person through time
Color-code instances consistently
Batch operations like "triangulate all frames for track X"

Identities¶

An Identity is a per-frame assignment that maps instances to unique individuals within a single frame. Identities are useful for:

Distinguishing multiple animals in the same frame
Cross-view correspondence (same identity = same individual)
Auto-grouping instances across cameras

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¶

Create a Track¶

Tracks → New Track in the menu
Enter a name (e.g., "mouse_1")

Assign a Track¶

Select an instance, then press Shift+1 through Shift+9 for quick assignment
Or use Tracks → Assign Track in the menu

Rename/Delete Tracks¶

Tracks → Rename Track — Change a track's display name
Tracks → Delete Track — Remove the track (instances become trackless)

Managing Identities¶

Assign an Identity¶

Select an instance, then press 1 through 9 for quick assignment
Identities are auto-created if they don't exist yet

Create Named Identities¶

Tracks → New Identity — Create an identity with a custom name

Color Modes¶

Control how instances are colored via the Tracks menu:

Mode	Behavior
Color by Track	Each track gets a distinct color (default)
Color by Identity	Each identity gets a distinct color

Grouping Instances Across Views¶

Creating Groups (Assignment Mode)¶

Click an ungrouped instance in one camera view — this starts a group (assignment mode)
Click the instances in other camera views that show the same individual
Press Shift+G or Enter to create the group

The linked instances form an InstanceGroup and can now be triangulated.

Automatic grouping

Rather than group by hand, run Track Frame (Shift+T) 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 → Edit Group or use the toolbar
Click instances to reassign them between groups
Press Enter to confirm or Esc to cancel

Unlinking Groups¶

Select a grouped instance and press Shift+U or use Edit → Unlink Group
The group is dissolved and instances become independent again

Auto-Grouping¶

LUC3D can automatically group instances across views based on track or identity assignments:

Edit → Group by Track & Triangulate All — 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

Tip

Auto-grouping works best when you've consistently assigned tracks or identities across all camera views before grouping.

Propagating Between Tracks and Identities¶

The tracker assigns identities; tracks and identities are otherwise independent. 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. Instances with no identity become trackless.
Tracks → Propagate Tracks → IDs — turns each track label into an identity (id_<n>), stamping the per-frame identity for every instance on that track.

Warning

Propagating Tracks → IDs assumes track numbers correspond across cameras, which holds for cross-view-tracked or 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 collision occurs, LUC3D swaps the identities to keep them unique, and Deduplicate repairs collisions in loaded data.

Trust Track Labels¶

Enable Tracks → Trust Track Labels to automatically create identities from track names. This is useful when your track names already represent unique individuals and you want identity assignment to follow automatically.

Timeline¶

The timeline widget 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 on the timeline to jump to a frame. Use Shift + drag for range selection.