Apple 的 Cubify Anything：扩展室内 3D 对象检测

本仓库包含了 Cubify Transformer 的公开实现和相关的 CA-1M 数据集。

论文

Apple

Cubify Anything: Scaling Indoor 3D Object Detection

Justin Lazarow, David Griffiths, Gefen Kohavi, Francisco Crespo, Afshin Dehghan

CVPR 2025

Teaser

仓库概述

本仓库包括：

  1. CA-1M 数据集底层数据和标注的链接。
  2. 来自 Cubify Anything 论文的 Cubify Transformer (CuTR) 模型的已发布模型的链接。
  3. 运行 CuTR 在提供的数据上的基本读取器和推理代码。
  4. 使用 NeRF Capture app 从自有设备捕获的图像的基本支持。

安装

我们推荐 Python 3.10 和最新 2.x 版本的 PyTorch。 我们包含了一个 requirements.txt 文件，它应该封装了所有必要的依赖项。 请确保您先安装了 torch，例如：

pip install torch torchvision

然后，在仓库的根目录下：

pip install -r requirements.txt
pip install -e .

CA-1M 与 ARKitScenes？

这项工作与 ARKitScenes 相关。 我们通常共享相同的底层捕获。 CA-1M 的一些显著差异：

  1. 每个场景都已使用与类别无关的 3D 框进行了详尽的标注。 我们在激光扫描仪的坐标系中发布这些标注。
  2. 对于每次捕获中的每一帧，我们都包含“每帧” 3D 框真值，该真值是使用 Cubify Anything 论文中概述的渲染过程生成的。 因此，这些注释与任何姿势无关。

还有一些其他优点：

  1. 我们发布了每次捕获中每帧的 GT 姿势（已注册到激光扫描仪）。
  2. 我们发布了每次捕获中每帧的 512 x 384 的 GT 深度（从激光扫描仪渲染）。
  3. 每帧都已定向到直立位置。

注意： CA-1M 仅包含已成功注册到激光扫描仪的捕获。 因此，并非 ARKitScenes 中包含的每个捕获都将出现在 CA-1M 中。

下载和使用 CA-1M 数据

数据许可

所有数据均根据 CC-by-NC-ND 发布。

所有数据的链接都包含在 data/train.txt 和 data/val.txt 中。 您可以使用 curl 下载列出的所有文件。 如果您不需要预先下载整个数据集，您可以显式地传递这些链接，或者传递分割的 txt 文件本身，并使用 --video-ids 参数来过滤所需的视频。

如果您传递 txt 文件，请注意该文件将被缓存在 data/[split] 下。

了解 CA-1M 数据

CA-1M 以 WebDataset 格式发布。 因此，它本质上是每个捕获（即视频）的精美 tar 存档。 因此，单个存档 ca1m-[split]-XXXXXXX.tar 对应于捕获 XXXXXXXX 的所有数据。

两个分割都以全帧率发布。

所有数据都应由 CubifyAnythingDataset 简洁地加载。 请参阅 dataset.py，了解有关如何读取/解析磁盘上数据的更多详细信息。 一些一般性提示：

[video_id]/[integer_timestamp].wide/image.png        # 对应于主摄像头的 1024x768 RGB 图像。
[video_id]/[integer_timestamp].wide/depth.png        # 以 UInt16（以毫米为单位）存储的 256x192 深度图像，源自捕获设备的板载 LiDAR（ARKit 深度）。
[video_id]/[integer_timestamp].wide/depth/confidence.tiff  # 存储每个深度测量的 [0, 1] 置信度值的 256x192 置信度图像（当前未使用）。
[video_id]/[integer_timestamp].wide/instances.json     # GT 实例及其 3D 框的列表（即 GT 渲染过程的结果）。
[video_id]/[integer_timestamp].wide/T_gravity.json     # 编码摄像头的俯仰/滚转的旋转矩阵，我们假设它是已知的（例如，IMU）。
[video_id]/[integer_timestamp].gt/RT.json          # 对应于激光扫描仪空间中注册姿势的 4x4（行优先）JSON 编码矩阵。
[video_id]/[integer_timestamp].gt/depth.png         # 以 UInt16（以毫米为单位）存储的 512x384 深度图像，源自 FARO 激光扫描仪注册。

