ACE0（ACE 零）

本仓库包含与 ACE0 论文相关的代码：

场景坐标重建：通过增量学习重定位器对图像集合进行姿态估计

Eric Brachmann、 Jamie Wynn、 Shuai Chen、 Tommaso Cavallari、 Áron Monszpart、 Daniyar Turmukhambetov，以及 Victor Adrian Prisacariu

ECCV 2024，口头报告

更多信息请访问：

• 项目主页（包含方法概述和视频）
• arXiv

变更日志

注意：我们尽量确保所有代码更改都向后兼容，即 ECCV 2024 论文的结果仍然可复现。但为保险起见，我们添加了一个标签 eccv_2024_checkpoint，您可以检出该标签以获取用于 ECCV 2024 论文的精确代码版本。

• 2025年11月5日：新增说明，介绍如何使用此代码库运行 标准 ACE（CVPR 2023）。
• 2025年11月6日：增加了 场景坐标重建先验（ICCV 2025） 的功能，默认关闭。
  • ACE/ACE0 的 RGB-D 版本
  • 使用重建先验：深度分布先验和 3D 点云扩散先验

目录

• 安装
• 使用
  • 基本用法
  • 可视化功能
  • 高级用法
    • 优化现有位姿
    • 从部分重建开始
    • RGB-D 重建（“SCR 先验”论文，ICCV 2025）
    • 使用重建先验（“SCR 先验”论文，ICCV 2025）
    • 标准重定位（“ACE”论文，CVPR 2023）
    • 自监督重定位
    • 训练 NeRF 模型或高斯泼溅模型
  • 实用脚本
• 基准测试
  • Nerfacto
  • Splatfacto
• 论文实验
  • 7-Scenes
  • Mip-NeRF 360
  • Tanks and Temples
• 常见问题解答
• 参考文献

安装

本代码使用 PyTorch，并已在 Ubuntu 20.04 系统上搭载 V100 Nvidia 显卡进行了测试，不过它也应该能在其他 Linux 发行版和显卡上正常运行。如果您希望在显存较小的 GPU 上运行 ACE0，请参阅我们的 FAQ。

我们提供了一个预配置的 conda 环境，其中包含了运行代码所需的所有依赖项。 您可以通过以下命令重新创建并激活该环境：

conda env create -f environment.yml
conda activate ace0

本文件中的所有后续命令都需要在仓库根目录下，并且在 ace0 环境中执行。

ACE0 使用 ACE 场景坐标回归模型来表示场景。 为了将相机注册到场景中，它依赖于 DSAC* 论文（Brachmann 和 Rother，TPAMI 2021）中的 RANSAC 实现，该实现是用 C++ 编写的。 因此，您需要构建并安装这些函数的 C++/Python 绑定。 您可以通过以下命令完成这一操作：

cd dsacstar
python setup.py install
cd ..

完成上述步骤后，您就可以开始体验 ACE0 了！

重要提示： 第一次运行 ACE0 时，脚本可能会要求您确认是否同意从 GitHub 下载 ZoeDepth 深度估计代码及其预训练权重。 其许可证和详细信息请参阅 此链接。 ACE0 使用该模型来估计种子图像的深度。 该模型可以被替换，详情请参阅下方的 FAQ 部分。

Docker

如果您更倾向于在 Docker 容器中运行 ACE0，可以使用以下命令启动容器：

docker-compose up -d 

然后，您可以通过以下命令进入容器：

docker exec -it acezero /bin/bash

之后，您可以按照 README 底部所述的高斯泼溅教程进行操作 此处。 请务必将您的图像添加到 docker-compose.yml 中定义的卷中。

使用

我们将介绍如何从头开始使用 ACE0 重建图像，无论是否了解图像的内参。 我们还将说明如何利用 ACE0 优化现有位姿，或者使用部分位姿作为初始条件来进行重建。 此外，我们还会讲解 ACE0 的可视化功能，包括将重建结果导出为视频和 3D 模型。

基本用法

在最简单的情况下，您可以使用 glob 模式指定的一组图像来运行 ACE0。

# 在一组图像上使用默认参数运行
python ace_zero.py "/path/to/some/images/*.jpg" result_folder

请注意，glob 模式周围加了引号，以确保它被传递给 ACE0 脚本，而不是由 shell 展开。

如果你想对视频运行 ACE0，可以先从视频中提取帧，然后在提取的帧上运行 ACE0，详情请参阅我们的 实用脚本。

ACE0 脚本会循环调用 ACE 训练（train_ace.py）和相机注册（register_mapping.py），直到所有图像都已注册到场景表示中，或者迭代之间没有变化为止。

ACE0 重建的结果是结果文件夹中的 poses_final.txt。这些文件包含估计的图像位姿，格式如下：

filename qw qx qy qz x y z focal_length confidence

filename 是相对于仓库根目录的图像文件名。 qw qx qy qz 是相机旋转的四元数表示，x y z 是相机平移。 相机位姿是世界坐标系到相机坐标系的变换，采用 OpenCV 的相机约定。 focal_length 是 ACE0 估计的焦距，或由外部设置的焦距（见下文）。 confidence 是估计的可靠性。如果置信度小于 1000，则应视为不可靠，可能需要忽略。

