Calibration tools for Apollo .record data and related image / point-cloud
workflows.
| Module | Current status | Practical recommendation |
|---|---|---|
lidar2lidar |
real-bag validated | keep scan2scan as production baseline; use scan2map as conditional refinement |
gril / LiDAR-to-IMU |
GRIL is the first algorithm baseline; ROS-free native build remains research-only | use Weilan 0827 corrected-IMU as a provisional input/regression fixture, not accuracy truth; its physical check rejects the candidate and native full A/B rotation discrepancy remains 0.406964 deg versus a 0.2 deg gate (method, release gate) |
camera |
standalone intrinsic tool exists | usable as a local intrinsic calibrator |
camera2camera |
target-based stereo baseline exists | use the checkerboard paired-image pipeline as the current production baseline; add ChArUco next |
lidar2camera |
target-based industrial baseline exists | use the target-based pipeline as the current production baseline; keep targetless paths experimental |
If you are new to the repo, follow the docs in this order:
- Apollo-side prerequisites and recording: docs/apollo_data_collection.md
- Module quick starts: docs/quickstart_index.md
- How to review metrics and visualization: docs/calibration_review_guide.md
- Advanced design / method / SOTA context: docs/calibration_methodology.md
| Module | Current tool input | Apollo-side raw data that should be recorded | Extra information you must know in advance |
|---|---|---|---|
camera |
live camera or exported image directory | camera image topic if you want to archive the session in Apollo; direct live capture is also supported | board pattern size, square size, fixed camera mode / exposure |
camera2camera |
paired image directories | two camera image topics if you want Apollo traceability; the current tool itself consumes exported image pairs | parent / child intrinsics, board pattern size, square size, multi-pose board plan |
lidar2camera |
paired image + .pcd files |
camera image topic, LiDAR PointCloud2, /tf_static, optional /tf |
camera intrinsics, distortion, checkerboard size, square size |
lidar2lidar |
Apollo .record or prepared dataset |
all raw LiDAR PointCloud2 topics, /tf_static, optional /tf |
sensor topic list, approximate TF tree / initial extrinsics, scene plan |
gril / LiDAR-to-IMU |
Apollo .record, ROS1 bag, or canonical GRIL dataset |
one raw LiDAR topic, measurement-time IMU topic, /tf_static, optional independent GNSS/INS odometry for holdout |
LiDAR topic, IMU topic, scan-line count, reviewed sensor configuration |
Use a virtual environment:
python3 -m venv .venv
source .venv/bin/activate
pip install -e .The base package installs only the shared numerical and YAML dependencies. Install the extra matching the calibration workflow you need:
pip install -e ".[camera]"
pip install -e ".[camera2camera]"
pip install -e ".[lidar2lidar]"
pip install -e ".[lidar2imu]"
pip install -e ".[lidar2camera]"To install every calibration workflow in one environment, combine all extras:
pip install -e ".[all]"The lidar2imu extra installs Python dependencies for offline bag parsing and
validation; it does not install ROS, compile GRIL, or include native
executables. Apollo .record ingress uses the Bzlmod C++ wheelos_core
adapter, which must be built separately. Offline bag parsing uses rosbags
without ROS. Record and bag inputs converge to the same canonical dataset
before entering the native frontend and solver. The native executable must
also be built separately with CMake and the reviewed Eigen/PCL/Ceres toolchain;
this is currently a developer/research workflow, not a production installer.
See the
LiDAR-to-IMU quick start for the exact steps
and release restrictions. New input formats belong in lidar2imu.adapters; verify
canonical data equivalence before running the unchanged GRIL algorithm. Live
ROS topic subscription is not currently supported. The quick start also documents
an opt-in TF rotation-seed experiment; the frozen identity seed remains the default.
If the default PyPI route is slow or unstable in this environment, switch pip to the Tsinghua mirror inside the active virtual environment first:
python -m pip config --site set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip install -e ".[all]"See docs/apollo_data_collection.md for the full checklist. The short version is:
# examples from /home/humble/01code/apollo-base
bash scripts/transform.sh start
bash scripts/gps.sh start
bash scripts/localization.sh start
bash scripts/camera.sh start
cyber_launch start /apollo/modules/drivers/lidar/launch/lidar_with_fusion_and_compensator.launch
# record all channels from the target output directory
cyber_recorder record -a -i 60 -m 2048If you prefer Apollo's wrapper script, scripts/record_bag.sh start in
apollo-base launches the same recorder command.
RECORD_DIR=/path/to/record_dir
lidar2lidar-topics "$RECORD_DIR"- LiDAR-to-LiDAR: docs/lidar2lidar_quickstart.md
- LiDAR-to-IMU: docs/lidar2imu_quickstart.md
- GRIL ROS-free migration: docs/gril_ros_free_migration.md
- Camera intrinsic: docs/camera_quickstart.md
- Camera-to-camera: docs/camera2camera_quickstart.md
- LiDAR↔Camera: docs/lidar2camera_quickstart.md
- LiDAR↔Camera nuScenes benchmark: docs/lidar2camera_nuscenes_benchmark.md
Across modules, the stable review order is:
diagnostics/standardized_data.yamldiagnostics/data_quality.yamlmetrics.yamldiagnostics/acceptance_report.yamldiagnostics/visualization_index.yaml
Use docs/calibration_review_guide.md for the module-specific thresholds and visualization files.
lidar2lidar-auto \
--record-path "$RECORD_DIR" \
--conf-dir lidar2lidar/conf \
--output-dir outputs/lidar2lidar/auto_calib_review \
--sync-threshold-ms 10 \
--min-overlap 0.30 \
--methods 2 \
--max-samples 1For a four-LiDAR raw rig, prepare a reusable raw-only dataset first:
lidar2lidar-rig-dataset \
--record-path "$RECORD_DIR" \
--output-dir outputs/prepared/run-eight-raw4 \
--lidar-topics \
/apollo/sensor/vanjeelidar/left_front/PointCloud2 \
/apollo/sensor/vanjeelidar/right_front/PointCloud2 \
/apollo/sensor/vanjeelidar/right_back/PointCloud2 \
/apollo/sensor/vanjeelidar/left_back/PointCloud2 \
--reference-topic /apollo/sensor/vanjeelidar/left_front/PointCloud2 \
--sync-threshold-ms 40 \
--frame-stride 2 \
--export-voxel-size 0.10# Weilan 0827 profile; audit timestamp provenance before choosing another IMU topic.
lidar2imu run-native \
--input "$RECORD_DIR" \
--input-type record \
--core-record-ingress tools/gril_record_core_reader/bazel-bin/record_ingress \
--config .agents/skills/gril-calib-validation/resources/vanjeelidar16.yaml \
--executable third_party/gril_native/build/gril_native_full_frontend \
--output-dir outputs/gril/0827_corrected_imu_baseline/run_01 \
--lidar-topic /apollo/sensor/vanjeelidar/up/PointCloud2 \
--imu-topic /apollo/sensor/gnss/corrected_imu \
--scan-lines 16camera2camera-calibrate --write-default-config --config camera2camera_config.yaml
camera2camera-calibrate --config camera2camera_config.yamllidar2camera-calibrate --write-default-config --config config.yaml
lidar2camera-calibrate --config config.yamllidar2camera-nuscenes-benchmark \
--info-path /mnt/synology/nuScenes/OpenDataLab___nuScenes/raw/Trainval/train/nuscenes_infos_val.pkl \
--camera-names CAM_FRONT \
--sample-limit 8camera-intrinsic-calibrate --config camera_config.yamlCamera intrinsic and ROS-free GRIL use separate images and the same read-only input / writable output mount convention. See docker/README.md. Live camera capture requires a GUI; headless camera execution is supported only for offline image datasets.
The repo keeps the final review surface stable on purpose. Depending on the module, look for:
customer_summary.yamlfor the concise customer verdict and key metricscalibrated_tf.yamlmetrics.yamldiagnostics/standardized_data.yamldiagnostics/data_quality.yamldiagnostics/acceptance_report.yamldiagnostics/status_summary.csvdiagnostics/visualization_index.yamlinitial_guess/*.yamlcalibrated/*.yaml
For camera, the equivalent outputs live under
outputs/camera_intrinsic/runs/<session>/calibration_diagnostics/, while live
accepted samples are archived under
outputs/camera_intrinsic/captures/<session>/accepted/.
Detailed metric layering is documented in docs/calibration_metric_layers.md.
The durable project knowledge base lives under context/.
Recommended entry points:
context/index.mdcontext/knowledge_base/calibration_overview.mdcontext/knowledge_base/validated_conclusions.mdcontext/knowledge_base/verification_points.md
Module docs:
- LiDAR-to-LiDAR overview: docs/lidar2lidar.md
- LiDAR-to-LiDAR Quick Start: docs/lidar2lidar_quickstart.md
- LiDAR-to-LiDAR current design: docs/lidar2lidar_design.md
- LiDAR-to-IMU quick start: docs/lidar2imu_quickstart.md
- LiDAR-to-IMU Quick Start: docs/lidar2imu_quickstart.md
- Camera-to-camera Quick Start: docs/camera2camera_quickstart.md
- Camera-to-camera design: docs/camera2camera_design.md
- ROS-free GRIL design and release gate: docs/gril_ros_free_migration.md
- Camera intrinsic quick start: docs/camera_quickstart.md
- LiDAR↔Camera Quick Start: docs/lidar2camera_quickstart.md
- LiDAR↔Camera current design: docs/lidar2camera_design.md