Skip to content

Installation

LUC3D is a static web application — there is no build step or package to install.

No installation required

Use LUC3D right away at https://luc3d.sleap.ai/ — no setup needed. For the best performance with large files, run a local server as described below.

Hosted Channels

URL What you get
luc3d.sleap.ai The live site
luc3d.sleap.ai/stable/ Newest full release
luc3d.sleap.ai/latest/ Newest release, pre-releases included
luc3d.sleap.ai/dev/ Most recent push to main

Clone the Repository

git clone https://github.com/talmolab/luc3d.git
cd luc3d

Serve Locally

python3 -m http.server 8080

Or use the included server script (port is optional):

python3 server.py 8080
npx serve .

Point any static file server at the repository root. LUC3D has no server-side dependencies.

Then open http://localhost:8080 in your browser.

Browser Requirements

Chrome or Edge is recommended. LUC3D does not gate on browser type, but some features depend on the File System Access API, which Firefox and Safari do not ship:

Feature Chrome / Edge Firefox / Safari
Load Single Session Folder, Load Videos, Load Calibration ✓ ✓
Load Multi-Session Folder ✓ ✗ (requires a directory picker)
Save / Save As, SLP exports Written to a file you pick Fall back to browser downloads
Large video / JSON exports Streamed to disk Built in memory (may run out)

For frame-accurate video seeking, LUC3D decodes exact frames with WebCodecs via mediabunny. If WebCodecs is unavailable — or any decode fails — LUC3D transparently falls back to HTML5 <video> seeking, which still works but is less precise on long-GOP / HEVC footage.

Tip

To force the HTML5 fallback for debugging, set localStorage.LUCID_VIDEO_BACKEND = 'html5' in the browser console and reload.

Dependencies

No npm install or build step is needed. Most libraries are vendored locally under lib/; a few load from CDN (about 11 MB on first visit, cached afterwards).

Library Version Role Loaded from
Three.js 0.147 3D viewport rendering CDN
mediabunny 1.30.0 Frame-accurate video decode (WebCodecs) and MP4 encoding for video exports lib/
mp4box.js 0.5.2 MP4 metadata (FPS + frame count) CDN
h5wasm 0.10.3 WebAssembly HDF5 read/write lib/
sleap-io.js 0.5.5 SLEAP .slp read and write lib/
pako 2.2.0 Compression (sleap-io.js dependency) lib/
yaml 2.8.0 sleap-io.js dependency CDN
dockview-core 6.6.1 Dockable panel layout CDN

Video decode

Frame-accurate stepping and seeking go through mediabunny. mp4box.js is used only to read accurate FPS and frame counts — not to decode frames.

Running Tests

Open the test runner in your browser:

http://localhost:8080/tests/test-runner.html