amc-setup-calibration-stack

スキル：AutoMagicCalib のリリースコンテナを起動する

リリースコンテナから AutoMagicCalib のマイクロサービスと UI をセットアップします。AMC のチェックアウト先を解決し、NGC に認証し、必要に応じて VGGT をダウンロードし、Docker Compose を設定してサービスを起動し、準備状況を確認します。

前提条件

• Docker と Docker Compose がインストールされていること
• NVIDIA Docker Runtime が設定されていること（GPU サポート用）
• ディスク上に auto-magic-calib リポジトリがあること。ステップ 0b で、現在のリポジトリ、DeepStream の tools/auto-magic-calib、DEEPSTREAM_REPO_ROOT、または ~/auto-magic-calib を解決します。いずれも見つからない場合は、https://github.com/NVIDIA-AI-IOT/auto-magic-calib をクローンする前に確認します。
• NVIDIA コンテナレジストリにアクセスできる NGC アカウント
• sudo なしで Docker を実行できること。続行前に docker ps で確認してください。

手順

ステップ 0：sudo なしで Docker を実行できることを確認する

docker ps

• 成功した場合 → 続行します。
• 「permission denied」で失敗した場合 → ユーザーは docker グループに所属していません。次のコマンドを実行するようユーザーに依頼してください。

  sudo usermod -aG docker $USER && newgrp docker
  

  次に、続行する前に docker ps が動作することをユーザーに確認してください。

エージェント向けの注意：エージェントのサンドボックス内から docker ps を実行できない場合は、先に docker ps が sudo なしで動作することをユーザーに確認してください（例：「docker ps が sudo なしで実行できることを確認していただけますか？」）。

ステップ 0b：リポジトリのチェックアウト先を解決する

このスキルでは、AMC リポジトリのアセット（compose/、サンプルデータ、models/）が必要です。まず既存のチェックアウトを解決します。~/auto-magic-calib にクローンする前に確認してください。

REPO_URL="https://github.com/NVIDIA-AI-IOT/auto-magic-calib.git"
DEFAULT_CLONE_DIR="$HOME/auto-magic-calib"
CURRENT_GIT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"

is_amc_checkout() {
  [ -n "$1" ] \
    && [ -f "$1/README.md" ] \
    && grep -q "AutoMagicCalib" "$1/README.md" 2>/dev/null \
    && [ -f "$1/compose/compose.yml" ] \
    && grep -q "auto-magic-calib-ms" "$1/compose/ms/compose.yml" 2>/dev/null \
    && grep -q "auto-magic-calib-ui" "$1/compose/ui/compose.yml" 2>/dev/null
}

REPO_ROOT=""
for candidate in \
  "$CURRENT_GIT_ROOT" \
  "${CURRENT_GIT_ROOT:+$CURRENT_GIT_ROOT/tools/auto-magic-calib}" \
  "${DEEPSTREAM_REPO_ROOT:+$DEEPSTREAM_REPO_ROOT/tools/auto-magic-calib}" \
  "$PWD/tools/auto-magic-calib" \
  "$DEFAULT_CLONE_DIR"; do
  if is_amc_checkout "$candidate"; then
    REPO_ROOT="$candidate"
    echo "✓ Using auto-magic-calib checkout: $REPO_ROOT"
    break
  fi
done

if [ -z "$REPO_ROOT" ]; then
  if [ -n "$CURRENT_GIT_ROOT" ] && [ -d "$CURRENT_GIT_ROOT/tools/auto-magic-calib" ]; then
    echo "Found $CURRENT_GIT_ROOT/tools/auto-magic-calib, but it is not an initialized AMC checkout."
    echo "If running from the DeepStream repository root:"
    echo "  git submodule update --init tools/auto-magic-calib"
  fi

  # Nothing usable on disk — STOP and ask the user for confirmation using the
  # host's question mechanism; if none is available, ask in chat and wait.
  # Do NOT clone silently from this block or clone over a tracked submodule path.
  echo "No usable auto-magic-calib checkout found. Ask the user for confirmation:"
  echo "  Clone $REPO_URL into $DEFAULT_CLONE_DIR? [y/N]"
  echo "On 'y' — run: git clone \"$REPO_URL\" \"$DEFAULT_CLONE_DIR\""
  exit 1
