deepstream-run-mv3dt

スキル：DeepStream MV3DT の実行

このスキルを使用するタイミング

ユーザーが DeepStream Multi-View 3D Tracking のリファレンスアプリをセットアップ、実行、検証、またはデバッグしたい場合に、このスキルを有効にします。代表的なプロンプト：

• 「MV3DT DeepStream をセットアップして」
• 「4 カメラの MV3DT サンプルを実行して」
• 「12 カメラの MV3DT サンプルを実行して」
• 「同期済みの MP4 で MV3DT を実行して」
• 「動画はありますが、キャリブレーションがありません。キャリブレーションして MV3DT を実行してください」
• 「BEV ビジュアライザーまたは Kafka メタデータを表示して」
• 「MV3DT を停止して」／「MV3DT をクリーンアップして」／「MV3DT を終了して」

シングルビューの 3D トラッキング、一般的な DeepStream アプリ開発、ライブストリームのオンボーディングには、ユーザーがその作業をこのリポジトリの MV3DT パイプラインに明示的に対応付けていない限り、このスキルを使用しないでください。

例

• 「DeepStream MV3DT の 4 カメラサンプルをデプロイして、OSD ウィンドウと BEV ウィンドウを表示してください。」
• 「MV3DT の 12 カメラサンプルを RTDETR でヘッドレス実行して、動画を保存してください。」
• 「PeopleNetTransformer を使って、/data/mv3dt-demo にある同期済み MP4 で MV3DT を実行してください。」
• 「カスタム MV3DT 動画にキャリブレーションデータがありません。AutoMagicCalib を使用してから、MV3DT を実行してください。」

概要

DeepStream Container のパスを使用して、DeepStream/src/apps/reference_apps/deepstream-tracker-3d-multi-view にある Multi-View 3D Tracking リファレンスアプリを操作します。このスキルでは、セットアップ、付属サンプルの実行、同期済み MP4 のカスタムデータセット、AutoMagicCalib へのキャリブレーション引き継ぎ、ディスプレイを使用した実行とヘッドレス実行、OSD／BEV 出力、Kafka メタデータの確認に対応します。

前提条件

• DeepStream/src/apps/reference_apps/deepstream-tracker-3d-multi-view 内の MV3DT リファレンスアプリのディレクトリがディスク上に存在すること。存在しない場合は、公開 DeepStream リポジトリをクローンする前にユーザーに確認してください
• NVIDIA GPU に対応した Docker
• DeepStream コンテナーイメージへのアクセス
• リポジトリのセットアップスクリプトで準備された MV3DT サンプルデータセット、モデル、カスタムパーサーライブラリ、Kafka、Mosquitto、mv3dt_venv
• OSD／BEV ウィンドウをライブ表示するための動作中の X11／VNC ディスプレイ、またはタイル表示した DeepStream MP4 と Kafka 由来の BEV MP4 を保存するヘッドレス実行パス

手順

ステップ 0：MV3DT アプリのチェックアウト先を特定する

このスキルは DeepStream リポジトリの外部にもインストールできます。REPO_ROOT は、必ずしも Git のトップレベルディレクトリではなく、MV3DT アプリのディレクトリに解決してください。

MV3DT_APP_SUBDIR="src/apps/reference_apps/deepstream-tracker-3d-multi-view"

is_mv3dt_app_dir() {
  test -f "$1/README.md" || return 1
  test -d "$1/config_templates" || return 1
  test -d "$1/scripts" || return 1
  grep -q "Multi-View 3D Tracking" "$1/README.md"
}

GIT_TOP="$(git rev-parse --show-toplevel 2>/dev/null || true)"
CANDIDATES=()
if [ -n "${MV3DT_REPO_ROOT:-}" ]; then CANDIDATES+=("${MV3DT_REPO_ROOT}"); fi
if [ -n "${DEEPSTREAM_REPO_ROOT:-}" ]; then CANDIDATES+=("${DEEPSTREAM_REPO_ROOT}/${MV3DT_APP_SUBDIR}"); fi
CANDIDATES+=("${PWD}")
if [ -n "${GIT_TOP}" ]; then
  CANDIDATES+=("${GIT_TOP}" "${GIT_TOP}/${MV3DT_APP_SUBDIR}")
fi
CANDIDATES+=("${HOME}/DeepStream/${MV3DT_APP_SUBDIR}" "${HOME}/deepstream/${MV3DT_APP_SUBDIR}")

REPO_ROOT=""
for candidate in "${CANDIDATES[@]}"; do
  if [ -n "$candidate" ] && is_mv3dt_app_dir "$candidate"; then
    REPO_ROOT="$(cd "$candidate" && pwd)"
    break
  fi
done

if [ -z "${REPO_ROOT}" ]; then
  cat <<'EOF'
ERROR: MV3DT reference app directory was not found.
Set MV3DT_REPO_ROOT to an existing deepstream-tracker-3d-multi-view app directory, or ask the user to approve cloning the public DeepStream repo and then run:

  DEEPSTREAM_REPO_ROOT="${DEEPSTREAM_REPO_ROOT:-$HOME/DeepStream}"
  git clone https://github.com/NVIDIA/DeepStream.git "$DEEPSTREAM_REPO_ROOT"
  export MV3DT_REPO_ROOT="$DEEPSTREAM_REPO_ROOT/src/apps/reference_apps/deepstream-tracker-3d-multi-view"

Do not clone silently.
EOF
  exit 1
fi

cd "${REPO_ROOT}"
export REPO_ROOT MV3DT_REPO_ROOT="${REPO_ROOT}"

アプリのディレクトリを特定できない場合は、既存のチェックアウト先をユーザーに尋ねるか、https://github.com/NVIDIA/DeepStream をクローンする許可を求めてください。確認せずにクローンしてはいけません。

ステップ 1：主要なワークフローを選択する

ユーザーの現在のリクエストに対して、主要なリファレンスを 1 つだけ読み込みます。

ユーザーの意図	リファレンス
前提条件をインストール、準備、または検証する	references/setup.md
同梱の 4 カメラまたは 12 カメラのサンプルを実行する	references/sample-run.md
同期済み MP4 のカスタムデータセットを実行する	references/custom-dataset.md
カスタムキャリブレーションがない	references/amc-calibration-handoff.md、続いて references/custom-dataset.md
OSD、BEV、スクリーンショット、録画、または Kafka メタデータを表示する	references/visualization-metadata.md
実行を停止する、生成された成果物をクリーンアップする、または前提サービスを停止する	references/setup.md

セットアップ、データセット、モデル、Kafka、Mosquitto、Docker GPU ランタイム、または Python 仮想環境が不足している場合は、ユーザーの元のワークフローを続行する前に references/setup.md を読み込んでください。

sample-run.md または custom-dataset.md で DeepStream の設定を再生成する必要がある場合は、シェルの処理を重複させず、共有設定生成の標準リファレンスとして references/generate-configs.md を読み込んでください。

ステップ 2：実行ステージに従う

実行のたびに、次の順序でステージを進めます。

ステージ	アクション
検証	アプリケーションディレクトリ、前提条件、データセットの形式、ディスプレイ／ヘッドレスモード、Docker の GPU サポート、出力ディレクトリへの書き込み可否を確認します。
準備	選択したサンプル／カスタムデータセット、検出器、実行モード、出力ディレクトリ、想定される出力先、起動前の --privileged --net=host に関する Docker セキュリティの判断を明示します。
実行	設定を生成し、ヘッドレスモードの場合、または保存済み BEV MP4 が明示的に要求された場合は、まずオフライン BEV キャプチャを開始してから DeepStream を実行します。キャリブレーションが不足している場合は AutoMagicCalib に委任します。
確認	App run successful、ファイル出力が有効な場合は新しい MP4 アーティファクト、Kafka のオフセット／メッセージ、BEV MP4 キャプチャを実行した場合は BEV のメッセージ数／フレーム数によって、機能上の準備が整ったことを確認します。
報告	選択したオプション、生成ファイル、アーティファクトのパス、ファイルサイズ／件数、スキップまたは失敗した出力先をまとめます。デフォルトの 4 カメラサンプルを実行した後は、12 カメラサンプルも次の実行候補として利用できることを伝えます。

ステップ 3：デフォルトを明示的に適用する

• 実行パス：DeepStream コンテナ。
• ディスプレイパス：動作する X11／VNC ディスプレイが利用できる場合は、OSD ウィンドウと BEV ウィンドウを使うリポジトリのクイックスタート手順を使用します。OSD ウィンドウではデフォルトで MP4 は保存されません。ディスプレイモードで出力の保存が明示的に要求された場合は、--enable-osd、--enable-file-output、--enable-msg-broker をすべて指定して設定を再生成します。
• ヘッドレスパス：動作するディスプレイがない場合は、デフォルトで保存済み出力を使用します。--enable-file-output と --enable-msg-broker を指定して設定を生成し、DeepStream 実行前にオフライン BEV キャプチャを開始します。これにより、DeepStream のタイル表示 MP4 と Kafka 由来の BEV MP4 の両方が生成されます。
• サンプルデータセット：同梱の 4 カメラと 12 カメラのデータセットの両方をサポートします。サンプルが指定されていない場合は、まず 4 カメラサンプルを実行し、最終報告で 12 カメラサンプルも利用可能で、次に実行できることを伝えます。
• 検出器：ユーザーが RTDETR または PeopleNet2.6.3 を指定しない限り、PeopleNetTransformer を使用します。選択した DETECTOR_MODEL は、設定生成と AMC camInfo の modelInfo 正規化に引き継ぎます。カスタムキャリブレーションへの引き継ぎでは、デフォルトを黙って選択せず、AutoMagicCalib の検出器をユーザーに選んでもらいます。
• カスタムデータソース：同期済み MP4 ファイル。ライブストリームへの対応は、この初回リリースのスキルの対象外です。
• キャリブレーションの引き継ぎ：設定や API のワークフローを重複して実装せず、単独の AutoMagicCalib スキルを使用します。

ステップ 4：冪等性とユーザーデータを保護する

• 準備状況の確認は安全に再実行できます。
• セットアップでは、パッケージのインストール、コンテナの取得、モデルのダウンロード、サービスの起動が行われる場合があります。実行前にユーザーに確認します。
• 設定の生成と DeepStream の実行では、EXPERIMENT_DIR 以下の生成ファイルが更新されます。RUN_STARTED_AT を記録し、古いアーティファクトを今回の実行の成功として報告しないでください。
• 通常のクリーンアップでは、今回の実行で起動したプロセスのみを停止し、ユーザーがサービスの停止やファイルの削除を明示的に求めない限り、Kafka、Mosquitto、モデル、データセット、生成済みアーティファクトはそのまま残します。
• カスタムデータセットはユーザーデータです。キャリブレーション形式のバリエーションが不足している場合は、デフォルトでコピーします。データセットのファイル名の変更、上書き、消去、削除を行う前に、ユーザーに確認します。

成功条件

• 前提条件のチェックに合格するか、不足している前提条件と具体的な次の手順が報告されます。
• DeepStream の実行で、最終的に App run successful が出力されます。
• ディスプレイモードでは、デフォルトで DeepStream の OSD グリッドとライブ BEV ビジュアライザーが表示されます。
• ヘッドレスモードでは、新しい ${EXPERIMENT_DIR}/outVideos/tiled_display_raw.mp4 が生成され、デフォルトで BEV MP4 のキャプチャが試行されます。
• メッセージブローカーの出力が有効な場合、Kafka トピック mv3dt に今回の実行の protobuf メタデータが届きます。
• BEV MP4 は、別途実行された BEV キャプチャプロセスで 0 件より多くのメッセージとフレームが生成された場合にのみ、成功として報告されます。

