transmcap

transmcap is a CLI that decodes MCAP messages through mcapdecode and writes results as JSON Lines, CSV, or Parquet.

Installation

cargo install transmcap

Usage

transmcap <command> <input.mcap> [options]

Commands:

• convert: convert MCAP messages to jsonl/csv/parquet
• schema: print inferred field schema for a topic

Supported Schema Encodings

transmcap uses McapReader::with_default_decoders(). Supported encoding pairs:

mcapdecode default features are protobuf, ros2msg, ros2idl.

convert Options

• -f, --format <FORMAT>: jsonl | csv | parquet (default: jsonl)
• -t, --topic <TOPIC>: topic name to convert (required)
• -o, --output <PATH>: output file path (jsonl/csv defaults to stdout)
• --list-policy <POLICY>: drop | keep | flatten-fixed
• --list-flatten-size <N>: only valid with --list-policy flatten-fixed
• --array-policy <POLICY>: drop | keep | flatten
• --map-policy <POLICY>: drop | keep
• --fields <FIELDS>: comma-separated field paths to include (applied before flattening)
• -p, --parallel: enable parallel chunk decompression and decoding

schema Options

• -t, --topic <TOPIC>: topic name (required)
• -o, --output <PATH>: output file path (default: stdout)

Policy Behavior

convert flattens Arrow RecordBatch columns before writing.

• list-policy (List): drop | keep | flatten-fixed
• array-policy (FixedSizeList): drop | keep | flatten
• map-policy (Map): drop | keep
• struct-policy (Struct): fixed by format (not a CLI option)

Semantics:

• drop: skip the column
• keep: keep the column as-is
• flatten-fixed: expand list to fixed columns (name.0, name.1, ...)
• flatten: expand child fields into separate columns

If --list-flatten-size is set without --list-policy flatten-fixed, command returns an error.

Format Defaults

CLI flags override defaults.

Examples

JSON Lines

transmcap convert sample.mcap --format jsonl --topic /imu/data [-o imu.jsonl]

CSV

transmcap convert sample.mcap --format csv --topic /imu/data [-o imu.csv]

Parquet to file

parquet output requires -o/--output:

transmcap convert sample.mcap --format parquet --topic /imu/data -o imu.parquet

Custom flatten policy

transmcap convert sample.mcap --format parquet --topic /imu/data \
  --list-policy drop --array-policy flatten --map-policy drop \
  -o out.parquet

Print schema

transmcap schema sample.mcap --topic /imu/data

Notes

• --topic is required for both commands.
• parquet requires -o/--output.
• convert runs sequentially by default; use -p/--parallel to enable parallel chunk decompression and decoding.
• Column name collisions during flattening return an error.

Development

cargo run -p transmcap -- <command> <input.mcap> [options]
cargo test -p transmcap