请注意，由于我们已经对图像进行了定向，因此这些尺寸可能会被转置。 GT 深度可能具有 0 值，这些值对应于未注册的点。

一个附加文件作为 [video_id]/world.gt/instances.json 包含，它对应于完整的世界 3D 标注集，每帧标签都是从中生成的。 这些实例包括一些结构标签：wall、floor、ceiling、door_frame，这些标签可能有助于渲染。

可视化

我们包含使用 rerun 的可视化支持。 可视化应该会自动发生。 如果您不希望运行任何模型，而只想可视化数据，请使用 --viz-only。

在推理过程中，您可能希望检查预测的 3D 准确性。 当使用 --viz-on-gt-points 标志时，我们支持可视化 GT 点云（源自 Faro 深度）上的预测。

示例命令

python tools/demo.py [path_to_downloaded_data]/ca1m-val-42898570.tar --viz-only

python tools/demo.py data/train.txt --viz-only --video-ids 45261548

跳过帧

数据以高帧率提供，因此使用 --every-nth-frame N 将仅处理每 N 帧。

运行 CuTR 模型

所有模型均根据 LICENSE_MODEL 中的 Apple ML Research Model Terms of Use 发布。

  1. RGB-D
  2. RGB

可以使用 --model-path 参数将模型提供给 demo.py。 我们会检测这是否是 RGB 或 RGB-D 模型，并相应地禁用深度。

RGB-D

CuTR 的第一个变体需要 RGB 图像和度量深度图。 我们在 ARKit 深度上进行训练，尽管您可能会发现它也可以与其他度量深度估计器一起使用。

示例命令

如果您的计算机已启用 MPS：

python tools/demo.py data/val.txt --video-ids 42898570 --model-path [path_to_models]/cutr_rgbd.pth --viz-on-gt-points --device mps

如果您的计算机已启用 CUDA：

python tools/demo.py data/val.txt --video-ids 42898570 --model-path [path_to_models]/cutr_rgbd.pth --viz-on-gt-points --device cuda

否则：

python tools/demo.py data/val.txt --video-ids 42898570 --model-path [path_to_models]/cutr_rgbd.pth --viz-on-gt-points --device cpu

仅 RGB

CuTR 的第二个变体仅需要 RGB 图像，并尝试从图像本身推导出场景的度量比例。

示例命令

如果您的设备已启用 MPS：

python tools/demo.py data/val.txt --video-ids 42898570 --model-path [path_to_models]/cutr_rgb.pth --viz-on-gt-points --device mps

在您自己设备的捕获上运行

我们还支持在您自己设备捕获的 RGB/深度上运行的基本支持。

  1. 确保您已在设备上安装了 NeRF Capture
  2. 在运行 demo.py 之前 启动 NeRF Capture 应用程序（如果由于某种原因停止工作或未建立连接，请强制退出并重新打开）。
  3. 运行普通命令，但传递 "stream" 而不是通常的 tar/文件夹路径。
  4. 在应用程序中点击“发送”以发送用于推理的帧。 这将在 rerun 窗口中可视化。

我们将继续打印“Still waiting”以显示活跃状态。

如果您有一个配备 LiDAR 的设备，您可以将其与 RGB-D 模型结合使用，否则，您只能使用仅 RGB 模型。

RGB-D（在 MPS 上）

python tools/demo.py stream --model-path [path_to_models]/cutr_rgbd.pth --device mps

RGB（在 MPS 上）

python tools/demo.py stream --model-path [path_to_models]/cutr_rgb.pth --device mps

引用

如果您在您的研究中使用 CA-1M 或 CuTR，请使用以下条目：

@article{lazarow2024cubify,
 title={Cubify Anything: Scaling Indoor 3D Object Detection},
 author={Lazarow, Justin and Griffiths, David and Kohavi, Gefen and Crespo, Francisco and Dehghan, Afshin},
 journal={arXiv preprint arXiv:2412.04458},
 year={2024}
}

许可证

示例代码根据 Apple Sample Code License 发布。

数据根据 CC-by-NC-ND 发布。

模型根据 Apple ML Research Model Terms of Use 发布。

致谢

我们在 ACKNOWLEDGEMENTS 中使用并感谢多个开源项目的贡献。