Exporting Data¶
LUC3D supports multiple export formats for 2D annotations, 3D reconstructions, rendered videos, calibration data, and skeleton definitions. All export options are under the File menu.
| Menu item | Output | Use it for |
|---|---|---|
| Save / Save As... | .slp project |
Everything — resume work later |
| Export SLEAP File Per Session | One .slp per camera (active session) |
Retraining SLEAP on individual views |
| Export SLEAP File By Cam | One .slp per camera spanning sessions |
Pooling many sessions per camera |
| Export Labels (JSON) | labels_export.json |
Custom downstream analysis |
| Export Video Overlays | .mp4 with poses burned in |
Figures, talks, QC |
| Export 3D Video | .mp4 of the 3D viewport |
Visualizing reconstructions |
| Export 3D Points (H5) | points3d.h5 |
3D analysis |
| Export Reprojections (H5) | reprojections.h5 |
Consistency evaluation |
| Export Calibration (TOML) | calibration.toml |
Sharing calibration |
| Save Skeleton (JSON) | <name>.skeleton.json |
Reusing a skeleton |
Project Files¶
File → Save (Ctrl+S) and File → Save As... write a standard SLEAP .slp file containing every session in the project:
- All 2D user and predicted instances, tracks, and video references
- Camera calibration
- Skeleton definition
- Instance groups, 3D points, and the triangulation method used per group
- Identities and per-session settings (trusted-tracks flag, Visibility-panel brightness/contrast/rotation, hidden cameras and tracks), stored under
metadata.lucid
The extra metadata is opaque to SLEAP, so the file still opens in the SLEAP GUI. File → Load Project... restores it (.slp or .h5). Projects over 200 MB reopen lazily and prompt you to re-attach the videos.
Unsaved changes
LUC3D tracks unsaved changes per session and prompts you to save before switching sessions.
SLEAP .slp¶
LUC3D writes .slp files in SLEAP's native (canonical) format, so they open directly in sleap-io and the SLEAP GUI. Two export modes:
File → Export SLEAP File Per Session — For the active session, writes one 2D .slp per camera into that camera's folder inside an output folder you choose. Filenames are versioned: a loaded cam_v2.slp exports as cam_v3.slp, and a camera with no source file gets <video>_v1.slp. You can edit each filename and toggle Download per camera.
File → Export SLEAP File By Cam — A session × camera grid. Download All prompts for an output folder and writes one flat <CamName>.slp per included camera, spanning all checked sessions. Cameras whose skeleton doesn't match are blocked from export.
Both dialogs share an Include group:
| Option | Default | Effect |
|---|---|---|
| User labels | Always saved | Cannot be turned off |
| Predicted Instances | On | Include tracker / imported predictions |
| Reprojections | Off | Save reprojected instances as UserInstance or PredictedInstance |
SLEAP version
Reading the exports natively requires SLEAP ≥ 1.6 (sleap-io ≥ 0.7).
Large sessions
For a large, lazily-loaded session (see Loading large files), project save and per-camera export use a memory-bounded streaming writer, so no labeled frame is dropped. Without the File System Access API (Firefox/Safari), files fall back to browser downloads.
Labels (JSON)¶
File → Export Labels (JSON) writes labels_export.json, keyed by frame and then camera:
{
"skeleton": { "name": "...", "nodes": [...], "edges": [[0, 1], ...] },
"cameras": [ { "name": "back", "matrix": [...], "dist": [...], "rvec": [...], "tvec": [...], "size": [w, h] } ],
"tracks": [ "mouse_1", "mouse_2" ],
"frames": {
"0": {
"back": [
{ "points": [[x, y], null, ...], "trackIdx": 0, "type": "user", "score": null, "modified": true }
]
}
}
}
points entries are null for unplaced nodes. The export is streamed, so it covers every frame of a lazy project.
Video Overlays (MP4)¶
File → Export Video Overlays renders camera views with the pose overlays drawn exactly as on screen, encoded to H.264 MP4 via mediabunny.
- Pick the views to include from the strip; the 3D View tile is available when a calibration is loaded.
- Arrange the tiles in the dockable composition — what you see is what is rendered.
- Set the options and click Export.
| Group | Options |
|---|---|
| Frame Range | Start / End frame |
| Layers | Render Video Names, User instances, Predicted instances, Reprojections, Reprojection errors, Legend, Color by (Track / Identity), Node trails, Background (video / black / white / gray) |
| Appearance | Node size, edge width and opacity for user, predicted, and reprojected instances (seeded from the Visibility tab) |
| Quality & Output | Resolution (480p / 720p / 1080p / 2160p / Custom), Quality, Output FPS, Stitched (one file) or Individual (one file per tile) |
Output is named <session>_overlay_f<start>-<end>.mp4, with a _<view> suffix per tile in Individual mode. Exports estimated above 256 MB stream to a file or folder you pick.
3D Video (MP4)¶
File → Export 3D Video renders the 3D viewport to a 16:9 H.264 MP4. The dialog shows a live preview, a frame-range slider, and a Quality preset (480p, 720p, 1080p, 2160p) with live duration and file-size estimates. Output is <session>_3d_<res>_f<start>-<end>.mp4. Triangulate first (or load 3D points) so there is something to render.
3D Points (HDF5)¶
File → Export 3D Points (H5) writes points3d.h5. Requires triangulation to have been run.
/points_3d (n_frames, n_tracks, n_nodes, 3) XYZ, NaN where missing
/reprojection_error (n_frames, n_tracks, n_nodes) mean pixel error per node
/frame_indices (n_frames,)
/track_names (n_tracks,) identities if any exist, otherwise tracks
/node_names (n_nodes,)
File → Load 3D Points (H5) reads the same layout back (only /points_3d and /frame_indices are required).
Reprojections (HDF5)¶
File → Export Reprojections (H5) writes reprojections.h5 — the 3D points projected back into each camera:
/reprojections (n_frames, n_tracks, n_cameras, n_nodes, 2)
/frame_indices (n_frames,)
/track_names (n_tracks,)
/node_names (n_nodes,)
/camera_names (n_cameras,)
Calibration (TOML)¶
File → Export Calibration (TOML) saves the current camera calibration as calibration.toml in the format LUC3D reads.
Skeleton (JSON)¶
File → Save Skeleton (JSON) (also the Save Skeleton button in the Skeleton tab) writes <name>.skeleton.json in SLEAP's skeleton JSON format, so it can be loaded by SLEAP or by File → Load Skeleton... in another LUC3D project.
Python Scripts¶
The scripts/ directory contains helpers that run outside the browser:
| Script | Purpose |
|---|---|
validate_slp_sleap_compat.py |
Check that an exported .slp opens in sleap-io (uv run --with 'sleap-io>=0.7,<0.8' --with numpy python scripts/validate_slp_sleap_compat.py file.slp) |
json_to_slp.py, json_to_h5.py |
Legacy converters for LUC3D's older JSON project dumps (require h5py, numpy). Prefer the native .slp and H5 exports above. |