Nomadic MCAP Specification

Version 1.1 · Changelog This specification defines the recording format the Nomadic platform accepts. It is written for anyone building a converter from their own logs (ROS bags, HDF5, Parquet, proprietary formats) into a file Nomadic ingests with no dataset-specific code on our side. A conforming file is an ordinary MCAP file:

the data is Foxglove well-known messages (camera images, point clouds, transforms, poses, GPS), so the same file opens in Foxglove with no conversion;
two small Nomadic message types cover what Foxglove has no schema for: nomadic.Signal for time series and nomadic.Skeleton for 3D keypoints;
one nomadic_spec overlay, a JSON document stored in the file’s metadata, says what each channel means: which camera is the front one, which point cloud is LiDAR, a signal’s name and unit, and what body the recording comes from.

A JSON Schema can say which overlay fields exist. It cannot say that LiDAR points must be in a frame whose z = 0 is the ground, or that joint angles are in radians. This specification is both halves: the schemas and the value rules that go with them.

Conformance language

Keyword	Meaning
MUST / MUST NOT	Enforced. A violation rejects the file, with a rule id naming what is wrong.
SHOULD / SHOULD NOT	Strongly recommended. A violation is accepted with a warning.
MAY	Optional.

Versions

spec_version in the overlay is "1.0" or "1.1". Every 1.0 file remains valid. Version 1.1 adds the body model for robots and people: platform.kind, platform.body_dimensions and platform.parts, plus nomadic.Skeleton keypoints. New converters SHOULD write "1.1".

At a glance

recording.mcap
├── metadata "nomadic_spec"         { "spec": "<overlay JSON>" }        ← what the channels mean
├── /cam/front                      foxglove.CompressedVideo            ← views
├── /lidar/top                      foxglove.PointCloud                 ← point clouds
├── /tf                             foxglove.FrameTransform             ← sensor extrinsics
├── /cam/front/calibration          foxglove.CameraCalibration          ← intrinsics
├── /gnss/fix                       foxglove.LocationFix                ← GPS
├── /ego/pose                       foxglove.PoseInFrame                ← body pose
├── /arm/ee_pose                    foxglove.PoseInFrame                ← a part's pose (1.1)
├── /hands/left/keypoints           nomadic.Skeleton                    ← keypoints (1.1)
└── /sig/speed, /sig/joints, …      nomadic.Signal                      ← signals

Every channel carries protobuf-encoded messages. A recording uses whichever modalities it has. A camera-only recording, a LiDAR-only recording and a bimanual robot with tactile hands are all the same format.

Reading this specification

File structure

One recording per file, channels, the overlay record and its top-level fields.

Recording and time

Recording identity, the clock, tasks and time-segmented annotations.

Frames, poses and units

Coordinate frames, transforms, the body pose, units and quaternions.

Body and parts

What the recording is of, and its arms, hands, legs, head and torso.

Signals

Any named time series: types, wire format, units and recognised names.

Cameras

Views and roles, intrinsics and accepted encodings.

Point clouds

LiDAR and radar, their frames and fields.

GPS

Geographic position as foxglove.LocationFix.

Validation

What is rejected or warned, and how to check an overlay before you upload.

Schemas

The overlay JSON Schema and the nomadic.* protobuf definitions.

The examples section has a complete converter and a full overlay for each kind of body: a car, a robot arm, dexterous hands, a person and a humanoid.

​Conformance language

​Versions

​At a glance

​Reading this specification