Frequently asked Questions (FAQ) about Bundler


  1. 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 these cases:

    • 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 something like:

      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


  2. 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 matches. 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.)


  3. 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.


  4. 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.


  5. 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>
      <parameters1>
      <parameters2>
        ...
      <parametersN>

    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.


  6. 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 to time.