Skip to main content

openmvg-rs

OpenMVG-rs, Structure from Motion in Rust: an illustration of photographs of Mont-Saint-Michel taken from many viewpoints, each linked by rays to the island they show

Turn a folder of overlapping photographs into camera poses and a sparse 3D point cloud with Structure from Motion (SfM). openmvg-rs is the Python package of OpenMVG-rs.

Installation

pip install openmvg-rs

Or, in a uv project, uv add openmvg-rs. It needs CPython 3.11 or newer, and wheels cover Linux, macOS (Apple silicon) and Windows; see Platforms and building from source below for the details.

To try a release candidate when a final release also exists, ask for pre-releases: pip install --pre openmvg-rs (with uv: --prerelease allow).

Quick start

Download the 11 Sceaux Castle photographs:

git clone https://github.com/openMVG/ImageDataset_SceauxCastle

Save this script as sceaux.py next to the downloaded folder, and run it with python sceaux.py (or, with uv and no project, uv run --with openmvg-rs sceaux.py):

import openmvg_rs

scene = openmvg_rs.reconstruct("ImageDataset_SceauxCastle/images")
print(scene)  # <openmvg_rs.Reconstruction engine='incremental' registered=11/11 points=...>
scene.write_ply("sceaux.ply")

Open sceaux.ply in a point-cloud viewer such as MeshLab or CloudCompare. The downloaded folder holds K.txt, the camera matrix of the photographs, so the run keeps that camera fixed.

Writing the results

scene.write_colmap("sceaux")  # COLMAP text model in sceaux/sparse/0/
scene.write_ply("sceaux/points.ply")  # Binary PLY: white points and green camera centers
scene.write_ply("sceaux/points_ascii.ply", format=openmvg_rs.PlyFormat.Ascii)
scene.save("sceaux/scene.omvgrs")  # read back with openmvg_rs.load_reconstruction

scene.save writes a binary file that only OpenMVG-rs reads back, with a release that writes the same schema version. It is not an exchange format: share results as COLMAP or PLY.

Using the results in Python

The points and the registered views are also NumPy values, ready for your own code or for a library such as Open3D:

points = scene.points  # (n, 3) array of 3D points, in world coordinates
for view in scene.views:  # the registered images, in the order of registered_images
    print(view.image.name, view.pose.center)  # where the photograph was taken
    R, t = view.pose.rotation, view.pose.translation  # X_cam = R @ X_world + t
    K = view.camera.matrix  # 3x3 camera matrix, None for a spherical camera

Each View holds the image path, a Pose and a Camera. A Camera names its model ("PINHOLE", "BROWN_CONRADY", "FISHEYE" or "SPHERICAL"), the image width and height, and its parameters by name: fx, fy, cx, cy, and the distortion coefficients it models (k1 to k4, p1, p2), as in the OMVG format's cameras table. Views that share a camera share one Camera object. Pixel coordinates put the center of the top-left pixel at (0, 0); COLMAP puts it at (0.5, 0.5), so write_colmap adds 0.5 to cx and cy. All arrays are read-only copies.

reconstruct

reconstruct(image_dir, /, *, engine="incremental", extraction_method="alp", seed=42,
            intrinsics=None, progress=True, max_workers=None) -> Reconstruction
  • image_dir holds the images directly or in an images/ subfolder. Images are JPEG, PNG or TIFF; convert HEIC photographs first.
  • A K.txt file (a 3x3 camera matrix) in image_dir or next to the images, or the file passed as intrinsics, gives every image the same fixed intrinsics. Without it, the intrinsics are initialized from EXIF metadata and refined during the run; Reconstruction.intrinsics_mode reports which case applied.
  • engine="incremental" adds views one at a time; engine="global" estimates all their poses at once from the pairwise geometry.
  • extraction_method="alp", the default, detects features with ALP (Analytic Laplacian Polynomial), the project's own detector; "sift" uses SIFT. Both describe the features the same way, and the choice is independent of engine.
  • The same inputs and seed give the same result, whatever the number of threads.
  • progress=True draws progress bars on stderr when it is a terminal. Jupyter and other notebooks do not give stderr a terminal, so no bars appear there.
  • max_workers caps the compute worker threads of the call; None uses all cores.

