crosstyan/cvmmap-streamer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(mcap): split legacy single-camera layout reference

Browse Source 
Move the legacy /camera/* contract into its own reference page so the main MCAP layout doc can stay focused on current bundled and copy-layout behavior.

Document the compatibility model explicitly: legacy single-camera is operationally equivalent to one-camera copy when the effective camera label is treated as the literal `camera`.

Update the mcap_rgbd_example helper and recipe docs to accept legacy /camera/* inputs under that compatibility rule instead of rejecting them.
This commit is contained in:
crosstyan
2026-03-24 10:55:01 +00:00
parent ffd246e508
commit d0f3dc5cf1
5 changed files with 94 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/mcap_layout.md
+6 -28
View File
@@ -1,30 +1,15 @@
# MCAP Layout
`cvmmap-streamer` currently deals with three active MCAP layouts plus one legacy single-camera layout:
`cvmmap-streamer` currently deals with three active MCAP layout shapes:
- legacy single-camera `/camera/*` MCAP export
- bundled multi-camera timeline export
- multi-camera copy export
- single-source `zed_svo_to_mcap` output, which now uses the one-camera `copy` shape
This document covers the topic layout, schema types, and timestamp semantics for both.
This document covers the current bundled and copy contracts.
## Legacy Single-Camera Layout
Default topics:
| Topic | Schema / Encoding | Notes |
|------|------|------|
| `/camera/video` | `foxglove.CompressedVideo` | H.264 or H.265 Annex B access units |
| `/camera/depth` | `cvmmap_streamer.DepthMap` | RVL-compressed depth payload |
| `/camera/calibration` | `foxglove.CameraCalibration` | Video intrinsics |
| `/camera/depth_calibration` | `foxglove.CameraCalibration` | Written only when depth resolution differs from video |
| `/camera/pose` | `foxglove.PoseInFrame` | Optional; only when pose export is enabled and tracking is valid |
| `/camera/body` | raw `cvmmap.body_tracking.v1` | Optional raw body-tracking packets; see [mcap_body_tracking.md](./mcap_body_tracking.md) |
Single-camera export preserves the original per-frame source timestamp on video, depth, and pose messages.
This layout is still used by the generic sink/testers in the repository, but it is no longer the default shape written by `zed_svo_to_mcap` for a single `.svo` or `.svo2` input.
Legacy `/camera/*` is documented separately in [mcap_legacy_single_camera_layout.md](./mcap_legacy_single_camera_layout.md).
Conceptually, it is compatible with one-camera `copy` if you treat the camera label as the literal `camera` instead of `zedN` or another derived label.
## Bundled Multi-Camera Layout
@@ -135,15 +120,6 @@ Bundled `strict` export stays strict:
## Validation Expectations
For single-camera MCAP files, the current validation contract is:
- `/camera/video` must exist and contain at least one message
- `/camera/depth` must exist and contain at least one message
- `/camera/calibration` must exist exactly once
- `/camera/video` and `/camera/depth` message counts must match
- `/camera/depth_calibration` may appear zero or one time
- `/camera/pose` is optional, but it may not outnumber `/camera/video`
For bundled MCAP files, the current validation contract is:
- `/bundle` must exist
@@ -159,4 +135,6 @@ For multi-camera `copy` MCAP files, the current validation contract is:
- each camera must have `/zedN/video`, `/zedN/depth`, and `/zedN/calibration`
- for each camera, `/zedN/video` and `/zedN/depth` message counts must match
Legacy `/camera/*` validation expectations are documented in [mcap_legacy_single_camera_layout.md](./mcap_legacy_single_camera_layout.md).
The repository-level Python helper [scripts/mcap_bundle_validator.py](../scripts/mcap_bundle_validator.py) understands bundled, copy, and legacy `/camera/*` layouts and reports which one it found before applying the corresponding validation rules.