-------------------------------------------------------------------------------
|   Bundler v0.4 User's Manual                                                |
|     copyright 2008-2009 Noah Snavely (snavely@cs.cornell.edu)               |
|                                                                             |
|  based on the Photo Tourism work of Noah Snavely, Steven M. Seitz,          |
|       (University of Washington) and Richard Szeliski (Microsoft Research)  |
|                                                                             |
|  For more technical details, visit http://phototour.cs.washington.edu       |
-------------------------------------------------------------------------------

Table of Contents

    I.    What is Bundler?
    II.   Conditions of use
    III.  What's included in this distribution
    IV.   Before you begin
    V.    Running bundler
    VI.   Output format and scene representation
    VII.  Command-line options
    VIII. Acknowledgements 
    IX.   Contact information

I. What is Bundler?

Currently, Bundler has primarily been compiled and tested under Linux (though Windows versions for cygwin and Visual Studio 2005 have also been released).

II. Conditions of use

III. What's included in this distribution

A utility program for converting bundle files (.out) to the input required by Dr. Yasutaka Furukawa's PMVS multi-view stereo system (online here) called Bundle2PMVS is also included. This distribution also includes a program called RadialUndistort for generating undistorted images (based on the undistortion parameters estimated by Bundler).

Finally, included in the bin directory is the 'jhead' program for reading Exif tags from JPEG images. Very special thanks to Matthias Wandel for putting this useful program in the public domain.

IV. Before you begin

    http://phototour.cs.washington.edu/bundler/ (the binary distribution is highly recommended)

and extract it into a directory (to be referred to as BASE_PATH).

You'll also need ImageMagick installed on you system (for converting jpg files to pgm format, required for David Lowe's SIFT binary).

In addition, you'll need a feature detector to get the system working. Assuming you will be using SIFT features generated by David Lowe's SIFT binary, you'll need to get SIFT from

    http://www.cs.ubc.ca/~lowe/keypoints/

and copy it to BASE_PATH/bin (making sure it is called 'sift', or 'siftWin32.exe' under Windows).

The RunBundler.sh script relies on bash and perl being installed. The easiest way to run this script in Windows is through cygwin.

