Bundler v0.3-Structure from Motion (SfM) for Unordered Image Collections

--------------------------------------------------------------------------
  Bundler v0.3 User's Manual
    copyright 2008-2009 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 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包含文件
---------------
二进制发布版Bundler可执行文件bin/bundler和一组其他辅助脚本和可执行文件（bin/ 目录）。另外，示例图像集和图像结果在examples目录。

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.

一个实用的Bundle2PMVS程序也包含在内，它能转换bundle文件.out到Yasutaka Furukawa博士的 PMVS多视立体系统要求的输入文件。最后这种分布
包括了一项名为RadialUndistort的软件它生成无畸变图像（基于Bundler的对无畸变参数估计）。

A utility program for converting bundle files (.out) to the input required by Dr. Yasutaka Furukawa's PMVS multi-view stereo system(点击打开链接)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).

最后，bin目录中的jhead程序能够读取JPEG图像中的Exif标记。

注：exif abbr. 可交换图像文件（Exchangeable Image File）可交换照片文件资料

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.



在成功执行Bundler前，我们需要做几步准备工作：
----------------
Before you begin
----------------
下载Bundler后，将其解压到一个路径，比如：E:\bundler（下面都以BASE_PATH来代替）。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).

下载特征检测器。Bundler推荐使用SIFT来进行特征提取，可以到SIFT的作者David Lowe的主页上下载他提供的SIFT Demo作为我们的检测器。下载页面为： http://www.cs.ubc.ca/~lowe/keypoints/ 或者直接点击右边的下载地址下载：SIFT demo program (Version 4, July 2005)

下载完成后，解压该文档，将目录下的siftWin32.exe文件拷贝到BASE_PATH\bin目录中。

下面对运行Bundler的脚本文件进行修改：

把RunBundler.sh文件中BASE_PATH=$(dirname $(which $0)); 一句等号后边的东西替换为Bundler的根目录，也就是RunBundler.sh文件所在的目录，记得加双引号。如BASE_PATH="E:/SDK/bundler-v0.4-source";。

然后把ToSift.sh文件中BIN_PATH设为bin目录，如BIN_PATH="E:/SDK/bundler-v0.4-source/bin"。

注意bash命令要用斜杠/。

5.这下就大功告成了！！

打开Cygwin，cd定位到Bundler根目录下，然后输入下面的命令测试一下例子的图片：

./RunBundler.sh examples/ET

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 fromhttp://www.cs.ubc.ca/~lowe/keypoints/   and copy it to BASE_PATH/bin (making sure it is called 'sift', or'siftWin32.exe' under Windows).

由于Bundler默认是通过在Unix环境下执行shell脚本来启动Bundler的，因此在Windows环境下需要安装Cygwin以执行shell脚本bash和per，需要安装的库和软件(直接在安装时选择)： Devel, Perl, Python, ImageMagick, GSL, vim
l。
下载和安装Cygwin。Cygwin是许多自由软件的集合，最初由Cygnus Solutions开发，用于各种版本的Microsoft Windows上，运行UNIX类系统。　　要下载cygwin，直接在setup.exe上点右键“另存为”即可。也可以复制右边这个地址：http://cygwin.com/setup.exe

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

最后一步，拷贝近似近邻（Approximate Nearest Neighbors，ANN）共享库

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).

siftWin32.exe只能出来PGM文件，所以过程中必有转换。