fi

cd "$REPO_ROOT"
export REPO_ROOT
echo "REPO_ROOT=$REPO_ROOT"

エージェント向けの注意：ユーザーに知らせずにクローンしないでください。初期化済みの DeepStream tools/auto-magic-calib を優先し、そのサブモジュールのパスにクローンしないでください。存在するものの空の場合は、git submodule update --init tools/auto-magic-calib を実行するようユーザーに依頼してください。別の AMC パスが指定されている場合は、それを尊重してください。

ステップ 0c：Python venv をインストールする（新しいシステムのみ）

新しいシステムでは、pip と python3-venv が利用できない場合があります。まず、次のコマンドでインストールしてください。

# Create a venv for HuggingFace CLI (project-local preferred)
REPO_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
HF_VENV="${REPO_DIR}/venv"
python3 -m venv "$HF_VENV" 2>/dev/null || {
  echo "ERROR: python3-venv not available." >&2
  echo "Install it manually: sudo apt install -y python3-venv python3-pip" >&2
  exit 1
}

# Install HuggingFace hub (needed for VGGT download)
"$HF_VENV/bin/pip" install --upgrade pip huggingface_hub

注：すでに hf を含む venv がある場合は、このステップをスキップしてください（リポジトリルートの venv/bin/hf、または ~/venv/amc/bin/hf を確認します）。

ステップ 1：NGC にログインする

ホストの質問機能を使用して、ユーザーに NGC API キーを尋ねてください。質問機能を利用できない場合は、チャットで尋ねて、回答を待ってください。その後、次を実行します。

echo "<NGC_API_KEY>" | docker login nvcr.io --username '$oauthtoken' --password-stdin
echo "✓ NGC authentication complete"

ステップ 2：VGGT モデルをダウンロードする（まだ存在しない場合）

export REPO_ROOT=$(git rev-parse --show-toplevel)
cd "$REPO_ROOT"

if [ -f "models/vggt/vggt_1B_commercial.pt" ]; then
  echo "✓ VGGT model already present"
else
  echo "✗ VGGT model not found"
  echo "Options:"
  echo "  1. Continue without VGGT (AMC only - sufficient for most use cases)"
  echo "  2. Download VGGT model (~4.7GB, requires HuggingFace account)"
fi

VGGT をダウンロードする場合：ホストの質問機能を使用して、https://huggingface.co/facebook/VGGT-1B-Commercial でライセンスに同意し、https://huggingface.co/settings/tokens から読み取りトークンを提供するようユーザーに依頼してください。ps の出力に表示されないよう、HF_TOKEN 経由で渡します。

REPO_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
cd "$REPO_DIR"

# Find the HuggingFace CLI binary (named 'hf', not 'huggingface-cli')
HF_BIN="$(find "$REPO_DIR/venv" ~/venv/amc -name hf -type f 2>/dev/null | head -1)"
{ [ -z "$HF_BIN" ] || [ ! -x "$HF_BIN" ]; } && { echo "ERROR: hf binary not found or not executable; install the hf CLI (Step 0c) or set HF_BIN" >&2; exit 1; }

# Do NOT use --token on the command line (leaks via ps/argv). The HF CLI
# reads HF_TOKEN from the environment automatically.
HF_TOKEN="<HF_TOKEN>" "$HF_BIN" download facebook/VGGT-1B-Commercial \
  --local-dir models/vggt/

# Verify
ls -lh models/vggt/vggt_1B_commercial.pt
# Should show ~4.7GB file

