编译好的Bundler (Structure from Motion)

-------------------------------------------------------------------------- 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 information, visit http://phototour.cs.washington.edu An html version of this manual is available at http://phototour.cs.washington.edu/bundler/ -------------------------------------------------------------------------- ---------------- What is Bundler? ---------------- Bundler is a structure-from-motion system for unordered image collections (for instance, images from the Internet). Bundler takes a set of images, image features, and image matches as input, and produces a 3D reconstruction of the camera and (sparse) scene geometry as output. The system, described in [1] and [2], reconstructs the scene incrementally, a few images at a time, using a modified version of the Sparse Bundle Adjustment package of Lourakis and Argyros [3] as the underlying optimization engine. Currently, Bundler has been primarily compiled and tested under Linux (though a Windows version for cygwin has also been released). ----------------- Conditions of use ----------------- Bundler is distributed under the GNU General Public License. For information on commercial licensing, please contact the authors at the contact address below. --------------- What's included --------------- Included with the binary distribution is the Bundler executable (bin/bundler), as well as a number of other utility scripts and executables (in the bin/ directory). In addition, there are a number of example image sets (and example results) under the examples/ directory. A version of the approximate nearest neighbors (ANN) library of David M. Mount and Sunil Arya, customized for searching verctors of unsigned bytes, is also included. A utility program for converting bundle files (.out) to the input required by Dr. Yasutaka Furukawa's PMVS multi-view stereo system (http://www.cs.washington.edu/homes/furukawa/research/pmvs/index.html) called Bundle2PMVS is also included. Finally, this distribution 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. ---------------- Before you begin ---------------- You'll first need to download the Bundler distribution from: 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 a feature detector components to get the system working. Assuming you will be using SIFT features generated by David Lowe's SIFT binary, you'll need to download that binary 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/bin/libANN_char.so (Linux/cygwin) or BASE_PATH/bin/ann_1.1_char.dll (Windows VS2005) to a location in your LD_LIBRARY_PATH (or add BASE_PATH/lib to LD_LIBRARY_PATH). --------------- Running bundler --------------- The easiest way to start using Bundler is to use the included bash shell script, RunBundler.sh. Just execute this script in a directory with a set of images in JPEG format, and it will automatically run all the steps needed to run structure from motion on the images (assuming everything goes well). 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 probably 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. Again, running the RunBundler.sh script is the easiest way to perform these steps. To simplify steps 1-3, a number of utility scripts and programs are included with this distribution (and invoked from the RunBundler.sh script). 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. ------------- Output format ------------- Bundler produces files typically called 'bundle_*.out' (we'll call these "bundle files"). With the default commands, Bundler outputs a bundle file called 'bundle_<n>.out' containing the current state of the scene after each set of images has been registered (n = the number of currently registered cameras). After all possible images have been registered, Bundler outputs a final file named 'bundle.out'. In addition, a "ply" file containing the reconstructed cameras and points is written after each round. These ply files can be viewed with the "scanalyze" mesh viewer, available at http://graphics.stanford.edu/software/scanalyze/. 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 <pointI> 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"). 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 f