updating README

README.md

@@ -1,11 +1,12 @@
 Bundler v0.4 User's Manual
 --------------------------
-copyright 2008-2012 Noah Snavely ([email protected])
+copyright 2008-2013 Noah Snavely ([email protected])
 
 based on the Photo Tourism work of Noah Snavely, Steven M. Seitz, 
   (University of Washington) and Richard Szeliski (Microsoft Research)
 
-For more information, see the Bundler homepage at http://www.cs.cornell.edu/~snavely/bundler/.
+For more information, see the Bundler homepage at 
+    http://www.cs.cornell.edu/~snavely/bundler/
 
 What is Bundler?
 ----------------
@@ -20,16 +21,19 @@ 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).
-
+(though it may also compile in Windows under Cygwin, and a Visual
+Studio solution file is also provided).
 
 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.
+contact address below.  If you use Bundler for a publication, please
+cite the following paper:
 
+  Noah Snavely, Steven M. Seitz, and Richard Szeliski. Photo Tourism:
+  Exploring Photo Collections in 3D. SIGGRAPH Conf. Proc., 2006.
 
 What's included
 ---------------
@@ -53,9 +57,10 @@ images (based on the undistortion parameters estimated by Bundler).
 Before you begin
 ----------------
 
-You'll first need to download the Bundler distribution from:
+You'll first need to download the Bundler distribution from GitHub:
 
-    http://phototour.cs.washington.edu/bundler 
+or visit the Bundler homepage at 
+   http://phototour.cs.washington.edu/bundler 
 
 and extract it into a directory (to be referred to as BASE_PATH).
 
@@ -68,26 +73,45 @@ Lowe's SIFT binary, you'll need to download that binary from
 and copy it to BASE_PATH/bin (making sure it is called 'sift', or
 'siftWin32.exe' under Windows).
 
-The bundler.py script requires that you have Python and the Python
-Image Library (PIL) installed on your computer.
+The utils/bundler.py script requires that you have Python and the
+Python Image Library (PIL) installed on your computer.
+
+To make bundler, just type 'make' in the main bundler directory.
+Note that if you plan to run Bundler on large problems, you may wish
+to enable the use of the Ceres solver for bundle adjustment, which can
+improve speed over the default SBA bundle adjuster.  To do so, edit
+the file 'src/Makefile' and uncomment the line
+
+    USE_CERES=true
+
+Note that this assumes you have Ceres and its dependencies installed
+on your system.  See the Ceres solver page at
+
+   https://code.google.com/p/ceres-solver/
+
+for more information.
 
-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/bin to LD_LIBRARY_PATH with a 
-command like (in bash):
+Finally, once Bundler is compiled, 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/bin to
+LD_LIBRARY_PATH with a command like (in bash):
 
     LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/bundler/bin
 
 
 Running bundler
 ---------------
 
-The easiest way to start using Bundler is to use the included Python
-script, bundler.py.  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 easiest way to start using Bundler is to either use the provided
+RunBundler.sh bash script, or the included Python script (by Isaac
+Lenton), utils/bundler.py.  Just execute either 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).  For RunBundler.sh, you may optionally provide
+a configuration file as a command line argument---see RunBundler.sh
+for a description of the configuration options available.  Notably,
+you can choose to use Ceres when running Bundler.
 
 To get help on using the Python script bundler.py:
 
@@ -125,19 +149,21 @@ therefore:
    'matches.init.txt'.
 4. Run 'bundler' with a suitable options file.
 
-Again, running the bundler.py script is the easiest way to perform
-these steps.  Steps 1-3 can also be invoked individually from
-functions contained in the bundler.py script.
+Again, running the RunBundler.sh or bundler.py script is the easiest
+way to perform these steps.  Steps 1-3 can also be invoked
+individually from functions contained in the bundler.py 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.
-Next, an options file containing settings to be used for the
-current run is given.  bundler.py creates an options file that will
-work in many situations.  Common options are described later in this
-document.  To generate only the list of images, run:
+The first argument is the list of images to be reconstructed.  Next,
+an options file containing settings to be used for the current run is
+given.  The RunBundler.sh and bundler.py scripts create an options
+file that will work in many situations (and some of these options can
+be controlled by the configuration file passed to RunBundler.sh).
+Common options are described later in this document.  To generate only
+the list of images, run:
 
  > bundler.py --extract-focal
 
@@ -236,10 +262,10 @@ Bundler has a number of internal parameters, so there are a large
 number of command-line options.  That said, we've found that a common
 set of parameters works well for most image collections we've tried,
 so it is probably safe to start with the recommended options (used by
-the bundler.py script).  One very useful option is 
+the RunBundler.sh and bundler.py scripts).  One very useful option is
 "--options_file <file>", which tells Bundler to read a list of options
-from a file.  The default options file created by bundler.py
-includes the following:
+from a file.  The default options file created by RunBundler.sh or
+bundler.py includes the following options:
 
   --match_table matches.init.txt
      [specifies the file where the match files are stored]
@@ -316,7 +342,8 @@ ones listed above, including:
 
 Links
 -----
-Pierre Moulon has a cmake version of Bundler available here: https://github.com/TheFrenchLeaf/Bundler.
+Pierre Moulon has a cmake version of Bundler available here: 
+    https://github.com/TheFrenchLeaf/Bundler.
 
 Acknowledgements
 ----------------

RunBundler.sh

@@ -17,6 +17,11 @@
 #   INIT_FOCAL=<num>   # value to use for initial focal length
 #   FOCAL_WEIGHT=<num> # weight used to constrain focal length
 #   RAY_ANGLE_THRESHOLD=<num> # used to remove ill-conditioned points
