例如，默认情况下密集特征会存储在内存中。如果重建的是大型场景或 RAM 较少，则应将其写入缓存文件，并按需加载。通过 Python API，我们可以传递配置更新：

refiner = PixSfM(conf={"dense_features": {"use_cache": True}})

或者等效地使用命令行，通过 dotlist：

python -m pixsfm.refine_hloc reconstructor [...] dense_features.use_cache=true

我们还在 pixsfm/configs/ 目录中提供了涵盖主要用例的即用型配置模板。例如，pixsfm/configs/low_memory.yaml 可降低内存消耗，以便处理大型场景，使用方法如下：

refiner = PixSfM(conf="low_memory")
# 或
python -m pixsfm.refine_hloc reconstructor [...] --config low_memory

如果相机位姿已知，我们可以直接从现有的参考 COLMAP 模型中三角测量出 3D 点云，命令如下：

model, _ = refiner.triangulation(..., path_to_reference_model, ...)

或者

python -m pixsfm.refine_hloc triangulator [...] \
    --reference_sfm_model path_to_reference_model

默认情况下，相机位姿和内参会通过光束法平差进行优化。若希望保持它们不变，只需覆盖相应的选项即可：

conf = {"BA": {"optimizer": {
    "refine_focal_length": False,
    "refine_extra_params": False,  # 畸变参数
    "refine_extrinsics": False,    # 相机位姿
}}}
refiner = PixSfM(conf=conf)
refiner.triangulation(...)

或者等价地：

python -m pixsfm.refine_hloc triangulator [...] \
  'BA.optimizer={refine_focal_length: false, refine_extra_params: false, refine_extrinsics: false}'

若要精炼存储在 hloc HDF5 特征文件中的特征点：

from pixsfm.refine_hloc import PixSfM
refiner = PixSfM()
keypoints, _, _ = refiner.refine_keypoints(
    path_to_output_keypoints.h5,
    path_to_input_keypoints.h5,
    path_to_list_of_image_pairs,
    path_to_matches.h5,
    path_to_image_dir,
)

若要精炼存储在 COLMAP 数据库中的特征点：

from pixsfm.refine_colmap import PixSfM
refiner = PixSfM()
keypoints, _, _ = refiner.refine_keypoints_from_db(
    path_to_output_database,  # 若为原地精炼，传入 path_to_input_database
    path_to_input_database,
    path_to_image_dir,
)

无论哪种情况，都有对应的命令行接口。

若要精炼存储在文件中的 3D 模型：

from pixsfm.refine_colmap import PixSfM
refiner = PixSfM()
model, _, _, = refiner.refine_reconstruction(
    path_to_input_model,
    path_to_output_model,
    path_to_image_dir,
)

使用命令行接口：

python -m pixsfm.refine_colmap bundle_adjuster \
    --input_path path_to_input_model \
    --output_path path_to_output_model \
    --image_dir path_to_image_dir

1. 若要从头重新计算参考特征点，需传入参考图像的路径：

from pixsfm.localization import QueryLocalizer
localizer = QueryLocalizer(
    reference_model,  # pycolmap.Reconstruction 3D 模型
    image_dir=path_to_reference_image_dir,
    dense_features=cache_path,  # 可选：缓存到文件以供后续重用
)
pose_dict = localizer.localize(
    pnp_points2D      # 具有有效 3D 对应关系的特征点 (N, 2)
    pnp_point3D_ids,  # 重建中对应 3D 点的 ID
    query_camera,     # pycolmap.Camera
    image_path=path_to_query_image,
)
if pose_dict["success"]:
    # 查询图像相对于世界坐标系的四元数和平移向量
    qvec, tvec = pose_dict["qvec"], pose_dict["tvec"]

默认的定位配置可通过 QueryLocalizer.default_conf 获取。

2. 或者，如果在像素级精度的 SfM 过程中已经计算了密集的参考特征点，则更高效的做法是直接复用这些特征点：

refiner = PixSfM()
model, outputs = refiner.reconstruction(...)
features = outputs["feature_manager"]
# 或者手动加载特征点
features = pixsfm.extract.load_features_from_cache(
    refiner.resolve_cache_path(output_dir=path_to_output_sfm)
)
localizer = QueryLocalizer(
    reference_model,  # pycolmap.Reconstruction 3D 模型
    dense_features=features,
)

我们首先需要安装 ETH3D多视图评估工具：

sudo apt install libpcl-dev  # 仅限 Linux
git clone git@github.com:ETH3D/multi-view-evaluation.git
cd multi-view-evaluation && mkdir build && cd build
cmake .. && make -j

然后，我们可以评估使用Pixel-Perfect SfM三角测量得到的稀疏3D点云的精度，例如在带有SuperPoint关键点的庭院场景上：

python -m pixsfm.eval.eth3d.triangulation \
    --scenes courtyard \
    --methods superpoint \
    --tag pixsfm

