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.

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.

...and so much more!

Releases and Updates

MetriCal is updated regularly based on feedback from customers. We encourage you to keep track of these releases via the Releases and Changelogs page, or to subscribe to our newsletter for updates.

Note that this documentation is versioned, so you can always find information that matches what you're using. The Dev releases are documented under the "Next" version. Access different versions via the navigation bar.

All of the schema, examples, and object space template code is available in the MetriCal Sensor Calibration Utilities repository. This repository is also versioned, so you can find and use example code matching whatever version of MetriCal you're using.

---

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

There are two types of MetriCal releases. All releases can be found listed on Docker Hub.

Stable Release

Stable releases are an official version bump for MetriCal. These versions are verified and tested by Tangram Vision and MetriCal customers. They are guaranteed to have a stable API and follow SemVer. Find documentation for these releases under their version number in the nav bar.

Stable releases can be pulled using the following command:

docker pull tangramvision/cli:latest

Install a specific version with a command like:

docker pull tangramvision/cli:7.0.0

Dev Release

Dev releases are, as the name implies, created as MetriCal develops. They are cut automatically whenever a commit is pushed to the main branch of Tangram Vision's internal repositories. There is no guarantee of any API compatibility between Dev releases, or Dev and Stable releases. The documentation for Dev releases is kept as version "Next".

Pull down the latest dev release with this command:

docker pull tangramvision/cli:dev-latest

Install a specific dev release with a command like:

docker pull tangramvision/cli:7.0.1-dev.20240116224249.67029fc9

This is generally not recommended; if you're on Dev, sticking to dev-latest is probably your best bet.

---

With that, you should now have a MetriCal instance on your machine! We'll assume the Stable release (tangramvision/cli:latest) for the rest of the introduction.

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):

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

Now you should be able to run metrical wherever!

--volume and --workdir

The --volume flag syntax represents a bridge between the host machine and the docker instance. If your data is contained within the directory /home/user/datasets, then you would replace $MOUNT with /home/user/datasets.

--workdir indicates that we're now primarily working in the /datasets directory within the docker container. All subsequent MetriCal commands are run as if from that /datasets directory.

---

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 or offline-licensing is configured (see further below).

Using a License Key

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

1. Command Line Argument

Provide the key as a string before the command you would like to run, since it's a global argument. This command line argument can be included directly in the metrical shell function shown above by adding it before the "$@" line.

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

2. Environment Variable

Provide the key as a string in the environment variable TANGRAM_VISION_LICENSE. Recall that MetriCal runs in a docker container, so the environment variable must be set inside the container. The docker run documentation shows various methods for setting environment variables inside a container.

One example of how you can do this is to add an --env flag to the docker run invocation inside the metrical shell function that was shown above, which would then look like this:

metrical() {
    docker run --rm --tty --init --user="$(id -u):$(id -g)" \
    --volume="$MOUNT":"/datasets" \
    --volume=metrical-license-cache:/.cache/tangram-vision \
    --workdir="/datasets" \
    --add-host=host.docker.internal:host-gateway \
    # Note the following line!
    --env=TANGRAM_VISION_LICENSE="key/<your_key>" \
    tangramvision/cli:latest \
    "$@";
    }

3. Config File

Provide the key as a string in a config TOML file, assigned to a top-level license key.

license = "key/{your_key}"

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

metrical() {
    docker run --rm --tty --init --user="$(id -u):$(id -g)" \
    --volume="$MOUNT":"/datasets" \
    --volume=metrical-license-cache:/.cache/tangram-vision \
    # Note the following line!
    --volume=path/to/config.toml:/.config/tangram-vision/config.toml:ro \
    --workdir="/datasets" \
    --add-host=host.docker.internal:host-gateway \
    tangramvision/cli:latest \
    "$@";
    }

Using a License Key Offline

MetriCal can validate a license via a local license-cache file, ensuring that internet hiccups don't cause license validation failures that interrupt critical calibration processes.

In order to use MetriCal without an active internet connection, you must:

1. Include an additional volume mount when running the docker container, so a license-cache file can persist between MetriCal runs. Update the metrical shell function to include the --volume=metrical-license-cache:... line shown below:

   metrical() {
       docker run --rm --tty --init --user="$(id -u):$(id -g)" \
       --volume="$MOUNT":"/datasets" \
       # The following line enables offline licensing
       --volume=metrical-license-cache:/.cache/tangram-vision \
       --workdir="/datasets" \
       --add-host=host.docker.internal:host-gateway \
       tangramvision/cli:latest \
       "$@";
       }

2. Run any MetriCal mode with an active internet connection once. (This can be as simple as running metrical calibrate foo bar baz, even if foo, bar, and baz files do not exist.) This will create a license-cache file that is valid (and enables offline usage of MetriCal) for 1 week. Every time MetriCal is run with an active connection, the license-cache file will be refreshed and valid for 1 week. If the license-cache file hasn't been refreshed in more than a week and MetriCal is run offline, it will exit with a "License-cache file is expired" error.

Managing Licenses

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

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. Please reach out to support@tangramvision.com for help.

---

Rendering via Rerun

MetriCal's Calibrate, Evaluate, and Display modes can all interact with Rerun to visualize different parts of the calibration process.

Downloading Rerun v0.18

Match Versions!

Rerun is a great tool, but it's still in heavy development, and there's no guarantee of backwards compatibility. It's important to ensure that the Rerun version you're running matches the version used in the MetriCal binary. Otherwise, data sent from MetriCal may not be rendered correctly, or at all.

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

# via pip
pip install rerun-sdk~=0.18

# via cargo
cargo install rerun-cli --version ^0.18

Start a Rerun rendering server with the rerun command in a separate terminal. We recommend running with a memory limit of 1GB to avoid any potential memory issues:

rerun --memory-limit=1GB

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 passing verbosity flags to any MetriCal command:

• -vv: Trace
• -v: Debug
• default: Info
• -q: Warn
• -qq: Error
• -qqq: Off

Some outputs will change slightly depending on the verbosity level to avoid spamming your console.