{"id":20065005,"url":"https://github.com/colmap/pycolmap","last_synced_at":"2025-02-28T21:08:15.527Z","repository":{"id":39865453,"uuid":"232513773","full_name":"colmap/pycolmap","owner":"colmap","description":"Python bindings for COLMAP","archived":false,"fork":false,"pushed_at":"2024-07-09T23:33:38.000Z","size":380,"stargazers_count":947,"open_issues_count":15,"forks_count":130,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-02-21T20:08:47.652Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/colmap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-08T08:19:27.000Z","updated_at":"2025-02-19T20:30:16.000Z","dependencies_parsed_at":"2023-02-18T01:15:47.485Z","dependency_job_id":"64da33a3-5fd2-46d7-bd14-dbead7b188bf","html_url":"https://github.com/colmap/pycolmap","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colmap%2Fpycolmap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colmap%2Fpycolmap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colmap%2Fpycolmap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colmap%2Fpycolmap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/colmap","download_url":"https://codeload.github.com/colmap/pycolmap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241236768,"owners_count":19931913,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T13:48:38.381Z","updated_at":"2025-02-28T21:08:15.495Z","avatar_url":"https://github.com/colmap.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cb\u003e\n    ⚠️ \u003ca href=\"https://github.com/colmap/colmap/tree/main/pycolmap\"\u003eThe development of PyCOLMAP has moved to the COLMAP repository.\u003c/a\u003e ⚠️\u003cbr\u003ePyCOLMAP remains available on \u003ca href=\"https://pypi.org/project/pycolmap/\"\u003ePyPi\u003c/a\u003e. This repository will be archived soon.\n  \u003c/b\u003e\n\u003c/p\u003e\n\n# Python bindings for COLMAP\n\nThis repository exposes to Python most capabilities of [COLMAP](https://colmap.github.io/) for Structure-from-Motion and Multiview-stereo, such as reconstruction pipelines \u0026 objects and geometric estimators.\n\n## Installation\n\nWheels for Python 8/9/10 on Linux, macOS 10/11/12 (both Intel and Apple Silicon), and Windows can be installed using pip:\n```bash\npip install pycolmap\n```\n\nThe wheels are automatically built and pushed to [PyPI](https://pypi.org/project/pycolmap/) at each release. They are currently not built with CUDA support, which requires building from source.\n\n\u003cdetails\u003e\n\u003csummary\u003e[Building PyCOLMAP from source - click to expand]\u003c/summary\u003e\n\n1. Install COLMAP from source following [the official guide](https://colmap.github.io/install.html). Use COLMAP 3.8 or 3.9.1 for PyCOLMAP 0.4.0 or 0.5.0/0.6.0.\n\n4. Clone the PyCOLMAP repository:\n```bash\ngit clone -b 0.6.0 https://github.com/colmap/pycolmap.git\ncd pycolmap\n```\n\n3. Build:\n  - On Linux and macOS:\n```bash\npython -m pip install .\n```\n  - On Windows, after installing COLMAP [via VCPKG](https://colmap.github.io/install.html), run in powershell:\n```powershell\npy -m pip install . `\n    --cmake.define.CMAKE_TOOLCHAIN_FILE=\"$VCPKG_INSTALLATION_ROOT/scripts/buildsystems/vcpkg.cmake\" `\n    --cmake.define.VCPKG_TARGET_TRIPLET=\"x64-windows\"\n```\n\n\u003c/details\u003e\n\n## Reconstruction pipeline\n\nPyCOLMAP provides bindings for multiple steps of the standard reconstruction pipeline:\n\n- extracting and matching SIFT features\n- importing an image folder into a COLMAP database\n- inferring the camera parameters from the EXIF metadata of an image file\n- running two-view geometric verification of matches on a COLMAP database\n- triangulating points into an existing COLMAP model\n- running incremental reconstruction from a COLMAP database\n- dense reconstruction with multi-view stereo\n\nSparse \u0026 Dense reconstruction from a folder of images can be performed with:\n```python\noutput_path: pathlib.Path\nimage_dir: pathlib.Path\n\noutput_path.mkdir()\nmvs_path = output_path / \"mvs\"\ndatabase_path = output_path / \"database.db\"\n\npycolmap.extract_features(database_path, image_dir)\npycolmap.match_exhaustive(database_path)\nmaps = pycolmap.incremental_mapping(database_path, image_dir, output_path)\nmaps[0].write(output_path)\n# dense reconstruction\npycolmap.undistort_images(mvs_path, output_path, image_dir)\npycolmap.patch_match_stereo(mvs_path)  # requires compilation with CUDA\npycolmap.stereo_fusion(mvs_path / \"dense.ply\", mvs_path)\n```\n\nPyCOLMAP can leverage the GPU for feature extraction, matching, and multi-view stereo if COLMAP was compiled with CUDA support.\nSimilarly, PyCOLMAP can run Delauney Triangulation if COLMAP was compiled with CGAL support.\nThis requires to build the package from source and is not available with the PyPI wheels.\n\nAll of the above steps are easily configurable with python dicts which are recursively merged into\ntheir respective defaults, for example:\n```python\npycolmap.extract_features(database_path, image_dir, sift_options={\"max_num_features\": 512})\n# equivalent to\nops = pycolmap.SiftExtractionOptions()\nops.max_num_features = 512\npycolmap.extract_features(database_path, image_dir, sift_options=ops)\n```\n\nTo list available options and their default parameters:\n\n```python\nhelp(pycolmap.SiftExtractionOptions)\n```\n\nFor another example of usage, see [`example.py`](./example.py) or [`hloc/reconstruction.py`](https://github.com/cvg/Hierarchical-Localization/blob/master/hloc/reconstruction.py).\n\n## Reconstruction object\n\nWe can load and manipulate an existing COLMAP 3D reconstruction:\n\n```python\nimport pycolmap\nreconstruction = pycolmap.Reconstruction(\"path/to/reconstruction/dir\")\nprint(reconstruction.summary())\n\nfor image_id, image in reconstruction.images.items():\n    print(image_id, image)\n\nfor point3D_id, point3D in reconstruction.points3D.items():\n    print(point3D_id, point3D)\n\nfor camera_id, camera in reconstruction.cameras.items():\n    print(camera_id, camera)\n\nreconstruction.write(\"path/to/reconstruction/dir/\")\n```\n\nThe object API mirrors the COLMAP C++ library. The bindings support many other operations, for example:\n\n- projecting a 3D point into an image with arbitrary camera model:\n```python\nuv = camera.img_from_cam(image.cam_from_world * point3D.xyz)\n```\n\n- aligning two 3D reconstructions by their camera poses:\n```python\nrec2_from_rec1 = pycolmap.align_reconstructions_via_reprojections(reconstruction1, reconstrution2)\nreconstruction1.transform(rec2_from_rec1)\nprint(rec2_from_rec1.scale, rec2_from_rec1.rotation, rec2_from_rec1.translation)\n```\n\n- exporting reconstructions to text, PLY, or other formats:\n```python\nreconstruction.write_text(\"path/to/new/reconstruction/dir/\")  # text format\nreconstruction.export_PLY(\"rec.ply\")  # PLY format\n```\n\n## Estimators\n\nWe provide robust RANSAC-based estimators for absolute camera pose (single-camera and multi-camera-rig), essential matrix, fundamental matrix, homography, and two-view relative pose for calibrated cameras.\n\nAll RANSAC and estimation parameters are exposed as objects that behave similarly as Python dataclasses. The RANSAC options are described in [`colmap/optim/ransac.h`](https://github.com/colmap/colmap/blob/main/src/colmap/optim/ransac.h#L43-L72) and their default values are:\n\n```python\nransac_options = pycolmap.RANSACOptions(\n    max_error=4.0,  # for example the reprojection error in pixels\n    min_inlier_ratio=0.01,\n    confidence=0.9999,\n    min_num_trials=1000,\n    max_num_trials=100000,\n)\n```\n\n### Absolute pose estimation\n\nFor instance, to estimate the absolute pose of a query camera given 2D-3D correspondences:\n```python\n# Parameters:\n# - points2D: Nx2 array; pixel coordinates\n# - points3D: Nx3 array; world coordinates\n# - camera: pycolmap.Camera\n# Optional parameters:\n# - estimation_options: dict or pycolmap.AbsolutePoseEstimationOptions\n# - refinement_options: dict or pycolmap.AbsolutePoseRefinementOptions\nanswer = pycolmap.absolute_pose_estimation(points2D, points3D, camera)\n# Returns: dictionary of estimation outputs or None if failure\n```\n\n2D and 3D points are passed as Numpy arrays or lists. The options are defined in [`estimators/absolute_pose.cc`](./pycolmap/estimators/absolute_pose.h#L100-L122) and can be passed as regular (nested) Python dictionaries:\n\n```python\npycolmap.absolute_pose_estimation(\n    points2D, points3D, camera,\n    estimation_options=dict(ransac=dict(max_error=12.0)),\n    refinement_options=dict(refine_focal_length=True),\n)\n```\n\n### Absolute Pose Refinement\n\n```python\n# Parameters:\n# - cam_from_world: pycolmap.Rigid3d, initial pose\n# - points2D: Nx2 array; pixel coordinates\n# - points3D: Nx3 array; world coordinates\n# - inlier_mask: array of N bool; inlier_mask[i] is true if correpondence i is an inlier\n# - camera: pycolmap.Camera\n# Optional parameters:\n# - refinement_options: dict or pycolmap.AbsolutePoseRefinementOptions\nanswer = pycolmap.pose_refinement(cam_from_world, points2D, points3D, inlier_mask, camera)\n# Returns: dictionary of refinement outputs or None if failure\n```\n\n### Essential matrix estimation\n\n```python\n# Parameters:\n# - points1: Nx2 array; 2D pixel coordinates in image 1\n# - points2: Nx2 array; 2D pixel coordinates in image 2\n# - camera1: pycolmap.Camera of image 1\n# - camera2: pycolmap.Camera of image 2\n# Optional parameters:\n# - options: dict or pycolmap.RANSACOptions (default inlier threshold is 4px)\nanswer = pycolmap.essential_matrix_estimation(points1, points2, camera1, camera2)\n# Returns: dictionary of estimation outputs or None if failure\n```\n\n### Fundamental matrix estimation\n\n```python\nanswer = pycolmap.fundamental_matrix_estimation(\n    points1,\n    points2,\n    [options],       # optional dict or pycolmap.RANSACOptions\n)\n```\n\n### Homography estimation\n\n```python\nanswer = pycolmap.homography_matrix_estimation(\n    points1,\n    points2,\n    [options],       # optional dict or pycolmap.RANSACOptions\n)\n```\n\n### Two-view geometry estimation\n\nCOLMAP can also estimate a relative pose between two calibrated cameras by estimating both E and H and accounting for the degeneracies of each model.\n\n```python\n# Parameters:\n# - camera1: pycolmap.Camera of image 1\n# - points1: Nx2 array; 2D pixel coordinates in image 1\n# - camera2: pycolmap.Camera of image 2\n# - points2: Nx2 array; 2D pixel coordinates in image 2\n# Optional parameters:\n# - matches: Nx2 integer array; correspondences across images\n# - options: dict or pycolmap.TwoViewGeometryOptions\nanswer = pycolmap.estimate_calibrated_two_view_geometry(camera1, points1, camera2, points2)\n# Returns: pycolmap.TwoViewGeometry\n```\n\nThe `TwoViewGeometryOptions` control how each model is selected. The output structure contains the geometric model, inlier matches, the relative pose (if `options.compute_relative_pose=True`), and the type of camera configuration, which is an instance of the enum `pycolmap.TwoViewGeometryConfiguration`.\n\n### Camera argument\n\nSome estimators expect a COLMAP camera object, which can be created as follow:\n\n```python\ncamera = pycolmap.Camera(\n    model=camera_model_name_or_id,\n    width=width,\n    height=height,\n    params=params,\n)\n```\n\nThe different camera models and their extra parameters are defined in [`colmap/src/colmap/sensor/models.h`](https://github.com/colmap/colmap/blob/main/src/colmap/sensor/models.h). For example for a pinhole camera:\n\n```python\ncamera = pycolmap.Camera(\n    model='SIMPLE_PINHOLE',\n    width=width,\n    height=height,\n    params=[focal_length, cx, cy],\n)\n```\n\nAlternatively, we can also pass a camera dictionary:\n\n```python\ncamera_dict = {\n    'model': COLMAP_CAMERA_MODEL_NAME_OR_ID,\n    'width': IMAGE_WIDTH,\n    'height': IMAGE_HEIGHT,\n    'params': EXTRA_CAMERA_PARAMETERS_LIST\n}\n```\n\n\n## SIFT feature extraction\n\n```python\nimport numpy as np\nimport pycolmap\nfrom PIL import Image, ImageOps\n\n# Input should be grayscale image with range [0, 1].\nimg = Image.open('image.jpg').convert('RGB')\nimg = ImageOps.grayscale(img)\nimg = np.array(img).astype(np.float) / 255.\n\n# Optional parameters:\n# - options: dict or pycolmap.SiftExtractionOptions\n# - device: default pycolmap.Device.auto uses the GPU if available\nsift = pycolmap.Sift()\n\n# Parameters:\n# - image: HxW float array\nkeypoints, descriptors = sift.extract(img)\n# Returns:\n# - keypoints: Nx4 array; format: x (j), y (i), scale, orientation\n# - descriptors: Nx128 array; L2-normalized descriptors\n```\n\n## TODO\n\n- [ ] Add documentation\n- [ ] Add more detailed examples\n- [ ] Add unit tests for reconstruction bindings\n\nCreated and maintained by [Mihai Dusmanu](https://github.com/mihaidusmanu/), [Philipp Lindenberger](https://github.com/Phil26AT), [John Lambert](https://github.com/johnwlambert), [Paul-Edouard Sarlin](https://psarlin.com/), and other contributors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolmap%2Fpycolmap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcolmap%2Fpycolmap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolmap%2Fpycolmap/lists"}