Skip to main content
Version: dev-latest

Plex Learn

Usage​

Plex Learn - CLI Example
metrical plex learn [OPTIONS] [PLEX_OR_RESULTS_PATH]
Plex Learn - Manifest Example
command = "plex-learn"
input-plex = "input.json"
dataset = "{{variables.dataset}}"
system-specification = "{{variables.system-spec}}"
topic-to-model = [
  ["topic", "model"],
  ["topic2", "model2"],
]
output-plex = "{{auto}}"

Purpose​

metrical plex learn infers Plex information — components, intrinsics estimates, covariances, and constraints — from a dataset and/or a system specification. The result is a Plex ready to be passed to metrical calibrate.

This command replaces the now-deprecated metrical init for the day-to-day workflow of initializing a Plex from a dataset.

At least one of --dataset or --system-specification must be provided.

  • Use --dataset to infer components and constraints directly from raw observations in a dataset (MCAP or folder-based).
  • Use --system-specification to seed spatial constraints, camera focal lengths, and coordinate basis corrections from a system specification.
  • Both can be provided together; when they are, dataset-inferred values are computed first, then system specification values override them.

An optional input Plex can be supplied as a positional argument. Any components or constraints already present in that Plex will be carried through and enriched by the learning process.

Examples​

Learn a Plex from a dataset​

Assign all topics matching *cam_ir* to the OpenCV Radtan model and *lidar* to the LiDAR model:

metrical plex learn \
    --dataset $DATA \
    -m '*cam_ir*:opencv-radtan' \
    -m '*lidar*:lidar' \
    -o $PLEX

Learn from a system specification only​

Apply mechanical layout and camera parameters from a system specification without providing any dataset:

metrical plex learn -S system_spec.json -o $PLEX

Augment an existing Plex with dataset information​

metrical plex learn --dataset $DATA -m /camera/1:opencv-radtan input_plex.json -o $PLEX

Learn from a merged set of plexes​

metrical merge plex_cams.json plex_lidar.json -K complement \
    | metrical plex learn --dataset data.mcap

Learn from both a dataset and a system specification​

Combine data-driven inference with mechanical priors. The system specification seeds focal lengths and overrides spatial constraints with CAD-measured extrinsics:

metrical plex learn \
    --dataset $DATA \
    -S system_spec.json \
    -m '*camera*:opencv-radtan' \
    -m '*lidar*:lidar' \
    -o $PLEX

Manifest with a system specification​

metrical.toml (plex-learn stage)
[stages.plex-learn]
command = "plex-learn"
input-plex = "{{variables.init-plex}}"
dataset = "{{variables.dataset}}"
system-specification = "{{variables.system-spec}}"
topic-to-model = [
    ["*infra*", "opencv-radtan"],
    ["*color*", "opencv-radtan"],
    ["*imu*", "scale-shear"],
]
output-plex = "{{auto}}"

If plex learn is given an input Plex that already contains components and constraints, the learning process will enrich that Plex rather than starting from scratch. This lets you merge disparate calibrations across one system into a single Plex and then run plex learn to fill in any missing information.

Arguments​

[PLEX_OR_RESULTS_PATH]​

An optional path to an existing input Plex. If provided, its components and constraints will be carried through and enriched by the learning process. If omitted, MetriCal will attempt to read a Plex from stdin; if nothing is available on stdin, a new empty Plex is used as the starting point.

Options​

Global Arguments​

As with every command, all global arguments are supported (though not all may be used).

-D, --dataset [DATASET]​

The dataset to learn/infer components and constraints from. Accepts an MCAP file (.mcap extension) or a top-level directory containing a set of nested directories for each topic.

Expected to contain raw observations (e.g., images, point clouds, IMU samples). Cached detections or results from a prior MetriCal run are not supported here.

-S, --system-specification [SYSTEM_SPECIFICATION]​

A path to a system specification JSON file. The system specification encodes mechanical layout transforms, camera coordinate bases, and nominal diagonal fields of view from CAD or datasheets.

When provided, MetriCal seeds camera focal lengths from DFoV entries, replaces spatial constraint extrinsics with mechanical layout values, and applies basis-change corrections for cameras that do not use the RDF convention. JSON with comments is supported.

This flag can be used alone (without --dataset) to apply a specification to an existing Plex, or combined with --dataset for a more complete initialization. When both are provided, the system specification values take precedence over data-inferred values.

In a manifest, use the system-specification key (kebab-case).

-m, --topic-to-model [TOPIC_NAME:MODEL]​

A mapping of topic/folder names to intrinsics models. All topics intended for calibration must be enumerated by this argument. Any matching topic models already in the input Plex will be overwritten.

Example:

-m /camera/1:opencv-radtan -m /camera/2:opencv-fisheye

Wildcards are also supported:

-m '/camera/*:opencv-radtan'

Available models​

Cameras​
LiDAR​
IMU​
Radar​
  • radar
Local Navigation Systems​
Transform Trees​
  • transform-tree

-o, --output [OUTPUT]​

The path to output the resulting Plex. If omitted, MetriCal will write the Plex to stdout.