Consolidate Object Spaces Mode

Purpose

• Combine multiple object spaces from a calibration result into a single, unified object space.
• Process object space transformations using object relative extrinsics (OREs) to create a consolidated target configuration.

Usage

metrical consolidate-object-spaces [OPTIONS] <OBJECT_SPACE_OR_RESULTS_PATH>

Concepts

The Consolidate Object Spaces command takes a results file or an object space file that contains object relative extrinsics (OREs) and uses those transformations to combine all object spaces into a single, unified object space.

This command is particularly useful for calibration scenarios with minimal sensor or target overlap. In such cases, users would typically:

1. Run an initial "survey" calibration to determine object relative extrinsics
2. Use this command to consolidate the results into a single object space
3. Run a full calibration using the consolidated object space
4. Use this reference in subsequent calibrations to ensure consistency

By consolidating object spaces, you can effectively combine calibration data from multiple scenes or captures, even when there isn't significant overlap between all sensors.

The ability of MetriCal to consolidate object spaces depends on the presence of object relative extrinsics in the source object space or results file. Object space files are usually created manually with basic target parameters (type, width, height, marker size, etc.) but often without any extrinsics. Results files, on the other hand, are generated by MetriCal during calibration and typically contain extrinsics of targets that are observed simultaneously by one or more sensors in the dataset. It is these extrinsics that MetriCal uses to consolidate object spaces, and thus consolidation is dependent on the data capture process.

Targets will be grouped together based on the simultaneous target observations in the data. MetriCal will stitch together target groups that were not directly observed together, if there is a chain of mutual observations connecting them. So if we see target A and B together in some images, and targets B and C together in other images, MetriCal can infer the relationship between A and C, even if they were never observed together. If there are no mutual observations of a target, it will be left unconsolidated. Also it's possible to have multiple disjoint groups of consolidated targets if there are no mutual observations connecting them.

Examples

Consolidate object spaces from a calibration result, visualizing the result

metrical consolidate-object-spaces \
    --output-path consolidated.json \
    --render \
    results.json

Use the consolidated object space in a subsequent calibration

After creating a consolidated object space, you can use it in your calibration:

metrical calibrate \
    --output-json final_results.json \
    $DATA $PLEX consolidated.json

Force overwrite of an existing consolidated object space file

metrical consolidate-object-spaces \
    --overwrite-consolidated-objects \
    --output-path consolidated.json \
    results.json

Arguments

[OBJECT_SPACE_OR_RESULTS_PATH]

A path pointing to a description of the object space or a MetriCal results JSON file. For this command to work effectively, the input file should contain object relative extrinsics that relate multiple object spaces together.

Options

Universal Options

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

-o, --consolidated-object-space-path [CONSOLIDATED_OBJECT_SPACE_PATH]

Default: consolidated_objects.json

The output path to save the consolidated object space, in JSON format. If a directory is provided, the file will be created as "consolidated_objects.json" within that directory.

-y, --overwrite-consolidated-objects

Default: false

Overwrite an existing consolidated object space file if it exists at the specified location. If this flag is not set and the output file already exists, the operation will fail with an error.

-r, --render

Default: false

Render the consolidated object space in Rerun

--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. If running locally (not via Docker), Rerun's default port is 127.0.0.1:9876 When running Rerun from its CLI, the IP would correspond to its --bind option and the port would correspond to its --port option.