From 02a04b1877ffa49dc3ed48eebc276fec9b2bd190 Mon Sep 17 00:00:00 2001 From: Noah Snavely Date: Sat, 28 Dec 2013 20:50:19 -0500 Subject: [PATCH] updating README --- README.md | 89 +++++++++++++++++++++++++++++---------------- RunBundler.sh | 16 ++++++++ src/Bundle.cpp | 5 +-- src/BundleCeres.cpp | 2 - src/BundleFast.cpp | 2 + src/BundlerApp.h | 2 +- src/Makefile | 23 ++++++++---- 7 files changed, 95 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 63d2014..a4e3287 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,12 @@ Bundler v0.4 User's Manual -------------------------- -copyright 2008-2012 Noah Snavely (snavely@cs.cornell.edu) +copyright 2008-2013 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 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,14 +73,29 @@ 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 @@ -83,11 +103,15 @@ command like (in bash): 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 ", 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 ---------------- diff --git a/RunBundler.sh b/RunBundler.sh index 74f0c0a..4d1b028 100755 --- a/RunBundler.sh +++ b/RunBundler.sh @@ -17,6 +17,11 @@ # INIT_FOCAL= # value to use for initial focal length # FOCAL_WEIGHT= # weight used to constrain focal length # RAY_ANGLE_THRESHOLD= # 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= # 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! diff --git a/src/Bundle.cpp b/src/Bundle.cpp index 6d23814..3c52a57 100644 --- a/src/Bundle.cpp +++ b/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 } diff --git a/src/BundleCeres.cpp b/src/BundleCeres.cpp index 33f33d0..6fb0fe2 100644 --- a/src/BundleCeres.cpp +++ b/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; diff --git a/src/BundleFast.cpp b/src/BundleFast.cpp index 9bc797b..e27eae6 100644 --- a/src/BundleFast.cpp +++ b/src/BundleFast.cpp @@ -400,6 +400,8 @@ void BundlerApp::BundleAdjustFast() } // printf(" [%03d] %0.3f\n", i, cameras[i].f); } + + fflush(stdout); } #if 0 diff --git a/src/BundlerApp.h b/src/BundlerApp.h index 23d589a..96134f4 100644 --- a/src/BundlerApp.h +++ b/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; diff --git a/src/Makefile b/src/Makefile index db4ddac..fdc9c51 100644 --- a/src/Makefile +++ b/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,12 +26,10 @@ 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 \ @@ -37,12 +37,21 @@ BUNDLER_OBJS=BaseApp.o BundlerApp.o keys.o Register.o Epipolar.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)