The GIL is released while the reconstruction runs, so other Python threads keep running. Ctrl-C stops the run promptly and raises KeyboardInterrupt when reconstruct is called from the main thread; from other threads Python does not deliver signals and the run completes. Processes forked after a run (multiprocessing's fork start method) can call reconstruct as well.

Getting good results

  • Give a K.txt when you know the camera. Its intrinsics stay fixed, instead of being initialized from EXIF metadata and estimated during the run.
  • Start with engine="incremental", which tries to register every image. engine="global" keeps only the images whose poses pass its consistency checks, and raises NoReconstructionError when none do; unregistered_images lists the images a run left out.
  • Keep seed fixed to repeat a run exactly, and change it to see how stable a result is.
  • Photographs that overlap more, with some change of viewpoint between neighbors, register more reliably than distant or nearly identical ones.

Reconstruction

An immutable result with engine, seed, intrinsics_mode, num_images, num_registered_images, num_points, the registered_images and unregistered_images path tuples, and the points array and views tuple described above. Each input image is one view; a registered view is one the engine gave a pose. write_colmap(directory) and write_ply(path) create missing directories and replace an earlier export.

save(path) writes the reconstruction to a binary file (its parent directory must exist) and openmvg_rs.load_reconstruction(path) reads it back. The file is checksummed and versioned; a file that is not a reconstruction, was written by an incompatible version, or is corrupt raises OpenMVGError. It records the image paths, cameras, poses, points, seed, engine and intrinsics_mode. Pickling uses the same bytes.

Geometry estimators

Robust estimators fit two-view geometry or a camera pose to NumPy arrays of correspondences. Here x1 and x2 hold matched pixel coordinates in two images, and points3d the 3D points seen at x2:

import numpy as np
import openmvg_rs

K = np.array([[2759.48, 0, 1520.69], [0, 2764.16, 1006.81], [0, 0, 1]])
f = openmvg_rs.estimate_fundamental(x1, x2)  # x1, x2: (n, 2) pixels
h = openmvg_rs.estimate_homography(x1, x2)
e = openmvg_rs.estimate_essential(x1, x2, K)  # camera_matrix2=None uses K for both views
a = openmvg_rs.estimate_absolute_pose(points3d, x2, K)  # points3d: (n, 3)

print(e.pose.rotation, e.pose.translation, e.inlier_mask)  # X2 = R X1 + s t, |t| = 1
print(a.pose.rotation, a.pose.translation, a.pose.center)  # X_cam = R X_world + t
  • Every estimator takes keyword-only threshold (pixels, default 4) and seed (default 42); the same inputs and seed give the same result.
  • Camera matrices are [[fx, 0, cx], [0, fy, cy], [0, 0, 1]]. estimate_essential and estimate_absolute_pose (P3P, then refinement on the inliers) convert the pixel threshold with the smallest focal length.
  • The results (FundamentalEstimate, HomographyEstimate, EssentialEstimate, AbsolutePoseEstimate) are frozen dataclasses of read-only arrays: the model and a boolean inlier_mask. The two pose estimators return the same Pose type as Reconstruction.views.
  • The input arrays are converted to float64 and copied into the library's types, whatever their memory layout, and the estimation runs with the GIL released.

Errors

All library errors derive from openmvg_rs.OpenMVGError:

Exception Raised when
DatasetError the folder has no usable images or the calibration is malformed
ReconstructionError matching or reconstruction fails
NoReconstructionError (a ReconstructionError) no view could be registered
ExportError a reconstruction cannot be written
EstimationError a geometry estimator finds no model (too few or inconsistent correspondences)

A missing image folder, image, calibration or reconstruction file raises FileNotFoundError, and a read or write the operating system refuses raises PermissionError. Invalid arguments raise TypeError or ValueError.

Platforms and building from source

Wheels cover CPython 3.11 and newer on Linux (x86-64 and aarch64, glibc 2.17 or later), macOS (Apple silicon) and Windows (x86-64). On x86-64 they need a CPU with SSE4.2 and POPCNT (the x86-64-v2 level, every x86-64 CPU since about 2009). On other platforms, and on free-threaded CPython, pip builds the source distribution instead, which needs a Rust toolchain 1.97 or newer.

To build from a checkout of the repository, with pixi:

pixi run -e python py-build   # build and install into the pixi Python environment
pixi run -e python py-test    # run the contract tests

License

Licensed under either of the Apache License, Version 2.0 or the MIT license at your option. Wheels and the source distribution also ship THIRD_PARTY_LICENSES.txt, the licenses of the compiled-in Rust dependencies.

Metadata

Release files for openmvg-rs 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openmvg-rs 0.1.0
File Size Uploaded Provenance Actions
openmvg_rs-0.1.0.tar.gz 1.7 MB With provenance Details for openmvg_rs-0.1.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for openmvg-rs 0.1.0
File Actions
openmvg_rs-0.1.0-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for openmvg_rs-0.1.0-cp311-abi3-win_amd64.whl
openmvg_rs-0.1.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.11 abi3 Linux glibc 2.17+ x86-64 Details for openmvg_rs-0.1.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
openmvg_rs-0.1.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.11 abi3 Linux glibc 2.17+ ARM64 Details for openmvg_rs-0.1.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
openmvg_rs-0.1.0-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for openmvg_rs-0.1.0-cp311-abi3-macosx_11_0_arm64.whl

Total release size: 14.4 MB

Release files / openmvg_rs-0.1.0.tar.gz

Download URL openmvg_rs-0.1.0.tar.gz
Size 1.7 MB
Tags Source
SHA-256 checksum
How to use checksums
4717e576274b75f33c1f86c6f938741f1f5026c66d5690b91d8a6a48382a2639
BLAKE2b-256 checksum
How to use checksums
0a4aef462a1d960fc98a623895ba40cdb36ee1822754293752fbaf2dc031b97e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / openmvg_rs-0.1.0-cp311-abi3-win_amd64.whl

Download URL openmvg_rs-0.1.0-cp311-abi3-win_amd64.whl
Size 3.6 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
a565a4ebad7799fc7dc93cc6c228a9e5fec947dc631e7d9d272fffe7f5ccbbaf
BLAKE2b-256 checksum
How to use checksums
b6c52e6103befdfeb24c453e81ddef7175acac05502a25af028c3851bf31c88d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / openmvg_rs-0.1.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL openmvg_rs-0.1.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 3.5 MB
Tags CPython 3.11 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
39b861aa82468b8c844269f90be6fbb7220a0591575f7f35d182e0d8f5aa3f66
BLAKE2b-256 checksum
How to use checksums
2c99252a9da856112c5ec92393cd89788b4f210b88269b79f437aa712ce400b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / openmvg_rs-0.1.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL openmvg_rs-0.1.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 2.9 MB
Tags CPython 3.11 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
fd1747f4d4af5968fab762cc46aada1825ad222157615458f06dc4ac540443ae
BLAKE2b-256 checksum
How to use checksums
9927b0e086ef55b7d58c4214ca008a04af5ad2bcc8d3abcc2772fe7bdd72a9eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / openmvg_rs-0.1.0-cp311-abi3-macosx_11_0_arm64.whl

Download URL openmvg_rs-0.1.0-cp311-abi3-macosx_11_0_arm64.whl
Size 2.8 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
ff430b88937bf73309cae377ef1f2205810abde5e5fc16df52af7aaa5a8d56a8
BLAKE2b-256 checksum
How to use checksums
4c104fe132b70f09723cbb7d404856f514ff00939f8e97f12e6f503e2a3b3073
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for openmvg-rs 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for openmvg_rs-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

5 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page