Skip to main content
Version: dev-latest

MetriCal Command: Plex Add

Usage​

Plex Add - CLI Example
metrical plex add [OPTIONS] <SUBCOMMAND> [PLEX_OR_RESULTS_PATH]
Plex Add - Manifest Example (component)
command = "plex-add"
subcommand = "component"
input-plex = "input.json"
name = "/camera/1"
model = "opencv-radtan"
output-plex = "{{auto}}"

Purpose​

metrical plex add adds a new element to an existing Plex. It supports four subcommands, each adding a different kind of element:

  • component — Adds a new sensor component with a default intrinsics model.
  • spatial-constraint (alias: spatial) — Adds a new default spatial constraint between two components.
  • temporal-constraint (alias: temporal) — Adds a new default temporal constraint between two components.
  • formation — Adds a new named group of components.

By default, plex add will refuse to overwrite an element that already exists. Use --force to override this behaviour.

Examples​

Add a camera component to a Plex​

metrical plex add component /camera/1 opencv-radtan input.json -o output.json

Add a spatial constraint between two components​

metrical plex add spatial-constraint --from /camera/1 --to /imu input.json -o output.json

Force-overwrite an existing constraint​

metrical plex add --force spatial-constraint --from /camera/1 --to /imu input.json -o output.json

Add a formation grouping two cameras​

metrical plex add formation stereo_pair -C /camera/left -C /camera/right input.json -o output.json

Add a formation using a glob pattern​

metrical plex add formation all_cameras --glob -C '*camera*' input.json -o output.json

Build a Plex from scratch using pipes​

metrical plex new \
    | metrical plex add component /camera/left opencv-radtan \
    | metrical plex add component /camera/right opencv-radtan \
    | metrical plex add spatial-constraint --from /camera/left --to /camera/right \
    -o my_plex.json

Options​

Global Arguments​

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

-f, --force​

Forcibly overwrite any pre-existing components, constraints, or formations that already exist in the Plex with a new default version. Without this flag, the command will fail if the element to be added already exists.

-o, --output [OUTPUT]​

The path to output the resulting Plex. If omitted, MetriCal will write the Plex to stdout.

Subcommands​

component <NAME> <MODEL>​

Adds a new component to the Plex with a default intrinsics model.

Arguments​

NAME​

The topic name for the new component (e.g., /camera/1).

MODEL​

The intrinsics/component model. See the full list of available models in the plex learn documentation.

spatial-constraint (alias: spatial)​

Adds a new default spatial constraint (i.e., the extrinsic relationship) between two existing components. The command will fail if the relationship already exists in the Plex (regardless of direction) unless --force is specified.

Options​

--from [FROM]​

The component whose coordinate frame we are transforming from. Accepts a topic name or UUID.

--to [TO]​

The component whose coordinate frame we are transforming into. Accepts a topic name or UUID.

temporal-constraint (alias: temporal)​

Adds a new default temporal constraint (i.e., the clock synchronization relationship) between two existing components. The command will fail if the relationship already exists in the Plex (regardless of direction) unless --force is specified.

Options​

--from [FROM]​

The component whose clock we are transforming from. Accepts a topic name or UUID.

--to [TO]​

The component whose clock we are transforming into. Accepts a topic name or UUID.

formation <NAME>​

Adds a new named formation (a labelled group of components) to the Plex. Formations can be associated with specific metrics output by MetriCal, or can serve a purely organizational purpose.

Unlike constraints, formation names do not need to be unique within a Plex.

Arguments​

NAME​

The name for the new formation.

Options​

-C, --component [COMPONENT]​

A component to add to the formation. All specified components must already exist in the Plex and must not already belong to a formation of the same name. Repeat this flag for multiple components.

-G, --glob​

Treat the component identifiers provided via -C/--component as glob patterns rather than exact matches. For example, *camera* will match both /camera/1 and /camera/2.