Bundler Installation Procedures

Given a set of images depicting a number of 3D points from different viewpoints, bundle adjustment can be defined as the problem of simultaneously refining the 3D coordinates describing the scene geometry as well as the parameters of the relative motion and optical characteristics of the camera(s) employed to acquire the images, according to an optimality criterion involving the corresponding image projections of all of the points.

As I understand it, this is what PhotoSynth does. PhotoSynth the outgrowth of a Photo Tourism project that was based on structure from motion code. Bundler is a structure-from-motion system that can be applied to unordered image collections. Given a set of images, image features, and image matches, using a modified version of the A generic Sparse Bundle Adjustment package in C/C++ that is based on the Levenberg-Marquardt Algorithm, Bundler will reconstruct the scene incrementally to produce a sparse point cloud.

I have been able to get Bundler to run properly on a laptop computer. However, because SIFT (described below) will only process images of a particular size, I have only been able to process images that are 2272x1704. If the images are larger, SIFT runs out of memory and the processing fails. I'm still not sure how to solve this issue so that larger images can be processed. However, for now Bundler seems to be working very well on images that are 2272x1704 or smaller.

Snavely's instructions for installing Bundler can be found here. Because I am neither a mathematician nor an expert computer programmer, some of the steps were not entirely clear to me. I suspect that they may not be clear to other anthropologists either. Thus, becuase I see so much potential for the technology, below I provide a description of how I installed Bundler on my computer. If you are interested in trying out Bundler then I hope the following text will serve as some help. Here is what I did to get Bundler working:

1. Download and install Cygwin. Cygwin is a Linux-like environment for Windows.Bundler runs under Cygwin, and another script that is useful for extracting point clouds from PhotoSynth images also runs under Cygwin. So if you are serious about generating point clouds through structure-from-motion, it is a good idea to install Cygwin on your computer.
2. Download the Bundler distribution from: http://phototour.cs.washington.edu/bundler/. It is highly recommended that one use the Linux/Windows binary distribution which is this file: bundler-v0.3-binary.zip.
3. Extract Bundler zip file into a directory and place it in an appropriate location. Since I run Bundler from a bash shell under Cygwin, I placed Bundler in the Cygwin "home" directory. My user directory is "C:\cygwin\home\Nathan Craig\". The space in my usr director seemed to cause problems for some of the Bundler scripts so I created an additional directory that is "C:\cygwin\home\Nathan_Craig\". I placed the files extraced from the Bundler zip file under this structure as "C:\cygwin\home\Nathan_Craig\bundler_v3". The location where the contents of the Bundler zip file is extracted (in my case "C:\cygwin\home\Nathan_Craig\bundler_v3") is now refered to as BASE_PATH.
4. Download ImageMagick and install it on the computer. Some of the Bundler scripts use ImageMagick to convert jpg files into the pgm format which is required for the Scale-invariant feature transform (SIFT) that is used in finding key-points on the images in the unstreuctured collection.
5. Download the SIFT binary, extract the file, and copy the file "siftWin32.exe" it into the directory "BASE_PATH/bin".
6. The instructions in the Bundler manual state that three files must be edited: ASE_PATH/RunBundler.sh, BASE_PATH/bin/ToSift.sh, and BASE_PATH/bin/extract_focal.pl. I did not edit any of these three files, and Bundler runns fine. In fact when I tried to edit the files as described in the Bundler Manual, the scripts would not run properly. I've left them alone and everything works fine.
7. Establish the environment variable LD_LIBRARY_PATH. There may be more than one way to do this, but I could only figure out one method. I set this variable from Cygwin. I do so in the following way:
   

• Start Cygwin by double clicking on it. You'll be put into the bash shell.
  
• Type in the commands to move into the directory where Bundler is located. Because my default usr directory has a space in the name, I have to move up to the home directory and then navigate into the directory that I created and from there into the directory where Bundler is located.

Move into the directory:
Nathan Craig@DD2P7MJ1 ~
$ cd ../Nathan_Craig/bundler_v3

Set the environmental variable:
Nathan Craig@DD2P7MJ1 ~
$ LD_LIBRARY_PATH=$HOME/Nathan_Craig/bundler_v3/lib

Check to ensure that it has been properly set:
Nathan Craig@DD2P7MJ1 ~
$ echo $LD_LIBRARY_PATH
/home/Nathan_Craig/bundler_v3/lib

8. Now Bundler can be run from the Cygwin bash shell. If you are still in the directory where Bundler is installed, you are ready to go. Noah Snavely, provides a script the makes executing Bundler very easy. Simply run the script RunBundler.sh. If image files are placed into the BASE_PATH directory, by default Bundler will process these. If image files are placed into a subdirectory under BASE_PATH Bundler can be directed to process these as well.

To run Bundler on a group of images that are located in BASE_PATH:
Nathan Craig@DD2P7MJ1 ~
$ RunBundler.sh

To run Bundler on a directory of images under BASE_PATH:
Nathan Craig@DD2P7MJ1 ~
$ RunBundler.sh images
Note, in this case the directory is named images. This directory could be named just about anything that does not contain a space.

Ok, that is it. Bundler will create a series of output files. The ones that are most interesting to me are the PLY files. These contain the point clouds that are generated by Bundler. In the future, I'll be posting information that describes strategies for processing these files to generate products that are useful for recording things like large archaeological sites. For now, I hope to have provided some helpful hints to get Bundler up and running on your computer.