Skip to navigation
System ComponentsCalibrationAuto Calibration

Getting Started

View as Markdown

This guide explains how to deploy and access the Auto Calibration microservice and user interface.

The detailed Auto Calibration workflow, input requirements, rectification, alignment, results, and troubleshooting content is documented in the Auto Calibration Workflow Steps, Custom Dataset, and Troubleshooting pages.

Prerequisites

Before using the VSS Auto Calibration service and UI, ensure you have:

  • x86_64 system
  • Ubuntu 24.04
  • NVIDIA GPU with hardware encoder (NVENC)
  • NVIDIA Driver 590 or newer
  • Docker configured to run without sudo
  • NVIDIA Container Toolkit
  • An NGC API key with access to the required VSS images

Required calibration inputs and detailed method-specific requirements are documented in Custom Dataset.

Deployment Steps (Docker Compose)

These steps deploy the Auto Calibration service using the VSS repository. They are separate from running Auto Calibration as a Warehouse Blueprint profile.

Running Auto Calibration as a Warehouse Blueprint profile

Auto Calibration can also be deployed as part of the Warehouse Blueprint with MODE=auto-calibration and BP_PROFILE=bp_wh_auto_calib. That profile starts the same vss-auto-calibration service and UI from the blueprint’s Compose stack, alongside the VIOS/VST services, rather than through the steps below. The blueprint profile deploys no sdr-controller, so the SDRC routing keys VST_USE_SDRC, STREAM_PROCESSOR_MODULE_ENDPOINT, and VST_NGINX_MODE must be commented out so the direct VST defaults in services/vios/vst.env apply. blueprint-deploy.sh comments them for you in the generated env file; with the direct docker compose command you must comment them yourself in industry-profiles/warehouse-operations/overrides.env. For the exact settings, see Configure Environment settings in the Warehouse Quickstart.

1. Authenticate with NGC

export NGC_CLI_API_KEY=<NGC_CLI_API_KEY>
export NGC_CLI_ORG='nvidia'
printf '%s' "${NGC_CLI_API_KEY}" | docker login nvcr.io -u '$oauthtoken' --password-stdin

Generate an API key from NGC Setup if needed. Do not print or commit the key.

2. Clone the VSS repository

git clone https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization.git
cd video-search-and-summarization
git checkout "v3.3.0"

3. Open the VSS Auto Calibration deployment directory

cd deploy/docker/services/auto-calibration

The directory contains:

compose.yml
ms/compose.yml
ui/compose.yml

4. Configure the VSS environment

Create .env in the current directory:

VSS_AUTO_CALIBRATION_HOST_PORT=8010
VSS_AUTO_CALIBRATION_UI_HOST_PORT=5000
VSS_APPS_DIR=/path/to/video-search-and-summarization/deploy/docker
VSS_DATA_DIR=/path/to/your/data_dir
HOST_IP=<HOST_IP_ADDRESS>
# Optional, uncomment and update this to support RTSP Stream input
# VIOS_BASE_URL=http://<VIOS_HOST_IP>:30888

Replace the paths and host address with your values. HOST_IP must be reachable from the browser.

This Compose deployment does not start VIOS. To use RTSP capture, deploy VIOS separately and set VIOS_BASE_URL to an endpoint reachable from the Auto Calibration container. Otherwise, use file upload.

5. Optional VGGT model setup

The Auto Calibration service can run the AMC method without VGGT support. To enable VGGT calibration, download the licensed VGGT model and place it in ${VSS_DATA_DIR}/auto-calib/vggt/:

mkdir -p "${VSS_DATA_DIR}/auto-calib/vggt"

For the default case, use vggt_1B_commercial.pt. To use any other model name, update VGGT_MODEL_PATH in .env to the new model’s full path inside the container: /tmp/vggt_model/<filename>.

You must accept the model license before downloading it.

6. Prepare the projects directory

mkdir -p "${VSS_APPS_DIR}/services/auto-calibration/projects"
if ! sudo -n true 2>/dev/null; then
  echo "sudo requires authentication; enter your password when prompted."
  sudo -v || { echo "sudo authentication failed. Verify sudo access, then retry." >&2; exit 1; }
fi
sudo chown -R 1000:1000 "${VSS_DATA_DIR}/auto-calib"
sudo chown -R 1000:1000 "${VSS_APPS_DIR}/services/auto-calibration/projects"

The Auto Calibration service stores project data in the projects directory and the containers use UID/GID 1000.

7. Start the VSS Auto Calibration service and UI

docker compose \
  --profile "vss-auto-calibration" \
  --profile "vss-auto-calibration-ui" \
  up -d

Wait for the service to be ready.

The microservice will be available at:

http://<HOST_IP>:<VSS_AUTO_CALIBRATION_HOST_PORT>

The UI is available at:

http://<HOST_IP>:<VSS_AUTO_CALIBRATION_UI_HOST_PORT>

8. Stop the service

docker compose \
  --profile "vss-auto-calibration" \
  --profile "vss-auto-calibration-ui" \
  down

Next Steps