Boxer CLI参数速查表：从阈值到精度，所有命令行选项一次讲透

Boxer 是一个将开放世界 2D 检测框"抬升"（lifting）为 3D 方向包围盒（OBB）的开源项目，已发表于 ECCV 2026。本文一次性讲透 Boxer 主入口 run_boxer.py 与三个可视化脚本的全部 CLI 参数：如何调整 2D/3D 置信度阈值、强制推理精度、切换摄像头流，以及在线跟踪与离线融合怎么选，可直接当速查手册用。

1️⃣ 快速上手：3 条命令跑通

git clone https://gitcode.com/gh_mirrors/boxer13/boxer cd boxer bash scripts/download_ckpts.sh # 下载 BoxerNet / DINOv3 / OWLv2 模型到 ckpts/ bash scripts/download_aria_data.sh # 下载 3 个 Project Aria 示例序列 python run_boxer.py --input nym10_gen1 --max_n=90 --track

--input的值会自动识别数据集类型：scene0084_02→ ScanNet，ca1m-val-42898570→ CA-1M，SUNRGBD→ Omni3D，其余按 Project Aria 序列处理（先查sample_data/，再查~/boxy_data/）。

2️⃣ run_boxer.py 完整参数表

所有定义集中在 run_boxer.py 的argparse块中。按用途分组如下：

📥 输入与数据流

🎯 检测与阈值（最常用）

--labels的用法很灵活：

# 使用内置类别表 lvisplus（读取 owl/lvisplus_classes.csv） python run_boxer.py --input hohen_gen1 --labels=lvisplus # 自定义文本提示 python run_boxer.py --input hohen_gen1 --labels=chair,table,lamp # 只写 --labels 不带值 = 空提示词列表 python run_boxer.py --input hohen_gen1 --labels

内置类别表由 utils/taxonomy.py 的load_text_labels加载，规则是：若owl/<名称>_classes.csv存在则读取整表，否则按你输入的字符串原样使用。

🔄 跟踪与融合（后处理二选一）

⚠️ 两个参数互斥，同时传入会直接报错--fuse and --track are mutually exclusive。另外对 Omni3D（单张图片数据集）两者都会自动禁用并打印警告。

💾 输出、缓存与帧控制

⚡ 性能、精度与硬件

设备选择逻辑：优先mps（Mac），其次cuda，否则回退cpu，加--force_cpu则跳过前两者。

3️⃣ 三个查看器脚本的参数

view_*.py系列共享一组公共参数，定义在 utils/viewer_3d.py 的add_common_args中：

各脚本的特色参数：

• view_prompt.py：交互式演示，在窗口内画 2D 框 + 输入文本提示 OWL 检测，是最直观的试玩入口；
• view_fusion.py：查看离线融合后的 3D 框，建议先跑完 Demo #1 生成 CSV；
• view_tracker.py：在线跟踪回放，支持--autoplay（自动播放）、--init_follow（跟随视角）、--init_follow_above（默认 6.0 米）、--record_fps（录屏帧率，0 = 自动）、--bb2d_csv（指定 2D 框 CSV 文件名）等。

python view_prompt.py --input nym10_gen1 # 交互式提示演示 python view_fusion.py --input nym10_gen1 # 查看融合结果 python view_tracker.py --input nym10_gen1 --autoplay # 跟踪回放

4️⃣ 结果文件在哪里

每次运行（未加--no_csv）会在output/<序列名>/下生成：

• boxer_3dbbs.csv—— 逐帧 3D 包围盒
• owl_2dbbs.csv—— 逐帧 2D 检测结果
• boxer_3dbbs_tracked.csv—— 加了--track时的跟踪框
• boxer_viz_final.mp4—— 可视化视频（未加--skip_viz时），逐帧图如：

5️⃣ 常见坑与 FAQ

• --fuse和--track不能同时开，脚本会直接报错退出；
• --cache3d会静默开启--cache2d（没有 2D 缓存就没法重跑后处理）；
• --thresh2d代码默认值是 0.25，如果 README 表格与代码不一致，以 run_boxer.py 源码为准；
• --labels单独出现不带值表示空列表，常用于纯--gt2d调试流程；
• MPS 不支持torch.autocast，所以 Mac 上--force_precision实际不会生效（代码中已做特判）；
• Omni3D 数据上--fuse/--track无效，因为它是单张图片而非视频序列；
• 想复现更快实验？组合拳：--skip_viz --max_n 90 --cache2d可把重计算环节全部跳过。

更多细节可参考 README.md 中的 CLI Reference 表格与 Demo #1～#7 完整流程，测试用例见 tests/ 目录。