Skip to main content
Version: 9.0

MetriCal banner

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.

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) 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>" \
    "$@";
    }

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 virtual directory /datasets within the docker container. All subsequent MetriCal commands are run as if from that virtual /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.

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/config.toml 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.14.0​

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

# via pip
pip install rerun-sdk~=0.14

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

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