Event Calibration Studio

A Python/Qt desktop application for Prophesee event-camera and offline sensor-rig calibration on Ubuntu 24.04 x86-64. The Linux distributions contain Python, Qt, the native EVT3 decoder, and an isolated OpenEB 5.1.1 camera helper. ROS and a separately installed Python or OpenEB are not required to run them.

The E2VID workflow has calibrated the supplied data/8x6_24mm recording from 60 retained checkerboard views, with 1.49 px RMS and 1.54 px held-out reprojection error. HyperE2VID remains available and produced 46 views with 1.94 px RMS and 1.87 px held-out error. The native Corner2Tag-inspired — experimental workflow works on independent simulated events, but currently finds no complete checkerboards in this recording. Real stereo, LiDAR, GPU inference, and USB capture accuracy remain to be validated on appropriate hardware and recordings. See validation status.

Run a Linux binary

Use the CPU edition on any supported machine. The CUDA edition contains PyTorch 2.10.0 with CUDA 12.6; use NVIDIA driver 560.28.03 or newer. CUDA can fall back to CPU. The CUDA archive is substantially larger because it includes CUDA runtime libraries; no system CUDA toolkit is required.

chmod +x dist/EventCalibration-0.3.0-linux-x86_64-cpu.AppImage
dist/EventCalibration-0.3.0-linux-x86_64-cpu.AppImage

If FUSE is unavailable, use AppImage's extraction mode:

APPIMAGE_EXTRACT_AND_RUN=1 dist/EventCalibration-0.3.0-linux-x86_64-cpu.AppImage

Alternatively, extract the portable archive and run its AppRun:

tar -xf dist/EventCalibration-0.3.0-linux-x86_64-cpu.tar.gz
./EventCalibration-0.3.0-linux-x86_64-cpu/AppRun

Checksums are in dist/SHA256SUMS. Each edition has a .build.json manifest with pinned versions and hashes of the source files used for that build. The same commands apply to filenames ending in cuda.

Intrinsic calibration

1. Open an MCAP file or ROS bag directory. Split MCAP recordings are streamed in chronological order. Select the event topic; give each physical sensor a distinct optional name when separate recordings reuse the same topic.
2. Configure the printed target. For the supplied fixture choose checkerboard, 8 columns × 6 rows of inner corners, 24 mm squares. These are inner corners, so the printed board has 9 × 7 squares. The Target PDF button creates metric checkerboards or padded Kalibr-style AprilGrids. AprilGrid defaults are tag36h11, two border bits, and symmetric corner pads; physical geometry and first tag ID are recorded.
3. Choose E2VID intensity or HyperE2VID intensity. Click Download official model, or select the corresponding converted model directory containing model.json and model.safetensors. Each pinned checkpoint is checksum verified before conversion. Converted models are available in this workspace at artifacts/models/E2VID and artifacts/models/HyperE2VID; copy the required directory to another machine for offline use. Arbitrary pickle checkpoints are not accepted. E2VID uses five event bins, nonzero-voxel normalization, recurrent state, and robust 1st/99th-percentile output scaling.
4. Extract observations. Reconstruction defaults to 30 Hz and advances recurrent state through every event window. CPU reconstruction at 1280 × 720 is slower than recording playback; the offline worker preserves all events while the GUI stays responsive. The fixture validation used 5 Hz reconstruction and sampled views about every 0.4 seconds. Changing reconstruction rate can change detection quality.
5. Review corner overlays, reject poor observations, and check image coverage and pose diversity. Select the corresponding sensor and observation pipeline, then solve with at least 20 distinct views. Pinhole/radtan has four coefficients with k3 explicitly fixed to zero; fisheye/equidistant has four coefficients.
6. Inspect residuals, held-out error, coverage, and undistortion. Save the project and export its JSON, OpenCV/ROS YAML, Kalibr camera-chain YAML, and HTML report. Solver warnings and termination status remain in the result.

The E2VID fixture project and report are artifacts/validation/e2vid/project.json and artifacts/validation/e2vid/calibration/quality.html. The HyperE2VID fixture remains at artifacts/validation/hypere2vid/calibrated-project.json. A saved project keeps observation PNGs and their timestamp sidecars in a sibling <project-name>.assets directory. Move this directory with the project JSON. Source recordings and model weights remain external references. Frames without detections also have JSON sidecars in the processing cache and can be imported into the LiDAR workflow.

Other workflows

