LIMAP

The documentations on brief tutorials and APIs are available here.

LIMAP is a toolbox for holistic 3D mapping, localization and structure from motion (SfM) with structured features. Alongside keypoints, it treats lines, vanishing points, planes, parametric primitives (spheres, cylinders, ellipsoids, cuboids, cones) and the wireframe connecting them as first-class citizens of the reconstruction, optimized jointly with the camera poses. It grew out of the highlight paper 3D Line Mapping Revisited at CVPR 2023 in Vancouver, Canada, with the SfM pipeline introduced and further improved in subsequent papers at ECCV 2024 and ECCV 2026 (please refer to the Citations section for details). Contributors to this project are from the Computer Vision and Geometry Group at ETH Zurich.

Three pipelines are provided:

• Visual mapping / triangulation — build a holistic 3D model from images whose camera poses are already known, for instance from an existing COLMAP reconstruction.
• Visual localization — estimate the camera pose of a query image with respect to an existing 3D model, using point and line correspondences jointly. Both calibrated and uncalibrated queries are supported.
• Holistic incremental SfM — recover the camera poses and the 3D model together from images alone, with nothing given as input. Calibrated and uncalibrated inputs are both supported.

[!NOTE] Starting from LIMAP 2.0.0, the toolbox is fully compatible with the COLMAP ecosystem (version 4.2.0 as of Sep 1, 2026): a reconstruction is written as a plain COLMAP model, with the line, group and wireframe structures alongside it under structures/, so any output can be opened in COLMAP GUI and read with pycolmap. The unification runs deeper than the file format: the point side of the pipeline comes directly from COLMAP, consolidating with its scene types, database, estimators, correspondence graph, and various incremental mapper logic, with LIMAP adding the structures on top instead of maintaining a parallel implementation. Advances on the COLMAP side therefore carry over directly: multi-camera rig support, improved two-view geometry estimation, etc.

The line detectors, matchers, vanishing point estimators and plane detectors are abstracted behind registries to ensure flexibility to support recent advances and future development.

From multi-view images, LIMAP jointly optimizes the features, the camera poses and the structural constraints.
This yields a sparse 3D reconstruction with geometric primitives (planes, spheres, cylinders) beyond point clouds.

Installation

LIMAP has been tested on Linux, macOS and Windows.

Dependencies:

• Python 3.10/11/12/13
• CMake >= 3.17
• CUDA (for deep learning based detectors/matchers)
• System dependencies [Per-platform guide]

Note that one cannot visualize reconstructions on Python 3.13, as there are no published wheels available for open3d and our 3D viewer depends on it.

Starting from 2.0.0, each official release is published to PyPI as pylimap, which installs the compiled core library without building it:

python -m pip install pylimap

The distribution is named pylimap; the import name is still limap. A wheel provides the Core only mode described below, so the extras and the git-sourced detectors remain opt-in on top.

To build and install the LIMAP Python package from source:

python -m pip install -r requirements.txt   # git-sourced detectors and matchers
python -m pip install -Ive ".[all]"

To double check if the package is successfully installed:

python -c "import limap; print(limap.__version__)"

For faster incremental rebuilds during development (reuses the CMake build directory instead of rebuilding from scratch):

python -m pip install -Cbuild-dir=./pylimap_build --no-build-isolation -Ive .

python -m pip install -Ive .

python -m pip install -r requirements.txt
python -m pip install -Ive ".[all,dev]"

python -m pip install patchelf
LIMAP_SO=$(python -c 'import limap._limap as m; print(m.__file__)')
patchelf --set-rpath "${CONDA_PREFIX}/lib" "$LIMAP_SO"
ldd "$LIMAP_SO" | grep mkl   # none should resolve to /lib/x86_64-linux-gnu

Quickstart

Example of Point-Line Triangulation

Download the test scene (100 images) with the following command.

bash scripts/quickstart.sh

Step 1: Undistort images to pinhole cameras

First, prepare the Hypersim scene by undistorting images and creating a COLMAP model:

python runners/hypersim/undistort_images.py \
    --data_dir data \
    --scene_id ai_001_001 \
    --output_dir outputs/quickstart \
    --max_image_dim 800

This creates:

• outputs/quickstart/init_model/ - Initial COLMAP model
• outputs/quickstart/undistorted/images/ - Undistorted images
• outputs/quickstart/undistorted/sparse/ - Undistorted COLMAP model

Step 2: Run point-line triangulation

Then, run point-line triangulation on the undistorted images:

python -m limap.cli.automatic_point_line_triangulation \
    -m outputs/quickstart/undistorted/sparse \
    -i outputs/quickstart/undistorted/images \
    -o outputs/quickstart/triangulation

Visualization

To visualize the full reconstruction (points + lines):

python visualize_holistic_recon.py --input_dir outputs/quickstart/triangulation/final_model --cam_scale 0.1

To visualize points only (using pycolmap):

python visualize_colmap_model.py --input_dir outputs/quickstart/triangulation/final_model --cam_scale 0.1

