VSS Deploy Detection & Tracking — 3D (RTVI-CV-3D)

Activez la stack RTVI-CV-3D à partir du blueprint warehouse : perception DeepStream par caméra (vss-rtvi-cv-mv3dt) + Fusion BEV (vss-rtvi-cv-bev-fusion) + bus MQTT mosquitto + broker + stack VST sensor — sans la stack agent / LLM / VLM qui accompagne le blueprint warehouse complet.

La machinery compose réelle se trouve dans deploy/docker/industry-profiles/warehouse-operations/warehouse-mv3dt-app/. Cette skill pilote les overrides d'env, la chaîne de calibration et la vérification.

Routage

Posez à l'utilisateur au maximum quatre questions, puis dispatchez.

Q0 — Taille du profil (overlays ou non)

Par défaut, extended sauf si l'utilisateur demande explicitement minimal. Extended déploie ELK + vss-video-analytics-api-mv3dt + vss-kibana-init-mv3dt + vss-import-calibration-output-mv3dt en plus du core MV3DT — ce sont ces composants dont le mur vidéo VST a besoin pour afficher les overlays de boîtes englobantes. Sans eux, le mur vidéo fonctionne mais affiche les flux bruts sans overlays.

Note sur ELK sélectif : il n'existe pas de chemin intermédiaire « minimal + ELK uniquement » dans la compose actuelle. Chaque service encadré par ${MINIMAL_PROFILE:+_extended} démarre ensemble (ES, Logstash, Kibana, video-analytics-api, kibana-init, import-calibration). L'expansion de paramètre :+ de bash produit le suffixe _extended quand MINIMAL_PROFILE est défini ; extended bascule la chaîne d'encadrement en retour vers plain bp_wh_kafka_mv3dt que le profil compose actif correspond déjà. Soit vous acceptez le bundle extended complet, soit vous restez minimal.

Q1 — Source de données

Posez cette question sauf si la source est explicite dans le premier message de l'utilisateur. Une demande nue comme « déployer rtvi-cv-3d » n'implique pas sample.

• sample — le dataset synthétique 4-caméras fourni (warehouse-4cams-20mx20m-synthetic). La calibration est fournie en arborescence ; aucune exécution AMC nécessaire.
• videos — l'utilisateur dispose de fichiers vidéo locaux (tout *.mp4 nommé d'après ses caméras). AMC autonome (profil auto_calib) s'exécutera si la calibration est manquante.
• rtsp — l'utilisateur dispose d'URLs RTSP en direct. Calibration via AMC piloté par VIOS.

Q2 — Couverture de calibration (ignorer pour sample)

Pour videos et rtsp, vérifiez si la calibration se trouve déjà sur disque au chemin de montage attendu par le conteneur de perception :

DATASET="${SAMPLE_VIDEO_DATASET:?}"          # le slug dataset de l'utilisateur ; voir Q3
CAL_DIR="${VSS_APPS_DIR}/industry-profiles/warehouse-operations/warehouse-mv3dt-app/calibration/sample-data/${DATASET}"

# Rechercher L'UN DE : calibration.json, plus camInfo/*.yml ou *.yaml avec l'un ou
# l'autre des nommages 'cam_*' ou 'Camera*' (l'exemple fourni utilise Camera*.yml, AMC peut
# produire cam_*.yaml — élargissez en conséquence)
test -f "${CAL_DIR}/calibration.json" \
  && ls "${CAL_DIR}/camInfo/"*.{yml,yaml} 2>/dev/null

Si l'utilisateur a fourni lui-même un chemin de calibration, validez ce chemin à la place — ne pas recalculer. Voir configure-cameras.md pour la découverte de nombre de caméras faisant autorité (analyse calibration.json).

Q3 — Slug détecteur + dataset (seulement quand Q2 déclenche AMC)

• resnet (défaut, rapide) ou transformer (plus lent, meilleur sous occlusion) — passé à l'API AMC /v1/calibrate/<id> à l'étape B (voir vss-generate-video-calibration/SKILL.md:48-62).
• Un slug dataset court en kebab-case utilisé comme SAMPLE_VIDEO_DATASET (p. ex. customer-aisle-4cams). Ceci pilote le chemin de montage de calibration et est persisté dans .env.

Tableau de routage

Chaque chemin converge vers references/verify-and-view.md une fois que up -d se termine. references/troubleshooting.md et references/teardown.md sont liés mais hors du parcours heureux.

