Documentation - CMVS
Installation
The following installation procedure is primarily for Linux. Major
modifications may be necessary for Windows and some other platforms.
In some system, you may need extract "#include" statements. For
example, you may want to add "#include " in
base/cmvs/bundle.cc, and "#include " in genOption.cc.
- Installing dependent software and libararies
- Install latest Bundler. Please install the latest Bundler
(version 0.4 or higher), whose Bundle2PMVS outputs camera parameters
and image names in the compatible format.
- Install PMVS2.
Follow instructions on the website.
- Install Graclus.
Version 1.2 is compatible. Assume you are using a 64bit machine, set a compilation option (-DNUMBITS=64) in stead of (-DNUMBITS=32), which is the default.
(We thank Nghia Ho for pointing this out). Place the compiled
libmetis.a and libmultilevel.a into the directory, which is specified as YOUR_LDLIB_PATH in PMVS2's Makefile.
- Installing CMVS
- > cd ./pmvs-2
// Go to PMVS2 directory
- > mv program/main/Makefile program/main/Makefile.bak // Back-up Makefile
- > wget http://grail.cs.washington.edu/software/cmvs.tar.gz // Download cmvs.tar.gz.
- > tar -xvzf cmvs.tar.gz
// Unpack. Overwrite existing files if any.
- Edit program/main/Makefile as follows.
- Copy YOUR_INCLUDE_PATH and YOUR_LDLIB_PATH from program/main/Makefile.bak.
- Set YOUR_INCLUDE_METIS_PATH to the directory that contains header files of Graclus (metis.h, defs.h, macros.h, proto.h rename.h, and struct.h under graclus1.2/metisLib/).
- > make // Three binaries are pmvs2, cmvs, and genOption
Command specifications
cmvs
Usage: ./cmvs prefix maximage[=100] CPU[=4]
Example: If you want to specify maximage=70 and CPU=6 with the data directory located at ./pmvs,
try the following command
./cmvs ./pmvs/ 70 6
You should choose maximage based on the amount of memory in your machine.
CPU should be the number of (virtual) CPUs or cores in your machine.
If you want more control of the program, look into the comments inside program/main/cmvs.cc
genOption
Usage: ./genOption prefix level[=1] csize[=2] threshold[=0.7] wsize[=7] minImageNum[=3] CPU[=8]
Parameters are for PMVS2 option files.
Please refer to PMVS2 documentation for the definitions:
Output file formats
cmvs generates four types of outputs.
- ske.dat
This file contains the clustering information. I use hall dataset as an example, which is included in the package, to explain the format.
Note that since genOption automatically generates PMVS2 option-files from ske.dat, you need not really understand the format.
-------------------------------------------------------------------------------------------------------
SKE
// Just a header
61
4
// The first number (61) is the number of images in the dataset.
// The second number (4) is the number of extracted clusters.
13
0
// The next 2 lines contain the information about the first cluster.
15 18 19 21 22 23 24 25 27 28 30 32
33 // The first
number in the first line (13) is the number of images in the cluster.
// The second number in the first line is always 0.
//
The second line is the list of image indexes in the cluster.
11
0
// Information about the second cluster. 11 images in the second
cluster.
1 3 4 5 6 7 10 12 15 18
19
// A list of image indexes belonging to the second cluster.
9
0
// Same thing for the third and the fourth clusters...
49 50 51 53 55 56 58 59 60
11 1
32 33 36 37 38 41 42 43 47 49 50
-------------------------------------------------------------------------------------------------------
- vis.dat
This file is an optional input data for PMVS2, and contains image
neighborhood information. Look at PMVS2 website for the definition of
its format.
- centers-%04d.ply (centers-0000.ply, centers-0001.ply, ...)
A file contains a set of 3D points, where each point
represents the camera center of an image belonging to the corresponding
cluster. For example, you can visualize camera centers belonging to the
first cluster by rendering centers-0000.ply.
- centers-all.ply
This file contains the centers of all the input cameras as 3D points. Note that centers-%04d.ply
typically overlap with each other at their boundaries (otherwise MVS
reconstruction accuracy degrades at cluster borders). Also note that
the union of centers-%04d.ply is typically a subset of centers-all.ply, because CMVS removes redundant images that are not necessary for MVS reconstruction.
genOption reads in ske.dat and generates two types of outputs.
- option-%04d
PMVS2 option files. Refer to PMVS2 website for the definition of its internal format.
- pmvs.sh
A list of pmvs2 commands to be
executed. You can just run this script, or if you have multiple
machines, you can run each command on a different machine independently
(and in parallel) to minimize your waiting time.
Example usage
Kermit
The package contains kermit
data (from Bundler), whose files are stored in three directories. Three
directories correspond to three different stages of the reconstruction
pipeline (Bundler, CMVS, and PMVS2).
- data/kermit-after-bundler
contains data after Bundler (and Bundle2PMVS).
- data/kermit-after-bundler-cmvs contains data after cmvs and genOption (i.e., CMVS software).
> cmvs pmvs/
// ske.dat, vis.dat, centers-0000.ply and centers-all.ply are generated.
> genOption pmvs/
// pmvs.sh and option-0000 are generated.
- data/kermit-after-bundler-cmvs-pmvs contains data after pmvs2 (i.e., PMVS2 software).
> sh pmvs/pmvs.sh
// models/option-0000.ply, models/option-0000.patch and models/option-0000.pset are generated.
Starting from kermit-after-bundler, if you run cmvs and genOption, you should get results similar to those in kermit-after-bundler-cmvs. If you run pmvs2 after that, you should get results similar to those in kermit-after-bundler-cmvs-pmvs.
Hall
kermit is a small dataset, and
only one view cluster is found by CMVS. The following dataset (hall) is
relatively large and more interesting. Similarly to kermit,
you should see three directories. Starting from hall-after-bundler and
using the folloiwng commands, you should get similar results.
- data/hall-after-bundler
contains bundle.rd.out, camera parameter files (.txt) and image files
(.jpg)
- data/hall-after-bundler-cmvs contains data after cmvs and genOption (i.e., CMVS software).
> cmvs pmvs/ 20
// ske.dat, vis.dat, centers-0000.ply, centers-0001.ply, centers-0002.ply, centers-0003.ply and centers-all.ply are generated.
> genOption pmvs/
// pmvs.sh, option-0000, option-0001, option-0002 and option-0003 are generated. - data/hall-after-bundler-cmvs-pmvs contains data after pmvs2 (i.e., PMVS2 software).
> sh pmvs/pmvs.sh
// Reconstruction results are under models/.
In running cmvs, I specified a parameter 20
to enforce the size of each view cluster to be at most 20. You should
choose this parameter based on the amount of memory your machine has.
Four view clusters are found and pmvs.sh
contains four pmvs2 commands. If you have more than one machine, you
can, for example, use four computers to run four jobs simultaneously
(four times less waiting time!)
Note on dependent libraries
CMVS depends on several libraries as PMVS2 does (e.g., blas and lapack). CMVS additionally requires Graclus and Stann.
While you need to download and install Graclus (version 1.2) by yourself, CMVS contains
Stann at program/base/stann with some very minor modifications to make
the compilation easy.