16.72. theia_sfm¶

The theia_sfm program is a wrapper around the Theia Structure-from-Motion (SfM) software. It assumes that the there are are several sensors with each acquiring images.

The produced SfM solution can be passed on to rig_calibrator (Section 16.60), but this program can be used without a rig.

ASP offers another wrapper around Theia, namely camera_solve (Section 16.12), whose aim is to work with ASP’s bundle_adjust program (Section 16.5).

16.72.1. Naming convention¶

To distinguish which images are made with which sensor, either:

The image file name (without directory) should contain the sensor name.

The name of the immediate directory having the image should be the sensor name.

A list should be provided, in which each line has the image name, sensor name and image timestamp, separated by spaces.

Examples:

my_images/image1_cam1.png

my_images/cam1/image1.png

where cam1 is the name of the sensor that acquired this image.

If a list is provided, each line should be of the form:

my_images/image1.png cam1 <timestamp>

This list should be passed in via --image_sensor_list. The timestamp is not used but is there for compatibility with rig_calibrator (Section 16.60.2).

All images names (without directory path) must be unique.

16.72.2. Configuration¶

The configuration file contains the intrinsics for each sensor. Is the same as for rig_calibrator (Section 16.60.4). This program does not use the transforms between sensors, and there is no concept of reference sensor.

See Theia’s supported camera model types. In the rig configuration those are named no_distortion, radtan, fisheye and fov.

16.72.3. Flags file¶

This program will use the Theia flags file from share/theia_flags.txt in the software distribution, which can be copied to a new name, edited, and passed to theia_sfm via --theia_fags.

As an example, for tricky configurations, setting:

--feature_density=DENSE

in the flags file can create a lot more interest points matches.

16.72.4. Examples¶

A step-by-step-example is in Section 10.3.

16.72.5. Usage¶

theia_sfm --rig_config <rig config> [images]  \
  [--theia_flags <flag file>] --out_dir <out dir>

The input images can be specified as wildcards:

theia_sfm --rig_config rig_input/rig_config.txt        \
  --images 'rig_input/cam1/*.tif rig_input/cam2/*.tif' \
  --out_dir rig_theia

in a list:

ls rig_input/cam*/*.jpg > image_list.txt
theia_sfm --rig_config rig_input/rig_config.txt        \
  --image_list image_list.txt                          \
  --out_dir rig_theia

on the command line:

theia_sfm --rig_config rig_input/rig_config.txt        \
  rig_input/cam1/image1.png rig_input/cam2/image2.png  \
  --out_dir rig_theia

Use --image_sensor_list instead of --list if the sensor names are not part of image names (Section 16.72.1).

16.72.6. Output files¶

This tool produces an SfM solution with a name like out_dir/cameras.nvm. The optical offsets per image are in out_dir/cameras_offsets.txt. A reconstruction in binary format is saved to out_dir/reconstruction-0.

The nvm file can be passed in to bundle_adjust (Section 16.5.10.3) and rig_calibrator (Section 16.60).

16.72.7. Visualization¶

The created camera poses can be visualized as:

view_reconstruction --reconstruction out_dir/reconstruction-0

See this program’s manual in Section 16.74.

The interest point matches in the .nvm file can be inspected with stereo_gui (Section 16.70.9.4). This will show the images in the random order produced by Theia. The rig_calibrator program (Section 16.60), which can be used as the next step, will order these lexicographically.

16.72.8. Manipulating SfM solutions¶

Several produced solutions can be merged into a larger reconstruction with the sfm_merge (Section 16.63) program. Portions can be extracted with sfm_submap (Section 16.65).

16.72.8.1. Command-line options for theia_sfm¶

--rig_config <string (default: “”)>: Rig configuration file.
--images <string (default: “”)>: Images, as individual wildcards. Example: 'dir/cam1/*tif dir/cam2/*tif'.
--image_list <string (default: “”)>: Use the images from this list, instead of setting --images. Images must be separated by a newline.
--image_sensor_list <string (default: “”)>: An alternative way of listing the input images, when the sensor name is specified separately in the same file (Section 16.72.1).
--theia_flags <string (default: “”)>: The flags to pass to Theia. By default, the file share/theia_flags.txt in the software distribution is used.
--out_dir <string (default: “”)>: The output directory.
-h, --help: Show this help message and exit.