概述HLOC(Hierarchical-Localization) 是由瑞士ETH Zurich的CVG (Computer Vision and Geometry) 研究组开发的开源视觉定位与三维重建工具箱。它集成了多种深度学习特征提取和匹配方法号称可无缝对接COLMAP等三维重建软件但是实际Colmap一直在升级数据库表格字段等都在不断修改用新版本会出现数据无法适配问题。核心定位模块化的视觉定位工具箱支持 Structure-from-Motion (SfM) 全流程提供端到端的特征提取、匹配、定位方案GitHub仓库https://github.com/cvg/Hierarchical-Localization安装与测试环境要求项目要求Python3.8 (推荐 3.10)PyTorch1.8CUDA可选用于GPU加速COLMAP3.8 (可选用于重建)安装方式方式一pip安装推荐# 基础安装pipinstallhloc# 安装LightGlue支持pipinstallhloc[lightglue]# 安装所有可选依赖pipinstallhloc[all]方式二源码安装开发调试gitclone https://github.com/cvg/Hierarchical-LocalizationcdHierarchical-Localization pipinstall-e.快速测试fromhlocimportextract_features,match_features# 测试特征提取confextract_features.confs[superpoint]print(SuperPoint配置:,conf)# 测试LightGlue配置match_confmatch_features.confs[superpoint-lightglue]print(LightGlue配置:,match_conf)验证安装成功python-cfrom hloc import extract_features; print(HLOC安装成功)支持的模型类型特征提取模型 (Feature Extractors)模型年份类型描述子维度特点SuperPoint2018稀疏256自监督学习实时性好SuperPoint22024稀疏256SuperPoint改进版精度更高DISK2021稀疏128专为匹配训练鲁棒性强ALIKED2023稀疏128轻量级速度最快SIFT1999稀疏128传统方法尺度不变LoFTR2021半密集-无需检测直接匹配特征匹配模型 (Feature Matchers)模型年份特点适用场景LightGlue2023轻量级自适应层数推荐通用场景SuperGlue2020图神经网络固定层数高精度场景LoFTR2021无需特征检测直接匹配低纹理场景常用组合组合特点推荐场景SuperPoint LightGlue速度快精度适中通用三维重建SuperPoint SuperGlue精度高速度较慢高精度定位DISK LightGlue鲁棒性好大视角变化LoFTR无检测步骤低纹理/重复纹理ALIKED LightGlue最快速度实时应用模型特点对比SuperPoint vs 传统SIFT维度SuperPointSIFT检测方式深度学习heatmap尺度空间极值检测描述子256维float128维float尺度不变性较弱单尺度强多尺度金字塔旋转不变性较弱有orientation输出强主方向计算速度GPU下实时CPU较快大视角变化鲁棒性较差较好LightGlue vs SuperGlue维度LightGlueSuperGlue架构简化的GNN完整的GNN层数自适应(1-9层)固定(9层)速度快2-3倍较慢内存低30-50%较高精度略低更高适用通用场景高精度需求资源占用GPU显存需求模型图像尺寸显存占用SuperPoint (推理)640×480200-500 MBSuperPoint (推理)1920×1080500-800 MBSuperPoint (推理)4000×3000800-1200 MBLightGlue (匹配)N×N特征100-300 MBSuperGlue (匹配)N×N特征300-600 MBLoFTR (推理)640×480800-1500 MB推理速度参考 (NVIDIA RTX 3080)操作图像尺寸耗时SuperPoint特征提取640×480~15msSuperPoint特征提取1920×1080~40msLightGlue匹配1024个特征~10msSuperGlue匹配1024个特征~30msCPU运行无GPUSuperPoint: 约50-100ms/张640×480LightGlue: 约100-200ms/对建议大规模处理建议使用GPU适用场景推荐使用场景场景推荐配置说明无人机航拍重建SuperPointLightGlue图像质量好视角变化小室内SLAMSuperPointLightGlue实时性好街景定位SuperGlue精度高容忍一定视角变化低纹理场景LoFTR直接密集匹配无需检测大视角变化DISKLightGlue鲯棒性更强不推荐场景场景原因替代方案航向角差异大(30°)SuperPoint检测不稳定使用DISK或LoFTR极端尺度变化单尺度检测限制使用传统SIFT旋转差异大orientation不够鲁棒结合图像旋转预处理低纹理重复纹理特征点稀少/混淆使用LoFTR特征提取方法基本用法fromhlocimportextract_featuresfrompathlibimportPath# SuperPoint配置confextract_features.confs[superpoint]conf[max_keypoints]4096# 每张图最大特征点数conf[resize_max]1600# 图像最大尺寸# 执行特征提取extract_features.main(confconf,image_dirPath(images/),feature_pathPath(output/feats-superpoint.h5))主要配置参数参数默认值说明max_keypoints1024每张图最大特征点数量resize_maxNone图像缩放最大尺寸resize_forceFalse是否强制缩放keypoint_threshold0.005检测阈值输出格式特征提取结果存储为HDF5文件# HDF5结构feats-superpoint.h5 ├── image1.jpeg │ ├── keypoints:(N,2)float32# 特征点坐标│ └── descriptors:(256,N)uint8# 描述子│ └── scores:(N,)float32# 检测置信度├── image2.jpeg │ └──...关键点坐标说明坐标原点图像左上角 (0, 0)坐标单位像素COLMAP兼容需要 0.5 偏移特征匹配方法图像对生成fromhlocimportpairs_from_exhaustive,pairs_from_retrieval# 方式1全连接配对适合小规模pairs_from_exhaustive.main(outputsPath(pairs-exhaustive.txt),image_dirPath(images/))# 方式2基于检索配对适合大规模pairs_from_retrieval.main(outputsPath(pairs-retrieval.txt),image_dirPath(images/),num_matched10# 每张图配对数量)LightGlue匹配fromhlocimportmatch_features confmatch_features.confs[superpoint-lightglue]match_features.main(confconf,pairsPath(pairs-exhaustive.txt),featuresPath(feats-superpoint.h5),matchesPath(matches-lightglue.h5))匹配输出格式# matches-lightglue.h5结构matches.h5 ├── image1.jpeg │ └── image2.jpeg │ └── matches0:(N1,)int32# img1每个kp对应的img2 kp索引│# matches0[i] -1 表示无匹配│# matches0[i] j 表示img1的第i个kp匹配img2的第j个kp│ └── matching_scores0:(N1,)float32# 匹匹置信度匹配转COLMAP格式importnumpyasnp# LightGlue matches0 - COLMAP interleaved formatmatches0f[img1][img2][matches0][:]valid_maskmatches00kp1_idsnp.where(valid_mask)[0].astype(np.uint32)kp2_idsmatches0[valid_mask].astype(np.uint32)# COLMAP格式: [kp1_0, kp2_0, kp1_1, kp2_1, ...]match_datanp.column_stack([kp1_ids,kp2_ids])match_datamatch_data.flatten().astype(np.uint32)模型微调SuperPoint微调官方支持程度部分支持预训练模型已足够好通常无需微调可通过homographic adaptation进行自监督训练需要 自己实现训练代码微调流程参考# 1. 准备合成数据homographic变换# 2. 使用homographic adaptation生成伪标签# 3. 训练检测和描述分支LightGlue微调官方支持程度不支持LightGlue是固定架构不支持微调如需定制建议修改SuperGlue替代方案如需定制化特征提取使用DISK支持在自定义数据上训练使用ALIKED有官方训练代码使用传统方法SIFT无需训练常见问题与升级方向问题1大角度差异匹配失败现象图像拍摄角度差异30°的图像对匹配数为0原因SuperPoint单尺度检测对大视角变化鲁棒性差特征点重复检测率低升级方向尝试DISK或XFeat专门为大视角变化设计问题2尺度漂移问题现象重建结果尺度与真实尺度相差数十倍原因HLOC默认流程不使用GPS先验incremental_mapping无法控制尺度升级方向使用COLMAP的pose_prior_mapper修改HLOC流程支持GPS输入问题3数据库兼容性现象HLOC输出与COLMAP新版本数据库Schema不兼容原因COLMAP 3.13引入新表结构frames, frame_datapair_id编码方式变化升级方向使用hloc官方提供的数据库导入函数手动构建兼容数据库使用COLMAP CLI而非pycolmap绑定问题4特征点检测不一致现象相似位置的特征点在不同图像中描述子差异大原因SuperPoint检测不稳定同一物理点可能检测到不同kp描述子受局部纹理影响参考资料官方资源GitHub仓库https://github.com/cvg/Hierarchical-Localization文档目录https://github.com/cvg/Hierarchical-Localization/tree/master/doc示例代码https://github.com/cvg/Hierarchical-Localization/tree/master/pipeline论文SuperPointSuperPoint: Self-Supervised Interest Point Detection and Description (2018)SuperGlueSuperGlue: Learning Feature Matching with Graph Neural Networks (2020)LightGlueLightGlue: Local Feature Matching at Light Speed (2023)LoFTRLoFTR: Detector-Free Local Feature Matching with Transformers (2021)DISKDISK: Learning local features with policy gradient (2021)相关工具COLMAPhttps://github.com/colmap/colmapLightGlue独立仓库https://github.com/cvg/LightGlue快速参考卡片# 安装pipinstallhloc[lightglue]# 特征提取python-c from hloc import extract_features extract_features.main( conf{superpoint: {max_keypoints: 4096}}, image_dirimages/, feature_pathfeats.h5 )# 匹配python-c from hloc import match_features, pairs_from_exhaustive pairs_from_exhaustive.main(outputspairs.txt, image_dirimages/) match_features.main( conf{superpoint-lightglue: {}}, pairspairs.txt, featuresfeats.h5, matchesmatches.h5 )