重要：モデルのダウンロードが完了する前に、モデルディレクトリに対して chown 1000:1000 を設定しないでください。ダウンロード中は、現在のユーザーに書き込み権限が必要です。ダウンロード完了後、ステップ 4 で権限を設定します。

ステップ 3：Compose 環境変数を設定する

Compose の環境ファイルでポートとパスを管理します。起動前に更新してください。

cd $REPO_ROOT/compose

# Find available backend port (8000-8009)
for port in {8000..8009}; do
  if ! lsof -Pi :$port -sTCP:LISTEN -t >/dev/null 2>&1; then
    MS_PORT=$port
    echo "Using backend port: $MS_PORT"
    break
  fi
done
[ -z "$MS_PORT" ] && { echo "ERROR: no free backend port in 8000-8009; free one or widen the range." >&2; exit 1; }

# Find available UI port (5000-5009)
for port in {5000..5009}; do
  if ! lsof -Pi :$port -sTCP:LISTEN -t >/dev/null 2>&1; then
    UI_PORT=$port
    echo "Using UI port: $UI_PORT"
    break
  fi
done
[ -z "$UI_PORT" ] && { echo "ERROR: no free UI port in 5000-5009; free one or widen the range." >&2; exit 1; }

# Get host IP
HOST_IP=$(hostname -I | awk '{print $1}')
echo "Host IP: $HOST_IP"

# Preserve existing keys and restrict permissions on the Compose environment file.
COMPOSE_ENV_BASENAME="env"
ENV_FILE=".${COMPOSE_ENV_BASENAME}"
if [ -f "$ENV_FILE" ]; then
  BACKUP="${ENV_FILE}.bak.$(date +%s)"
  cp "$ENV_FILE" "$BACKUP"
  chmod 600 "$BACKUP"
fi
touch "$ENV_FILE"
chmod 600 "$ENV_FILE"
set_env_key() {
  local k="$1" v="$2"
  if grep -qE "^${k}=" "$ENV_FILE"; then
    sed -i "s|^${k}=.*|${k}=${v}|" "$ENV_FILE"
  else
    echo "${k}=${v}" >> "$ENV_FILE"
  fi
}
set_env_key AUTO_MAGIC_CALIB_MS_PORT "${MS_PORT}"
set_env_key AUTO_MAGIC_CALIB_UI_PORT "${UI_PORT}"
set_env_key PROJECT_DIR "../../projects"
set_env_key MODEL_DIR "../../models"
set_env_key HOST_IP "${HOST_IP}"

# Keep timestamped Compose environment backups out of git.
GITIGNORE="$REPO_ROOT/.gitignore"
touch "$GITIGNORE"
BACKUP_PATTERN="compose/${ENV_FILE}.bak.*"
grep -qxF "$BACKUP_PATTERN" "$GITIGNORE" || echo "$BACKUP_PATTERN" >> "$GITIGNORE"

echo "✓ Compose environment file updated"
cat "$ENV_FILE"

重要：HOST_IP にはマシンのネットワーク IP を設定してください（localhost ではありません）。これにより、UI コンテナからブラウザー経由でバックエンドに接続できます。

任意：VGGT モデルがデフォルト以外のコンテナパスにマウントされている場合に限り、VGGT_MODEL_PATH を設定してください。デフォルトは、MS コンテナ内の /tmp/vggt_model/vggt_1B_commercial.pt です。

RTSP キャリブレーションを行う場合は任意：起動後に skills/amc-run-rtsp-calibration/SKILL.md を使用してください。このスキルは VIOS への到達性を確認し、必要に応じて、チェックイン済みの compose ファイルを変更せずに VIOS_BASE_URL をエクスポートする一時的な compose オーバーライドを使ってマイクロサービスを再起動します。

ステップ 4：ディレクトリの権限を設定する