Règle de désambiguïsation. Si l'utilisateur mentionne « warehouse » sans « mv3dt » / « 3D tracking » / « multi-view », envisagez plutôt un routage vers ../vss-deploy-profile/references/warehouse.md — c'est le blueprint warehouse complet (2D / 3D / MV3DT + agents). Cette skill est pour MV3DT uniquement sans la stack agent / LLM / VLM.

Prérequis

1. Chemin du repo

Localisez video-search-and-summarization/ sur disque. Toutes les commandes compose s'exécutent à partir de <repo>/deploy/docker/. Si inconnu, demandez à l'utilisateur.

2. NGC CLI + clé

$NGC_CLI_API_KEY doit être défini. nvidia/vss-core/* et nvstaging/vss-core/* sont tous deux des orgs valides selon celui que la clé de l'utilisateur résout. Voir vss-deploy-profile/references/ngc.md pour la configuration si manquante.

Si l'utilisateur a précédemment exécuté ngc config set mais que $NGC_CLI_API_KEY n'est pas exporté dans ce shell, la clé est déjà sur disque :

NGC_CLI_API_KEY=$(awk -F'= ' '/^apikey/{print $2}' ~/.ngc/config 2>/dev/null)
test -n "${NGC_CLI_API_KEY}" && echo "key sourced from ~/.ngc/config"

Assurez-vous que la valeur de la clé aboutit aussi dans industry-profiles/warehouse-operations/.env:164 (NGC_CLI_API_KEY=...) — compose ne la lit que de là au moment de up, pas à partir de votre env shell.

3. Slug HARDWARE_PROFILE

Les clés HARDWARE_PROFILE canoniques se trouvent dans industry-profiles/warehouse-operations/blueprint-configurator/blueprint_config.yml (lignes 592–642). Utilisez le slug du tableau ci-dessous — p. ex. sur un hôte RTX A6000 (Ampere) la valeur est RTXA6000.

Choisissez à partir de nvidia-smi --query-gpu=name --format=csv,noheader :

Le plafond MV3DT par GPU est appliqué au moment du déploiement. vss-configurator-mv3dt calcule final_stream_count = min(NUM_STREAMS, max_streams_supported) et applique une opération de gestion de fichiers keep_count contre ${VSS_DATA_DIR}/videos/${SAMPLE_VIDEO_DATASET}/ pour que seuls final_stream_count fichiers .mp4 subsistent (triés lexicographiquement, les N derniers conservés). Si le plafond mv3dt de votre GPU (tableau ci-dessus) est inférieur à votre nombre de caméras, perception / mdx-raw / mdx-bev s'exécutent avec la valeur du plafond de flux. Soit choisissez un GPU avec un plafond plus élevé, soit surfacez le plafond explicitement à l'utilisateur pour qu'il soit conscient des flux qui seront traités.

4. Données d'app sur disque

VSS_DATA_DIR doit pointer vers le répertoire extrait vss-warehouse-app-data (séparé du repo). Le faire pointer vers deploy/docker/ du repo provoque l'arrêt du déploiement : le configurator ne peut pas trouver le dataset, redis ne peut pas ouvrir son fichier log, et perception reste dans Created. Vérifiez le chemin avant le déploiement.

Vérification avant déploiement :

DATA_DIR="${VSS_DATA_DIR:?VSS_DATA_DIR not set in .env}"
DATASET="${SAMPLE_VIDEO_DATASET:-warehouse-4cams-20mx20m-synthetic}"

for sub in videos models data_log; do
  test -d "${DATA_DIR}/${sub}" || { echo "ERROR: ${DATA_DIR}/${sub} missing"; exit 1; }
done

# Pour les modes sample / videos — le répertoire videos doit exister
test -d "${DATA_DIR}/videos/${DATASET}" \
  || { echo "ERROR: ${DATA_DIR}/videos/${DATASET} missing — wrong slug or app-data not extracted"; exit 1; }

# Santé : le nombre de vidéos devrait correspondre au nombre de calibrations.
# Certaines tarballs app-data publiées sont connues pour livrer le dataset sample avec
# moins de vidéos que le nom du dataset l'implique — vérifiez et sourcer les caméras manquantes
# séparément si le plafond mv3dt de votre GPU est assez élevé pour les utiliser toutes.
ls "${DATA_DIR}/videos/${DATASET}/"*.mp4 2>/dev/null | wc -l

# Assurez-vous que chaque sous-répertoire par service sous data_log/ existe, puis ouvrez les permissions.
# kafka / elasticsearch / redis s'exécutent comme des UIDs non-root différents contre
# des chemins montés en bind sur hôte — sans 777 les daemons sortent avec
# « Permission denied » (kafka cluster_id), « AccessDeniedException » (ES),
# ou « Can't open the log file » (redis). chmod 777 est le correctif documenté ;
# NE PAS faire chown récursif — voir data-directory.md pour le rationnel par UID.
mkdir -p \
  "${DATA_DIR}/data_log/analytics_cache" \
  "${DATA_DIR}/data_log/calibration_toolkit" \
  "${DATA_DIR}/data_log/elastic/data" \
  "${DATA_DIR}/data_log/elastic/logs" \
  "${DATA_DIR}/data_log/kafka" \
  "${DATA_DIR}/data_log/redis/data" \
  "${DATA_DIR}/data_log/redis/log"
chmod -R 777 "${DATA_DIR}/data_log"

Facile à rater, difficile à récupérer. L'étape mkdir -p + chmod -R 777 sur ${DATA_DIR}/data_log est requise, pas optionnelle. Les arbres vss-warehouse-app-data fraîchement extraits sont possédés par l'utilisateur qui extrait (celui qui a exécuté tar -xvf) et les UIDs des conteneurs ne correspondront pas. Le tableau détaillé par conteneur UID se trouve dans ../vss-deploy-profile/references/data-directory.md ; le même doc explique pourquoi chown récursif est le mauvais correctif.

Si app-data n'est pas encore extrait : téléchargez via ngc registry resource download-version "nvidia/vss-warehouse/vss-warehouse-app-data:<version>" et tar -xvf (voir references/deploy-rtvi-cv-3d-stack.md pour la découverte de tag et les étapes complètes).

5. Pré-vol (système)

nvidia-smi, runtime NVIDIA Docker visible (docker info | grep -i runtimes), et docker run --rm --gpus all ubuntu:24.04 nvidia-smi tous au vert. Les vérifications complètes de pilote / kernel / sysctl se trouvent dans vss-deploy-profile/references/prerequisites.md.

Si une vérification échoue, corrigez avant de continuer — ne procédez pas au déploiement.

6. Accessibilité du navigateur (hôtes cloud / VPN d'entreprise uniquement)

Si l'utilisateur verra le mur vidéo VST via un navigateur sur un réseau différent de l'hôte de déploiement (VM cloud, VPN d'entreprise, session ssh-tunnellisée), les règles de firewall en amont peuvent bloquer VST WebRTC (STUN vers stun.l.google.com:19302, plus UDP aléatoire pour le média). Voir references/verify-and-view.md#browser-reachability pour les symptômes et les contournements. Aussi : certains hôtes bloquent le port par défaut du microservice AMC (TCP/8010) ; si l'utilisateur signale que l'UI AMC sur :5000 fonctionne mais que ses appels de données échouent, réessayez avec un VSS_AUTO_CALIBRATION_PORT différent.

Comment cela s'emboîte

SKILL.md (ce fichier — routage Q0/Q1/Q2/Q3)
  └─ si cal manquante ─> calibration-workflow.md
  │                     └─ chaîne vers vss-generate-video-calibration (déploiement + pilotage API)
  │                     └─ récupère /v1/result/{project_id}/mv3dt_result?result_type=amc
  │                     └─ dépose les fichiers de calibration dans warehouse-mv3dt-app/calibration/sample-data/<slug>/
  ├─> configure-cameras.md (synchronisation NUM_STREAMS, élagage capteur VST)
  └─> deploy-rtvi-cv-3d-stack.md (compose up avec bp_wh_kafka_mv3dt + extended/minimal)
        └─> verify-and-view.md (FPS, fusion_ready, mdx-bev, mur vidéo VST + vérifications WebRTC)

Skills connexes

• vss-generate-video-calibration — la skill AMC. Possède le profil compose auto_calib, l'API de calibration, et le hook d'export /v1/result/.../mv3dt_result que cette skill consomme. calibration-workflow.md s'enchaîne vers celle-ci.
• vss-deploy-profile — parapluie multi-profils. Utilisez cela à la place quand l'utilisateur veut le blueprint warehouse complet (avec agents / LLM / VLM), pas seulement MV3DT.
• vss-manage-video-io-storage — skill VIOS / VST API. Utile pour le mur vidéo VST (viz overlay) et pour la gestion des capteurs référencée dans configure-cameras.md.

La référence warehouse-blueprint faisant autorité du repo à ../vss-deploy-profile/references/warehouse.md couvre 2D / 3D / MV3DT dans la stack warehouse complète — cette skill est la compagne MV3DT uniquement qui élague la couche agent / LLM / VLM.