• 省略 --scenes 和 --methods 可以运行所有场景和所有特征检测器。
• 结果默认会写入 ./outputs/ETH3D/
• 使用 --tag some_run_name 来区分不同的运行。
• 添加 --config norefine 来关闭任何优化，或者使用 dotlist KA.apply=false BA.apply=false
• 添加 --config photometric 来运行光度BA（不进行关键帧选择）。

为了汇总结果并比较不同运行，例如有无优化的情况，我们运行：

python -m pixsfm.eval.eth3d.plot_triangulation \
    --scenes courtyard \
    --methods superpoint \
    --tags pixsfm raw

在所有场景和所有检测器上运行应该会得到如下结果（±1%）：

----场景---- -关键点- -标签-- -X cm处精度- 完整性 @ X cm
                                  1.0   2.0   5.0   1.0   2.0   5.0 
----------------------------------------------------------------------
室内        sift        raw    75.95 85.50 92.88  0.21  0.88  3.65
                          pixsfm 83.16 89.94 94.94  0.25  0.96  3.77
              superpoint  raw    78.96 87.77 94.55  0.64  2.36  9.39
                          pixsfm 89.93 94.09 97.04  0.76  2.62  9.85
              r2d2        raw    67.91 80.25 90.45  0.55  2.12  8.85
                          pixsfm 81.09 87.78 93.41  0.67  2.32  9.04
----------------------------------------------------------------------
室外        sift        raw    57.70 72.90 86.41  0.06  0.34  2.46
                          pixsfm 68.10 80.57 91.59  0.08  0.42  2.75
              superpoint  raw    53.63 68.93 83.27  0.11  0.64  4.43
                          pixsfm 71.83 82.65 92.06  0.18  0.89  5.40
              r2d2        raw    49.33 66.21 83.37  0.11  0.55  3.62
                          pixsfm 67.94 81.02 91.68  0.16  0.71  3.99

本次评估的结果可能与论文中报告的数字有所不同。然而，趋势是相似的，论文中的结论仍然成立。这种差异是由于 pixsfm 代码的改进以及 SuperPoint 实现的变化：我们最初使用的是 PatchFlow 的设置，后来切换到了 hloc，hloc 性能更好且更容易安装。

同样地，我们评估基于从其他视角三角测量得到的稀疏3D模型的相机位姿估计精度：

python -m pixsfm.eval.eth3d.localization --tag pixsfm

再次强调，我们也可以只针对部分场景或关键点检测器进行运行。为了汇总结果并比较不同运行，例如有无关键帧选择和光束法平差的情况，我们运行：

python -m pixsfm.eval.eth3d.plot_localization --tags pixsfm raw

随后我们应该会得到如下表格和图表（±2%）：

-关键点- -标签-- -AUC @ X cm (%)--
                    0.1    1    10  
sift        raw    16.92 55.39 81.15
            pixsfm 23.08 60.47 84.01
superpoint  raw    15.38 63.41 87.24
            pixsfm 41.54 73.86 89.66
r2d2        raw     6.15 51.70 83.46
            pixsfm 23.85 62.41 86.89

对于0.1cm阈值的结果可能会因环境配置不同而有所变化，因此可能与论文中报告的数字存在差异。这可能是由于PyTorch和COLMAP依赖库的更新所致。我们正在调查这个问题，欢迎任何帮助！

dense_features:  # 精细化特征
  model:  # 提取特征的 CNN
    name: s2dnet  # 定义在 pixsfm/features/models/ 中的模型名称
    num_layers: 1  # 输出层的数量（模型特定参数）
  device: auto  # CPU、CUDA 或根据 CUDA 是否可用自动选择
  max_edge: 1600  # 将图像缩放，使最长边达到此值
  resize: LANCZOS  # 图像缩放时使用的插值算法
  pyr_scales: [1.0]   # 在多个尺度上提取的特征进行拼接
  fast_image_load: false  # 对大图像进行近似缩放
  l2_normalize: true  # 是否对特征进行归一化，使其具有单位范数
  sparse: true  # 是否存储稀疏的特征块而非完整的特征图
  patch_size: 8  # 如果是稀疏存储，特征块的大小
  dtype: half  # 存储特征时的数据类型，半精度浮点或双精度
  use_cache: false  # 是否将特征缓存到文件中，还是保留在内存中
  overwrite_cache: false  # 如果缓存文件已存在，是否覆盖
  cache_format: chunked
interpolation:
  nodes: [[0.0, 0.0]]  # 用于计算代价的网格，默认为单个点
  mode: BICUBIC  # 插值算法
  l2_normalize: true
  ncc_normalize: false  # 仅当 nodes 的数量大于 1 时有效，主要用于光度一致性
