Docs / Compare workflow

Prepare two runs with Velune Adapter

Velune Adapter runs on your machine. It reads a Reference run and a Target run and writes one derived file, comparison.velune, for VeluneOS Compare. This page covers Beta Kit 0.1.1b5, which matches the current Compare service.

1. Install the Beta Kit

Requires Python 3.12 or 3.13. Download velune-adapter-beta-kit.zip (SHA-256) and unzip it. It contains two Python packages, BETA_QUICKSTART.md and SHA256SUMS.

$ cd beta-kit
$ sha256sum -c SHA256SUMS
velune_adapter-0.2.0-py3-none-any.whl: OK
velune_local_prepare-0.1.1b5-py3-none-any.whl: OK
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install velune_adapter-0.2.0-py3-none-any.whl velune_local_prepare-0.1.1b5-py3-none-any.whl
$ velune --help
usage: velune [-h] {mapping,prepare} ...

You use one command, velune, with two subcommands: mapping and prepare. pip also installs the packages the Adapter needs to read MCAP (such as mcap, zstandard and lz4) from your package index.

2. Choose the two runs

• Reference — the run you compare against, for example before a change. It is the baseline you choose, not a claim that it is correct.
• Target — the run you want to compare, for example after a change.
• Each run is one .mcap file. For a rosbag2 recording stored as MCAP, pass the .mcap file inside the bag directory. rosbag2 SQLite (.db3) files cannot be read.
• Comparisons are most useful when both runs exercise the same scenario (same route, task or test).

3. Discover streams

$ velune mapping init reference.mcap target.mcap --output mapping.json
Discovered 5 streams across Reference and Target.
Mapping template: /path/to/mapping.json
Next: fill canonical_subsystem_id and canonical_category_id for the streams you want to recognise in the report (at least one). Every stream is compared and transferred either way; a stream without a category appears in the report by its neutral key.

This reads both files locally and writes mapping.json, listing every stream and how the Adapter pairs streams across the two runs. --output defaults to ./mapping.json. mapping.json contains your topic and schema names; it stays on your machine and is not part of the uploaded file.

4. Configure the mapping

Each discovered stream is a rule:

{
  "raw_match_key": "/lidar/points",
  "canonical_subsystem_id": null,
  "canonical_category_id": null,
  "_presence": "both",
  "_reference_schema": "…",
  "_target_schema": "…"
}

• raw_match_key — the topic found in your recordings.
• _presence — both, reference or target: where the stream appears.
• canonical_subsystem_id / canonical_category_id — the labels you assign, for example "PERCEPTION" / "PERCEPTION_LIDAR". Set both or neither.

Assign labels to the streams you want to recognise in the report — at least one. Every stream is compared either way; a stream without labels appears in the report by its neutral key (for example stream.unmapped.003). The report never shows your topic names, so labels are how you recognise streams.

5. Confirm stream pairings

Streams are paired across runs by identical topic name. Two cases need your confirmation, and mapping init lists them under correspondence_review:

• matched_by_message_type — a topic exists in only one run and the Adapter paired it with a topic of the same message type in the other run. Right for a renamed topic, wrong for a different sensor.
• duplicate_topic_name — a topic name appears more than once, so the pairing between channels is ambiguous.

Check: 1 Reference/Target pairing(s) are not based on an identical, unique topic name. …
  - /lidar (Reference) <-> /lidar_top (Target): matched_by_message_type

"correspondence_review": [
  {
    "reference_topic": "/lidar",
    "target_topic": "/lidar_top",
    "reference_channel_id": 2,
    "target_channel_id": 2,
    "basis": "matched_by_message_type",
    "same_stream": null
  }
]

Set "same_stream": true only if the pair really is the same stream. In the usual case — every stream keeps its topic name — the list is empty and there is nothing to confirm.

A mapping.json created by an older kit has no correspondence_review section; if any pairing needs review, re-run velune mapping init.

6. Generate comparison.velune

$ velune prepare reference.mcap target.mcap \
    --mapping-profile mapping.json --output comparison.velune
Velune Adapter — preparation complete
Artifact: /path/to/comparison.velune
Transfer ID: vtransfer_sha256_…
Transfer preview: /path/to/comparison.preview.json (11 files in comparison.velune, 132279 bytes -- raw MCAP, payloads, original paths/topic/schema names, and absolute timestamps are not included; see the file for the full list of what is)

Next: review the transfer preview, then upload this file to VeluneOS Compare
https://compare.veluneos.ai/compare

Pass the same two files, in the same order, that you used for mapping init. --output defaults to ./comparison.velune; running prepare again overwrites it. Nothing is sent over the network.

If the artifact is written but its preview cannot be, prepare prints “preparation incomplete”, exits with an error, and you should not upload the file until you can review it.

7. Review comparison.preview.json

Open the preview before uploading anything. It describes exactly what is inside comparison.velune:

• files — every entry in the archive, with size, SHA-256 and top-level fields (11 entries: manifests, per-run observation series, stream inventories and run manifests, the mapping record and the stream pairing record).
• explicitly_excluded_categories — what is not in the file: raw MCAP and logs, raw and decoded payloads, absolute local paths, original file, topic and schema names, absolute timestamps, credentials and environment variables, and more.
• privacy_declarations — per-file declarations, for example original_topic_name_included: false.
• streams — each stream's neutral key and role.
• network_transfer_performed: false and instruction: send only comparison.velune, nothing else on this machine.

The file still describes your system's structure (stream counts, message rates and timing). It is not described as anonymous. See Data boundaries.