位姿文件可用于训练 Nerfacto 或 Splatfacto 模型，方法是使用我们的基准测试脚本，详见 Benchmarking。我们的基准测试脚本还允许你仅将我们的位姿文件转换为 Nerfstudio 所需的格式，而无需运行基准测试本身。

结果文件夹中的其他内容说明。

结果文件夹中会包含如下文件：

• iterationX.pt: 第 X 次迭代时的 ACE 场景模型（MLP 网络）。第 X 次迭代时 train_ace.py 的输出。
• iterationX.txt: 第 X 次迭代时 ACE 模型的训练统计信息，例如损失值、位姿统计等。详见 ace_trainer.py。第 X 次迭代时 train_ace.py 的输出。
• poses_iterationX_preliminary.txt: 映射迭代后、重定位前的相机位姿。包含由 MLP 优化后的位姿，而非由 RANSAC 重新估计的位姿。第 X 次迭代时 train_ace.py 的输出。
• poses_iterationX.txt: 第 X 次迭代的最终位姿，即经过重定位后由 RANSAC 重新估计的位姿。第 X 次迭代时 register_mapping.py 的输出。
• poses_final.txt: 场景中图像的最终位姿。对应于最后一次重定位迭代的位姿，即最后一次调用 register_mapping.py 的输出。
• pc_final.ply: ACE0 生成的场景点云，用于可视化或初始化高斯样条。此输出为可选，通过在 ace_zero.py 中使用 --export_point_cloud True 选项来触发。

设置标定参数

使用默认参数时，ACE0 会根据启发式值（图像对角线的 70%）估计图像的焦距。如果你有更准确的焦距估计，可以将其作为初始参数提供。

# 使用焦距初始猜测运行 ACE0
python ace_zero.py "/path/to/some/images/*.jpg" result_folder --use_external_focal_length <focal_length>

使用上述命令，ACE0 会在整个重建过程中不断优化焦距。如果你确信自己的焦距值是正确的，可以禁用焦距优化。

# 使用固定焦距运行 ACE0
python ace_zero.py "/path/to/some/images/*.jpg" result_folder --use_external_focal_length <focal_length> --refine_calibration False

注意： 当前 ACE0 的实现只支持所有图像共享一个焦距值。此外，ACE0 还假定主点位于图像中心，且像素为正方形、无畸变。若要改变这些假设，理论上可行，但需要一定的实现工作量。

可视化功能

ACE0 可以将重建过程可视化为视频。

# 启用可视化运行 ACE0
python ace_zero.py "/path/to/some/images/*.jpg" result_folder --render_visualization True

启用可视化后，ACE0 会将每一帧渲染到子文件夹 renderings 中，并在最后调用 ffmpeg。可视化结果将以视频形式保存在结果文件夹中，名为 reconstruction.mp4。

renderings 文件夹中的其他内容说明。

• frame_N.png: 视频中的第 N 帧。
• iterationX_mapping.pkl: 第 X 次迭代中映射调用的可视化缓冲区。它存储了场景的 3D 点云、用于平滑过渡的上一帧渲染相机以及上一帧的索引。
• iterationX_register.pkl: 第 X 次迭代中重定位调用的可视化缓冲区。

请注意，这会显著减慢重建速度。 或者，你可以不启用可视化，而是将最终重建结果导出为 3D 模型，详情请参阅 实用脚本。

高级用例

你可以将 ACE0 元脚本与自定义调用 train_ace.py 和 register_mapping.py 结合使用，以满足更高级的用例需求。

• train_ace.py: 根据一组带有相应位姿的图像训练 ACE 模型。
• register_mapping.py: 根据 ACE 模型估计场景中图像的位姿。
• ace_zero.py: 可以从现有的 ACE 模型开始。

你可以在这些函数的调用之间自由切换图像集。我们提供了一些高级用例示例，其中也涵盖了我们论文中的一些实验。

优化现有位姿

如果你已经对所有图像的位姿有了初步估计，可以使用 ACE 快速对其进行优化。我们将一次 ACE 映射调用与位姿优化功能结合，并再进行一次重定位调用。

# 运行启用位姿优化的 ACE 映射
python train_ace.py "/path/to/some/images/*.jpg" result_folder/ace_network.pt --pose_files "/path/to/some/images/*.txt" --pose_refinement mlp --pose_refinement_wait 5000 --use_external_focal_length <focal_length> --refine_calibration False

# 重新估计所有图像的位姿
python register_mapping.py "/path/to/some/images/*.jpg" result_folder/ace_network.pt --use_external_focal_length <focal_length> --session ace_network

在这个示例中，ACE 将 7-Scenes 格式的现有位姿作为输入：每张图像对应一个文本文件，其中相机到世界坐标系的位姿以 4×4 矩阵的形式存储。选项 --pose_refinement mlp 启用基于精炼网络的位姿精炼。选项 --pose_refinement_wait 5000 在前 5000 次迭代中冻结位姿，这在从头开始进行位姿精炼建图时可以提高稳定性。

