Skip to content

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.

  1. Pick the views to include from the strip; the 3D View tile is available when a calibration is loaded.
  2. Arrange the tiles in the dockable composition — what you see is what is rendered.
  3. 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.