Hierarchical-Localization 安装与常见问题解决手册

1. 项目简介

Hierarchical-Localization (hloc) 是一个基于深度学习的图像定位与三维重建工具箱，支持多种特征提取与匹配方法（如 SuperPoint、LightGlue、SuperGlue、SIFT、LoFTR 等），常用于结构光重建、视觉定位、SLAM 等任务。

2. 安装流程

2.1 环境准备

推荐使用 conda 创建独立 Python 环境（如 Python 3.8/3.9/3.10）。
建议使用 Ubuntu 20.04/22.04，CUDA 11.8+，PyTorch 1.12+。

bash 复制代码

conda create -n hloc python=3.9
conda activate hloc

2.2 安装依赖

方式一：requirements.txt

bash 复制代码

pip install -r requirements.txt

方式二：手动安装主要依赖

bash 复制代码

pip install torch torchvision
pip install opencv-python matplotlib tqdm h5py scipy
pip install pycolmap
# LightGlue/SuperGlue/LoFTR等可选依赖见下文

方式三：安装特定特征/匹配器

LightGlue 依赖需单独安装（且需能访问 GitHub）：
bash 复制代码
```
pip install git+https://github.com/cvg/LightGlue
```

LoFTR 依赖：

bash 复制代码

pip install kornia
pip install git+https://github.com/zju3dv/LoFTR

3. 常见问题与解决办法

3.1 pip/conda 安装依赖失败

问题：

pip install 时出现 Failed to connect to github.com 或 Could not find a version that satisfies the requirement ...。

原因：

国内网络无法访问 GitHub 或 PyPI。
requirements.txt 中有 git+https 依赖，镜像源无效。

解决办法：

科学上网，或在能访问 GitHub 的环境下载依赖源码后本地安装。
对于 git+https 依赖（如 LightGlue），可手动 clone 后 pip install .。

对于 PyPI 包，可用清华/阿里等镜像：

bash 复制代码

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3.2 权重文件下载与格式问题

问题：

NetVLAD/DELG 等全局特征权重 .mat 文件加载时报 MatlabOpaque 错误或 AttributeError: 'MatlabOpaque' object has no attribute 'weights'。

原因：

权重文件为 MATLAB v7.3 (HDF5) 格式，scipy 只能解析 v7/v7.2 (Level 5) 格式。
权重文件结构与 hloc 代码不兼容。

解决办法：

优先下载 hloc 官方推荐的 v7/v7.2 权重 ，如 NetVLAD 官方权重。
用 file xxx.mat 检查格式，若为 HDF5，需用 MATLAB 重新保存为 v7/v7.2 格式：
matlab 复制代码
```
load('xxx.mat');
save('xxx_v7.mat', 'net', '-v7');
```
若无 MATLAB，可在社区求助转换。

3.3 NumPy 2.x 兼容性问题

问题：

A module that was compiled using NumPy 1.x cannot be run in NumPy 2.2.6 as it may crash.
RuntimeError: Could not infer dtype of numpy.float32

原因：

PyTorch、OpenCV 等依赖未适配 NumPy 2.x。

解决办法：

降级 NumPy 到 1.x：
bash 复制代码
```
pip install "numpy<2"
```

3.4 hloc/pipeline 参数与文件名不匹配

问题：

AssertionError: outputs/features.h5 或 outputs/matches.h5 文件不存在。
KeyError: 'superpoint_lightglue'。

原因：

传递给 reconstruction.main 的特征/匹配文件名与实际生成文件名不一致。
hloc 版本不包含 LightGlue 配置。

解决办法：

特征文件名 应为 outputs/feats-superpoint-n4096-r1024.h5（或配置中 output 字段对应的名字）。
匹配文件名 应为 outputs/matches-superpoint-lightglue_pairs.txt.h5。

代码中应这样写：

python 复制代码

features_name = feature_conf["output"]
features_path = outputs / f"{features_name}.h5"
matches_path = outputs / f"{match_conf['output']}_{pairs_path.stem}.h5"

若 confs["superpoint_lightglue"] 不存在，手动定义：

python 复制代码

match_conf = {
    "output": "matches-superpoint-lightglue",
    "model": {"name": "lightglue", "features": "superpoint"}
}

3.5 路径类型错误

问题：

TypeError: unsupported operand type(s) for /: 'str' and 'str'
TypeError: expected str, bytes or os.PathLike object, not list

原因：

hloc 期望参数为 Path 类型，传入了字符串或列表。

解决办法：

用 Path 包装目录和文件路径：

python 复制代码

from pathlib import Path
images_dir = Path('/path/to/images')

3.6 其它常见问题

3.6.1 CUDA/显存不足

可用 --force_cpu 或设置 CUDA_VISIBLE_DEVICES='' 只用 CPU。
降低 max_keypoints、resize_max 等参数。

3.6.2 COLMAP/pycolmap 报错

确保已正确安装 COLMAP 和 pycolmap，且版本兼容。
Ubuntu 下推荐用 conda/pip 安装 pycolmap，或用官方 release 安装 COLMAP。

4. 推荐的最简 pipeline 示例

python 复制代码

from pathlib import Path
from hloc import extract_features, match_features, reconstruction
import itertools

images_dir = Path('/path/to/images')
outputs = Path('outputs')
outputs.mkdir(exist_ok=True)

images = sorted([f for f in images_dir.iterdir() if f.suffix.lower() in ['.jpg', '.jpeg', '.png']])
pairs_path = outputs / 'pairs.txt'
with open(pairs_path, 'w') as f:
    for i, j in itertools.combinations([img.name for img in images], 2):
        f.write(f"{i} {j}\n")

feature_conf = extract_features.confs["superpoint_aachen"]
features_name = feature_conf["output"]
features = extract_features.main(feature_conf, images_dir, outputs)
features_path = outputs / f"{features_name}.h5"

match_conf = {
    "output": "matches-superpoint-lightglue",
    "model": {"name": "lightglue", "features": "superpoint"}
}
matches = match_features.main(match_conf, pairs_path, features_name, outputs)
matches_path = outputs / f"{match_conf['output']}_{pairs_path.stem}.h5"

sfm_dir = outputs / "sfm"
reconstruction.main(
    image_dir=images_dir,
    pairs=pairs_path,
    features=features_path,
    matches=matches_path,
    sfm_dir=sfm_dir,
    image_list=[img.name for img in images]
)

5. 总结建议

优先用官方推荐的依赖和权重文件。
遇到报错先看 Traceback，定位是路径、依赖、权重还是参数问题。
多用 Path 类型，少用字符串拼接路径。
遇到 git+https 依赖，优先科学上网或本地安装。
遇到 NumPy 2.x 报错，直接降级到 1.x。
遇到 KeyError/AssertionError，检查配置和实际文件名是否一致。

如有新问题，建议先查官方 issue 或社区，绝大多数问题都能找到解决办法。

祝你顺利用好 Hierarchical-Localization！