调用 register_mapping.py 后，结果文件夹中将包含精炼后的位姿，保存在 poses_ace_network.txt 文件中。

请注意，上述示例假设焦距已知且固定。如果让 ACE 自动精炼标定参数，则需要将 train_ace.py 精炼得到的焦距传递给 register_mapping.py。完整的示例请参阅 scripts/reconstruct_7scenes_warmstart.sh，其中我们使用 ACE 对 KinectFusion 的位姿进行精炼。

从部分重建开始

如果你已经拥有部分图像的位姿估计，可以使用 ACE0 完成整个重建。首先，对带有位姿的部分图像运行 ACE 建图，生成一个 ACE 场景模型。然后将该模型传递给 ACE0，ACE0 会将剩余的图像注册到该场景中。

# 对带有位姿的部分图像运行 ACE 建图
python train_ace.py "/images/with/poses/*.jpg" result_folder/iteration0_seed0.pt --pose_files "/poses/of/images/*.txt" --use_external_focal_length <focal_length> --refine_calibration False

# 使用 ACE 模型作为种子，并对完整图像集运行 ACE0
python ace_zero.py "/all/images/*.jpg" result_folder --seed_network result_folder/iteration0_seed0.pt --use_external_focal_length ${focal_length} --refine_calibration False

ACE0 会将最终的位姿存储在结果文件夹中的 poses_final.txt 文件中，包含所有图像的位姿。请注意，上述示例假设焦距已知且固定。你也可以让 ACE 或 ACE0 估计或精炼焦距，但需要确保在不同步骤之间正确传递焦距值。

完整的示例请参阅 scripts/reconstruct_t2_training_videos_warmstart.sh，其中我们基于 COLMAP 的部分重建结果来重建 Tanks and Temples 训练场景。更多关于此示例的信息，请参阅 Tanks and Temples 部分。

RGB-D 重建

ACE0 支持基于 场景坐标重建先验（SCR 先验）论文 的 RGB-D 重建方法，该论文发表于 ICCV 2025。你可以通过 ace_zero.py 的 --depth_files 选项为所有图像提供深度图，并将 --depth_use_always 设置为 True 来启用 RGB-D 重建功能。为了获得最佳效果，我们建议使用 SCR 先验论文中提出的 RGB-D 损失函数。

# 使用 RGB-D 图像和推荐的 RGB-D 损失函数运行 ACE0
python ace_zero.py "/path/to/some/images/*.jpg" result_folder --depth_use_always True --depth_files "/path/to/some/depths/*.png" --loss_structure probabilistic --prior_loss_type rgbd_laplace_nll --prior_loss_weight 1.0 --prior_loss_bandwidth 0.1

更多信息请参考 SCR 先验论文及其 代码库。

使用重建先验

ACE0 支持使用 场景坐标重建先验（SCR 先验）论文 中提出的重建先验，该论文发表于 ICCV 2025。可用的先验分为两类：基于预期深度分布的手工先验，以及基于 3D 扩散模型的可学习先验。需要注意的是，这些参数和预训练模型主要针对室内场景设计。在室外场景中使用这些先验可能需要调整手工先验的参数，并针对可学习先验重新训练扩散模型。

可以通过 ace_zero.py 的相应命令行选项启用重建先验。

# 使用基于负对数似然损失的深度分布先验运行 ACE0
python ace_zero.py "/path/to/some/images/*.jpg" result_folder --loss_structure probabilistic --prior_loss_type laplace_nll --prior_loss_weight 0.1 --prior_loss_bandwidth 0.6 --prior_loss_location 1.73

# 或者使用基于 Wasserstein 距离的深度分布先验运行 ACE0
python ace_zero.py "/path/to/some/images/*.jpg" result_folder --loss_structure probabilistic --prior_loss_type laplace_wd --prior_loss_weight 0.1 --prior_loss_bandwidth 0.6 --prior_loss_location 1.73

使用扩散先验需要额外的设置。首先，按照 SCR 先验代码库 的说明安装并激活 ace0_priors conda 环境，因为扩散先验有额外的依赖项。其次，从 这里 下载预训练的扩散先验模型。

# 使用扩散先验运行 ACE0
python ace_zero.py "/path/to/some/images/*.jpg" result_folder --loss_structure "dsac*" --prior_loss_type diffusion --prior_loss_weight 200 --prior_diffusion_model_path /path/to/diffusion_prior.pt

扩散先验（diffusion 文件夹）包含了以下项目的代码：

• denoising-diffusion-pytorch（MIT 许可证）
• projection-conditioned-point-cloud-diffusion（MIT 许可证）
• pvcnn（MIT 许可证）

有关所有重建先验的详细信息，请参阅 SCR 先验代码库 的 README 文件。

标准重定位

ACE0 构建于 ACE 代码库 之上，完全支持 ACE 论文（CVPR 2023）中提出的标准重定位功能。train_ace.py 可用于对带位姿的图像进行建图，而 register_mapping.py 则可用于对查询图像进行重定位。

