Skip to main content
Version: 15.0

MetriCal Command: Init

Usage​

Init - CLI Example
metrical init [OPTIONS] <DATASET> <INITIALIZED_PLEX>
Init - Manifest Example
command = "init"
dataset = "{{variables.dataset}}"
reference-source = []
topic-to-model = [
  ["topic", "model"],
  ["topic2", "model2"],
  ...
]
remap-reference-component = []
overwrite-strategy = "preserve"
uuid-strategy = "inherit-reference"
initialized-plex = "{{auto}}"

Purpose​

Init will infer all components, spatial constraints, and temporal constraints based on the observations and interactions in the dataset. It will then write this information out in plex form to a JSON file (listed as $INIT_PLEX in code samples below). This is our Initialized Plex! MetriCal will use this plex as the initialization to the Calibrate command.

Let's break down this example Init command:

metrical init -m *cam_ir*:opencv-radtan -m *cam_color*:eucm -m *lidar*:lidar $DATA $INIT_PLEX
  • Assign all topics/folders that match the *cam_ir* pattern to the OpenCV Radtan model.
  • Assign all topics/folders that match the *cam_color* pattern to the EUCM model.
  • Assign all topics/folders that match the *lidar* pattern to the No Offset model (just extrinsics)
  • Use the data in $DATA to initialize the plex.

MetriCal will discard information from any topics that aren't assigned a model using the command line. See all of the models available to MetriCal in the --topic-to-model/-m documentation.

Plex Reference Sources​

If you have a good idea of some aspect of your system, you can actually provide Init mode with a Plex Reference. A Plex Reference can come in the form of another plex (possibly from a previous calibration) or a URDF XML. It's common to provide a "golden plex" for initialization of new systems this way.

REF_PLEX=golden_plex.json
metrical init --reference-source $REF_PLEX $DATA $INIT_PLEX

All components, spatial constraints, and temporal constraints that are in the reference plexes will be applied to the initialized plex. Spatial constraints are applied to the initialized plex only if the names of the topics in the plex reference match one of the components mapped by the -topic-to--model arguments.

All this being said, the data always comes first. If any figures in a plex reference conflict with the input data, the initialized plex will be modified to a "best guess" value by MetriCal. An example of this would be changing the image size of a camera based on the observations in the dataset, but keeping any existing spatial constraints intact.

Plex Reference Application​

You can apply as many plex references as you would like to Init before running the command:

metrical init --reference-source $PLEX_ONE \
    --reference-source $URDF_ONE \
    --reference-source $PLEX_TWO \
    $DATA $INIT_PLEX

In this case, MetriCal will apply each Plex Reference in the order that they were provided. This also means that components and constraints that show up in multiple plex references may be overwritten as each reference is applied.

Overwrite Strategy​

By default, MetriCal will prevent you from overwriting a plex if one exists at the initialized plex path. However, this behavior can be changed depending on your operating environment by defining the --overwrite-strategy argument.

  • warn: Default value. Preserve existing output file if it exists. Exit with an error if an overwrite is attempted.
  • preserve: Preserve existing output file if it exists. Don't throw an error, just exit quietly.
  • replace: Replace existing output file completely.

Redefining this overwrite strategy can be helpful in manifest or scripting scenarios.

UUID Strategy​

Plexes assign UUIDs to every component in order to differentiate that component with another component of the same name/topic from another run, as they can represent different hardware sets or systems in real life. However, a few problems arise when considering using plex references:

  • If every plex reference has a different UUID to describe the same topics, what UUIDs should be used in the ultimate initialized plex?
  • What if my plex reference does reference the same hardware as my plex references?

MetriCal provides a configurable UUID strategy to answer this question.

  • inherit-existing: Default value. Inherit existing UUIDs from the existing initialized plex, if available. This will preserve the ability to re-run detections. If no existing initialized plex is available, this behaves like inherit-reference.
  • inherit-reference: Generate new UUIDs from reference sources, if available. Don't preserve existing UUIDs from an existing initialized plex. If there are no reference sources, this behaves like generate.
  • generate: Generate all new UUIDs regardless of the existing initialized plex or sources.

Examples​

Create a plex from input data​

Use OpenCV's Brown-Conrady model for all topics whose name starts with the substring /camera/.

metrical init --topic-to-model /camera/*:opencv-radtan $DATA $INIT_PLEX

Reference a "golden" plex from a previous calibration​

In this scenario, we're telling MetriCal to use a plex from a previous calibration as a starting point, but to assign brand new UUIDs to the initialized plex at the end. This can be handy in a production line scenario, where calibration from similar systems must be audited across their product lifecycle.

metrical init \
    --reference-source $GOLDEN_PLEX \
    --uuid-strategy generate \
    $DATA $INIT_PLEX

Arguments​

[DATASET]​

The dataset with which to calibrate, or the detections from an earlier run. Users can pass MCAP files (usually with an .mcap extension) or a top-level directory containing a set of nested directories for each topic

[INITIALIZED_PLEX]​

The initialized plex output from this step. Default: initialized-plex.json.

Options​

Global Arguments​

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

-p, --reference-source [REFERENCE_SOURCE]​

The path to a reference source, which informs Init mode of any known models, spatial constraints, or temporal constraints. This can be a MetriCal results file, a plex, or a URDF

-m, --topic-to-model​

A mapping of topic/folder names to models in the input plex. NOTE: All topics intended for calibration must be enumerated by this argument. If an initial plex is provided, any matching topic models in the plex will be overwritten.

Example: We would like the topic "camera_1" to be modeled using OpenCV's regular distortion model (aka Brown Conrady), and "camera_2" to be modeled using its fisheye model:

-m camera_1:opencv-radtan -m camera_2:opencv-fisheye

One may also use wildcards to designate many topics at a time:

-m /camera/\*:opencv-radtan

Available models​

Cameras​
Lidar​
IMU​
Local Navigation Systems​

-T, --remap-reference-component [REMAP_REFERENCE_COMPONENT]​

Remaps a component from the reference plex to a new topic name in the given dataset.

Can take a string of either format old_component_name:new_topic_name or old_component_uuid:new_topic_name.

--overwrite-strategy [OVERWRITE_STRATEGY]​

The strategy for overwriting an existing output plex.

Default: warn

Possible values:

  • warn: Preserve existing output file if it exists. Exit with an error if an overwrite is attempted
  • preserve: Preserve existing output file if it exists. Don't throw an error, just exit quietly
  • replace: Replace existing output file completely

--uuid-strategy [UUID_STRATEGY]​

The strategy for handling UUIDs in the output plex.

Default: inherit-existing

Possible values:

  • inherit-existing: Inherit existing UUIDs from the existing output plex, if available. This will preserve the ability to re-run detections. If no existing output plex is available, this behaves like inherit-reference.
  • inherit-reference: Generate new UUIDs from reference sources, if available. Don't preserve existing UUIDs from an existing output plex. If there are no reference sources, this behaves like generate.
  • generate: Generate all new UUIDs regardless of existing output or sources