Skip to content

lidarslam_ros2 v0.7.0

The productized map-authoring release candidate. v0.7.0 keeps the deterministic mapping and map-quality work developed after v0.6, but narrows the supported product to one outcome:

Start with a supported rosbag2, run one documented command, obtain a verified Autoware-compatible pointcloud map bundle, and diagnose a failure without reading the implementation.

The release remains a prerelease. ROS buildfarm packages and the three-user external-adoption gate are not yet complete.

Golden path

The supported installed command surface is:

lidarslam-map doctor /data/bag
lidarslam-map run /data/bag --output-dir /data/map
lidarslam-map inspect /data/map

view is an optional viewer-runtime command. Advanced recovery commands are available through --help-all:

lidarslam-map migrate-manifest --help
lidarslam-map rollback-plan --help

Source execution, installed lidarslam-map, and ros2 run lidarslam lidarslam-cli share the same machine-readable option contract and Bash completion. Completion is checked for exact option parity, path and duration values use consistent metavars, and invalid option usage exits with status 2. The historical C++ node remains ros2 run lidarslam lidarslam.

Product artifacts and failure behavior

Every run has versioned, schema-validated product evidence:

  • preflight-v3 records bag identity, required topics, PointCloud2 fields, timestamp-order bounds, and the selected profile;
  • run-manifest-v2 records the exact input, software identity, command plan, lifecycle stage, durable outputs, checksums, and resume decision;
  • diagnosis-v1 maps unsupported input and runtime failures to actionable operator guidance;
  • map verification checks the Autoware pointcloud-map layout and projector metadata before success is reported.
  • first-map-validation-receipt-v1 derives an issue-ready, geometry-free verification summary from the final manifest, diagnosis, and verifier log.

Output publication is atomic and existing outputs are never overwritten. Collision, low free space, real filesystem exhaustion, timestamp reversal, termination, and partial output all fail closed. A 2 MiB terminal-evidence reserve allows the final failed manifest and diagnosis to survive a real ENOSPC event.

Distribution and recovery

Humble 22.04 amd64 and Jazzy 24.04 amd64 are the tested product targets:

  • clean non-symlinked installs expose the same CLI, schemas, completion, and runtime resources;
  • fresh and v0.6.0-upgraded prefixes have identical package-owned files and behavioral checks;
  • versioned GHCR images are built from the exact tag commit with an OCI SBOM, maximum-mode BuildKit provenance, and a signed GitHub attestation;
  • both image digests are smoke-tested before version tags are created;
  • immutable promotion reuses an identical version tag and refuses a conflicting digest instead of moving it;
  • each image publishes release-image-<distro>.json and rollback-plan-<distro>.json, and the release publishes release-promotion.json;
  • the deterministic release bundle embeds release-bundle-manifest-v1.json with every bundled file hash.

The release JSON records are the supported rollback input:

lidarslam-map rollback-plan release-image-jazzy.json

The generated pull, attestation, and CLI smoke commands use only the immutable ghcr.io/...@sha256:... reference. Rollback never retags an old image and never overwrites a map output.

Operational evidence

The product path is exercised beyond unit fixtures:

  • the pinned public MID-360 E2E workflow downloads a fixed archive, runs the installed Jazzy product, and validates non-geometry evidence;
  • one-hour and eight-hour named-hardware soaks passed with zero documented drop signatures, bounded per-iteration time, storage telemetry, and exact machine/input/software provenance;
  • the real bounded-filesystem gate confines output to a 32 MiB Docker tmpfs, observes PCL raw_fallocate ... returned 28, exits nonzero, and preserves a terminal failed manifest, storage diagnosis, and logs;
  • Humble/Jazzy install-upgrade, normal CI, docs, Docker, and the real reliability workflows are independently change-gated.

See the tracked bounded-filesystem evidence, recovery-command evidence, and operational reliability contract.

Mapping engine changes since v0.6

  • Event-driven backend processing is now the only loop-search path; the deprecated wall-clock option was removed.
  • Graph state, loop search, pose-graph optimization, filtering, registration, and ROS-shell ownership boundaries were decomposed and characterized.
  • Deterministic offline frontend/backend runners and map-quality metrics remain release gates.
  • Offline plane refinement, degeneracy diagnostics, radar/tunnel presets, coloured maps, calibration, dynamic cleaning, and alternative loop detectors remain advanced or research capabilities. They do not add beginner entrypoints or silently expand the hardware support promise.

Upgrade notes

  • Use lidarslam-map for the supported map-authoring workflow. Existing direct scripts and launch files remain compatibility, benchmark, or research interfaces as documented.
  • Run lidarslam-map doctor before mapping an existing bag; timestamp order, required field, and storage checks are stricter than v0.6.
  • Existing schema-v1 terminal manifests are inspectable but not resumable. migrate-manifest requires an explicit historical verification mode and writes a new inspect-only schema-v2 record.
  • The legacy event_driven_loop_search parameter is gone because event-driven processing is no longer optional.

Known boundaries

  • There is no supported apt install ros-<distro>-lidarslam path yet. ndt_omp_ros2 must be released first. Official RKO-LIO releases now exist for Humble/Jazzy (0.3.2-1 is in testing; main currently carries older versions), but compatibility with the maintained fork and pinned golden path must pass clean installed E2E before adding the runtime dependency.
  • arm64 and Jetson are evaluation tier; release images are amd64.
  • Lanelet2 generation remains operator-reviewed.
  • The v1.0 readiness gate still requires three independent users to complete first-map validation from public documentation.
  • The report form, evidence ledger schema, and check_external_first_map_readiness.py --require-complete command now make that gate reproducible; the accepted count remains 0/3.

Full product scope and remaining work: