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 窗口。”
• “使用 RTDETR 无头运行 MV3DT 12 路摄像头示例，并保存视频。”
• “使用 PeopleNetTransformer 在 /data/mv3dt-demo 下的同步 MP4 文件上运行 MV3DT。”
• “我的自定义 MV3DT 视频没有标定数据；请使用 AutoMagicCalib，然后运行 MV3DT。”

概述

通过 DeepStream 容器运行位于 DeepStream/src/apps/reference_apps/deepstream-tracker-3d-multi-view 的 Multi-View 3D Tracking 参考应用。此技能支持设置、运行随附示例、处理自定义同步 MP4 数据集、将标定工作移交给 AutoMagicCalib、执行显示或无头模式、生成 OSD/BEV 输出，以及检查 Kafka 元数据。

先决条件

• 磁盘上存在 MV3DT 参考应用目录 DeepStream/src/apps/reference_apps/deepstream-tracker-3d-multi-view；如果不存在，请先征求用户同意，再克隆公开的 DeepStream 仓库
• 支持 NVIDIA GPU 的 Docker
• 可访问 DeepStream 容器镜像
• 由仓库设置脚本准备好的 MV3DT 示例数据集、模型、自定义解析器库、Kafka、Mosquitto 和 mv3dt_venv
• 可用的 X11/VNC 显示环境，用于实时 OSD/BEV 窗口；或者使用无头模式保存输出，生成平铺的 DeepStream MP4 和基于 Kafka 的 BEV MP4

操作说明

步骤 0：解析 MV3DT 应用检出目录

此技能可以安装在 DeepStream 仓库之外。将 REPO_ROOT 解析为 MV3DT 应用目录，该目录不一定是 Git 顶层目录。

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：选择主要工作流

根据用户当前请求，准确加载一个主要参考文档：

用户意图	参考文档
安装、准备或验证先决条件	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 作为统一配置生成参考加载，不要重复编写 shell 逻辑。

第 2 步：遵循运行阶段

每次运行都按以下阶段顺序进行：

阶段	操作
Validate	检查应用目录、前置条件、数据集结构、显示／无头模式、Docker GPU 支持，以及输出目录是否可写。
Prepare	在启动前说明所选的示例／自定义数据集、检测器、运行模式、输出目录、预期输出形式，以及对 --privileged --net=host 的 Docker 安全决策。
Execute	生成配置；在无头模式下或明确要求保存 BEV MP4 时，先启动离线 BEV 捕获，然后运行 DeepStream，或将缺失的校准交由 AutoMagicCalib 处理。
Verify	通过 App run successful、启用文件输出时生成的最新 MP4 文件、Kafka 偏移量／消息，以及运行 BEV MP4 捕获时的 BEV 消息／帧数，确认功能已就绪。
Report	汇总所选选项、生成的文件、文件路径、文件大小／数量，以及任何已跳过或失败的输出形式；默认的 4 摄像头示例运行完成后，说明也可接着运行 12 摄像头示例。

第 3 步：明确应用默认设置

• 运行路径：DeepStream Container。
• 显示路径：如果有可用的 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；配置生成和 AMC camInfo modelInfo 规范化过程中都应使用所选的 DETECTOR_MODEL。对于自定义校准交接，请让用户选择 AutoMagicCalib 检测器，不要静默使用默认值。
• 自定义数据源：同步的 MP4 文件。首个版本的技能不处理实时流。
• 校准交接：使用独立的 AutoMagicCalib 技能，不要重复其设置或 API 工作流。

第 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 捕获进程生成了非零消息和帧时，才能报告 BEV MP4 成功。

关键输出

• 生成的配置文件：${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 - 从同步的本地 MP4 生成标定信息，然后返回 MV3DT。