mapping:  # pixsfm.refine_colmap.PixSfM
  dense_features: ${..dense_features}
  KA:  # 特征点调整
    apply: true  # 是否执行，否则跳过
    strategy: featuremetric  # 常规策略，或 alternatively topological_reference（速度更快）
    interpolation: ${...interpolation}  # 可以为 KA 使用不同的插值方法
    level_indices: null  # 可以优化部分层级，默认为全部
    split_in_subproblems: true  # 并行化优化过程
    max_kps_per_problem: 50  # 并行化参数，数值越小越节省内存，若为 -1 则较为保守
    optimizer:  # 优化问题及求解
      loss:
        name: cauchy  # 损失函数名称，可选 {huber, soft_l1, ...}
        params: [0.25]  # 损失函数特定参数
      solver:
        function_tolerance: 0.0
        gradient_tolerance: 0.0
        parameter_tolerance: 1.0e-05
        minimizer_progress_to_stdout: false  # 不显示进度条
        max_num_iterations: 100  # 最大优化迭代次数
        max_linear_solver_iterations: 200
        max_num_consecutive_invalid_steps: 10
        max_consecutive_nonmonotonic_steps: 10
        use_inner_iterations: false
        use_nonmonotonic_steps: false
        num_threads: 1
      root_regularize_weight: -1  # 通过向根节点添加边来防止漂移，若为 -1 则禁用
      print_summary: false  # 是否在完成时打印详细摘要
      bound: 4.0  # 相对于初始值的距离约束（以像素为单位）
      num_threads: -1  # 若分批并行化，则线程数
  BA:  #  Bundle Adjustment
    apply: true  # 是否执行，否则跳过
    strategy: feature_reference  # 常规策略，或 alternatively {costmaps, patch_warp}
    interpolation: ${...interpolation}  # 可以为 BA 使用不同的插值方法
    level_indices: null  # 可以优化部分层级，默认为全部
    max_tracks_per_problem: 10  # 参考点/代价图的并行化，数值越小越节省内存
    num_threads: -1
    optimizer:
      loss:  # 配置与 KA.optimizer.loss 相同
      solver:  # 配置与 KA.optimizer.solver 相同
      print_summary: false
      refine_focal_length: true  # 是否优化焦距
      refine_principal_point: false  # 是否优化主点
      refine_extra_params: true  # 是否优化畸变参数
      refine_extrinsics: true  # 是否优化相机位姿
    references:  # 若策略为 feature_reference
      loss:  # 计算鲁棒均值时需要最小化的量
        name: cauchy
        params: [0.25]
      iters: 100  # 计算鲁棒均值的迭代次数
      num_threads: -1
    repeats: 1
localization:  # pixsfm.localization.main.QueryLocalizer
  dense_features: ${..dense_features}
  target_reference: nearest  # 如何选择参考点，可选 {nearest, robust_mean, all_observations}
  overwrite_features_sparse: null  # 仅在查询定位时覆盖 dense_features.sparse
  references:  # 如何计算参考点
    loss:  # 计算鲁棒均值时需要最小化的量，与 BA.references.loss 相同
    iters: 100
    keep_observations: true  # 对于 target_reference 中的 {nearest, all_observations} 是必需的
    num_threads: -1
  max_tracks_per_problem: 50  # 参考点的并行化，数值越小越节省内存
  unique_inliers: min_error  # 如何为每个 3D 点选择唯一的匹配点
  QKA:  # 查询特征点调整
    apply: true  # 是否执行，否则跳过
    interpolation: ${...interpolation}
    level_indices: null
    feature_inlier_thresh: -1  # 丢弃特征误差较高的点，若为 -1 则禁用
    stack_correspondences: False # 将相同特征点的参考堆叠在一起
    optimizer:
      loss:  # 配置与 KA.optimizer.loss 相同
        name: trivial  # L2 损失，无鲁棒性
        params: []
      solver:  # 配置与 KA.optimizer.solver 相同
      print_summary: false
      bound: 4.0  # 相对于初始值的距离约束（以像素为单位）
  PnP:
    estimation:  # pycolmap.absolute_pose_estimation
      ransac:
        max_error: 12  # 内点阈值，以像素为单位的重投影误差
        estimate_focal_length: false  # 若焦距未知
    refinement:  # pycolmap.absolute_pose_estimation 中的精炼步骤
    	refine_focal_length: false
    	refine_extra_params: false
  QBA:  # 查询 Bundle Adjuster
    apply: true  # 是否执行，否则跳过
    interpolation: ${...interpolation}
    level_indices: null
    optimizer:
      loss:  # 配置与 KA.optimizer.loss 相同
      solver:  # 配置与 KA.optimizer.solver 相同
      print_summary: false
      refine_focal_length: false
      refine_principal_point: false
      refine_extra_params: false

请注意，该配置通过 omegaconf 支持 变量插值。

主要改进包括：

• dense_features
  • 以稀疏块形式存储：sparse=true
  • 减小块的大小：patch_size=8（或更小）
  • 存储到缓存文件中：use_cache=true
• KA
  • 将优化过程分块，每次只加载部分特征：split_in_subproblems=true
  • 每个分块最多优化约50个关键点：max_kps_per_problem=50
• BA
  • 使用代价图近似：strategy=costmaps（详见论文C节）

一些输出分辨率较低的关键点检测器，如D2-Net，预测的关键点定位不够准确。在这种情况下，精炼非常有益，但默认参数并不理想。需要增大补丁尺寸并使用多层特征。示例配置见 pixsfm_eth3d_d2net，用于在ETH3D数据集上评估D2-Net。