cpfind(1)
NAME
cpfind - Feature matching for panoramic stitching
SYNOPSIS
cpfind [options] -o output_project project.pto cpfind [options] -k i0 -k i1 [...] project.pto cpfind [options] --kall project.pto
DESCRIPTION
cpfind cpfind is a control-point detector for Hugin. It expects a project file as input and writes a project file with control-points on success. It depends on reasonable lens information in the input project file. The first step is the feature description: In this step the images of the project file are loaded and so called keypoints are searched. They describe destinctive features in the image. cpfind uses a gradient based descriptor for the feature description of the keypoints. In a second step, the feature matching, all keypoints of two images are matched against each other to find features which are on both images. If this matching was successfull two keypoints in the two images become one control point.
USAGE
Rectilinear and fisheye images
Cpfind can find control points in rectilinear and fisheye images. To
achieve good control points images with a high horizontal field of view
(e.g. ultra wide rectilinear or fisheye) are therefor remapped into a
conformal space (cpfind is using the stereographic projection) and the
feature matching occurs in this space. Before writing the control
points the coordinates are remapped back to the image space. This
happens automatic depending on the information about the lens in the
input project file. So check that your input project file contains
reasonable information about the used lens.
Using celeste
Outdoor panorama often contains clouds. Clouds are bad areas for
setting control points because they are moving object. Cpfind can use
the same algorithm as celeste_standalone to masked out areas which
contains clouds. (This is only done internal for the keypoint finding
step and does not change the alpha channel of your image. If you want
to generate a mask image use celeste_standalone). To run cpfind with
celeste use
cpfind --celeste -o output.pto input.pto
Using cpfind with integrated celeste should be superior against using
cpfind and celeste_standalone sequential. When running cpfind with
celeste areas of clouds, which often contains keypoints with a high
quality measure, are disregarded and areas without clouds are used
instead. When running cpfind without celeste also keypoints on clouds
are found. When afterwards running celeste_standalone these control
points are removed. In the worst case all control points of a certain
image pair are removed.
So running cpfind with celeste leads to a better "control point
quality" for outdoor panorama (e.g. panorama with clouds). Running
cpfind with celeste takes longer than cpfind alone. So for indoor
panorama this option does not need to specified (because of longer
computation time).
The celeste step can be fine tuned by the parameters --celesteRadius
and --celesteThreshold.
Matching strategy
All pairs
This is the default matching strategy. Here all image pairs are matched
against each other. E.g. if your project contains 5 images then cpfind
matches the image pairs: 0-1, 0-2, 0-3, 0-4, 1-2, 1-3, 1-4, 2-3, 2-4
and 3-4
This strategy works for all shooting strategy (single-row, multi-row,
unordered). It finds (nearly) all connected image pairs. But it is
computational expensive for projects with many images, because it test
many image pairs which are not connected.
Linear match
This matching strategy works best for single row panoramas:
cpfind --linearmatch -o output.pto input.pto
This will only detect matches between adjacent images, e.g. for the 5
image example it will matches images pairs 0-1, 1-2, 2-3 and 3-4. The
matching distance can be increased with the switch --linearmatchlen.
E.g. with --linearmatchlen 2 cpfind will match a image with the next
image and the image after next, in our example it would be 0-1, 0-2,
1-2, 1-3, 2-3, 2-4 and 3-4.
Multirow matching
This is an optimized matching strategy for single and multi-row
panorama:
cpfind --multirow -o output.pto input.pto
The algorithm is the same as described in multi-row panorama. By
integrating this algorithm into cpfind it is faster by using several
cores of modern CPUs and don't caching the keypoints to disc (which is
time consuming). If you want to use this multi-row matching inside
hugin set the control point detector type to All images at once.
Keypoints caching to disc
The calculation of keypoints takes some time. So cpfind offers the
possibility to save the keypoints to a file and reuse them later again.
With --kall the keypoints for all images in the project are saved to
disc. If you only want the keypoints of particular image use the
parameter -k with the image number:
cpfind --kall input.pto
cpfind -k 0 -k 1 input.pto
The keypoint files are saved by default into the same directory as the
images with the extension .key. In this case no matching of images
occurs and therefore no output project file needs to specified. If
cpfind finds keyfiles for an image in the project it will use them
automatically and not run the feature descriptor again on this image.
If you want to save them to annother directory use the --keypath
switch.
This procedure can also be automate with the switch --cache:
cpfind --cache -o output.pto input.pto
In this case it tries to load existing keypoint files. For images,
which don't have a keypoint file, the keypoints are detected and save
to the file. Then it matches all loaded and newly found keypoints and
writes the output project.
If you don't need the keyfile longer, the can be deleted automatic by
cpfind --clean input.pto
EXTENDED OPTIONS
Feature description
For speed reasons cpfind is using images, which are scaled to their
half width and height, to find keypoints. With the switch --fullscale
cpfind is working on the full scale images. This takes longer but can
provide "better" and/or more control points.
The feature description step can be fine-tuned by the parameters:
--sieve1width <int>
Sieve 1: Number of buckets on width (default: 10)
--sieve1height <int>
Sieve 1: Number of buckets on height (default: 10)
--sieve1size <int>
Sieve 1: Max points per bucket (default: 100)
--kdtreesteps <int>
KDTree: search steps (default: 200)
--kdtreeseconddist <double>
KDTree: distance of 2nd match (default: 0.25)
Cpfind stores maximal sieve1width * sieve1height * sieve1size keypoints
per image. If you have only a small overlap, e.g. for 360 degree
panorama shoot with fisheye images, you can get better results if you
increase sieve1size. You can also try to increase sieve1width and/or
sieve1height.
Feature matching
Fine-tuning of the matching step by the following parameters:
--ransaciter <int>
Ransac: iterations (default: 1000)
--ransacdist <int>
Ransac: homography estimation distance threshold (pixels) (default:
25)
--ransacmode (auto, hom, rpy, rpyv, rpyb)
Select the model used in the ransac step.
hom: Assume a homography. Only applicable for non-wide angle
views. Uses the original panomatic code. It is also more
flexible
than required and can generate false matches, particularly if
most
of the matches are located on a single line.
rpy: Align images using roll, pitch and yaw. This requires a good
estimate for the horizontal field of view (and distortion, for
heavily distorted images). It is the preferred mode if a
calibrated lens is used, or the HFOV could be read
successfully
from the EXIF data.
rpyv: Align pair by optimizing roll, pitch, yaw and field of
view. Should work without prior knowledge of the field of
view,
but might fail more often, due to error function used in the
panotools optimizer, it tends to shrink the fov to 0.
rpyvb: Align pair by optimizing roll, pitch, yaw, field of view and
the "b" distortion parameter. Probably very fragile, just
implemented for testing.
auto: Use homography for images with hfov < 65 degrees and rpy
otherwise.
--minmatches <int>
Minimum matches (default: 4)
--sieve2width <int>
Sieve 2: Number of buckets on width (default: 5)
--sieve2height <int>
Sieve 2: Number of buckets on height (default: 5)
--sieve2size <int>
Sieve 2: Max points per bucket (default: 2)
Cpfind generates between minmatches and sieve2width * sieve2height
* sieve2size control points between an image pair. (Default setting
is between 4 and 50 (=5*5*2) control points per image pair.) If
less then minmatches control points are found for a given image
pairs these control points are disregarded and this image pair is
considers as not connected. For narrow overlaps you can try to
decrease minmatches, but this increases the risk of getting wrong
control points.
OPTIONS
--celesteRadius <int>
Radius for celeste (default 20)
--celesteThreshold <double>
Threshold for celeste (default 0.5)
--celeste
Run celeste sky identification after loading images, this ignores
all features associated with 'clouds'.
-p <string, --keypath <string>
Path to cache keyfiles
--clean
Clean up cached keyfiles
-c, --cache
Caches keypoints to external file
--kall
Write keyfiles for all images
-k <int>, --writekeyfile <int>
Write a keyfile for this image number (accepted multiple times)
-o <string>, --output <string>
Output file, required
-n <int>, --ncores <int>
Number of CPU/Cores (default:autodetect)
-t, --test
Enables test mode
--fullscale
Uses full scale image to detect keypoints (default:false)
--sieve1width <int>
Sieve 1 : Number of buckets on width (default : 10)
--sieve1height <int>
Sieve 1 : Number of buckets on height (default : 10)
--sieve1size <int>
Sieve 1 : Max points per bucket (default : 100)
--kdtreesteps <int>
KDTree : search steps (default : 200)
--kdtreeseconddist <double>
KDTree : distance of 2nd match (default : 0.15)
--multirow
Enable heuristic multi row matching (default: off)
--linearmatch
Enable linear images matching (default : all pairs)
--linearmatchlen <int>
Number of images to match in linear matching (default:1)
--minmatches <int>
Minimum matches (default : 4)
--ransaciter <int>
Ransac : iterations (default : 1000)
--ransacdist <int>
Ransac : homography estimation distance threshold (pixels) (default
: 25)
--sieve2width <int>
Sieve 2 : Number of buckets on width (default : 5)
--sieve2height <int>
Sieve 2 : Number of buckets on height (default : 5)
--sieve2size <int>
Sieve 2 : Max points per bucket (default : 2)
--, --ignore_rest
Ignores the rest of the labeled arguments following this flag.
--version
Displays version information and exits.
-h, --help
Displays usage information and exits.
AUTHORS
Anael Orlinski, Pablo d'Angelo, Antoine Deleforge, Thomas Modes "Version: 2016.2.0" 2016-09-11 CPFIND(1)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