与 ACE0 不同，标准 ACE（即 train_ace.py + register_mapping.py）支持每张图像使用不同的焦距，具体可通过两个脚本中的 --calibration_files 和 --calibration_file_f_idx 选项实现。

# 使用 ACE 对带位姿的图像进行建图
python train_ace.py "/path/to/mapping/images/*.jpg" result_folder/ace_network.pt --pose_files "/path/to/mapping/poses/*.txt" --calibration_files "/path/to/mapping/calibrations/*.txt"

# 使用 ACE 重新定位查询图像
python register_mapping.py "/path/to/query/images/*.jpg" result_folder/ace_network.pt --calibration_files "/path/to/query/calibrations/*.txt"  --session query

重新定位结果将存储在 poses_query.txt 中。 我们提供了一个评估脚本，用于将估计位姿与查询的真实位姿进行比较，详情请参见 实用脚本。

# 比较估计位姿和真实位姿，假设它们已在同一坐标系中对齐
python eval_poses.py result_folder/poses_query.txt "/path/to/ground/truth/poses/*.txt" --estimate_alignment none

当然，在重新定位设置中，可以通过相应的参数启用 ACE0 提供的所有扩展功能，例如估计共享焦距、使用 RGB-D 图像进行建图、提前停止或优化建图位姿等。

自监督重新定位

您可以使用 ACE0 对一组图像进行建图，然后对另一组图像调用 register_mapping.py 进行重新定位。在此过程中，ACE0 将运行于建图图像集上，而 register_mapping.py 则运行于查询图像集上。

# 在建图图像上运行 ACE0
python ace_zero.py "/path/to/mapping/images/*.jpg" result_folder --use_external_focal_length <focal_length> --refine_calibration False

# 在查询图像上进行重新定位
python register_mapping.py "/path/to/query/images/*.jpg" result_folder/iterationX.pt --use_external_focal_length <focal_length> --session query

您需要将 register_mapping.py 指向上次建图迭代生成的 ACE 模型（例如 iterationX.pt）。重新定位的结果将存储在 poses_query.txt 中。请注意，ACE0 的重建结果仅为近似度量尺度。如果您要将查询位姿与真实位姿进行比较，首先需要拟合一个相似变换。我们为此提供了一个脚本。

# 拟合相似变换以对齐后，比较估计位姿和真实位姿
python eval_poses.py result_folder/poses_query.txt "/path/to/ground/truth/poses/*.txt"

有关评估脚本的更多信息，请参阅 实用脚本。

训练 NeRF 模型或高斯泼溅模型

有关如何在 ACE0 基础上使用 Nerfstudio 的说明，请参阅 基准测试。

实用脚本

视频转数据集

我们提供了一个脚本，可通过 ffmpeg 从 MP4 视频中提取帧。

python datasets/video_to_dataset.py datasets

该脚本会在目标文件夹（此处为 datasets）中查找所有 MP4 文件，并为每段视频提取帧，存入子文件夹 datasets/video_<mp4_file_name> 中。

将 3D 场景导出为点云

我们提供了一个脚本，用于从网络和位姿文件中导出 ACE 点云。

python export_point_cloud.py point_cloud_out.txt --network /path/to/ace_network.pt --pose_file /path/to/poses_final.txt

该脚本可以输出 TXT 或 PLY 文件，具体取决于您指定的输出文件扩展名。如果输出文件扩展名为 .txt，则脚本会将点云以文本格式写入文件，每行包含一个点的坐标 (x y z r g b)。如果输出文件扩展名为 .ply，则脚本会将点云以二进制 PLY 格式写入文件。这两种格式都可以导入大多数 3D 软件中，例如 Meshlab、CloudCompare 等。PLY 格式还可被 Nerfstudio 识别，用于初始化高斯泼溅模型。

注意，您也可以将脚本指向现有的可视化缓冲区 result_folder/renderings/iterationX_mapping.pkl，其中已包含点云，无需再次生成。

点云可以使用 OpenGL 或 OpenCV 坐标约定导出。Nerfstudio 预期使用 OpenCV 坐标。该脚本可以提取稀疏或密集点云。稀疏点云应用了更多滤波器，看起来更干净；而密集点云则更适合高斯泼溅，尤其是在图像数量较多（2000 张以上）时，因为它们能更好地覆盖背景。

将相机导出为网格

我们提供了一个脚本，用于将 ACE 位姿文件导出为显示相机位置的 PLY 文件。

python export_cameras.py /path/to/ace/pose_file.txt /path/to/output.ply

该脚本会根据相机的置信度值对相机进行颜色编码。PLY 格式可以导入大多数 3D 软件中，例如 Meshlab、CloudCompare 等。

评估位姿与（伪）真实位姿

我们提供了一个脚本，用于衡量一组估计位姿与一组真实位姿之间的误差。

python eval_poses.py /path/to/ace/pose_file.txt "/path/to/ground/truth/poses/*.txt"

真实位姿以 glob 模式给出，每个文件包含单张图像的 4x4 相机到世界变换矩阵（例如 7-Scenes 数据集提供的格式）。ACE 估计与真实位姿文件之间的对应关系将通过图像文件名的字母顺序建立。

