metrical init

Purpose

• Create a plex from a dataset.
• Modify an existing plex based on a dataset.

Usage

metrical init [OPTIONS] --topic-to-model <topic_name:model> <INPUT_DATA_PATH> [OUTPUT_JSON]

Description

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 Initial Plex! MetriCal will use this plex as the initialization to the Calibrate mode.

Init can also take a plex as an input to seed its output. It will run the same inference process as before, but keep any information that is already specified in the plex that does not conflict with that input data. An example of this behavior would be changing the image size of a camera based on the observations in the dataset, but keeping any existing spatial constraints intact.

Arguments

[INPUT_DATA_PATH]

Input data path for this initialization. MetriCal accepts a few data formats:

• Ros1 bags, in the form of a .bag file.
• Ros2 bags, in the form of a .mcap file.
• Folders of observations.

[OUTPUT_JSON]

The output JSON in which to save the final plex. [default: plex.json]

Options

-p, --plex-path <PLEX_PATH>

The plex.json used as a starting point.

-m, --topic-to-model <topic_name: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 mode:

-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

Camera Models:

• no_distortion
• pinhole_with_brown_conrady
• pinhole_with_kannala_brandt
• opencv_radtan
• opencv_fisheye
• opencv_rational
• eucm
• double_sphere

LiDAR Models:

• no_offset
• per_beam_offset_<8|16|32|64|128|some int>

IMU Models:

• consumer_grade

-s, --preset-device <PRESET_DEVICE>

A list of devices that Tangram has documented as useful calibration presets. Specify a device and follow it with a list of topics or folder names that are part of that device type. This flag may be repeated for multiple devices.

When a preset device is assigned, Init will print out helpful pointers about calibrating that device to the console. It will also issue warnings when streams aren't correctly configured for that device's recommended calibration procedure, a la:

👉 RealSense 435 Calibration Pointers (if flashing to device):
    - IR camera settings: Y16 format (16-bit), resolution of 1280x800 @ 15fps
    - Color camera settings: YUY2 format, resolution of 1920x1080 @ 15fps
    - Pause often during capture. The cameras do not temporally sync when streaming the above settings.
    - Capture features in the entire field of view of the image.
For more, visit https://dev.intelrealsense.com/docs/d400-series-custom-calibration-white-paper
...
...
RealSense Left IR stream cam_0_ir_1 is not Y16 format! This means that it's already rectified;
make sure to assign this topic the `no_distortion` model.

Sometimes, a different configuration can be desireable; for instance, your RealSense calibration might be fine, and you just want to register it to another sensor. These warnings are just MetriCal's way of making sure you know what you're doing.

Example: There are three streams, ir_left, ir_right, and visible, which all belong to a RealSense 435. Indicate to Plex Smith that this is the case with the following argument:

-s RealSense435:["ir_left", "ir_right", "visible"]

Order matters; reference the available models below for the proper order. If there is no available topic for a stream, indicate this with a _:

-s RealSense435:["ir_left", _, "visible"]

Available devices:

• RealSense415: [left ir, right ir, color]
• RealSense435: [left ir, right ir, color]
• RealSense435Imu: [left ir, right ir, color, imu]

Examples

1. Create a fresh 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 $OUTPUT_PLEX

2. Use an old plex to seed a new plex

metrical init --plex_path $INPUT_PLEX $DATA $OUTPUT_PLEX

3. Use a preset device to seed a new plex

In this case, we have two RealSense 435 with two ROS streams each: /cam[n]/ir_left and /cam[n]/ir_right. We only have two of its three streams, so we use _ to designate the missing camera streams from the visible (RGB) cameras.

metrical init \
    -s RealSense435:["/cam0/ir_left", "/cam0/ir_right", _] \
    -s RealSense435:["/cam1/ir_left", "/cam1/ir_right", _]  \
     $DATA $OUTPUT_PLEX