用convert 和 mogrify 批量转换目录树下的jpg文件到bmp文件，
开始我只会find ,xargs 命令进行 批量删除 操作。比如递归删除本目录下所有.db文件：
find ./ -name "*.db" | xargs rm
如果用
find ./ -name "*.db" | xargs convert "*.jpg" "*.bmp"
命令，转化得到的目标文件只是一个*.bmp。因为我不知道如何对文件名进行变量替换。所以只能寻求其他方法。
用下面的命令组合，能达到开篇说的效果了。
find ./ -name '*.jpg' | xargs -n1 mogrify -format bmp
我按照下面的链接，达到了效果：http://www.unix.com/shell-programming-scripting/63499-problem-using-find-xargs.html
文章内容是：
手上有一堆很大的tif图片，想要批量转成尺寸小一点的jpg图片。对于图片处理，特别是批量的时候，命令行工具
imagemagick
可以说是最好不过的工具了。
一般对于处理转换图片，imagemagick提供了convert和mogrify两个工具，convert一般用于处理完后输出到另一个文件，而mogrify一般用于修改源文件，但是如果指明不同的格式，mogrify也会保存到另一个不同扩展名的文件中去。这里我要用到的就是magrify。
命令很简单：
ls *tif | xargs -n1 mogrify -format jpg -resize ">1024x1024"
xargs的强大，这里就不说了。这里主要涉及mogrify的两个参数，-fromat和-resize。-format指
明格式，这里是jpg。-resize就是要修改尺寸，这里用的是">1024x1024"，意思是输出图片不能大于1024x1024，这也是一
个很方便的用法，这样，输出的图片最长的一边都不会超过1024，大小都比较统一。如果只是指明 -resize 1024
的话，只能保证横向宽度为1024，如果是纵向较长的竖图片，可能就会变成1024x1540之类的尺寸，大小就不统一了。
imagemagick非常强大，并且具备命令行工具特有的方便和适于脚本的特性，非常适合于批量处理。除了上述的例子，我原先还用imagemagick写过一个批量添加png图片透明层的简单脚本，不过不知道扔哪儿了，回头找找再帖上来。
                 


---------------
Running bundler
---------------

最简单的开始使用Bundler的方法是使用包含的bash shell脚本RnuBundlse.sh。仅需对包含一系列JPEG格式图像的目录运行这个脚本。打开Cygwin，cd定位到BASE_PATH目录下，然后输入下面的命令Picture为包含图像的目录，它就会自动运行所有步骤对图像运行SFM。

./RunBundler.sh Pictures

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).

在这一系列步骤中，Bundler程序实际上是重建场景所需运行的序列中的最后一个步骤。 RunBundler.sh为你考虑所有这些步骤，但是你如果知道正在发生什么将非常有用。主要的初始化步骤是生成图像集的特征和成对匹配特征。任何类型图像特征都可以使用，但是Bundler推荐使用SIFT格式，也即David Lowe的SIFT的检测器。而且必须创建包含估计焦距信息的列表。共4步来制作一个三维重建。

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 athttp://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:

第一步，使用'extract_focal.pl'脚本制作图像信息的焦距列表，可操作的从每张影像并存储到图像列表
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).

第二步，对每一图像生成SIFT特征
2. Generate (SIFT) features for each image.

第三步对成对匹配图像进行特征匹配（需要花一些时间）。计算的结果存储到'matches.init.txt'文件中。

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'.

第四步使用合适可选文件运行Bundler。
4. Run 'bundler' with a suitable options file.

再说一遍，使用包含的bash shell脚本RnuBundlse.sh是最简单的使用Bundler的方法。简化1-3步
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 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 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 .




--------------------
Command-line options
--------------------


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 RunBundler.sh script).  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 RunBundler.sh
includes the following:


  --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)]


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.]


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


  --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.]


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




----------------
Acknowledgements
----------------


This work was supported by Microsoft Research, the University of
Washington Animation Research Labs, an Achievement Rewards for College
Scientists (ARCS) fellowship, National Science Foundation grants
IIS-0413198 and DGE-0203031, and an endowment by Emer Dooley and Rob
Short.


Thanks to Manolis Lourakis and Antonis Argyros for their sparse bundle
adjustment package (http://www.ics.forth.gr/~lourakis/sba/), to David
Lowe for SIFT (http://www.cs.ubc.ca/~lowe/keypoints/), to David
M. Mount and Sunil Arya for their approximate nearest neighbors
library (http://www.cs.umd.edu/~mount/ANN/), and to Matthias Wandel
for his 'jhead' program.


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




-------------------
Contact information
-------------------


Questions?  Comments?  Bug reports?  Please see the FAQ at
http://phototour.cs.washington.edu/bundler/faq.html, or send email to
Noah Snavely at [email protected].




[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.