• Native event intrinsics: select Corner2Tag-inspired — experimental. Defaults are 20 ms windows, 2,000 minimum valid events, and a motion search within ±32 pixels per window. Drag on the preview to select the board region. Insufficient motion or four-edge support rejects a window. The optional unresolved-motion checkerboard setting attempts a null warp and still requires every corner to be measured; its uncertainty is recorded. See capture guidance. These settings are application defaults, not upstream paper settings.
• Camera–event and event–event extrinsics: extract each stream, import or solve its intrinsics, configure the supplied clock mappings, and choose the two sensors. Default pairing tolerance is 5 ms. Use slow target motion. AprilGrid IDs establish correspondence; every accepted checkerboard pair must have visually verified physical corner ordering. Row/column reversal controls invalidate verification until checked again. Intrinsics stay fixed during robust mixed-model reprojection optimization. No trajectory interpolation or automatic clock-offset estimation is performed.
• Event–LiDAR extrinsics: choose reconstructed E2VID/HyperE2VID intensity NID for stationary rigs, or Raw-event edge alignment — experimental for moving, predominantly rotational windows. The raw method estimates angular velocity by contrast maximization and aligns LiDAR geometric/reflectivity edges to the sharpened event image. Both require an initial transform or at least six manual 2D–3D correspondences. Read the assumptions and capture steps in the LiDAR workflow.
• Live intrinsic calibration: discover a directly connected Prophesee camera and start capture. Preview runs independently of inference. Processing lag, dropped batches, and overflow are reported; observations spanning gaps are invalidated and recurrent state resets. See USB setup and capture.

Transforms use p_to = T_to_from × p_from, with translation in metres. Clock mappings use common_ns = sensor_ns − sensor_origin_ns + common_origin_ns + offset_ns; negative offsets move a stream earlier. Event sensor timestamps are 64-bit, while host arrival timestamps are preserved separately. E2VID and HyperE2VID observations reference window end; native observations reference window midpoint. Conventional images use their message header timestamps; use the supplied origin and offset to express the exposure-time interpretation for that stream.

Source installation and reproducible builds

Use Ubuntu 24.04 with Python 3.12 and a C++17 compiler. The offline decoder and processing extension build without OpenEB. OpenEB headers, libraries, and camera plugins are needed to build the separate live helper.

The pinned OpenEB build recipe compiles the SDK into the workspace using a clean Ubuntu container, with system udev installation disabled.

python3 -m venv .venv
.venv/bin/python -m pip install -r packaging/requirements-cpu.lock --extra-index-url https://download.pytorch.org/whl/cpu
.venv/bin/python -m pip install --no-build-isolation --no-deps -e .
.venv/bin/python -m event_calibration

Build the live helper against OpenEB 5.1.1, installed under /usr/local or the selected OPENEB_PREFIX:

OPENEB_PREFIX=/usr/local EVENT_CALIBRATION_PYTHON=.venv/bin/python scripts/build_native.sh

Build both editions. The scripts create isolated environments, install the edition-specific pinned locks, compile the extension, bundle the private camera runtime, freeze the application, and generate archives and AppImages. Packaging requires g++, patchelf, and distribution library copyright files; downloads are checksum verified. The build records source hashes and whether source changed while building.

python3 scripts/build_binaries.py --edition cpu
python3 scripts/build_binaries.py --edition cuda
python3 scripts/make_source_archive.py

QT_QPA_PLATFORM=offscreen .venv/bin/python -m pytest -q
python3 scripts/validate_binaries.py

The binary validation script requires Docker. It runs a pinned Ubuntu 24.04 image without Python, ROS, or OpenEB, with networking disabled, and checks the GUI, spawned processing worker, official model inference on CPU, complete fixture decode, portable archives, and AppImage extraction mode. It does not establish physical camera, GPU, or sensor-rig accuracy.

Command line

The frozen AppRun or AppImage accepts the same commands as python -m event_calibration:

.venv/bin/python -m event_calibration inspect data/8x6_24mm --decode
.venv/bin/python -m event_calibration model download --backend e2vid
.venv/bin/python -m event_calibration extract data/8x6_24mm --backend e2vid --model-path artifacts/models/E2VID --frame-hz 5 --output artifacts/my-run
.venv/bin/python -m event_calibration intrinsics artifacts/my-run/project.json --output artifacts/my-calibration
.venv/bin/python -m event_calibration --self-test-worker --model artifacts/models/E2VID --model-backend e2vid

extract --help, stereo --help, and lidar --help describe the offline interfaces. Select one observation backend per sensor for stereo solving. A reconstructed LiDAR CLI manifest declares image/cloud paths and stationary: true; each image needs an E2VID/HyperE2VID sidecar and model SHA-256. A raw manifest sets method to raw-event-edges, supplies event/cloud NPZ paths, and declares motion_verified: true per pair. Event NPZ files contain either a structured events array or x, y, p, and t_ns; cloud NPZ files contain xyz, intensity, and optional point_times_ns. Both forms declare camera calibration, timestamps, clocks, and T_camera_from_lidar; relative paths resolve against the manifest directory.

Application source is Apache-2.0; the vendored EVREAL-compatible reconstruction code retains its MIT license. Bundled third-party licenses and notices are included in each distribution. See NOTICE for attribution and upstream references.