feat(record): add raw ZED body MCAP capture

2026-03-13 17:30:57 +08:00
parent e0946d777f
commit 172df30225
14 changed files with 681 additions and 19 deletions
@@ -0,0 +1,44 @@
+# MCAP ZED Body Tracking Contract
+
+`cvmmap-streamer` records native cv-mmap ZED body-tracking packets into MCAP as a raw binary channel.
+
+## Channel
+
+- default topic: `/camera/body`
+- `messageEncoding`: `cvmmap.body_tracking.v1`
+- schema: none (`schemaId = 0`)
+- channel metadata:
+  - `packet_layout = cvmmap_body_tracking_v1`
+  - `payload_format = raw`
+  - `source_transport = cv-mmap-body-pub`
+
+The channel is created lazily on the first valid body packet, so non-body inputs do not produce an empty `/camera/body` channel.
+
+## Payload
+
+Each MCAP message payload is byte-for-byte identical to the cv-mmap ZED body PUB packet:
+
+- 64-byte `body_tracking_message_header_t`
+- followed by `body_count` packed `body_tracking_body_t` records
+
+The intended parser contract is the existing cv-mmap body-tracking v1 layout:
+
+- `cvmmap::parse_body_tracking_message(...)`
+- `cv-mmap/docs/cvmmap_body_tracking_v1.ksy`
+
+This recording path does not remap joints, filter fields, or convert the packet into protobuf/JSON.
+
+## Timing And Alignment
+
+- `logTime` and `publishTime` use `header.timestamp_ns`
+- if `header.timestamp_ns == 0`, they fall back to `header.sdk_timestamp_ns`
+- cross-topic alignment should use body `frame_count` and timestamps, not MCAP file order
+
+## Configuration
+
+MCAP body capture follows the normal MCAP recording switch:
+
+- enable MCAP with `--mcap` or `record.mcap.enabled = true`
+- override the body topic with `--mcap-body-topic` or `record.mcap.body_topic`
+
+There is no separate body-enable flag. If the input never emits body packets, no body channel is written.