コンテナは UID/GID 1000 で実行されます。コンテナが適切に読み書きできるよう、projects ディレクトリと models ディレクトリの所有者をこの UID に設定する必要があります。

cd "$REPO_ROOT"

# Create projects directory if it doesn't exist
mkdir -p projects

# Set ownership (required for containers to write calibration outputs).
# Do this AFTER VGGT download is complete (current user needs write access during download).
# Get explicit user confirmation before running sudo chown — it recursively changes
# ownership of $REPO_ROOT/projects and $REPO_ROOT/models to UID/GID 1000.
[ -d projects ] && [ -d models ] || {
  echo "ERROR: expected projects/ and models/ under $REPO_ROOT" >&2; exit 1;
}
echo "About to chown -R 1000:1000 on:"
echo "  $REPO_ROOT/projects"
echo "  $REPO_ROOT/models"
echo "(required because containers run as UID 1000). Confirm before proceeding."
sudo chown 1000:1000 -R projects
sudo chown 1000:1000 -R models

echo "✓ Permissions set"

ステップ 5：サービスを起動する

イメージを取得する前に、ステップ 1 で認証した NGC キーでリリースイメージに実際にアクセスできることを確認し、アクセスできない場合はすぐに中止してください。そうしないと、作業が一部進んだ後に docker compose up が 401/403 エラーで途中終了します。

cd $REPO_ROOT/compose

# Fail-fast image-access check: confirm the NGC key can reach every release
# image BEFORE pulling. `docker manifest inspect` checks registry access without
# downloading layers, and the image list is read from the resolved compose so it
# tracks the release tag automatically.
IMAGES=$(docker compose config --images | sort -u)
[ -z "$IMAGES" ] && { echo "ERROR: no images resolved from compose — check the Compose environment settings and chosen profile." >&2; exit 1; }
for img in $IMAGES; do
  echo "Checking access: $img"
  if ! docker manifest inspect "$img" >/dev/null 2>&1; then
    echo "NGC login succeeded, but this key cannot access the required image:" >&2
    echo "  $img" >&2
    echo "Provide an NGC key with access to this image's namespace, then re-run Step 1 (login) and retry." >&2
    exit 1
  fi
done

# Start all services (images pulled automatically on first run)
docker compose up -d

# Check containers are running
docker compose ps

正確なイメージタグはリリースごとに変わるため、バージョンをハードコードせず、現在有効な compose ファイルから読み取ってください。

ステップ 6：サービスが実行中であることを確認する

# Read ports from the Compose environment file.
COMPOSE_ENV_BASENAME="env"
COMPOSE_ENV_FILE="$REPO_ROOT/compose/.${COMPOSE_ENV_BASENAME}"
MS_PORT=$(grep AUTO_MAGIC_CALIB_MS_PORT "$COMPOSE_ENV_FILE" | cut -d= -f2)
UI_PORT=$(grep AUTO_MAGIC_CALIB_UI_PORT "$COMPOSE_ENV_FILE" | cut -d= -f2)
HOST_IP=$(grep HOST_IP "$COMPOSE_ENV_FILE" | cut -d= -f2)

# Wait for microservice readiness. Cold image pulls or first startup can need
# extra time after `docker compose up -d` returns.
READY_URL="http://localhost:${MS_PORT}/v1/ready"
echo "Waiting for microservice readiness at ${READY_URL} ..."
ready_response=""
for attempt in $(seq 1 24); do
  if ready_response=$(curl -fsS --max-time 5 "${READY_URL}" 2>/dev/null) && \
     echo "${ready_response}" | grep -q '"code"[[:space:]]*:[[:space:]]*0'; then
    echo "Microservice ready: ${ready_response}"
    break
  fi
  if [ "${attempt}" -lt 24 ]; then
    printf "  [%02d/24] Microservice not ready yet; retrying in 5s...\n" "${attempt}"
    sleep 5
  fi
done

