Note: This repository has been archived!

Development on this project has moved to a new repository at https://gitlab.com/educelab/sfm-utils. This repository has been archived and no longer accepts pull requests or issues.

PySfMUtils

A Python package for interacting with Structure-from-Motion (SfM) projects.

Requirements

• Python 3.6+
• numpy 1.15+

Installation

The package is registered on PyPI. Released versions can be installed using pip:

pip install PySfMUtils

Development versions can be installed directly from the GitHub repository:

python -m pip install -e git+https://github.com/viscenter/sfm-utils.git

Usage

This package was originally designed to ease the process of importing pose priors into OpenMVG. It contains a format agnostic interface for defining an SfM Scene and its component parts:

import sfm_utils as sfm

# Create the scene
scene = sfm.Scene()
scene.root_dir = '/path/to/images/'

# Construct a view
view = sfm.View()
view.path = "view.jpg"
view.width = 800
view.height = 600
view.camera_make = 'PySfMUtils'
view.camera_model = 'Test Camera'
scene.add_view(view)

# Add the view's intrinsics
intrinsic = sfm.IntrinsicRadialK3()
intrinsic.width = view.width
intrinsic.height = view.height
intrinsic.focal_length = 50
intrinsic.sensor_width = 36
intrinsic.dist_params = [-0.1, -1.1, -1.1]
view.intrinsic = scene.add_intrinsic(intrinsic)

# Add the view's pose
pose = sfm.Pose()
pose.center = [10, 10, 10]
view.pose = scene.add_pose(pose)

# Write an OpenMVG project file
sfm.export_scene(path='sfm_data.json', scene=scene)

The exported sfm_data.json file can be passed directly to OpenMVG programs:

openMVG_main_ComputeFeatures -i sfm_data.json -o matches/

Export to AliceVision/Meshroom

To export a scene to an AliceVision/Meshroom compatible json file, use sfm_utils.export_scene:

import sfm_utils as sfm
scene = sfm.Scene()
...
sfm.export_scene(path='SfMData.json', scene=scene, fmt=sfm.Format.ALICE_VISION)

The AliceVision json file matches an example file generated by Meshroom, but has not been tested for actually performing reconstructions. Contributions to this functionality are welcome.

Pose coordinate system

This package assumes a right-handed¹ coordinate system, in contrast to the left-handed² system used by OpenMVG. When exporting to OpenMVG, this package will premultiply the Pose.rotation matrix with the following conversion matrix:

-1,  0,  0
 0,  1,  0
 0,  0, -1

To disable this behavior, set the convert_rotations parameters for export_scene to False:

sfm_utils.export_scene(path='sfm_data.json', scene=scene, convert_rotations=False)

1: Negative Z-forward, positive Y-up, and positive X-right
2: Positive Z-forward, positive Y-up, and negative X-right

Limitations

This package is a work-in-progress and currently implements only the most basic features needed to import pre-calibrated camera pose information into OpenMVG. We will gladly accept pull requests for new features. Known limitations in the current implementation are as follows:

• Only Views, Poses, and Intrinsics are supported. Feature points, control points, tracks, etc. are not provided.
• Only the Pinhole, RadialK3, and BrownT2 camera intrinsics are implemented.
• AliceVision support is untested.
• There is no support for loading pre-existing SfM files.