+#   USE_CERES=yes # enables use of Ceres solver for bundle adjustment
+#                 # (if this is enabled at compile time)
+#   NUM_MATCHES_ADD_CAMERA=<num> # number of matches above which bundler
+#                                # will definitely attempt to add a camera
+#                                # (e.g., you might use 500)
 #
 
 BASE_PATH=$(dirname $(which $0));
@@ -113,6 +118,17 @@ echo "--constrain_focal" >> options.txt
 echo "--constrain_focal_weight $FOCAL_WEIGHT" >> options.txt
 echo "--estimate_distortion" >> options.txt
 echo "--ray_angle_threshold $RAY_ANGLE_THRESHOLD" >> options.txt
+
+if [ "$NUM_MATCHES_ADD_CAMERA" != "" ]
+then
+    echo "--num_matches_add_camera $NUM_MATCHES_ADD_CAMERA" >> options.txt
+fi
+
+if [ "$USE_CERES" != "" ]
+then
+    echo "--use_ceres" >> options.txt
+fi
+
 echo "--run_bundle" >> options.txt
 
 # Run Bundler!

src/Bundle.cpp

@@ -561,9 +561,8 @@ double BundlerApp::RunSFM(int num_pts, int num_cameras, int start_camera,
     return 
         RunSFM_SBA(num_pts, num_cameras, start_camera, fix_points, 
                    init_camera_params, init_pts, 
-                   added_order, colors, pt_views,
-                   max_iter, max_iter2, verbosity, eps2, S, U, V, W, 
-                   remove_outliers, final_bundle, write_intermediate);
+                   added_order, colors, pt_views, eps2, S, U, V, W, 
+                   remove_outliers);
 #endif
 }
 

src/BundleCeres.cpp

@@ -648,8 +648,6 @@ double BundlerApp::RunSFM_Ceres(int num_pts, int num_cameras,
                                     iround(0.5 * num_pts_proj), dists), 
                    thresh);
 
-	    // printf("Outlier threshold is %0.3f\n", thresh);
-
 	    pt_count = 0;
 	    for (int j = 0; j < num_keys; j++) {
 		int pt_idx = GetKey(added_order[i],j).m_extra;

src/BundleFast.cpp

@@ -400,6 +400,8 @@ void BundlerApp::BundleAdjustFast()
                 }
                 // printf("   [%03d] %0.3f\n", i, cameras[i].f);
             }
+
+            fflush(stdout);
         }
 
 #if 0

src/BundlerApp.h

@@ -31,7 +31,7 @@ class BundlerApp : public BaseApp
 public:
     BundlerApp() {
         /* Set initial values */
-        m_bundle_version = 0.1;
+        m_bundle_version = 0.3;
 
         m_fisheye = false;
         m_fixed_focal_length = true;

src/Makefile

@@ -1,9 +1,11 @@
 # Makefile for bundler
 
+USE_CERES=true
+
 CC=gcc
 CXX=g++
 OPTFLAGS=-O3 -Wall
-OTHERFLAGS=-std=gnu++0x -D__USE_CERES__
+OTHERFLAGS=-std=gnu++0x
 
 OS=$(shell uname -o)
 
@@ -24,25 +26,32 @@ endif
 
 INCLUDE_PATH=-I../lib/imagelib -I../lib/sfm-driver -I../lib/matrix	\
 	-I../lib/5point -I../lib/sba-1.5 -I../lib/ann_1.1_char/include  \
-	-I../include -I/usr/include/eigen3
+	-I../include
 
 LIB_PATH=-L../lib -L../lib/ann_1.1_char/lib
 
-CPPFLAGS=$(OPTFLAGS) $(OTHERFLAGS) $(INCLUDE_PATH) $(DEFINES)
-
 BUNDLER_DEFINES=-D__NO_UI__ -D__BUNDLER__ -D__BUNDLER_DISTR__
 
 BUNDLER_OBJS=BaseApp.o BundlerApp.o keys.o Register.o Epipolar.o	\
 	Bundle.o BundleFast.o MatchTracks.o Camera.o Geometry.o		\
 	ImageData.o SifterUtil.o BaseGeometry.o BundlerGeometry.o	\
 	BoundingBox.o BundleAdd.o ComputeTracks.o BruteForceSearch.o	\
 	BundleIO.o ProcessBundle.o BundleTwo.o Decompose.o		\
-	RelativePose.o Distortion.o TwoFrameModel.o LoadJPEG.o		\
-	BundleCeres.o
+	RelativePose.o Distortion.o TwoFrameModel.o LoadJPEG.o
 
 BUNDLER_LIBS=-limage -lsfmdrv -lsba.v1.5 -lmatrix -lz -lblas -llapack \
 	-lcblas -lminpack -lm -l5point -ljpeg -lANN_char -lgfortran
-CERES_LIBS=-lceres -lgomp -lglog -lcholmod
+CERES_LIBS= -lceres -lgomp -lglog -lcholmod
+
+# if we are using Ceres, add to options
+ifdef USE_CERES
+BUNDLER_DEFINES+=-D__USE_CERES__
+BUNDLER_LIBS+=$(CERES_LIBS)
+BUNDLER_OBJS+=BundleCeres.o
+INCLUDE_PATH+=-I/usr/include/eigen3
+endif
+
+CPPFLAGS=$(OPTFLAGS) $(OTHERFLAGS) $(INCLUDE_PATH)
 
 all: $(BUNDLER) $(KEYMATCHFULL) $(BUNDLE2PLY) $(BUNDLE2PMVS) $(BUNDLE2VIS) $(RADIALUNDISTORT)