Skip to main content
Version: 11.0

Data Formats

MetriCal aims to be flexible with input data. Currently, it can ingest sensor data in the following formats:

MCAP Files​

MCAP is a flexible serialization format that supports a wide range of options and message encodings. This includes the capability to encode ROS1, ROS2/CDR serialized, Protobuf, Flatbuffer, and more.

Header Time vs Log Time​

MetriCal uses the header timestamp in each message for synchronization purposes. If your current workflow uses the log time instead, you should make sure that the header timestamp is also populated during recording. If not, MetriCal will not be able to synchronize your data correctly.

Message Kinds​

MetriCal only supports a limited subset of the total well-known message encodings in MCAP:

ROS1 Bags​

ROS1 itself is no longer supported. However, MetriCal still supports the reading of ROS1 bags. If you're looking to choose a format compatible with MetriCal today, we do not recommend picking ROS1 bags; instead, we suggest using MCAP (see previous section). ROS1 support is primarily here for those who are already using a ROS1 installation (i.e. for compatibility).

Message Kinds​

Like MCAP, MetriCal supports the following message ROS1 message kinds:

Folders​

If your system does not use ROS or encode data as an MCAP file at all, you can still use MetriCal by providing it with recursive folders of structured data. This approach is a little easier to get started with compared to using MCAP files, but can leave a lot of performance (and data size, as MCAP files are often compressed-by-default) on the table.

Message Kinds​

  • Images must be in JPEG or PNG format.
  • Point cloud data must be in PCD format.

Folder format description​

MetriCal assumes that the folder layout looks something like the following:

.
└── data/   <--- passed as $DATA argument in CLI
    ├── topic_1/
    ├── topic_2/
    └── topic_3/

Calibration Data Folder Structure

Where each directory contains inputs whose file names correspond to timestamps (canonically, in nanoseconds). For example, if we had a message topic named camera_1, we might have the following example tree of files:

.
├── camera_1/
│   ├── 1643230518150000000.png
│   ├── 1643230523197000000.png
│   ├── 1643230526125000000.png
│   ├── 1643230529419000000.png
│   ├── 1643230532161000000.png
│   └── 1643230537869000000.png
...

The folder names should correspond to the default topic names (e.g. such as in a ROS bag). Every topic does not need to have the same number of messages, or even share exactly the same timestamps as other topics. However, these timestamps will be assumed to be synced according to what is provided in the plex.

PointCloud2 messages and PCD Files​

MetriCal has partial support for v0.7 of the pcd file format for reading point cloud data. Since pcd is a very flexible format, we impose the following restrictions on pointclouds we can process:

  • Fields named "x", "y" and "z" are all present (referred to as Geometric data)
    • Geometric data fields are floating point (f32, float) values
  • One of the fields "intensity", "i", or "reflectivity" is present (referred to as Intensity data)
    • Intensity data contains data of one of the following types
      • Unsigned 8 bit integer (u8, uint8_t)
      • Unsigned 16 bit integer (u16, uint16_t)
      • Unsigned 32 bit integer (u32, uint32_t)
      • 32 bit floating point (f32, float)
  • Each of the Geometric data and Intensity data fields contains precisely 1 count

PCD Restrictions​

In addition to LiDAR / point cloud data needing to include the fields described above, we make some additional restrictions for PCD files when reading in data in the folder format:

  • The pcd data format is either ascii or binary
    • Explicitly, "binary_compressed" is not yet supported

As an example, a pcd with the header below would be supported.

# .PCD v.7 - Point Cloud Data file format
VERSION .7
FIELDS x y z intensity
SIZE 4 4 4 4
TYPE F F F F
COUNT 1 1 1 1
WIDTH 213
HEIGHT 1
VIEWPOINT 0 0 0 1 0 0 0
POINTS 213
DATA binary

Whereas, a pcd with the header below would not be supported

# .PCD v.7 - Point Cloud Data file format
VERSION .7
FIELDS x y z intensity
SIZE 4 4 4 4
TYPE F F F I
COUNT 3 3 3 1
WIDTH 213
HEIGHT 1
VIEWPOINT 0 0 0 1 0 0 0
POINTS 213
DATA binary_compressed