Manifest Overview

The MetriCal manifest is a central configuration file that defines the workspace for your calibration tasks. It specifies the sensors, calibration targets, data sources, and various settings required for MetriCal to perform calibrations effectively.

Using a manifest allows you to:

• Define complex calibration setups involving multiple sensors and targets
• Reuse configurations across different calibration sessions
• Maintain consistency in calibration parameters and settings
• Verify the order of operations of your calibration setup

They're handy things, useful for development and production alike!

Manifest Creation with metrical new

You should never have to write a manifest from scratch! Use the metrical new command to create a new manifest with default settings, which you can then modify to suit your needs.

The Anatomy of a Manifest

There are two main sections to a MetriCal manifest: the Project and the Stages. Let's break down a simple example manifest to understand what's going on:

metrical.toml

# Project Metadata
#-------------------
[project]
name = "MetriCal Demo Manifest"
version = "15.0.0"
description = "Demo calibration manifest"
workspace = "/home/cal_engineer/metrical_workspace/"

# Project Variables
#-------------------
[project.variables.data-dir]
description = "The directory where our data and object space live"
value = "/my/data/dir"

[project.variables.object-space]
description = "Our object space file for this calibration"
value = "my_cal_objects.json"

[project.variables.dataset]
description = "Our dataset for this calibration"
value = "my_cal.mcap"

# Stages
#-------------------
[stages.first-stage]
command = "init"
dataset = "{{variables.data-dir}}/{{variables.dataset}}"
... # All of our init arguments go here
initialized-plex = "{{auto}}"

[stages.second-stage]
command = "calibrate"
dataset = "{{variables.data-dir}}/{{variables.dataset}}"
input-plex = "{{first-stage.initialized-plex}}"
input-object-space ="{{variables.data-dir}}/{{variables.object-space}}"
... # All of our calibration arguments go here
detections = "{{auto}}"
results = "{{auto}}"

Project Metadata

[project]
name = "MetriCal Demo Manifest"
version = "15.0.0"
description = "Demo calibration manifest"
workspace = "/home/cal_engineer/metrical_workspace/"

This holds metadata about the manifest, as well as the workspace path where all outputs will be stored. Unless otherwise directed, manifests will automatically create the workspace directory to hold all outputs; each stage's outputs will be stored in a subdirectory named after the stage.

Key	Description
name	The name of the project.
version	The version of the project. This is not tied to MetriCal's versioning, but can be used for your own tracking purposes.
description	A brief description of the project.
workspace	The path to the workspace directory where all outputs will be stored. This can be overridden in the Run command using the --workspace argument.

Project Variables

[project.variables.data-dir]
description = "The directory where our data and object space live"
value = "/my/data/dir"

[project.variables.object-space]
description = "Our object space file for this calibration"
value = "my_cal_objects.json"

[project.variables.dataset]
description = "Our dataset for this calibration"
value = "my_cal.mcap"

Manifests allow the user to define variables for use in the Manifest's Stages. Each variable can be referenced as an input to a manifest stage using the syntax {{variables.<var-name>}}. We'll see an example of this in the Stages section below.

Override Variables with --set

When running a manifest using the Run command, you can override any variable defined in the manifest using the --set argument. For example, to override the data-dir variable defined above, you could run:

metrical run /path/to/metrical.toml --set data-dir:/new/data/dir

Stages

[stages.first-stage]
command = "init"
dataset = "{{variables.data-dir}}/{{variables.dataset}}"
... # All of our init arguments go here
initialized-plex = "{{auto}}"

[stages.second-stage]
command = "calibrate"
dataset = "{{variables.data-dir}}/{{variables.dataset}}"
input-plex = "{{first-stage.initialized-plex}}"
input-object-space ="{{variables.data-dir}}/{{variables.object-space}}"
... # All of our calibration arguments go here
detections = "{{auto}}"
results = "{{auto}}"

Each stage in the manifest has both a name (first-stage, second-stage, whatever) and a command. From there, the stage inputs, config, and outputs are defined by that command's CLI arguments. If you don't know what a command's argument does, just run metrical <command> --help for the full details (or, uh, read these docs).

Stage Execution Order

Note that the order of execution is determined by the input and output dependencies of each stage, not the ordering in the manifest file itself. Manifests will not process if there is a cyclic dependency between stages or a missing input dependency.

The {{auto}} Keyword

It's common for stages to produce outputs that are then used as inputs to later stages. To make this easier, MetriCal supports the special {{auto}} keyword for stage outputs. When a stage output is set to {{auto}}, MetriCal will automatically generate an appropriate output file path within the workspace for that output. This is especially useful for outputs like initialized plexes, detections, and results files that are commonly passed between stages.

Note that you don't have to use {{auto}} for outputs; you can specify explicit paths if you prefer, and the manifest will use those instead.

Referencing Stage Outputs

Stages can reference the outputs of previous stages using the syntax {{<stage-name>.<output-name>}}. In the example above, the second-stage references the initialized-plex output of the first-stage using {{first-stage.initialized-plex}}. This allows for seamless chaining of stages where the output of one stage becomes the input to another.