Example of Hybrid Point-Line Localization

We provide an example of hybrid point-line localization on the Stairs scene of the 7Scenes dataset.

Prepare the dataset following the hloc 7Scenes pipeline (scene images together with the SIFT SfM models, DenseVLAD retrieval pairs, and rendered depth maps), laid out under a single datasets/7scenes root. Then run:

python runners/7scenes/localization.py --dataset datasets/7scenes -s stairs --skip_exists

Add --use_dense_depth to build the line map from rendered depth maps instead of triangulation, or --use_points_only for the point-only baseline. The runner prints the pose errors for point-only (hloc) versus hybrid point-line localization; an improved accuracy from adding lines is expected.

We also support localization without knowing the query intrinsics, by adding the --uncalibrated flag:

python runners/7scenes/localization.py --dataset datasets/7scenes -s stairs --skip_exists --uncalibrated

The focal length is then estimated jointly with the pose from the same point and line correspondences. Lines give a consistent improvement here, both on the pose and on the consistency of the recovered focal length across queries.

Example of Holistic Incremental SfM

The same test scene can be reconstructed from scratch (no input poses) with the holistic incremental mapper, which jointly optimizes points, lines, vanishing points, planes and the wireframe:

python experiments/benchmark_sfm.py \
    --dataset hypersim \
    --scenes ai_001_001 \
    --data_dir data \
    --output_dir outputs/quickstart_sfm

This writes outputs/quickstart_sfm/hypersim/ai_001_001/holistic/models/ and prints relative pose AUC against the ground-truth poses. Add --methods holistic pycolmap to run the COLMAP mapper alongside it on the same features and matches.

We also support structure from motion without knowing the intrinsics, by adding the --uncalibrated flag:

python experiments/benchmark_sfm.py \
    --dataset hypersim \
    --scenes ai_001_001 \
    --data_dir data \
    --output_dir outputs/quickstart_sfm_uncalibrated \
    --uncalibrated

Nominal relative pose AUC over five runs on this quickstart scene:

Other datasets are selected with --dataset {hypersim,scannetpp,eth3d,7scenes,1dsfm}, each read directly from its own release via --data_dir.

Supported line detectors, matchers, VP and plane estimators

If you wish to use the methods with separate installation needed you need to install it yourself with the corresponding guides. This is to avoid potential issues at the LIMAP installation to ensure a quicker start.

Note: PR on integration of new features are very welcome.

The following line detectors are currently supported:

• LSD
• SOLD2
• HAWP (separate installation needed [Guide])
• TP-LSD (separate installation needed [Guide])
• DeepLSD

The following line descriptors/matchers are currently supported:

• LBD (separate installation needed [Guide])
• SOLD2
• LineTR
• L2D2
• Endpoint matching with SuperPoint + Nearest Neighbors
• Endpoint matching with SuperPoint + SuperGlue
• GlueStick
• Custom line matcher based on dense matcher RoMa (separate installation needed [Guide])

The following vanishing point estimators are currently supported:

• JLinkage
• Progressive-X (separation installation needed [Guide])

The following plane detectors are currently supported:

• PxwPlanar - monocular plane segmentation from a 4-head MoGe-2 backbone (planarity, metric depth, normals and mask) followed by GPU-accelerated region growing (ECCV 2026)

No separate installation is needed: pxwplanar is pulled in by requirements.txt and its weights download from Hugging Face on first use. It does require the MoGe fork that pxwplanar pins; another MoGe install in the same environment will shadow it and break metric prediction on CUDA.

Citations

If you use this code in your project, please consider citing the following paper:

@InProceedings{Liu_2023_LIMAP,
    author = {Liu, Shaohui and Yu, Yifan and Pautrat, Rémi and Pollefeys, Marc and Larsson, Viktor},
    title = {3D Line Mapping Revisited},
    booktitle = {Computer Vision and Pattern Recognition (CVPR)},
    year = {2023},
}

If you use the holistic incremental SfM pipeline, please consider additionally citing:

@InProceedings{Liu_2024_Robust,
    author = {Liu, Shaohui and Gao, Yidan and Zhang, Tianyi and Pautrat, Rémi and Schönberger, Johannes L. and Larsson, Viktor and Pollefeys, Marc},
    title = {Robust Incremental Structure-from-Motion with Hybrid Features},
    booktitle = {European Conference on Computer Vision (ECCV)},
    year = {2024},
}

@InProceedings{Liu_2026_Stable,
    author = {Liu, Shaohui and Pautrat, Rémi and Barath, Daniel and Hartley, Richard and Larsson, Viktor and Pollefeys, Marc},
    title = {Stable and Scalable Bundle Adjustment of Holistic 3D Structures},
    booktitle = {European Conference on Computer Vision (ECCV)},
    year = {2026},
}

Contributors

This project is mainly developed and maintained by Shaohui Liu, Yifan Yu, Rémi Pautrat, and Viktor Larsson. Issues and contributions are very welcome at any time.