Skip to main content
Version: 13.2

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 an argument to the metrical command.

metrical_runner.sh
metrical --license="key/<your_key>" calibrate ...
For Docker

This command line argument can be included directly in the metrical shell function by adding it before the "$@" line of your alias.

~/.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 \
    # Note the following line!
    --license="key/<your_key>" \
    "$@";
    }

2. Environment Variable​

Provide the key as a string in the environment variable TANGRAM_VISION_LICENSE.

metrical_runner.sh
TANGRAM_VISION_LICENSE="key/<your_key>"
metrical calibrate ...
For Docker

Using Environment Variables in Docker​

If running MetriCal via Docker, 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:

~/.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 \
    # 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. This key should be placed in your config directory at ~/.config/tangram-vision/config.toml.

~/.config/tangram-vision/config.toml
license = "key/{your_key}"
For Docker

Using a Config File in Docker​

To use a config file in Docker, 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.

~/.bashrc
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 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.

For Docker

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:

~/.bashrc
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 \
    "$@";
    }

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.