Introduction + Setup

MetriCal is a sophisticated global bundle adjustment software specifically built to give accurate, precise, and expedient calibration results for multimodal sensor suites. Its easy-to-use interface and detailed metrics enable enterprise-level autonomy at scale.

MetriCal Version 7.0.0

This documentation was written based off of MetriCal v7.0.0. There is no guarantee of compatibility with older versions.

Capabilities

• Process camera + lidar + IMU streams simultaneously.
• No restriction to the number of streams processed.
• Get visual and quantitative feedback on data input quality and output metrics.
• Process ROSbags, MCAP files, and folder datasets.
• Convert a calibration file into a URDF file for easy integration into ROS.
• Use a variety of fiducials and targets.
• Create pixel-wise lookup tables for both single camera correction and stereo pair rectification.

Releases and Updates

Check out the MetriCal Gitlab repository to see releases, planned features and fixes. If you have a suggestion for MetriCal functionality, or see something missing, let us know in the Issues there! You might find it's already listed, in which case you should leave a 👍 on the issue so that we can prioritize its addition.

---

Setup

Docker Install

MetriCal is a Docker image. If you do not have Docker installed, follow the instructions to do so at https://docs.docker.com/get-docker/

Get A License

Running MetriCal requires a license key. Get a trial of MetriCal by contacting the Tangram Vision team.

Download MetriCal via Docker

docker pull tangramvision/cli:latest

You now have a MetriCal instance on your machine!

MetriCal Docker Alias

Throughout the documentation, you will see references to metrical in the code snippets. This is a named bash function describing a larger docker command. For convenience, it can be useful to include that function (outlined below) in your script or shell config file (e.g. ~/.bashrc) file:

metrical() {
    docker run --rm --init --user="$(id -u):$(id -g)" \
    --volume="$MOUNT":"/datasets" \
    --workdir="/datasets" \
    --add-host=host.docker.internal:host-gateway \
    tangramvision/cli:latest \
    --license="key/<your_key_here>" \
    "$@";
    }

...where $MOUNT is the directory with all of your datasets. Now you should be able to run metrical wherever!

---

Licensing

Running MetriCal requires a license key. Get a trial of MetriCal by contacting the Tangram Vision team.

MetriCal keys are assigned by user, not by machine. This means that a license key may be used on any machine, provided it is connected to the internet and may access Tangram Vision servers for authentication.

Providing a License Key

MetriCal looks for license keys in 3 places, in this order:

1. Command Line Argument

Provide the entire key as a string before the command you would like to run, since it's a global argument.

metrical --license="key/<your_key_in_full>" calibrate ...

2. Environment Variable

If you wish to provide the environment variable via an env file or via an export in your local shell, please see the examples in the docker run documentation (https://docs.docker.com/engine/reference/commandline/run/#env).

docker run --rm --init \
  ...
  -e TANGRAM_PLATFORM_LICENSE=key/{your_key} \
  tangramvision/cli:latest "$@"

3. Config File

The config file is a TOML file with a single top-level license key:

license = "key/{your_key}"

To use a config file, you’ll need to modify the metrical script by mounting the config file to the expected location. Use the following snippet, making sure to update path/to/file to point to your config file.

# If you're providing the --user flag to the `docker run` command
docker run --rm --init \
  ...
  --volume=path/to/config.toml:/.config/tangram-vision/config.toml:ro \
  tangramvision/cli:latest "$@"

# If you're NOT providing the --user flag to the `docker run` command
docker run --rm --init \
  ...
  --volume=path/to/config.toml:/root/.config/tangram-vision/config.toml:ro \
  tangramvision/cli:latest "$@"

Revoking a License

Revoke license keys on the Account or Group page of the Hub. For more details, see the Hub Licenses documentation.

Generating New Licenses

Generate new license keys on the Account or Group page of the Hub. For more details, see the Hub Licenses documentation.

Using Existing Licenses

If you do not have an active subscription, existing license keys will be disabled. Using a disabled license with the CLI will result in a message like the following:

This license is suspended because your subscription is invalid or has been put on hold. If you believe this is in error, please contact support@tangramvision.com.

Please visit the Billing page and activate your subscription in order to enable existing licenses so they will work with the CLI again.

---

Rendering via Rerun

MetriCal's Calibrate and Evaluate modes have a render option (--render or -v) that allows you to inspect the adjustment and visualize results using Rerun.

For those new to Rerun, we suggest going through their wonderful documentation: https://www.rerun.io/docs/getting-started/viewer-walkthrough

Downloading Rerun v0.8.0

Rerun is a standalone process, and MetriCal is currently on v0.8.0. It can be installed using pip or cargo.

# via pip
pip install rerun-sdk=0.8.0

# via cargo
cargo install rerun-cli --version 0.8.0

Start a Rerun rendering server with the rerun command in a separate terminal.

Configuring Rerun

You might have noticed this line in the recommended Docker invocation of MetriCal:

...
--add-host=host.docker.internal:host-gateway \
...

This tells docker to allow your host machine to act as a gateway for data transfer. MetriCal sends visualization data to host.docker.internal:9876 in the docker container, and this option will forward that data to localhost:9876 on your host machine, where the Rerun Viewer listens by default.

---

Logging

MetriCal uses the log crate to produce logs at various levels of priority. Users can set the log level by modifying the docker CLI command that calls MetriCal:

docker run --rm --init \
  ...
  -e RUST_LOG=error \
  tangramvision/cli:latest "$@"

The available log levels, from least to most verbose, are

error → warn → info → debug → trace