1CPFIND(1) HUGIN CPFIND(1)
2
6 cpfind - Feature matching for panoramic stitching
7
9 cpfind [options] -o output_project project.pto
10 cpfind [options] -k i0 -k i1 [...] project.pto
12 cpfind [options] --kall project.pto
14
16 cpfind cpfind is a control-point detector for Hugin. It expects a
17 project file as input and writes a project file with control-points on
18 success. It depends on reasonable lens information in the input
19 project file.
20 The first step is the feature description: In this step the images of
22 the project file are loaded and so called keypoints are searched. They
23 describe destinctive features in the image. cpfind uses a gradient
24 based descriptor for the feature description of the keypoints.
25 In a second step, the feature matching, all keypoints of two images are
27 matched against each other to find features which are on both images.
28 If this matching was successful two keypoints in the two images become
29 one control point.
30
32 Rectilinear and fisheye images
33 Cpfind can find control points in rectilinear and fisheye images. To
34 achieve good control points images with a high horizontal field of view
35 (e.g. ultra wide rectilinear or fisheye) are therefore remapped into a
36 conformal space (cpfind is using the stereographic projection) and the
37 feature matching occurs in this space. Before writing the control
38 points the coordinates are remapped back to the image space. This
39 happens automatic depending on the information about the lens in the
40 input project file. So check that your input project file contains
41 reasonable information about the used lens.
42 Using celeste
44 Outdoor panorama often contains clouds. Clouds are bad areas for
45 setting control points because they are moving object. Cpfind can use
46 the same algorithm as celeste_standalone to masked out areas which
47 contains clouds. (This is only done internal for the keypoint finding
48 step and does not change the alpha channel of your image. If you want
49 to generate a mask image use celeste_standalone). To run cpfind with
50 celeste use
51 cpfind --celeste -o output.pto input.pto
53 Using cpfind with integrated celeste should be superior against using
55 cpfind and celeste_standalone sequential. When running cpfind with
56 celeste areas of clouds, which often contains keypoints with a high
57 quality measure, are disregarded and areas without clouds are used
58 instead. When running cpfind without celeste also keypoints on clouds
59 are found. When afterwards running celeste_standalone these control
60 points are removed. In the worst case all control points of a certain
61 image pair are removed.
62 So running cpfind with celeste leads to a better "control point
64 quality" for outdoor panorama (e.g. panorama with clouds). Running
65 cpfind with celeste takes longer than cpfind alone. So for indoor
66 panorama this option does not need to specified (because of longer
67 computation time).
68 The celeste step can be fine tuned by the parameters --celesteRadius
70 and --celesteThreshold.
71 Matching strategy
73 All pairs
74 This is the default matching strategy. Here all image pairs are matched
76 against each other. E.g. if your project contains 5 images then cpfind
77 matches the image pairs: 0-1, 0-2, 0-3, 0-4, 1-2, 1-3, 1-4, 2-3, 2-4
78 and 3-4
79 This strategy works for all shooting strategy (single-row, multi-row,
81 unordered). It finds (nearly) all connected image pairs. But it is
82 computational expensive for projects with many images, because it test
83 many image pairs which are not connected.
84 Linear match
86 This matching strategy works best for single row panoramas:
88 cpfind --linearmatch -o output.pto input.pto
90 This will only detect matches between adjacent images, e.g. for the 5
92 image example it will matches images pairs 0-1, 1-2, 2-3 and 3-4. The
93 matching distance can be increased with the switch --linearmatchlen.
94 E.g. with --linearmatchlen 2 cpfind will match a image with the next
95 image and the image after next, in our example it would be 0-1, 0-2,
96 1-2, 1-3, 2-3, 2-4 and 3-4.
97 Multirow matching
99 This is an optimized matching strategy for single and multi-row
101 panorama:
102 cpfind --multirow -o output.pto input.pto
104 The algorithm is the same as described in multi-row panorama. By
106 integrating this algorithm into cpfind it is faster by using several
107 cores of modern CPUs and don't caching the keypoints to disc (which is
108 time consuming). If you want to use this multi-row matching inside
109 hugin set the control point detector type to All images at once.
110 Keypoints caching to disc
112 The calculation of keypoints takes some time. So cpfind offers the
114 possibility to save the keypoints to a file and reuse them later again.
115 With --kall the keypoints for all images in the project are saved to
116 disc. If you only want the keypoints of particular image use the
117 parameter -k with the image number:
118 cpfind --kall input.pto
120 cpfind -k 0 -k 1 input.pto
121 The keypoint files are saved by default into the same directory as the
123 images with the extension .key. In this case no matching of images
124 occurs and therefore no output project file needs to specified. If
125 cpfind finds keyfiles for an image in the project it will use them
126 automatically and not run the feature descriptor again on this image.
127 If you want to save them to annother directory use the --keypath
128 switch.
129 This procedure can also be automate with the switch --cache:
131 cpfind --cache -o output.pto input.pto
133 In this case it tries to load existing keypoint files. For images,
135 which don't have a keypoint file, the keypoints are detected and save
136 to the file. Then it matches all loaded and newly found keypoints and
137 writes the output project.
138 If you don't need the keyfile longer, the can be deleted automatic by
140 cpfind --clean input.pto
142
144 Feature description
145 For speed reasons cpfind is using images, which are scaled to their
146 half width and height, to find keypoints. With the switch --fullscale
147 cpfind is working on the full scale images. This takes longer but can
148 provide "better" and/or more control points.
149 The feature description step can be fine-tuned by the parameters:
151 --sieve1width <int>
153 Sieve 1: Number of buckets on width (default: 10)
154 --sieve1height <int>
156 Sieve 1: Number of buckets on height (default: 10)
157 --sieve1size <int>
159 Sieve 1: Max points per bucket (default: 100)
160 --kdtreesteps <int>
162 KDTree: search steps (default: 200)
163 --kdtreeseconddist <double>
165 KDTree: distance of 2nd match (default: 0.25)
167 Cpfind stores maximal sieve1width * sieve1height * sieve1size keypoints
169 per image. If you have only a small overlap, e.g. for 360 degree
170 panorama shoot with fisheye images, you can get better results if you
171 increase sieve1size. You can also try to increase sieve1width and/or
172 sieve1height.
173 Feature matching
175 Fine-tuning of the matching step by the following parameters:
176 --ransaciter <int>
178 Ransac: iterations (default: 1000)
179 --ransacdist <int>
181 Ransac: homography estimation distance threshold (pixels) (default:
182 25)
183 --ransacmode (auto, hom, rpy, rpyv, rpyb)
185 Select the model used in the ransac step.
186 hom: Assume a homography. Only applicable for non-wide angle
188 views. Uses the original panomatic code. It is also more
189 flexible
190 than required and can generate false matches, particularly if
191 most
192 of the matches are located on a single line.
193 rpy: Align images using roll, pitch and yaw. This requires a good
195 estimate for the horizontal field of view (and distortion, for
196 heavily distorted images). It is the preferred mode if a
197 calibrated lens is used, or the HFOV could be read
198 successfully
199 from the EXIF data.
200 rpyv: Align pair by optimizing roll, pitch, yaw and field of
202 view. Should work without prior knowledge of the field of
203 view,
204 but might fail more often, due to error function used in the
205 panotools optimizer, it tends to shrink the fov to 0.
206 rpyvb: Align pair by optimizing roll, pitch, yaw, field of view and
208 the "b" distortion parameter. Probably very fragile, just
209 implemented for testing.
210 auto: Use homography for images with hfov < 65 degrees and rpy
212 otherwise.
213 --minmatches <int>
215 Minimum matches (default: 4)
216 --sieve2width <int>
218 Sieve 2: Number of buckets on width (default: 5)
219 --sieve2height <int>
221 Sieve 2: Number of buckets on height (default: 5)
222 --sieve2size <int>
224 Sieve 2: Max points per bucket (default: 2)
225 Cpfind generates between minmatches and sieve2width * sieve2height
227 * sieve2size control points between an image pair. (Default setting
228 is between 4 and 50 (=5*5*2) control points per image pair.) If
229 less then minmatches control points are found for a given image
230 pairs these control points are disregarded and this image pair is
231 considers as not connected. For narrow overlaps you can try to
232 decrease minmatches, but this increases the risk of getting wrong
233 control points.
234
236 --celesteRadius <int>
237 Radius for celeste (default 20)
238 --celesteThreshold <double>
240 Threshold for celeste (default 0.5)
241 --celeste
243 Run celeste sky identification after loading images, this ignores
244 all features associated with 'clouds'.
245 -p <string, --keypath <string>
247 Path to cache keyfiles
248 --clean
250 Clean up cached keyfiles
251 -c, --cache
253 Caches keypoints to external file
254 --kall
256 Write keyfiles for all images
257 -k <int>, --writekeyfile <int>
259 Write a keyfile for this image number (accepted multiple times)
260 -o <string>, --output <string>
262 Output file, required
263 -n <int>, --ncores <int>
265 Number of CPU/Cores (default:autodetect)
266 -t, --test
268 Enables test mode
269 --fullscale
271 Uses full scale image to detect keypoints (default:false)
272 --sieve1width <int>
274 Sieve 1 : Number of buckets on width (default : 10)
275 --sieve1height <int>
277 Sieve 1 : Number of buckets on height (default : 10)
278 --sieve1size <int>
280 Sieve 1 : Max points per bucket (default : 100)
281 --kdtreesteps <int>
283 KDTree : search steps (default : 200)
284 --kdtreeseconddist <double>
286 KDTree : distance of 2nd match (default : 0.15)
287 --multirow
289 Enable heuristic multi row matching (default: off)
290 --linearmatch
292 Enable linear images matching (default : all pairs)
293 --linearmatchlen <int>
295 Number of images to match in linear matching (default:1)
296 --minmatches <int>
298 Minimum matches (default : 4)
299 --ransaciter <int>
301 Ransac : iterations (default : 1000)
302 --ransacdist <int>
304 Ransac : homography estimation distance threshold (pixels) (default
305 : 25)
306 --sieve2width <int>
308 Sieve 2 : Number of buckets on width (default : 5)
309 --sieve2height <int>
311 Sieve 2 : Number of buckets on height (default : 5)
312 --sieve2size <int>
314 Sieve 2 : Max points per bucket (default : 2)
315 --, --ignore_rest
317 Ignores the rest of the labeled arguments following this flag.
318 --version
320 Displays version information and exits.
321 -h, --help
323 Displays usage information and exits.
324
326 Anael Orlinski, Pablo d'Angelo, Antoine Deleforge, Thomas Modes
327"Version: 2020.0.0" 2021-01-26 CPFIND(1)