该脚本计算：

• 注册率，即高于置信度阈值的估计比例（默认：1000 个内点）；
• 准确率，即低于位姿误差阈值的位姿比例（默认：5 cm 和 5°）；
• 旋转和平移误差的中位数；
• 绝对轨迹误差 (ATE) 和相对位姿误差 (RPE)。

由于 ACE0 的位姿仅为近似度量尺度，且处于任意参考框架中，因此在计算误差之前，脚本会先在估计位姿和真实位姿之间拟合一个相似变换。默认情况下，脚本会使用基于 RANSAC 的相机轨迹对齐方法。需要注意的是，ATE 和 RPE 误差通常是在最小二乘法对齐的基础上计算的。您可以通过相应的命令行标志更改对齐方式，或完全禁用对齐（例如在重新定位实验中）。

此外，评估脚本还可以将评估结果保存到文本文件中。

基准测试

我们使用 Nerfstudio 的新视图合成来评估 ACE0 位姿的质量。

注意： 所有论文中的结果均是使用 Nerfstudio v0.3.4 生成的。此后，我们更新了此仓库以支持更高版本的 Nerfstudio。我们验证发现，升级到 Nerfstudio v1.1.4 后，基准测试结果并未发生显著变化。然而，如果您在基准测试中观察到与论文不一致的情况，我们建议您先降级至 Nerfstudio v0.3.4，并使用 eccv_2024_checkpoint Git 标签检出我们的代码。

Nerfacto

在我们的论文中，我们通过训练一个Nerfacto模型，并在特定数据集的训练/测试图像划分上测量PSNR，来对ACE0重建进行基准测试。

要设置基准测试，请按照基准测试README中的说明操作。

请注意，基准测试运行在它自己的conda环境中，因此您需要在重建和基准测试之间切换环境。

基准测试会使用ACE0姿态文件并拟合一个Nerfacto模型。可选地，您也可以使用我们的基准测试脚本生成Nerfstudio的输入文件，而无需运行基准测试，参见--no_run_nerfstudio标志。

如果您确实运行基准测试，默认会应用1/8的图像划分来计算PSNR。我们为[论文实验]提供的脚本可以选择性地使用正确的划分在每个数据集上运行基准测试。

由于基准测试结果存储在一个嵌套结构中，我们提供了一个脚本来提取PSNR值：

# 在提供的顶级文件夹中以子文件夹的形式显示所有场景的基准测试结果
python scripts/show_benchmark_results.py /path/to/top/level/results/folder

该脚本假设文件夹结构为：每个场景都是某个数据集专用顶级文件夹下的一个子文件夹。例如，benchmark/7scenes包含子文件夹chess、fire、heads等。

在对重建结果进行基准测试后，您可以使用Nerfstudio的查看器加载NeRF模型，渲染视频等。

ns-viewer --load-config /path/to/nerf/config.yaml

Splatfacto

使用Splatfacto训练高斯样点与训练Nerfacto模型非常相似。Splatfacto还需要一个点云来初始化样点，您可以使用我们的实用脚本之一导出点云，或者在运行ACE0时设置--export_point_cloud True。我们的基准测试脚本会寻找名为pc_final.ply的文件传递给Nerfstudio。请注意，即使没有找到pc_final.ply文件，Nerfstudio也会继续执行，但此时样点将被均匀初始化，这可能导致质量非常差。您可以在Nerfstudio的日志中查找以下警告，以确认是否预期存在点云但实际缺失：

Warning: load_3D_points set to true but no point cloud found.

除此之外，您只需使用--method splatfacto运行我们的基准测试脚本，详情请参阅基准测试README。前一节提到的show_benchmark_results.py脚本也带有--method splatfacto选项，用于展示Splatfacto模型的基准测试指标。

请注意，我们为[论文实验]提供的所有脚本都支持Nerfacto和Splatfacto的基准测试。只需在每个脚本的顶部切换方法即可。我们建议您查看这些脚本，并将其用作您自己实验的模板。

论文实验

我们提供了运行论文主要实验的脚本。此外，在下面的相应章节中，我们也提供了所有这些实验的预计算结果以及相应的可视化内容。

7-Scenes

设置数据集。

# 在datasets文件夹中设置7-Scenes数据集
cd datasets
# 下载并解压数据集
python setup_7scenes.py
# 返回根目录
cd ..

该脚本可以选择性转换数据集为ACE格式、下载替代的伪真值姿态、校准深度图等。然而，对于ACE0实验来说，这些步骤并非必需。

（基准测试可选）为7-Scenes数据集创建基准测试的训练/测试划分，详情请参阅基准测试README。

python scripts/create_splits_7scenes.py datasets/7scenes split_files

重建每个场景（对应于表1左侧的“ACE0”）。

bash scripts/reconstruct_7scenes.sh