Finally, copy the approximate nearest neighbors (ANN) shared library at BASE_PATH/lib/libANN_char.so to a location in your LD_LIBRARY_PATH (or add BASE_PATH/lib to LD_LIBRARY_PATH.

V. Running bundler

The 'bundler' exectutable is actually the last in a sequence of steps that need to be run to reconstruct a scene. RunBundler.sh takes care of all these steps for you, but it's useful to know what's going on. The main initial steps are to generate features and pairwise feature matches for the image set. Any type of image features can be used, but Bundler assumes the features are in the SIFT format, and so David Lowe's SIFT detector, (available at http://www.cs.ubc.ca/~lowe/keypoints/) is the easiest to get working with Bundler (RunBundler.sh assumes that SIFT is used). A list of images containing estimating focal length information also must be created. The four steps to creating a reconstruction are therefore:

1. Create a list of images using the script 'extract_focal.pl' (this extracts focal length information, when available, from each image, and stores it in an image list).
2. Generate (SIFT) features for each image.
3. Match features between each pairs of images (this step can take a while). The computed feature matches are stored in a file called 'matches.init.txt'.
4. Run 'bundler' with a suitable options file.

Bundler itself is typically invoked as follows:

    > bundler list.txt --options_file options.txt

The first argument is the list of images to be reconstructed (created with the 'extract_focal.pl' utility). Next, an options file containing settings to be used for the current run is given. RunBundler.sh creates an options file that will work in many situations. Common options are described later in this document.

VI. Output format and scene representation

The bundle files contain the estimated scene and camera geometry have the following format:

    # Bundle file v0.3
    <num_cameras> <num_points>   [two integers]
    <camera1>
    <camera2>
       ...
    <cameraN>
    <point1>
    <point2>
       ...
    <pointM>

Each camera entry <cameraI> contains the estimated camera intrinsics and extrinsics, and has the form:

    <f> <k1> <k2>   [the focal length, followed by two radial distortion coeffs]
    <R>             [a 3x3 matrix representing the camera rotation]
    <t>             [a 3-vector describing the camera translation]

The cameras are specified in the order they appear in the list of images.

Each point entry has the form:

    <position>      [a 3-vector describing the 3D position of the point]
    <color>         [a 3-vector describing the RGB color of the point]
    <view list>     [a list of views the point is visible in]

The view list begins with the length of the list (i.e., the number of cameras the point is visible in). The list is then given as a list of quadruplets <camera> <key> <x> <y>, where <camera> is a camera index, <key> the index of the SIFT keypoint where the point was detected in that camera, and <x> and <y> are the detected positions of that keypoint. Both indices are 0-based (e.g., if camera 0 appears in the list, this corresponds to the first camera in the scene file and the first image in "list.txt"). The pixel positions are floating point numbers in a coordinate system where the origin is the center of the image, the x-axis increases to the right, and the y-axis increases towards the top of the image. Thus, (-w/2, -h/2) is the lower-left corner of the image, and (w/2, h/2) is the top-right corner (where w and h are the width and height of the image).

We use a pinhole camera model; the parameters we estimate for each camera are a focal length (f), two radial distortion parameters (k1 and k2), a rotation (R), and translation (t), as described in the file specification above. The formula for projecting a 3D point X into a camera (R, t, f) is:

    P = R * X + t       (conversion from world to camera coordinates)
    p = -P / P.z        (perspective division)
    p' = f * r(p) * p   (conversion to pixel coordinates)

where P.z is the third (z) coordinate of P. In the last equation, r(p) is a function that computes a scaling factor to undo the radial distortion:

     r(p) = 1.0 + k1 * ||p||^2 + k2 * ||p||^4.

This gives a projection in pixels, where the origin of the image is the center of the image, the positive x-axis points right, and the positive y-axis points up (in addition, in the camera coordinate system, the positive z-axis points backwards, so the camera is looking down the negative z-axis, as in OpenGL).

Finally, the equations above imply that the camera viewing direction is:

    R' * [0 0 -1]'  (i.e., the third row of -R or third column of -R')

(where ' indicates the transpose of a matrix or vector).

and the 3D position of a camera is

    -R' * t .

VII. Command-line options

  --match_table matches.init.txt
     [specifies the file where the match files are stored]

  --output bundle.out
     [specifies the name of the final output reconstruction]

  --output_all bundle_
     [specifies that all intermediate reconstructions should be
      output to files with prefix "bundle_"]

  --output_dir bundle
     [the directory all output files should be written to, typically
      called "bundle"]

  --variable_focal_length
     [directs bundler to optimize for an independent focal length for
      each image]

  --use_focal_estimate
     [directs bundler to use the estimated focal lengths obtained from
      the Exif tags for each image]

  --constrain_focal
     [constrain the focal length of each camera to be close to the
      initial focal length estimate (from Exif tags).  This option
      adds penalty terms to the bundle adjustment objective function]

  --constrain_focal_weight 0.0001
     [weight on the penalty terms for the focal length constraints (a
      small weight is typically sufficient)]

  --estimate_distortion
     [directs bundler to estimate radial distortion parameters for
      each image]

  --run_bundle
     [run structure from motion (as opposed to other operations on
      existing reconstructions)]

Other options.  There are a number of other useful options in addition to the default ones listed above, including:

  --init_pair1 <image_idx1>
  --init_pair2 <image_idx2>
     [Specifies which images to use as the initial pair.  Very useful
      when the automatically chosen pair results in a bad
      reconstruction.]

  --sift_binary <sift>
     [The location of the SIFT binary on your installation, e.g.,
     '/usr/bin/sift' or '/cygdrive/c/usr/bin/siftWin32.exe'.]

  --add_images <add_list>
     [Given an existing reconstruction specified with the --bundle
      option, attempts to add the images listed in the file <add_list>
      to the reconstruction, writing the results to the file
      'bundle.added.out'.  The new list of images is written to
      'list.added.txt'.  Use the 'extract_focal.pl' script to generate
      the file <add_list> from a directory of JPEGs, but note that the
      correct path to these images must be included -- which may
      require editing the add list file.  Do not include the
      '--run_bundle' option when adding new images.  If the SIFT key
      files have not yet been generated for the new images, bundler
      will try to extract features, but this requires that the
      --sift_binary option be set.]

  --options_file <options_file>
     [Read in a list of options from the specified file.]

  --help
     [Print out the complete list of command-line options.]

VIII. Acknowledgements

Thanks to Manolis Lourakis and Antonis Argyros for their sparse bundle adjustment package, to David Lowe for SIFT , to David M. Mount and Sunil Arya for their approximate nearest neighbors library, and to Matthias Wandel for his excellent 'jhead' program.

Special thanks as well to Kathleen Tuite and Sebastian Koch for testing this distribution.

IX. Contact information

References

[1] Noah Snavely, Steven M. Seitz, and Richard Szeliski.  Photo
    Tourism: Exploring Photo Collections in 3D.  SIGGRAPH Conf. Proc.,
    2006.

[2] Noah Snavely, Steven M. Seitz, Richard Szeliski.  Modeling the
    World from Internet Photo Collections. International Journal of
    Computer Vision (to appear), 2007.

[3] M.I.A. Lourakis and A.A. Argyros.  The Design and Implementation
    of a Generic Sparse Bundle Adjustment Software Package Based on
    the Levenberg-Marquardt Algorithm.  Tech.  Rep. 340, Inst. of
    Computer Science-FORTH, Heraklion, Crete, Greece. Available from
    http://www.ics.forth.gr/~lourakis/sba.