主な出力

• 生成された設定ファイル：${EXPERIMENT_DIR}/config_deepstream.txt、${EXPERIMENT_DIR}/config_tracker.yml、${EXPERIMENT_DIR}/config_msgconv.txt
• ファイル出力が有効な場合に保存される DeepStream のタイル表示 MP4：${EXPERIMENT_DIR}/outVideos/tiled_display_raw.mp4
• オフラインキャプチャを使用した場合に保存される BEV MP4：${EXPERIMENT_DIR}/bev_outputs/trajectory_video_<timestamp>.mp4
• Kafka トピック：mv3dt
• 出力先ルートの例：${REPO_ROOT}/experiments/deepstream/4cam および ${REPO_ROOT}/experiments/deepstream/12cam

トラブルシューティング

問題	最初に行うこと
セットアップの前提条件が不足している	references/setup.md を読み込み、セットアップ前にチェックのみの手順を実行してください。
Docker から GPU にアクセスできない	サンプルを起動する前に、NVIDIA Container Toolkit または Docker ランタイムを修正してください。
表示ウィンドウが表示されない	DISPLAY と /tmp/.X11-unix を確認してください。ディスプレイを利用できない場合は、ヘッドレスの保存済み出力の手順を使用してください。
DeepStream の MP4 が見つからない	--enable-file-output を指定して設定ファイルが生成されたことを確認し、成果物のタイムスタンプが RUN_STARTED_AT より新しいことを確認してください。
BEV MP4 がない、またはメッセージがゼロ件	DeepStream の前に --from-end を指定してオフライン BEV キャプチャを開始し、--first-message-timeout に十分な長さを設定して、実行中に Kafka のオフセットが進むことを確認してください。
Kafka クライアントにメッセージが表示されない	--enable-msg-broker を指定して設定ファイルを再生成し、トピック mv3dt が存在することを確認してください。
カスタムデータセットにキャリブレーションがない	references/amc-calibration-handoff.md を読み込み、委任する前に検出器と設定の選択について尋ねてください。
生成ファイルの所有者が root になっている	所有権の問題を報告し、生成ディレクトリに限定した権限修正を適用する前に確認してください。

安全上の注意

• sudo の使用、パッケージのインストール、コンテナのプル、モデルのダウンロード、サービスの起動または停止、ホストのディスプレイアクセスの変更、データセットファイルの上書き、生成状態の消去を伴うコマンドを実行する前に確認してください。
• Kafka、Mosquitto、モデル、データセット、実験出力の削除は、破壊的なクリーンアップとして扱ってください。削除する対象を正確に示し、削除前に明示的な承認を得てください。
• docker run --privileged --net=host を実行する前に、コンテナがホスト、デバイス、ネットワーク、およびマウントされたリポジトリに広範にアクセスできることを明確に伝え、ユーザーの承認を得てください。
• リポジトリを黙ってクローンしたり、リポジトリ外のホスト権限を変更したり、ユーザーデータセットの名前を変更または削除したり、古い成果物を今回の実行による成功として報告したりしないでください。
• カスタム動画、キャリブレーション、保存された可視化、追跡メタデータは、ローカルの機微なデータである可能性があるものとして扱ってください。ユーザーが明示的に移動または共有を求めない限り、出力はローカルに保管してください。
• 生成出力に権限修正が必要な場合は、生成ディレクトリのみに限定した最小限の修正案を提示し、事前に確認してください。広範囲にわたる再帰的な全ユーザー書き込み権限の変更は決して推奨しないでください。

関連スキル

• amc-setup-calibration-stack - キャリブレーションが必要な場合に、スタンドアロンの AutoMagicCalib スタックを起動します。
• amc-run-video-calibration - MV3DT に戻る前に、同期されたローカル MP4 からキャリブレーションを生成します。