> This page is for version 3.3.0 (default).
> For other versions, use one of these documentation indexes:
> - 3.3.0 (default): https://docs.nvidia.com/vss/3.3.0/llms.txt
> - Dev: https://docs.nvidia.com/vss/dev/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/vss/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/vss/_mcp/server.

# Getting Started

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](/system-components/calibration/auto-calibration/workflow-steps), [Custom Dataset](/system-components/calibration/auto-calibration/custom-dataset), and [Troubleshooting](/system-components/calibration/auto-calibration/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](/system-components/calibration/auto-calibration/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.

> **Note**
>
> **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](/vision-agent/agent-workflows/industry-specific-examples/warehouse-operations-blueprint/quickstart#configure-environment-settings) in the Warehouse Quickstart.

### 1. Authenticate with NGC

```bash
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](https://org.ngc.nvidia.com/setup) if needed. Do not print or commit the key.

### 2. Clone the VSS repository

```bash
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

```bash
cd deploy/docker/services/auto-calibration
```

The directory contains:

```text
compose.yml
ms/compose.yml
ui/compose.yml
```

### 4. Configure the VSS environment

Create `.env` in the current directory:

```dotenv
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](https://huggingface.co/facebook/VGGT-1B-Commercial) and place it in `${VSS_DATA_DIR}/auto-calib/vggt/`:

```bash
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

```bash
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

```bash
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:

```text
http://<HOST_IP>:<VSS_AUTO_CALIBRATION_HOST_PORT>
```

The UI is available at:

```text
http://<HOST_IP>:<VSS_AUTO_CALIBRATION_UI_HOST_PORT>
```

### 8. Stop the service

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

## Next Steps

* Follow the [Auto Calibration Workflow Steps](/system-components/calibration/auto-calibration/workflow-steps) for the complete 7-step UI workflow and screenshots.
* Follow [Custom Dataset](/system-components/calibration/auto-calibration/custom-dataset) for input videos, alignment data, lens distortion, and ground-truth requirements.
* Follow [Troubleshooting](/system-components/calibration/auto-calibration/troubleshooting) for common deployment and calibration failures.