> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomadicml.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nomadic MCAP Specification

> The recording format Nomadic ingests: Foxglove-native MCAP plus a small JSON overlay.

**Version 1.1** · [Changelog](/mcap-spec/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](https://mcap.dev) file:

* the data is **Foxglove well-known messages** (camera images, point clouds, transforms, poses,
  GPS), so the same file opens in [Foxglove](https://foxglove.dev) 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](/mcap-spec/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

```text theme={null}
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

<CardGroup cols={2}>
  <Card title="File structure" href="/mcap-spec/file-structure">
    One recording per file, channels, the overlay record and its top-level fields.
  </Card>

  <Card title="Recording and time" href="/mcap-spec/recording">
    Recording identity, the clock, tasks and time-segmented annotations.
  </Card>

  <Card title="Frames, poses and units" href="/mcap-spec/frames-and-units">
    Coordinate frames, transforms, the body pose, units and quaternions.
  </Card>

  <Card title="Body and parts" href="/mcap-spec/body-and-parts">
    What the recording is of, and its arms, hands, legs, head and torso.
  </Card>

  <Card title="Signals" href="/mcap-spec/signals">
    Any named time series: types, wire format, units and recognised names.
  </Card>

  <Card title="Cameras" href="/mcap-spec/cameras">
    Views and roles, intrinsics and accepted encodings.
  </Card>

  <Card title="Point clouds" href="/mcap-spec/point-clouds">
    LiDAR and radar, their frames and fields.
  </Card>

  <Card title="GPS" href="/mcap-spec/gps">
    Geographic position as `foxglove.LocationFix`.
  </Card>

  <Card title="Validation" href="/mcap-spec/validation">
    What is rejected or warned, and how to check an overlay before you upload.
  </Card>

  <Card title="Schemas" href="/mcap-spec/schemas">
    The overlay JSON Schema and the `nomadic.*` protobuf definitions.
  </Card>
</CardGroup>

The [examples](/mcap-spec/examples/writing-a-converter) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.