Tutorial: Loading Multiple Sessions¶
This tutorial covers how to load and manage multiple recording sessions in a single LUC3D project. Multi-session support is useful when you have recordings from different time points, conditions, or subjects that share the same camera rig.
Chrome or Edge required
Multi-session loading uses the browser's directory picker (File System Access API), which Firefox and Safari do not support.
Folder Structure¶
Each session is a subdirectory containing its own calibration file and per-camera subdirectories:
my_project/
├── skeleton.json # Optional: one skeleton applied to every session
├── session_01/
│ ├── calibration.toml # Per-session calibration
│ ├── back/
│ │ ├── video.mp4
│ │ └── back.slp # Optional: SLEAP annotations
│ ├── side/
│ │ └── video.mp4
│ └── top/
│ └── video.mp4
├── session_02/
│ ├── calibration.toml
│ ├── back/
│ │ └── video.mp4
│ ├── side/
│ │ └── video.mp4
│ └── top/
│ └── video.mp4
└── session_03/
├── calibration.toml
├── back/
│ └── video.mp4
└── side/
└── video.mp4
A subdirectory is detected as a session if it contains either a calibration file (with calib in the name) or at least one subdirectory. Sessions are sorted by name.
Step 1: Load the Multi-Session Folder¶
- Go to File → Load Multi-Session Folder
- Select the project root folder (the one containing the session subfolders)
- LUC3D discovers all session subdirectories and loads them as separate sessions
If the project root contains a skeleton*.json, it is applied to every session. Otherwise LUC3D asks whether to Choose a skeleton file for all sessions or Skip and use the skeletons found in the .slp files.
Step 2: Verify Sessions¶
After loading, the Sessions strip on the left shows all discovered sessions:
- Click a session to switch to it — the video views update to show that session's videos
- Use + to add an empty session and − to remove the active one
Step 3: Check Camera Assignments Per Session¶
Each session has its own camera-video assignments. Open the Session tab in the info panel to verify:
- Videos are correctly matched to camera names
- All expected cameras have videos assigned
Camera subdirectory names are matched to calibration names using the same rules as single-session loading. See Camera Directory Matching.
Working Across Sessions¶
Switching Sessions¶
Click a session in the strip to switch. If the current session has unsaved changes, LUC3D prompts you to save first.
Independent Annotations¶
Each session maintains its own:
- Video set and camera-video assignments
- Frame annotations (instances, groups)
- Tracks and identities
- Triangulation data
- Visibility settings (brightness, contrast, rotation, hidden cameras)
Shared Skeleton¶
The skeleton definition is shared across all sessions — changes to the skeleton (adding/removing nodes or edges) apply everywhere.
Moving Videos Between Sessions¶
If a video was placed in the wrong session folder:
- In the Views strip, find the video
- Drag it onto the correct session in the Sessions strip
- Confirm in the Move Videos to Another Session dialog
This transfers the video and its associated annotations.
Tips for Multi-Session Workflows¶
Consistent naming
Use the same camera subdirectory names across sessions (back/, side/, top/) so that camera auto-matching works consistently.
Per-session calibration
Each session should have its own calibration.toml inside the session folder. This allows for different camera positions between sessions.
Batch operations
Track All, Triangulate All, and "Group by Track & Triangulate All" run on the active session only. Switch sessions and run again for each session. Save writes every session to one project file, and Export SLEAP File By Cam pools sessions per camera.
Example Workflow¶
- Load the project folder with all sessions
- Session 1: Annotate poses, track, group instances, triangulate
- Switch to Session 2: Repeat annotation workflow
- Switch to Session 3: Repeat
- Save — every session's data is included in the project file
Troubleshooting¶
Sessions not detected
- Ensure each session is a direct subdirectory of the project folder
- Each session must contain either a calibration file (with
calibin the name) or at least one subdirectory
Wrong number of sessions
- Any subdirectory with a subfolder is treated as a session — move stray folders (e.g.
analysis/) out of the project root - Each session needs camera subdirectories with video files