docs(mcap): split legacy single-camera layout reference
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:
+20
-13
@@ -4,12 +4,12 @@ This guide is the simple, non-GUI path for inspecting RGB+depth MCAP files.
|
||||
|
||||
Use it when you want to:
|
||||
|
||||
- confirm whether an MCAP is bundled or `copy`
|
||||
- confirm whether an MCAP is bundled, `copy`, or legacy `/camera/*`
|
||||
- inspect camera labels, message counts, and timestamp ranges
|
||||
- export one RGB frame and one decoded depth sample as a concrete example
|
||||
- understand how `/bundle` changes the meaning of timestamps and sample grouping
|
||||
|
||||
For the full layout contract, see [mcap_layout.md](./mcap_layout.md).
|
||||
For the current bundled/copy layout contract, see [mcap_layout.md](./mcap_layout.md). The older `/camera/*` wire shape is documented separately in [mcap_legacy_single_camera_layout.md](./mcap_legacy_single_camera_layout.md).
|
||||
|
||||
## Quick Summary
|
||||
|
||||
@@ -41,14 +41,19 @@ uv sync --extra viewer
|
||||
|
||||
## The Practical Cases
|
||||
|
||||
For this helper, there are really two supported layouts:
|
||||
For this helper, there are really two operational cases:
|
||||
|
||||
- `bundled`: multiple namespaced camera topics plus `/bundle`
|
||||
- `copy`: namespaced camera topics with no `/bundle`
|
||||
- single-camera stream with no `/bundle`
|
||||
|
||||
Current single-source `zed_svo_to_mcap` output uses the one-camera `copy` shape by default, so even a one-camera file still looks like namespaced `/{label}/*` topics with no `/bundle`.
|
||||
That second case can appear in two wire shapes:
|
||||
|
||||
Legacy `/camera/*` MCAP files are intentionally out of scope for this helper. Regenerate them into `copy` layout if you still have old files around.
|
||||
- `copy`: namespaced topics such as `/zed4/video`
|
||||
- legacy single-camera: `/camera/video`
|
||||
|
||||
Current single-source `zed_svo_to_mcap` output uses the one-camera `copy` shape by default, so even a one-camera file usually looks like namespaced `/{label}/*` topics with no `/bundle`.
|
||||
|
||||
The helper treats legacy `/camera/*` as compatible with `copy` by using the implicit camera label `camera`.
|
||||
|
||||
## Recipe: Summarize One MCAP
|
||||
|
||||
@@ -70,7 +75,7 @@ What the summary prints:
|
||||
|
||||
This is the fastest way to answer:
|
||||
|
||||
- “is this file bundled or copy?”
|
||||
- “is this file bundled, copy, or legacy single-camera?”
|
||||
- “which camera labels are inside?”
|
||||
- “do video and depth counts match?”
|
||||
- “what timestamp range does each camera cover?”
|
||||
@@ -83,7 +88,7 @@ uv run python scripts/mcap_rgbd_example.py export-sample \
|
||||
--output-dir /tmp/mcap_sample
|
||||
```
|
||||
|
||||
For multi-camera or one-camera `copy` files, choose the camera explicitly when needed:
|
||||
For multi-camera or namespaced one-camera files, choose the camera explicitly when needed:
|
||||
|
||||
```bash
|
||||
uv run python scripts/mcap_rgbd_example.py export-sample \
|
||||
@@ -104,25 +109,26 @@ Outputs:
|
||||
|
||||
That means:
|
||||
|
||||
- `copy`: sample `N` is `/zedN/video[N]` + `/zedN/depth[N]`
|
||||
- legacy `/camera/*`: sample `N` is `/camera/video[N]` + `/camera/depth[N]`
|
||||
- `copy`: sample `N` is `/{label}/video[N]` + `/{label}/depth[N]`
|
||||
- `bundled`: sample `N` is the `N`th present sample for that camera, not bundle index `N`
|
||||
|
||||
In bundled files, `sample_metadata.json` also records the matched `/bundle` member metadata for the selected camera sample.
|
||||
|
||||
## Recipe: Understand Bundled vs Copy Timing
|
||||
## Recipe: Understand Bundled vs Non-Bundled Timing
|
||||
|
||||
Bundled files intentionally separate bundle time from camera sample time:
|
||||
|
||||
- `/bundle.timestamp` is the nominal common-timeline bundle timestamp
|
||||
- `/zedN/video` and `/zedN/depth` keep the original per-camera sample timestamps
|
||||
|
||||
Copy files do not have bundle time at all:
|
||||
Copy and legacy single-camera files do not have bundle time at all:
|
||||
|
||||
- there is no `/bundle`
|
||||
- each camera topic keeps its own original cadence and timestamps
|
||||
|
||||
If you care about grouping, use `/bundle` in bundled files.
|
||||
For `copy`, treat each camera stream independently.
|
||||
For `copy` and legacy single-camera files, treat each camera stream independently.
|
||||
|
||||
## Recipe: Inspect `/bundle` In Python
|
||||
|
||||
@@ -169,4 +175,5 @@ with path.open("rb") as stream:
|
||||
This is the important mental model:
|
||||
|
||||
- `bundled`: follow `/bundle` for grouping
|
||||
- `copy`: treat each camera as an independent stream
|
||||
- `copy`: treat each namespaced camera as an independent stream
|
||||
- legacy `/camera/*`: same model as one-camera `copy`, with the implicit label `camera`
|
||||
|
||||
Reference in New Issue
Block a user