默认情况下，该脚本会在启用基准测试的情况下运行（请确保已设置好基准测试，参见Nerfacto基准测试），使用Nerfacto且禁用可视化。您可以通过修改脚本中的相应标志来改变这一行为，例如改为训练高斯样点而非NeRF模型。ACE0重建文件将存储在reconstructions/7scenes中，而基准测试结果则存储在benchmark/7scenes中。要显示基准测试结果，可以调用：

python scripts/show_benchmark_results.py benchmark/7scenes

要使用ACE改进KinectFusion的姿态（对应于表1左侧的“KF+ACE0”），请运行：

bash scripts/reconstruct_7scenes_warmstart.sh
# 显示基准测试结果
python scripts/show_benchmark_results.py benchmark/7scenes_warmstart

7-Scenes的预计算姿态和重建视频可在这里找到。这些结果来自与我们用于论文结果不同的ACE0运行，但PSNR值非常接近（平均误差±0.1dB PSNR）。

对于论文中的部分实验（见表1右侧），我们在每个场景的子集图像上运行ACE0和基线模型。我们提供了这些图像列表，以及它们如何被划分为视图合成基准测试的数据集：每场景200张图像和每场景50张图像。

Mip-NeRF 360

设置数据集。

# 在datasets文件夹中设置Mip-NeRF 360数据集
cd datasets
# 下载并解压数据集
python setup_mip360.py

# 返回根目录
cd ..

该脚本可以选择性地将 COLMAP 真值转换为 ACE 格式，但在 ACE0 实验中并非必需。

（基准测试的可选步骤）为 Mip-NeRF 360 数据集创建基准训练/测试划分，详情请参阅 Benchmark README。 这使用了一种与默认基准划分略有不同的 1/8 划分。

python scripts/create_splits_mip360.py datasets/mip360 split_files

重建每个场景（对应于表 2(b) 中的“ACE0”）。

bash scripts/reconstruct_mip360.sh

默认情况下，脚本会启用基准测试模式运行（请确保已设置好基准测试环境，详见 Nerfacto 基准测试），使用 Nerfacto 并禁用可视化功能。
可通过修改脚本中的相应标志来改变此行为，例如改为训练 Gaussian splats 而不是 NeRF 模型。
ACE0 的重建文件将存储在 reconstructions/mip360 目录下，而基准测试结果则存储在 benchmark/mip360 目录下。
要查看基准测试结果，可运行以下命令：

python scripts/show_benchmark_results.py benchmark/mip360

Mip-NerF 360 数据集的预计算位姿和重建视频可在此处找到：这里。
这些结果来自与我们论文结果所用的 ACE0 运行不同的版本，但 PSNR 值非常接近（平均相差 ± 0.1dB）。

Tanks and Temples

您需要手动 下载数据集。 我们的数据集脚本假设您已将各组压缩包下载至 datasets/t2 目录，且未解压：

datasets/t2/training.zip
datasets/t2/training_videos.zip
datasets/t2/intermediate.zip
datasets/t2/intermediate_videos.zip
datasets/t2/advanced.zip
datasets/t2/advanced_videos.zip

设置数据集。

# 在 datasets 文件夹中设置 T&T 数据集
cd datasets
# 解压数据集
python setup_t2.py
# 返回根目录
cd ..

可选地，脚本还可以下载并设置 COLMAP 真值位姿，并将其转换为 ACE 格式。
这对于从稀疏 COLMAP 重建开始重建数据集视频的 ACE0 实验是必需的。
调用脚本时需添加 --with-colmap 参数。
这将在 datasets 文件夹中创建一个额外的 t2_colmap 目录，其中每个场景文件夹不仅包含图像文件，还包含对应的 *_pose.txt 文件，内含 COLMAP 提供的 4x4 相机到世界变换矩阵位姿。
此外，每个场景还会生成一个单独的 focal_length.txt 文件，记录 COLMAP 估计的焦距。

我们为 Tanks and Temples 数据集提供了按场景组划分的脚本，即训练组、中级组和高级组。
以下说明以训练组为例，但中级和高级组的脚本类似。

从几百张图像重建每个场景（对应于表 3 左侧的“ACE0”）。

bash scripts/reconstruct_t2_training.sh

默认情况下，脚本会启用基准测试模式运行（请确保已设置好基准测试环境，详见 Nerfacto 基准测试），使用 Nerfacto 并禁用可视化功能。
可通过修改脚本中的相应标志来改变此行为，例如改为训练 Gaussian splats 而不是 NeRF 模型。
ACE0 的重建文件将存储在 reconstructions/t2_training 目录下，而基准测试结果则存储在 benchmark/t2_training 目录下。
要查看基准测试结果，可运行以下命令：

python scripts/show_benchmark_results.py benchmark/t2_training

请注意，Tanks and Temples 数据集无需生成基准测试划分文件。
基准测试将采用默认的 1/8 划分。

要重建每个场景的完整视频（对应于表 3 右侧的“ACE0”），可运行以下命令：

bash scripts/reconstruct_t2_training_videos.sh
# 查看基准测试结果
python scripts/show_benchmark_results.py benchmark/t2_training_videos

若要从 COLMAP 重建开始重建每个场景的完整视频（对应于表 3 左侧的“Sparse COLMAP + ACE0”），可运行以下命令：

