metrical calibrate

Purpose

• Calibrate a multi-modal system based on pre-recorded data.
• Test new data against an existing calibration.
• 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 colourizing 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.

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

-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.

-f, --cache-filtered-data

Enable caching of filtered images. The application caches filtered images as pngs on disc in the default directory cached_data and in subdirectories corresponding to the component name as stored in the plex. This default directory can be overridden by using the --cache-dir option.

-F, --cache-dir <CACHE_DIR>

The output directory for cached filtered images. [default: "cached_data"]

-k, --outlier-filter

Detect outliers after calibration and recalibrate with outliers downweighted. By default, outliers won't be included in metrics output. That can be changed with the --metrics-with-outliers flag.

--metrics-with-outliers

If the outlier filter is enabled, this flag causes all measurements (including outliers) to be used in computing metrics.

-t, --stillness-threshold <STILLNESS_THRESHOLD>

The upper bound of the average flow to classify an image as still. This threshold is used for filtering data based on scene motion. This threshold applies to the average of the magnitudes of the flow field between subsequent images. 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.

--enable-ore-inference

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

The default behavior is to not infer object relative extrinsic constraints in the bundle adjustment. Pass this flag if object relative extrinsic constraints should be inferred.

-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 -v          \
    --output-json results.json \
    --render-results           \
    $DATA $PLEX $OBJSPC

---

2. Visualize the adjustment during calibration

Save the output to results.json.

metrical --render calibrate    \
    --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 --report-path metrical.log calibrate $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