---

name: hierarchical-localization description: "Use the hloc Hierarchical-Localization toolbox for visual localization, feature retrieval, matching, SfM mapping, dataset pipelines, and custom HDF5 interoperability." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Hierarchical-Localization (hloc)

Use this repo skill when a task involves the hloc visual localization toolbox: 6-DoF image localization, image retrieval pairs, local feature extraction, SuperPoint/SuperGlue/LightGlue/LoFTR workflows, pycolmap/COLMAP SfM models, Aachen or InLoc pipelines, or HDF5 feature/match interoperability.

Install and import check

hloc is a Python package whose distribution name and import name are both hloc. It requires Python, PyTorch/torchvision, OpenCV, NumPy/SciPy/HDF5 tooling, pycolmap, kornia, and other runtime dependencies. Learned extractors and matchers can download model weights on first use; CUDA accelerates many models but is not required for parser/import/data-format checks.

Minimal check in the user's active environment:

python -c "import hloc; print(hloc.__version__)"
python -m hloc.extract_features --help
python -m hloc.reconstruction --help

For a fuller safe diagnostic, run the bundled helper:

python scripts/check_hloc_environment.py --check-cli

Route by task

• Load feature-retrieval for built-in local/global feature extraction, NetVLAD-style retrieval descriptors, sparse/dense matching, exact config names, output file naming, and feature/match HDF5 schemas.
• Load mapping-localization for pair generation, reconstruction, triangulation, COLMAP/pycolmap model folders, localize_sfm, localize_inloc, query pose outputs, and localization logs.
• Load dataset-pipelines for Aachen, Aachen v1.1, InLoc, SfM demo, 4Seasons, 7Scenes, CMU, Cambridge, or RobotCar planning. These workflows usually require external datasets and should not be launched as routine smoke tests.
• Load custom-interop for external feature/global-descriptor/match HDF5 files, new extractor or matcher modules, BaseModel/dynamic_load, list/pair/pose schemas, and custom artifact validation.

Canonical workflow shape

Most HLoc tasks combine multiple routes:

1. Choose feature/retrieval/matcher configs and produce feature or descriptor HDF5 files (feature-retrieval).
2. Generate database or query pairs from retrieval, covisibility, poses, or exhaustive combinations (mapping-localization).
3. Match selected image pairs and validate HDF5 pair groups (feature-retrieval plus mapping-localization).
4. Reconstruct or triangulate a reference SfM model with pycolmap (mapping-localization).
5. Retrieve and match database images for each query (feature-retrieval).
6. Localize query images and inspect pose/log outputs (mapping-localization).
7. When the request names a public benchmark dataset, first read dataset-pipelines to verify the dataset layout and skip network/benchmark-scale surprises.

Read references/workflow-recipes.md for cross-sub-skill pipeline recipes before composing a long command sequence.

Public runtime references and helpers

• references/repo-provenance.md records the source commit, package version, evidence paths, and refresh baseline.
• references/repo-routing-metadata.json contains structured managed-router metadata for this skill.
• references/workflow-recipes.md summarizes generic SfM/localization, tiny demo-style, dataset, and custom-interoperability flows.
• references/troubleshooting.md covers install/import, model-download, CPU/GPU, pycolmap, artifact naming, and dataset-scale safety issues shared by multiple routes.
• scripts/check_hloc_environment.py checks installed hloc imports, versions, configs, optional CUDA status, and safe CLI parsers without running model inference or downloading data.

Safety and boundary rules

• Do not treat full Aachen/InLoc/RobotCar/CMU/4Seasons/Cambridge/7Scenes runs as safe smoke tests; they require external datasets, large outputs, and often model downloads.
• Do not assume CUDA is required. Verify the user's goal: CUDA is usually for speed, while CPU can validate imports, parsers, schemas, and many small logic checks.
• Keep image names consistent across lists, HDF5 groups, pair files, SfM model images, retrieval files, and pose outputs. Name mismatches are the most common cross-workflow failure.
• Prefer bundled validators and references from this skill over reopening a source checkout. If public APIs or configuration names differ from the provenance snapshot, run refresh-repo-skill.