bash scripts/reconstruct_t2_training_videos_warmstart.sh
# 查看基准测试结果
python scripts/show_benchmark_results.py benchmark/t2_training_videos_warmstart

请注意，最后这个实验要求您在设置数据集时使用 --with-colmap 参数。
代码会首先对带有 COLMAP 位姿的图像应用 ACE 映射，以创建初始场景模型。
然后将该模型传递给 ACE0，作为完整视频重建的种子。
在本示例中，我们信任 COLMAP 的焦距估计，并在整个重建过程中保持其固定。

Tanks and Temples 数据集的预计算位姿和重建视频可在此处找到：训练场景、中级场景、高级场景。
这些结果来自与我们论文结果所用的 ACE0 运行不同的版本，但 PSNR 值非常接近（平均相差 ± 0.3dB）。

常见问题解答

问：我想用我的图像生成 Gaussian splats。我需要做什么？

按照本文档开头的说明准备 ACE0：创建 ACE0 环境、编译 DSAC* 绑定，并 设置 Nerfstudio。
然后，在您的图像集上运行以下命令：

# 激活我们的 conda 环境
conda activate ace0

# 运行 ACE0 重建并导出点云
python ace_zero.py "/path/to/some/images/*.jpg" result_folder --export_point_cloud True

# 切换到 Nerfstudio conda 环境
conda activate nerfstudio

# 将 ACE0 输出转换为 Nerfstudio 兼容格式，并运行 Splatfacto 训练（也会进行评估，但速度很快）
python -m benchmarks.benchmark_poses --pose_file result_folder/poses_final.txt --output_dir benchmark_folder --images_glob_pattern "/path/to/some/images/*.jpg" --method splatfacto

# 查看高斯喷溅图
ns-viewer --load-config benchmark_folder/nerf_data/nerf_for_eval/splatfacto/run/config.yaml

问：我在进行ACE0重建时遇到了显存不足的问题，该怎么办？

答： 论文中的所有实验都是在16GB显存的GPU（如NVIDIA V100/T4）上完成的，默认设置在这种GPU上应该可以正常运行。 大部分显存被ACE训练缓冲区占用（最多约8GB）。 你可以通过添加--training_buffer_cpu True标志来将训练缓冲区放在CPU上，这样会牺牲一些重建速度，但显存占用会降低到约1GB。

问：我有一组包含不同尺寸、不同宽高比和不同内参的图像，能使用ACE0吗？

答： 不行。ACE0假设所有图像共享相同的内参，尤其是焦距。 这是当前实现的限制，而非方法本身的局限性。支持具有不同内参的图像理论上是可行的，但需要一定的开发工作，特别是在refine_calibration.py中进行修改。

问：ACE0会估计除焦距之外的其他内参吗？

答： 不会。ACE0假设主点位于图像中心，且像素为正方形、无畸变。只有所有图像共用的焦距是ACE0会估计和/或优化的唯一内参。

问：我的图像来自复杂的相机模型，例如存在严重畸变的情况，能使用ACE0吗？

答： 不行。场景坐标回归网络或许能够去除部分畸变，但效果可能有限。ACE的重投影损失以及RANSAC位姿估计算法都基于针孔相机模型。如果要处理畸变，这些部分需要引入相机畸变模型。如果已知畸变参数，建议在将图像输入ACE0之前先对其进行去畸变处理。

问：如何使用ZoeDepth以外的深度估计结果来运行ACE0？

答： 如果你已经预先计算好了深度图，可以通过--depth_files "/path/to/depths/*.png"参数调用ace_zero.py。此时，ACE0将直接使用提供的深度图作为种子图像的深度信息，而不再进行深度估计。否则，可以修改dataset_io.py中的get_depth_model()和estimate_depth()函数，以使用除ZoeDepth之外的其他深度估计器。需要注意的是，我们在实验中发现深度估计模型对最终结果的影响较小。

问：ACE0能否从少量稀疏视角的图像中进行重建？

答： 可以，但这种情况下对ACE0来说比较困难。我们预计其他方法，甚至COLMAP，在这种情况下表现会更好。ACE0依赖于图像之间有足够的视觉重叠，尤其是在将新图像注册到重建结果中时。你可以在运行ace_zero.py时通过--registration_confidence参数降低注册阈值，将其设置为300或100，但当阈值过低时，ACE0可能会变得不稳定。ACE0最适合用于密集覆盖场景的重建，并能在合理时间内完成大量图像的处理。

出版物

如果你在自己的工作中使用了ACE0或其代码的一部分，请引用以下文献：

