Detailed Manual
B. Creating the Point Cloud
This guide helps you to create a 3D-Model (in fact a dense point cloud) out of simple digital photographs.
The images you shoot should have an overlap of 60 % so that every part of the object will appear in at least
three pictures. Shoot from various angles and use different zooms. Wide shots are good and you can add a
couple of close-ups. Changing the position of an angle 15-25 degree should give you enough overlap. The
more pictures, the better - but this will, of course mean slower image generation. Make sure the orientation
of the each image is right-side up before you start the tool.
Not every object or material will be recognized when creating a model with these tools. In addition, the
quality and the overlap of each image used will have a strong influence on the final result. In some cases, the
system won´t be able to finish the process for these reasons!The process of getting a 3D Point cloud is
described below. To further edit the point cloud (meshing, measuring, modeling etc.), you will have to use
software that can open the *.ply format, which is the output of this.
Creating the point cloud is a process that includes several programs, mainly Bundler, CMVS and PMVS2. In
the "BundlerTools" folder you will find the script "run.pl" which will process every step automatically so you
do not need to activate every programme manually. You may wish to specify something, which is also
possible (see below "Detailed Details" or check the Documentation and FAQ´s on the Bundler, CMVS &
PMVS2 website).
The duration of this process depends on several factors including your computer's capabilities (memory,
speed etc...) and the selected resolution of the images and the surface/material (for finding keypoints and
matching) of the designated object. If the tool can´t finish properly, try to scale down the resolution or take
less pictures, each of which, can, in some cases lead to less points in the model, If not, it may be time for a
new computer!
The shortest way to get a decent point cloud is the following:
1. Take pictures of the desired object with as much overlap as possible.
2. Upload the pictures onto your computer and save into one folder.
3. Open a terminal window and navigate into the folder where the pictures are stored (using the cd
command)
4. Start the run-Script by using a relative path. For example:
/perl /home/computername/Desktop/BundlerTools/run.pl (UBUNTU)
ruby <bundler_tools_path>/run.rb <images_path> (FEDORA)
The bundler_tools_path could be like this: /home/computername/Desktop/BundlerTools/
The image_path could be like this: /home/computername/Desktop/Pictures/
Keep one space between both paths.
You will find a set of images plus the expected result in the TopoiLion.zip folder below. This folder was also
used for the following screenshots. Additionally it contains a logfile (TopoiLion.txt) where you can track
every single step processed in the terminal window by running BundlerTools with this set. More test data is
provided by PMVS2 - check the website. You will find a set of images and the expected result in the
directory BundlerTools -> src -> cmvs -> data.
run.pl
The Tool starts by running the programmes mentioned above. Firstly, it prepares the pictures and secondly, a
dense point cloud is generated. The single steps are:
a. "resize" - changes images to the designated size
b. "getKeypoints" - searches for special features in the images
c. "match" - matches corresponding features in pairs
d. "bundler" - creates a sparse point cloud
e. "cmvs" - decomposes the images into clusters and removes redundant images
f. "pmvs" - creates a dense point cloud, final output data type is .ply
Every step requires a certain amount of time depending on the size and quality of the images (i.e how many
features will be found. The more features, the better the point cloud - but also the longer the time to process),
and your machine's capabilities. In any case, all what you can do now is to ...
5. WAIT.
6. Once the programme has finished you will find two new folders. The first one contains all the files which
were created during the entire process. If you are just interested in the final result, go to the second folder
called “reconstruction-with-image-size-xxxx-results” where you find a file named "option-0000.ply". This is
the dense point cloud (you will also find it in the first folder under pmvs -> models). In order to save space
on your machine, it is recommended to delete the first folder (not the -result - folder!) and only keep the
images and the result.
Result
7. You can open this file (ply format), for example, in Meshlab and save it with another name, since every
next generated pointcloud will get the same name (option-0000.ply).
There is another run-script at the repository, which runs much faster due to another matching-process. Check
here:https://github.com/qwesda/BundlerTools/wiki/usage for more Details
For meshing, modelling or editing the point clouds, there are several programmes (e.g.
Meshlab:http://meshlab.sourceforge.net/) you can use.
C. Specifications/Troubleshooting:
In some cases, you may not achieve a satisfying result or the programme will stop before finishing for a
variety of reasons. In either case, you have several options to optimise the process and give it another try.
It is recommended to delete the files that were created in the first attempt and start with a folder that contains
only the desired pictures.
For using these specifications check also the “Run script details”-page.
1. First, you can the size of the pictures. The general rule is, the better (thus bigger) the pictures, the better
the point cloud. Your system may not be able to run the program with larger images and will ultimately
crash. If this happens, try scaling down the image size. Smaller images will result in a less denser
reconstruction, but will finish faster and consume less memory. If for example you want to do a quick test of
a model, choose a small size like 400x400 pixels. The default size is 1200x1200 pixels which usually gives a
nice model. A higher pixel value will give you more points in the cloud. At some point the model won´t
appear any better (just more points), so you have to find the right balance that best meets your requirements
Of course, finding this balance often results in the process taking a lot of time or crashing.
To scale the pictures simply add the command to the run.pl command. For instance:
run.pl --resize-to 400
2. If the process doesn't work properly you will have to check if the used Camera is registered. You will
notice your camera is not registered if the terminal window reads: no ccd width found for…You can also
look at the generated list.txt file for your dataset, which you find in the first of the newly created folders in
the "Bundler" folder. Each line should have three entries: the image name, a zero, and a focal length. If this
isn't the case, your camera model needs to be registered. You do so by displaying the file "ccd_defs.pl" in the
BundlerTools folder and entering the camera information in the same manner the others are written. You can
find such information for example at www.dpreview.com. Save the “ccd_defs.pl” file and start all over.
If you don´t want to register the camera, which is recommended if you use the camera often, or if the values
for the focal length or ccd width are not found in the exif information of the images, you can set them with
the following parameters:
run.pl --force-focal<positive float> or
run.pl --force-ccd <positive float>
3. The package includes the program CMVS which splits the number of photos into clusters and computed
singularly, thus requiring less memory. You can change the parameters of how many pictures you want in one
cluster and how many cpu´s should work on it. For example, if you want to process 100 pictures and you set
the parameter at 20, you get 5 clusters. You can check the number of clusters also in the ske.dat file, which
you find in the first of the newly created folders in the bundler folder: The first line contains the number of
pictures and then the number of clusters. If you want to change the parameter, set the desired number behind
the run.pl command, for example:
run.pl --cmvs-maxImages 20 (attention: Large I in the middle!)
As long as your machine has enough memory to run PMVS, you will want a smaller number of clusters (and
more images in each cluster), so set the parameter high (for example, the parameter 31 will produce just one
cluster with an input of 30 pictures)
4. If for some reason you need to start or end the script at a specific point, you can use theses comands:
--start-with <"resize", "getKeypoints", "match", "bundler", "cmvs", "pmvs">
--end-with <"resize", "getKeypoints", "match", "bundler", "cmvs", "pmvs">
--run-only <"resize", "getKeypoints", "match", "bundler", "cmvs", "pmvs">
For instance if you have already extracted the keypoints for an imageset, you can use:
run.pl --start-with match
to skip the resizing and keypoint extraction. If you started the first time with a different image size than the
default (1200), you need to add this information to the comand line:
run.pl --start-with bundler --resize-to 2400
D. Extras
1. Poisson Reconstruction
By using the .pset file in the result folder it is also possible to start a Poisson reconstruction in the shell. You
have to navigate in the result folder, use the .pset as input and creat a name for the desired output file by
executing the Poisson Reconstruction programm which you find in the bin folder of Bundler tools.
Typing
/home/computername/Desktop/BundlerTools/bin/PoissonRecon -h
will show you the options of parameters you can choose.
Typing
/home/computername/Desktop/BundlerTools/bin/PoissonRecon --in option0000.pset --out <any name.ply>
will do the Reconstruction.
After finished you find the <any name.ply> with the reconstruction right in the folder.
2. Using a video-camera...soon to come. Could work by using the force-focal and force-ccd command
consecutively. Since the exif data of the video is usually lost by converting the video into frames and jpegs,
this way works so far only by using a tripod and a turntable to film the object, so that the focal length stays
more or less equal (a plain background will probably help). One has to split the movie into frames to be
saved as images (.jpg), then add the force-commands with the right numbers to the regular process. Shoot
one photo from the same position to get these numbers as an example.
If you are not satisfied with the output, the reasons can be missing overlap between photos or blurry photos
or the surface of the object (for example glass), which is hard to be recognized adequately by the software.
For further information, check the Documention of Bundler (http://tacticalspace.org/archives/bundlerphotogrammetry-package/), CMVS (http://www.di.ens.fr/cmvs/) and PMVS.