metrical calibrate

Purpose

• Calibrate a multi-modal system based on pre-recorded data.
• Visualize the calibration data capture, adjustment, and results.

Usage

metrical calibrate [OPTIONS] <INPUT_DATA_PATH> <PLEX_PATH> <OBJECT_SPACE_PATH>

Description

The Calibrate command runs a full bundle adjustment over the input calibration data. It requires three main arguments:

• The input data
• An inital plex. This represents a naive guess at the state of your system.
• An object space file. This tells MetriCal what fiducials, targets, or other features to look for during calibration.

We mean it when we say this runs a full bundle adjustment. MetriCal will optimize both the plex values (the calibration of your system, effectively) and the object space values. This means that MetriCal is robust to bent boards, misplaced targets, etc. All of these values will be solved for during the adjustment, and your calibration results will be all the better for it.

We use ANSI terminal codes for colorizing output according to an internal assessment of metric quality. Generally speaking:

• Cyan: spectacular
• Green: good
• Orange: okay, but generally poor
• Red: bad

Note that these judgements are applied internally to the software and have limits that may change release-to-release. We advise that you determine your own internal limits for each independent metric.

Image Motion Filtering

Calibrate and Evaluate modes both run a motion filter over any and all cameras in the input dataset. This filter removes any features that might be affected by motion blur, rolling shutter, false detections, or other artifacts. This is a critical step in the calibration process, as it ensures that the data used for camera calibration is the best we can get.

The motion filter is based on the average flow of detected image features between subsequent frames. Background motion is not considered, so you can still use this filter when taking data in a busy place. The default value for the stillness threshold is 1 pixel/frame, but this can be adjusted using the --stillness-threshold flag.

The motion filter also works at the sync group level, not component-by-component. You can see how this decision affects the filter's behavior over time. If one component is moving, the motion filter labels all other components as moving as well, regardless of their actual detected motion status. This decision makes intuitive sense: in a calibration dataset, all components (or all object spaces) should be moving together.

If you have a dataset that is a series of snapshots, rather than continuous motion, you can disable the motion filter using the --disable-filter flag.

Extracting Optimized Values from a Results JSON

There is a lot of data in a results JSON output from MetriCal. Luckily, it's all JSON, and it's fairly easy to pick apart. Use jq to extract this data into its own file for easy analysis and comparison to the original inputs.

Install jq using apt:

sudo apt install jq

Then use jq to extract the relevant optimized data.

jq .plex results.json > optimized_plex.json
jq .object_space results.json > optimized_obj.json

Arguments

[INPUT_DATA_PATH]

Input data path for this calibration. 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, as a flat directory of data. The folder passed to MetriCal should itself hold one folder of data for every component.

In all cases, the topic/folder name must match a named component in the plex in order to be matched correctly. If this is not the case, there's no need to edit the plex directly; instead, one may use the --topic_to_component flag.

[PLEX_PATH]

The plex.json used as a prior for MetriCal's adjustment.

[OBJECT_SPACE_PATH]

A path pointing to a description of the object space for the adjustment. This should be a JSON file.

Options

Calibrate mode supports all global options, as well as the following:

-i, --interactive

Enable interactive mode, which checks heuristics for each component and confirms if the user wishes to continue the bundle adjustment with the input data.

When interactive mode is used, MetriCal runs data syncing, filtering, and detection, but then halts its processes to allow the user to review the current progress and state. This is an opportunity for a user to check whether the input data meets certain quality thresholds, such as feature coverage or proper synchronization between components.

If everything is satisfactory, the user must type y to continue calibration. Otherwise, MetriCal will exit early, and no output will be produced.

-d, --disable-filter

Disable data filtering based on scene motion. This is useful for datasets that are a series of snapshots, rather than continuous motion.

-t, --stillness-threshold <STILLNESS_THRESHOLD>

This threshold is used for filtering data based on detected feature motion in the image. An image is considered "still" if the average delta in features between subsequent frames is below this threshold. The units for this threshold are in pixels/frame. [default: 1]

-o, --output-json <OUTPUT_JSON>

The output path to save the final JSON output of the program. [default: results.json]

-x, --max-iterations <MAX_ITERATIONS>

The max number of iterations for each phase in the bundle adjustment.

-T, --topic-to-component <topic_name:component_name>

A mapping of ROS topic/folder names to component names/UUIDs in the input plex.

MetriCal only parses data that has a topic-component mapping. Ideally, topics and components share the same name. However, if this is not the case, use this flag to map topic names from the dataset to component names in the plex.

-p, --preserve-input-constraints

Preserve the spatial constraints that were input for this dataset.

The default behavior is to discard any constraints that were not derived from the data (e.g. spatial constraints from sync groups) or optimized. Pass this flag if the output plex should include any constraints that were input but not found or optimized.

--disable-ore-inference

Disable inference of object relative extrinsic constraints in the bundle adjustment.

The default behavior is to infer object relative extrinsic constraints in the bundle adjustment. Pass this flag if object relative extrinsic constraints should not be inferred; this may save a substantial amount of time in datasets using many object spaces.

-v, --render

Whether to visualize the current command using Rerun.

--render-socket <RENDER_SOCKET>

The web socket address on which Rerun is listening.

This should be an IP address and port number separated by a colon, e.g. --render-socket="127.0.0.1:3030". By default, Rerun will listen on socket host.docker.internal:9876.

When running Rerun from its CLI, the IP would correspond to Rerun's --bind option and the port would correspond to its --port option.

Examples

1. Run a calibration, and render the calibration process and results

Save the output to results.json.

metrical calibrate             \
    --output-json results.json \
    --render-results           \
    $DATA $PLEX $OBJSPC

---

2. Visualize the adjustment during calibration

Save the output to results.json.

metrical calibrate             \
    --render                   \
    --output-json results.json \
    $DATA $PLEX $OBJSPC

---

3. Remap topics to different components in a plex

With the --topic-to-component flag, you can map topics to component names or UUIDs in the input plex. This prevents laborious hand-tuning of a plex JSON whenever a dataset is recorded with a different topic name.

For example, if we called our folder camera_1 and that corresponded to some component named ir_SN5XXX in the plex, then we could do the following:

metrical calibrate                           \
    --topic-to-component camera_1:ir_SN5XXX  \ # our corrected topic-component relation
    --output-json results.json               \ # the output file
    $DATA $PLEX $OBJSPC

---

4. Save calibration log output

Log output from the program is output on stderr. If you want to record this for later, you can actually save a log by using the --report-path flag. This will save a .log file and, if possible, a HTML version of the log as well.

metrical calibrate --report-path metrical.log $DATA $PLEX $OBJSPC

---

5. Disable the motion filter for motion-heavy datasets

By default, MetriCal will run a motion filter over the input dataset and remove images with too much motion blur, or where it appears that relative motion was too large. For observation streams with inconsistent or infrequent observations, this can result in filtering almost every image! It can also be a sign of malformed timestamps.

Filtering is recommended when running a dataset with generally quick observation frequencies (>15Hz) and consistent timestamps. Otherwise, you should disable the filter with the --disable-filter flag.

metrical calibrate --disable-filter $DATA $PLEX $OBJSPC