@inproceedings{brachmann2024acezero,
    title={Scene Coordinate Reconstruction: Posing of Image Collections via Incremental Learning of a Relocalizer},
    author={Brachmann, Eric and Wynn, Jamie and Chen, Shuai and Cavallari, Tommaso and Monszpart, {\'{A}}ron and Turmukhambetov, Daniyar and Prisacariu, Victor Adrian},
    booktitle={ECCV},
    year={2024},
}

本代码基于ACE重新定位器，并使用DSAC*位姿估计算法。请一并参考以下文献：

@inproceedings{brachmann2023ace,
    title={Accelerated Coordinate Encoding: Learning to Relocalize in Minutes using RGB and Poses},
    author={Brachmann, Eric and Cavallari, Tommaso and Prisacariu, Victor Adrian},
    booktitle={CVPR},
    year={2023},
}

@article{brachmann2021dsacstar,
  title={Visual Camera Re-Localization from {RGB} and {RGB-D} Images Using {DSAC}},
  author={Brachmann, Eric and Rother, Carsten},
  journal={TPAMI},
  year={2021}
}

如果你使用了与“场景坐标重建先验”论文（ICCV 2025）相关的能力，请引用该论文。这包括RGB-D重建、概率损失函数的使用以及扩散先验等。

@inproceedings{bian2024scrpriors,
    title={Scene Coordinate Reconstruction Priors},
    author={Bian, Wenjing and Barroso-Laguna, Axel and Cavallari, Tommaso and Prisacariu, Victor Adrian and Brachmann, Eric},
    booktitle={ICCV},
    year={2025},
}

ACE0使用ZoeDepth估计种子图像的深度，请考虑引用以下文献：

@article{bhat2023zoedepth,
  title={Zoe{D}epth: Zero-shot transfer by combining relative and metric depth},
  author={Bhat, Shariq Farooq and Birkl, Reiner and Wofk, Diana and Wonka, Peter and M{\"u}ller, Matthias},
  journal={arXiv},
  year={2023}
}

本仓库依赖Nerfstudio进行基准测试，请根据其文档中的说明进行引用。

许可证

版权所有 © Niantic, Inc. 2024。专利申请中。 保留所有权利。 详细条款请参阅许可证文件。

ACE0 (ACE Zero) 快速上手指南

ACE0 是一个基于增量学习的场景坐标重建工具，能够通过图像集合自动估计相机位姿并构建场景表示。它适用于从无序图像或视频中恢复 3D 结构，并可作为 NeRF 或 3D Gaussian Splatting 的前端输入。

环境准备

• 操作系统: Linux (推荐 Ubuntu 20.04)，其他发行版可能兼容。
• 硬件要求: NVIDIA GPU (测试环境为 V100)。显存较小的显卡请参考相关优化策略。
• 核心依赖:
  • Python (通过 Conda 管理)
  • PyTorch
  • C++ 编译器 (用于编译 DSAC* RANSAC 绑定)
  • FFmpeg (可选，用于生成重建过程视频)

安装步骤

1. 创建并激活 Conda 环境

项目提供了预配置的 environment.yml 文件，包含所有必要的 Python 依赖。

conda env create -f environment.yml
conda activate ace0

提示：如果下载依赖较慢，建议在创建环境前配置国内镜像源（如清华源）：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/

2. 编译 C++/Python 绑定

ACE0 依赖 DSAC* 论文的 RANSAC 实现（C++ 编写），需要手动编译并安装绑定。

cd dsacstar
python setup.py install
cd ..

3. 首次运行确认

首次运行时，脚本会提示下载 ZoeDepth 深度估计模型及其预训练权重（用于种子图像的深度估计）。请根据提示确认下载，或参考官方文档替换为其他深度模型。

注意：以下所有命令需在仓库根目录下执行，且确保已激活 ace0 环境。

基本使用

最简单的重建流程

对一组图像进行从零开始的场景重建和位姿估计。支持使用通配符指定图像路径。

# 对指定路径下的所有 jpg 图像运行 ACE0，结果保存至 result_folder
python ace_zero.py "/path/to/some/images/*.jpg" result_folder

关键提示：请务必给图像路径的通配符加上双引号，以防止 Shell 提前展开路径，确保路径字符串正确传递给脚本。

输出结果说明

运行完成后，主要结果位于 result_folder 中：

• poses_final.txt: 最终估计的相机位姿文件。格式为：文件名 四元数 (qw qx qy qz) 平移 (x y z) 焦距 置信度。
  • 若置信度低于 1000，建议视为不可靠结果。
  • 位姿遵循 OpenCV 相机约定（世界到相机变换）。
• pc_final.ply: (可选) 导出的场景点云，可用于可视化或初始化 3D Gaussian Splatting。需添加参数 --export_point_cloud True 启用。

自定义焦距（可选）

默认情况下，ACE0 会根据图像对角线的 70% 启发式估计焦距。如果你已知准确的焦距参数：

# 使用外部焦距作为初始值，并在重建过程中继续微调
python ace_zero.py "/path/to/some/images/*.jpg" result_folder --use_external_focal_length <focal_length>

# 使用固定焦距，不进行微调
python ace_zero.py "/path/to/some/images/*.jpg" result_folder --use_external_focal_length <focal_length> --refine_calibration False

可视化重建过程（可选）

生成重建过程的演示视频（会显著降低运行速度）：

python ace_zero.py "/path/to/some/images/*.jpg" result_folder --render_visualization True

生成的视频将保存为 result_folder/reconstruction.mp4。