Tutorial: Loading a Session¶
This tutorial walks you through loading your first recording session into LUC3D, including videos, camera calibration, and skeleton setup.
What You Need¶
A session folder with per-camera subdirectories. Each camera gets its own folder containing a video and optionally an annotation file (.slp or .h5).
my_session/
├── calibration.toml # Camera calibration (filename must contain "calib")
├── skeleton.json # Optional: skeleton definition
├── back/ # Camera folder — name matches calibration
│ ├── video.mp4 # Video file
│ └── back.slp # Optional: SLEAP annotations
├── side/
│ ├── video.mp4
│ └── side.slp
├── top/
│ └── video.mp4
└── front/
└── video.mp4
Camera folder names like back, Back, or camback all match the calibration name back. See Camera Directory Matching for the exact rules and for the alternative Single SLP layout.
Step 1: Load the Session Folder¶
- Open LUC3D in your browser
- The first time, go to File → Session Folder Wizard... and pick Per-Camera SLP — the choice is remembered
- Go to File → Load Single Session Folder (or press Ctrl+O) and select your session folder
Note
You'll see a browser permission dialog the first time — click "Allow" to grant read access to the folder.
Step 2: Verify Camera Matching¶
After loading, LUC3D automatically matches camera subdirectory names to the camera names in your calibration file.
Check the Session tab in the info panel (press I if it's not visible) to see the camera assignments:
| Camera | Directory | Video |
|---|---|---|
| back | back/ | video.mp4 |
| side | side/ | video.mp4 |
| top | top/ | video.mp4 |
| front | front/ | video.mp4 |
If a calibration camera has no matching folder, a Missing Camera Directories popup lets you import its files manually or continue without it.
How Directory Matching Works¶
LUC3D matches subdirectory names to calibration camera names using three rules (tried in order, case-insensitive):
- Exact match — directory name equals camera name (
back/→back) - Cam-prefix match — directory is
cam+ camera name (camback/→back) - Strip cam — removing
camfrom the directory name leaves the camera name (backcam/→back)
Separators are not stripped, so Cam-back/ and cam_back/ do not match back.
Step 3: Verify the Skeleton¶
If your folder includes a skeleton.json, it's loaded automatically and overrides any skeleton found in the .slp files. Otherwise the skeleton comes from the first .slp, or LUC3D uses a default skeleton.
Check the Skeleton tab to verify:
- Nodes — All expected keypoint names are listed
- Edges — Connections between keypoints are correct
You can add, rename, and remove nodes and edges directly in the Skeleton tab.
Step 4: Verify Calibration¶
Check the Cameras tab to confirm all cameras loaded with correct parameters:
- Camera name
- Resolution (should match your videos)
- Focal length (from the intrinsic matrix)
Step 5: Navigate and Begin¶
You should now see your multi-camera views in a grid layout:
- Use Left / Right to step through frames
- Use Space to play/pause
- Use the timeline at the bottom to scrub to specific frames
- Press V to view a single camera, Up / Down to step through cameras, and G to return to the grid
Loading Videos Separately¶
If your videos and calibration are in different locations, you can load them individually:
- File → Load Videos... — Select one or more video files
- File → Load Calibration... — Load a TOML or JSON calibration file
- Check the Session tab to verify camera-video assignments
See Loading Videos & Linking Calibrations.
Loading a Skeleton Separately¶
If you have a skeleton from another project:
- File → Load Skeleton... — Select a skeleton JSON file. LUC3D reads its own
.skeleton.jsonexports and skeleton files saved from the SLEAP GUI - Verify in the Skeleton tab
One skeleton per project
Loading a skeleton replaces the project's skeleton for every session. LUC3D asks before overwriting a non-empty skeleton.
Loading SLEAP Predictions¶
SLEAP annotations are loaded automatically if .slp or .h5 files are present in the camera subdirectories. If multiple versions exist (e.g., cam_v1.slp, cam_v2.slp), LUC3D loads the highest version.
You can also load predictions manually:
- Load your session (videos + calibration) first
- File → Load SLP... — Select a SLEAP
.slpor analysis.h5file; it is added to the current session (or becomes a new session if none is loaded) - Predictions appear as predicted instances (dashed outlines)
- Double-click any predicted instance to convert it to an editable user instance
Large prediction files load lazily — see Loading large files.
Troubleshooting¶
Videos not showing
- Use a recent Chrome or Edge for the most reliable decoding
- Check the browser console (F12) for decode errors
- Try re-encoding videos with
ffmpeg -i input.mp4 -c:v libx264 -crf 23 output.mp4
Calibration not loading
- Verify the TOML/JSON syntax is valid
- Filename must contain
calib(e.g.,calibration.toml,my_calib.json) - Ensure camera names in the calibration match your subdirectory names
- Check that matrix values are nested arrays, not flat lists
Camera directories not detected
- Each camera must be a subdirectory at the root of the session folder
- Directory names must match calibration camera names (optionally with a bare
camprefix) - Each directory needs at least one video file (
.mp4,.avi,.webm,.mov,.mkv) - Files nested deeper than one level are ignored
- If you use a single
.slpfor all cameras, switch the layout in File → Session Folder Wizard...