{"id":10083,"library":"pycolmap","title":"pycolmap: Python Bindings for COLMAP","description":"pycolmap provides robust Python bindings for COLMAP, an open-source Structure-from-Motion (SfM) and Multi-View Stereo (MVS) pipeline. It allows programmatic control over COLMAP's feature extraction, matching, and 3D reconstruction functionalities directly from Python. The current version is 4.0.3, with releases typically synchronized with major COLMAP C++ releases, focusing on performance, new features, and bug fixes.","status":"active","version":"4.0.3","language":"en","source_language":"en","source_url":"https://github.com/colmap/colmap","tags":["computer vision","sfm","structure-from-motion","3d reconstruction","multi-view stereo","slam"],"install":[{"cmd":"pip install pycolmap","lang":"bash","label":"For CPU-only (recommended)"},{"cmd":"pip install pycolmap[cuda]","lang":"bash","label":"For GPU acceleration (Linux only)"}],"dependencies":[{"reason":"Fundamental for numerical operations and array handling.","package":"numpy","optional":false},{"reason":"Used for scientific computing and various algorithms.","package":"scipy","optional":false}],"imports":[{"symbol":"Sfm","correct":"from pycolmap import Sfm"},{"symbol":"Camera","correct":"from pycolmap import Camera"},{"symbol":"Image","correct":"from pycolmap import Image"},{"symbol":"Point3D","correct":"from pycolmap import Point3D"},{"symbol":"extract_features","correct":"from pycolmap import extract_features"},{"symbol":"match_features","correct":"from pycolmap import match_features"},{"symbol":"reconstruct","correct":"from pycolmap import reconstruct"}],"quickstart":{"code":"import os\nimport pycolmap\nimport numpy as np\nfrom PIL import Image\n\n# Create a dummy image directory\nimage_dir = \"pycolmap_quickstart_images\"\noutput_dir = \"pycolmap_quickstart_output\"\n\nos.makedirs(image_dir, exist_ok=True)\nos.makedirs(output_dir, exist_ok=True)\n\n# Create two dummy images (COLMAP typically needs more and with overlap)\nimg_size = (100, 100)\nfor i in range(2):\n    dummy_image = Image.fromarray(np.random.randint(0, 255, img_size + (3,), dtype=np.uint8))\n    dummy_image.save(os.path.join(image_dir, f\"image_{i+1:02d}.jpg\"))\n\nprint(f\"Dummy images created in {image_dir}\")\n\n# Run the high-level SfM reconstruction\n# Note: With only two random images, this is expected to fail or produce an empty model.\n# A real scenario requires actual images with sufficient overlap and features.\ntry:\n    sfm_pipeline = pycolmap.Sfm(image_dir, output_dir)\n    reconstruction = sfm_pipeline.run()\n    if reconstruction:\n        print(f\"Reconstruction successful! Found {len(reconstruction.images)} images and {len(reconstruction.points3D)} 3D points.\")\n    else:\n        print(\"Reconstruction did not produce a valid model (expected for random, non-overlapping images).\")\nexcept Exception as e:\n    print(f\"Reconstruction failed (expected for random images without overlap/features): {e}\")\n\n# Optional: Clean up created directories\n# import shutil\n# shutil.rmtree(image_dir, ignore_errors=True)\n# shutil.rmtree(output_dir, ignore_errors=True)\n","lang":"python","description":"This quickstart demonstrates the high-level `pycolmap.Sfm` class to run a full Structure-from-Motion pipeline. It creates dummy images and attempts a reconstruction, which is expected to fail with only two random images, but illustrates the basic API usage."},"warnings":[{"fix":"Consult the COLMAP documentation for supported CUDA versions. Ensure your CUDA Toolkit and GPU drivers are up-to-date and compatible with the `pycolmap` wheel you are installing.","message":"Installation of `pycolmap[cuda]` (for GPU support) requires a CUDA Toolkit version that is compatible with COLMAP's C++ build. Incompatibilities between CUDA Toolkit, NVIDIA drivers, and `pycolmap` can lead to runtime errors or prevent GPU acceleration from being utilized.","severity":"gotcha","affected_versions":"All versions with CUDA support"},{"fix":"Prefer installing via `pip install pycolmap` using pre-built wheels. If building from source is necessary, refer to the detailed COLMAP C++ build instructions and `pycolmap` specific build steps on its GitHub repository.","message":"Building `pycolmap` from source is highly complex due to its extensive C++ dependencies (e.g., Ceres, Boost, Eigen, SuiteSparse). Using the pre-built wheels (`pip install pycolmap`) is strongly recommended to avoid intricate build environment issues.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `numpy` is up-to-date and compatible with your `pycolmap` installation. Try reinstalling both `numpy` and `pycolmap` in a clean virtual environment: `pip install --upgrade numpy` then `pip install pycolmap`.","message":"Mismatched `numpy` versions can lead to ABI compatibility errors (e.g., `ValueError: numpy.ndarray size changed`, `ImportError` related to `_multiarray_umath`), especially with C++ extensions like `pycolmap`. This happens when `pycolmap` is compiled against a different NumPy ABI than the one currently installed.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure the latest Visual C++ Redistributable for Visual Studio is installed from Microsoft's website. If the problem persists, try reinstalling `pycolmap` in a clean virtual environment.","cause":"On Windows, this often indicates missing Visual C++ Redistributable packages, or an issue with the installed `pycolmap` wheel.","error":"ImportError: DLL load failed while importing _pycolmap"},{"fix":"Verify that the `image_dir` path passed to `pycolmap` functions is correct and points to a directory containing valid image files with supported extensions.","cause":"The specified image directory either does not exist, is empty, or contains files that are not recognized image formats (e.g., not `.jpg`, `.png`).","error":"RuntimeError: Could not find any images in directory"},{"fix":"For high-level reconstruction, use the `pycolmap.Sfm` class. For more granular control, consult `pycolmap`'s documentation for functions like `extract_features`, `match_features`, and `reconstruct` (lowercase `r` for the specific step).","cause":"The specific function `reconstruct_dense` might not be directly exposed at the top level of the `pycolmap` module, or its name has changed/is part of a lower-level API.","error":"AttributeError: module 'pycolmap' has no attribute 'reconstruct_dense'"}]}