Frequently asked Questions (FAQ) about Bundler
- Q. Something seems to be broken.
The geometry I get looks wrong. What's going on?
A. There are many reasons why Bundler
might produce erroneous results. However, there are a few common
failure modes. The first is that there is not enough overlap
between the images. A good rule of thumb is that each point in
the scene needs to be visible in at least three images, and that
when walking around an object, you should take photos at least
every 15 degrees (i.e., 24 photos when capturing a full 360 view
of an object).
A second common failure mode is that Bundler can't get a good
focal length estimate (though it will still try hard to produce a
usually wrong result). Your camera may need to be added to the
CCD width database in bin/extract_focal.pl. To tell if
this is a problem, look at the generated list.txt file
for your dataset. Each line should have three entries: the image
name, a zero, and a focal length. If this isn't the case, either
(a) your camera model needs to be registered (possible with most
still cameras) or (b) you are using a video camera and therfore
Bundler can't automatically detect focal lengths from the Exif
tags in your images. Here are some instructions for handling
Case (a): I am using a still digital camera: First, you
will need to find the sensor width (in millimeters (mm)) of your
camera. Sensor widths for most cameras can be found on
dpreview; see this page for more
information. Once you have found the sensor width in mm, you
must add a line to the sensor width database
in bin/extract_focal.pl. First, use the
provided jhead tool to find the camera make and model
as listed in the Exif tags. You will then add a line
to bin/extract_focal.pl of the form:
"[Camera make] [Camera model]" => [Sensor width]
See the existing entries for examples.
Case (b): I am using a video camera, or my camera otherwise
doesn't include the right Exif tags, or (a) didn't work for some
other reason: You'll need to calibrate your camera yourself,
to find the focal length. A good calibration tool is
Bouguet's Camera Calibration Toolbox. Once you know the
focal length, first run the bundler pipeline on your images
(it will probably not work well). Then edit
the list.txt file created (each line should contain
just a filename, e.g. foo001.jpg), and append to each
line a 0 followed by the focal length (assuming the
focal length is the same for each frame; if the camera is
zooming in or out you may have a problem). For instance, if
the focal length (in pixels) is 2410.5, each line would look
foo001.jpg 0 2410.5
Then rerun bundler (just bundler, and not the matching or
other steps) as:
bundler list.txt --options_file options.txt
- Q. Help! Bundler doesn't seem to
work right on the example datasets (ET and kermit). I get all 0's
for some camera parameters in the bundle.out file.
A. This is expected. A camera will
have all 0 parameters if it wasn't registered with the other
photos, often (but not always) because there weren't enough
The example sets are difficult in that the angle between camera
viewpoints is relatively large, stretching what SIFT can do. In
some photo collections, some photos may not be registered.
However, if your collections are dense enough, you are more likely
to avoid this problem. (In the future, easier example sets will
also be included.)
- Q. I don't see anything when I open
up an output ply file in Scanalyze.
A. Scanalyze by default renders models as
polygons, rather than the points output by bundler. To switch to
point rendering mode, select "Points" from the Render menu. You'll
also need to unselect "Lit" from the same menu, and select "True
color" (again from the Render menu) to see the points in color.
- Q. How can I generate a dense mesh?
A. Bundler only outputs sparse scene
geometry. To generate a mesh, you'll need to run multi-view
stereo software on the output of Bundler. See, for instance, Yasutaka
Furukawa's Patch-Based Multi-View Stereo page.
- Q. How can I constrain the reconstruction process using known camera intrinsics? What is this top-secret '--intrinsics' option?
A. This is actually getting somewhat untested areas of the code, but I can at least point you in the right direction. If you specify the (undocumented) --intrinsics <file> option, then it loads a set of camera calibration parameters (possibly more than one set) from the given file. The format of this file is related to the Bouguet calibration output, and is:
<number of sets of camera calibration parameters>
Where each <parameter> has the form:
<3x3 K matrix of intrinsic parameters>
<5 radial distortion parameters>
as produced by Bouguet's calibration toolkit. If all of your cameras have the same intrinsics, then you would just have one set of parameters in this file. If some cameras have different intrinsics, then bundler guesses which parameters go with which camera by comparing the estimated focal lengths in list.txt with the focal length from each set of parameters (somewhat crude, I know).
Note that this feature hasn't been extensively tested. To see the relevant parts of the code, look in Bundle.cpp and lib/sfm-driver/sfm.c for places where "known_intrinsics" is enabled.
- Q. How can I generate the
visualizations in the Photo Tourism videos?
A. Currently, only the structure from
motion code is available. I also hope to release a viewer, so
check back at the webpage from time