Boxer三阶段流水线拆解:OWLv2检测、BoxerNet提升、3D融合,一张图看懂整体架构
Boxer三阶段流水线拆解:OWLv2检测、BoxerNet提升、3D融合,一张图看懂整体架构
Boxer 是一个已被 ECCV 2026 收录的开源项目,它能把开放世界(open-world)的 2D 检测框稳健地"提升"(lifting)为静态、全局、融合后的 3D 朝向包围盒(OBB)。整条流水线由三个阶段组成:OWLv2 开放词汇 2D 检测 → BoxerNet 2D-to-3D 提升 → 多视角 3D 融合/跟踪,输入只需带位姿的图片序列、相机标定和重力方向,可选深度信息可显著改善精度。下面带你一张图看懂它的整体架构。
一张图看懂 Boxer 整体架构
先看官方系统图:左侧是四类输入(开放世界文本提示、视频、标定+位姿、可选深度/稀疏点云),中间依次经过"现成开放世界 2D 检测器"、BoxerNet、多视角时间融合三个模块,最终输出每个场景一整套去重后的 3D 包围盒。
可以把它类比成一条"三级传送带":
| 阶段 | 模型/模块 | 输入 | 输出 |
|---|---|---|---|
| ① 2D 检测 | OWLv2(开放词汇检测器) | 图像 + 文本提示(如 chair, table, lamp) |
每帧 2D 检测框 owl_2dbbs.csv |
| ② 3D 提升 | BoxerNet(自研) | 2D 框 + 图像 + 位姿 + 可选半稠密点云 | 每帧 3D OBB boxer_3dbbs.csv |
| ③ 3D 融合/跟踪 | 多视角时间融合(自研) | 所有帧的 3D 框 | 去重后的静态 3D 场景(或在线 3D 轨迹) |
阶段一:用 OWLv2 做开放词汇 2D 检测
Boxer 不绑定固定的类别表——你可以输入任意文本提示,比如 red figureine、guitar。2D 检测由 Meta 的 OWLv2 模型完成,配合 CLIP 分词器把文字变成检测条件:
- 检测器封装在 owl/owl_wrapper.py,文本嵌入由 owl/clip_tokenizer.py 提供;
- 内置了
lvisplus等标签分类法(taxonomy),见 owl/lvisplus_classes.csv,默认会加载上千个室内常见物体词; - 想只找特定物体?用
--labels=chair,table,lamp即可; - 2D 置信度由
--thresh2d控制(默认 0.25),检测输入分辨率由--detector_hw控制(默认 960)。
在交互式 Demo 中,你甚至可以直接在画面里拖一个 2D 框(Option A)或输入文字(Option B)来提示 OWLv2 检测:
阶段二:BoxerNet 把 2D 框"提升"到 3D
这是 Boxer 的核心创新,源码见 boxernet/boxernet.py。模型名 BoxerNet 对应图中蓝色的 "BoxerNet (ours)",内部是一个 encode → cross-attend → predict 三段式 Transformer:
- 编码图像:用冻结的 DINOv3 视觉主干(boxernet/dinov3_wrapper.py)把图像切成 16×16 的 patch 特征;再把半稠密点云(SDP)投影成"每个 patch 的中值深度图"拼接进去,可选再拼接 Plücker 光线编码(ray encoding);
- 自注意力:输入特征先做 4 层 self-attention 融合上下文;
- 交叉注意力查询:每个 2D 框(归一化的 4 个坐标)变成一个 query token,通过 6 层 cross-attention 去"询问"图像特征,从而把该框对应的物体特征聚拢过来;
- 7 自由度预测头(AleHead):输出 3D 中心、尺寸、偏航角,同时预测随机不确定性(log sigma²),转成置信度概率——这就是
--thresh3d过滤的分数来源。
两个工程细节值得注意:预测在**重力对齐坐标系(voxel frame)**中进行,保证 yaw 角稳定;最终用 T_world_voxel 变换回世界坐标,得到全局一致的 3D OBB。
下面这张图展示了逐帧运行的实时效果:左面板是 OWLv2 的 2D 检测,中间是 BoxerNet 投影回画面的 3D 框(还叠了深度点云),右侧是在线 3D 跟踪结果:
阶段三:多视角 3D 融合与在线跟踪
单帧的 3D 框有噪声且重复,Boxer 提供了两种互补方式把它们整理成"干净的全局场景":
① 离线融合(--fuse):实现于 utils/fuse_3d_boxes.py,算法四步走——计算两两 3D IoU 矩阵 → 按 IoU 阈值用连通分量聚类 → 簇内按置信度加权平均(偏航角用处理 180° 对称性的加权圆均值)→ 按最小检测次数过滤。此外还实现了匈牙利算法做最优分配匹配。完成后用 view_fusion.py 打开 3D 查看器,可以看到"763 个逐帧检测 → 58 个融合实例"的去重效果:
② 在线跟踪(--track):实现于 utils/track_3d_boxes.py 的 BoundingBox3DTracker。每条轨迹有 TENTATIVE → ACTIVE 状态机:新轨迹需要累计 min_hits 次(run_boxer.py 中默认 8 次)匹配才转正,连续 max_missed 帧(默认 90)未匹配则删除,且容忍阈值会随轨迹置信度自适应调整。两种模式互斥,二选一即可。
快速上手:一条命令跑通三阶段
git clone https://gitcode.com/gh_mirrors/boxer13/boxer
cd boxer
bash scripts/download_ckpts.sh # 下载 BoxerNet / DINOv3 / OWLv2 权重
bash scripts/download_aria_data.sh # 下载示例 Aria 数据
python run_boxer.py --input nym10_gen1 --max_n=90 --track
结果写入 output/<序列名>/,核心产物一览:
| 输出文件 | 含义 |
|---|---|
owl_2dbbs.csv |
每帧 2D 检测(阶段一) |
boxer_3dbbs.csv |
每帧 3D 包围盒(阶段二) |
boxer_3dbbs_tracked.csv |
跟踪后的 3D 框(--track 时) |
boxer_viz_final.mp4 |
可视化视频 |
更多参数(如 --fuse、--gt2d、--no_sdp、--force_precision 等)的完整说明见 run_boxer.py 的 CLI 定义;不同数据集的加载逻辑(Aria、CA-1M、ScanNet、Omni3D/SUN-RGBD)分别封装在 loaders/ 目录下。
核心文件导航
想深入源码时,按这三条主线找文件最快:
- 主流程:run_boxer.py(无头推理)、view_prompt.py(交互 Demo)、view_fusion.py(融合可视化)、view_tracker.py(在线跟踪)
- 模型:boxernet/boxernet.py(encode → cross-attend → predict)、boxernet/dinov3_wrapper.py
- 后处理:utils/fuse_3d_boxes.py(离线融合)、utils/track_3d_boxes.py(在线跟踪)、utils/tw/(相机/OBB/位姿张量工具)
小结
Boxer 的设计哲学很清晰:让现成的开放世界 2D 检测器负责"看见",让自研的 BoxerNet 负责"提升到 3D",再用几何驱动的融合/跟踪负责"整理全局"。三个阶段解耦又互补——单帧提升只需图像、标定、重力方向(深度可选),而融合与跟踪则把逐帧结果沉淀为一套静态、全局、去重的 3D 场景。如果你在做室内建图、机器人感知或 AR 场景理解,这条"文本提示进、3D 框出"的流水线值得直接上手试试。



