3
cpfind - Feature matching for panoramic stitching
7
B<cpfind> [options] -o I<output_project> I<project.pto>
9
B<cpfind> [options] -k i0 -k i1 [...] I<project.pto>
11
B<cpfind> [options] --kall I<project.pto>
15
B<cpfind> cpfind is a control-point detector for Hugin. It expects a project
16
file as input and writes a project file with control-points on success.
17
It depends on reasonable lens information in the input project file.
19
The first step is the feature description: In this step the images of the
20
project file are loaded and so called keypoints are searched. They describe
21
destinctive features in the image. B<cpfind> uses a gradient based descriptor
22
for the feature description of the keypoints.
24
In a second step, the feature matching, all keypoints of two images are matched
25
against each other to find features which are on both images. If this matching
26
was successfull two keypoints in the two images become one control point.
30
=head2 Rectilinear and fisheye images
32
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.
36
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
38
cpfind --celeste -o output.pto input.pto
40
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.
42
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).
44
The celeste step can be fine tuned by the parameters --celesteRadius and --celesteThreshold.
46
=head2 Matching strategy
50
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
52
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.
56
This matching strategy works best for single row panoramas:
58
cpfind --linearmatch -o output.pto input.pto
60
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.
62
=head3 Multirow matching
64
This is an optimized matching strategy for single and multi-row panorama:
66
cpfind --multirow -o output.pto input.pto
68
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.
70
=head3 Keypoints caching to disc
72
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:
74
cpfind --kall input.pto
75
cpfind -k 0 -k 1 input.pto
77
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.
79
This procedure can also be automate with the switch --cache:
81
cpfind --cache -o output.pto input.pto
83
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.
85
If you don't need the keyfile longer, the can be deleted automatic by
87
cpfind --clean input.pto
89
=head1 EXTENDED OPTIONS
91
=head2 Feature description
93
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.
95
The feature description step can be fine-tuned by the parameters:
99
=item B<--sieve1width> <int>
101
Sieve 1: Number of buckets on width (default: 10)
103
=item B<--sieve1height> <int>
105
Sieve 1: Number of buckets on height (default: 10)
107
=item B<--sieve1size> <int>
109
Sieve 1: Max points per bucket (default: 30)
111
=item B<--kdtreesteps> <int>
113
KDTree: search steps (default: 40)
115
=item B<--kdtreeseconddist> <double>
119
KDTree: distance of 2nd match (default: 0.15)
121
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 sizeve1size. You can also try to increase sieve1width and/or sieve1height.
123
=head2 Feature matching
125
Fine-tuning of the matching step by the following parameters:
129
=item B<--ransaciter> <int>
131
Ransac: iterations (default: 1000)
133
=item B<--ransacdist> <int>
135
Ransac: homography estimation distance threshold (pixels) (default: 25)
137
=item B<--minmatches> <int>
139
Minimum matches (default: 4)
141
=item B<--sieve2width> <int>
143
Sieve 2: Number of buckets on width (default: 5)
145
=item B<--sieve2height> <int>
147
Sieve 2: Number of buckets on height (default: 5)
149
=item B<--sieve2size> <int>
151
Sieve 2: Max points per bucket (default: 2)
153
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.
161
=item B<--celesteRadius> <int>
163
Radius for celeste (default 20)
165
=item B<--celesteThreshold> <double>
167
Threshold for celeste (default 0.5)
171
Run celeste sky identification after loading images, this ignores all features
172
associated with 'clouds'.
174
=item B<-p <string>, B<--keypath> <string>
176
Path to cache keyfiles
180
Clean up cached keyfiles
182
=item B<-c>, B<--cache>
184
Caches keypoints to external file
188
Write keyfiles for all images
190
=item B<-k> <int>, B<--writekeyfile> <int>
192
Write a keyfile for this image number (accepted multiple times)
194
=item B<-o> <string>, B<--output> <string>
196
Output file, required
198
=item B<-n> <int>, B<--ncores> <int>
200
Number of CPU/Cores (default:autodetect)
202
=item B<-t>, B<--test>
208
Uses full scale image to detect keypoints (default:false)
210
=item B<--sieve1width> <int>
212
Sieve 1 : Number of buckets on width (default : 10)
214
=item B<--sieve1height> <int>
216
Sieve 1 : Number of buckets on height (default : 10)
218
=item B<--sieve1size> <int>
220
Sieve 1 : Max points per bucket (default : 30)
222
=item B<--kdtreesteps> <int>
224
KDTree : search steps (default : 40)
226
=item B<--kdtreeseconddist> <double>
228
KDTree : distance of 2nd match (default : 0.15)
232
Enable heuristic multi row matching (default: off)
234
=item B<--linearmatch>
236
Enable linear images matching (default : all pairs)
238
=item B<--linearmatchlen> <int>
240
Number of images to match in linear matching (default:1)
242
=item B<--minmatches> <int>
244
Minimum matches (default : 4)
246
=item B<--ransaciter> <int>
248
Ransac : iterations (default : 1000)
250
=item B<--ransacdist> <int>
252
Ransac : homography estimation distance threshold (pixels) (default : 25)
254
=item B<--sieve2width> <int>
256
Sieve 2 : Number of buckets on width (default : 5)
258
=item B<--sieve2height> <int>
260
Sieve 2 : Number of buckets on height (default : 5)
262
=item B<--sieve2size> <int>
264
Sieve 2 : Max points per bucket (default : 2)
266
=item B<-->, B<--ignore_rest>
268
Ignores the rest of the labeled arguments following this flag.
272
Displays version information and exits.
274
=item B<-h>, B<--help>
276
Displays usage information and exits.
282
Anael Orlinski, Pablo d'Angelo, Antoine Deleforge, Thomas Modes