if ! echo "${ready_response}" | grep -q '"code"[[:space:]]*:[[:space:]]*0'; then
  echo "ERROR: microservice did not report ready within 120 seconds: ${READY_URL}" >&2
  echo "Check status and logs:" >&2
  echo "  cd ${REPO_ROOT}/compose && docker compose ps" >&2
  echo "  cd ${REPO_ROOT}/compose && docker compose logs auto-magic-calib-ms" >&2
  exit 1
fi

# Check UI is serving
UI_STATUS=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "http://localhost:${UI_PORT}")
if [ "${UI_STATUS}" != "200" ]; then
  echo "ERROR: Web UI returned HTTP ${UI_STATUS}; check docker compose ps and UI logs." >&2
  exit 1
fi
echo "Web UI ready: HTTP ${UI_STATUS}"

echo "Microservice: http://${HOST_IP}:${MS_PORT}"
echo "Web UI:       http://${HOST_IP}:${UI_PORT}"

成功条件

• docker compose ps で MS と UI のコンテナが Up と表示されます。MS は正常な状態である必要があります。
• /v1/ready が code:0 を返し、ステップ 6 でマイクロサービスと UI の URL が表示されます。
• ブラウザーから http://<HOST_IP>:<AUTO_MAGIC_CALIB_UI_PORT> にアクセスできます。
• プロジェクトは $REPO_ROOT/projects/ に保存されます。

トラブルシューティング

問題	対処方法
Docker の権限が拒否される	sudo usermod -aG docker $USER && newgrp docker を実行してから、docker ps を再試行するようユーザーに依頼してください。
docker login が拒否される	有効な NGC キーを入手して、再度ログインするよう依頼してください。
必要なイメージにアクセスできない	キーにイメージの名前空間へのアクセス権がありません。アクセス権のあるキーを入手してから、ステップ 1 とステップ 5 を再試行するよう依頼してください。
python3 -m venv、pip、または hf が見つからない	python3-venv／python3-pip をインストールしてください。HF バイナリの名前は hf です。
VGGT の権限エラー	chown 1000:1000 を実行する前に VGGT をダウンロードしてください。復旧するには、models/ の所有者をユーザーに戻してから、再ダウンロードしてください。
ポートが使用中	空いている MS ポート（8000〜8009）と UI ポート（5000〜5009）を選び、Compose の環境変数ファイルを更新してください。
起動準備のタイムアウト、またはコンテナが終了した	cd $REPO_ROOT/compose && docker compose ps を実行し、docker compose logs auto-magic-calib-ms を確認してください。
プロジェクト／モデルの権限が拒否される	projects/ または models/ のみに対してステップ 4 を再実行してください。
UI からバックエンドに接続できない	Compose の環境変数ファイル内の HOST_IP が localhost ではなく、マシンのネットワーク IP であることを確認してください。
GPU を利用できない	docker run --rm --runtime=nvidia --gpus all ubuntu:20.04 nvidia-smi で NVIDIA ランタイムを確認してください。

よくある対処方法：

cd $REPO_ROOT/compose

# View logs
docker compose logs -f

# View logs for specific service
docker compose logs -f auto-magic-calib-ms

# Restart all services
docker compose restart

# Stop and remove containers
docker compose down

# Update Compose environment settings and relaunch
docker compose up -d

サービスの停止

cd $REPO_ROOT/compose

# Stop all services (containers removed, data persisted)
docker compose down

# Stop and remove volumes
docker compose down -v

関連スキル

• skills/amc-run-sample-calibration/SKILL.md - 同梱のサンプルデータセットを使って、実行中のスタックを確認します
• skills/amc-run-video-calibration/SKILL.md - REST API 経由で、事前に録画した独自の MP4 ファイルからキャリブレーションします
• skills/amc-run-rtsp-calibration/SKILL.md - VIOS キャプチャを通じて、ライブ RTSP ストリームからキャリブレーションします