1CPFIND(1)                            HUGIN                           CPFIND(1)
2
3
4

NAME

6       cpfind - Feature matching for panoramic stitching
7

SYNOPSIS

9       cpfind [options] -o output_project project.pto
10
11       cpfind [options] -k i0 -k i1 [...] project.pto
12
13       cpfind [options] --kall project.pto
14

DESCRIPTION

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
21       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
26       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

USAGE

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
43   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
52          cpfind --celeste -o output.pto input.pto
53
54       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
63       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
69       The celeste step can be fine tuned by the parameters --celesteRadius
70       and --celesteThreshold.
71
72   Matching strategy
73       All pairs
74
75       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
80       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
85       Linear match
86
87       This matching strategy works best for single row panoramas:
88
89          cpfind --linearmatch -o output.pto input.pto
90
91       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
98       Multirow matching
99
100       This is an optimized matching strategy for single and multi-row
101       panorama:
102
103          cpfind --multirow -o output.pto input.pto
104
105       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
111       Keypoints caching to disc
112
113       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
119          cpfind --kall input.pto
120          cpfind -k 0 -k 1 input.pto
121
122       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
130       This procedure can also be automate with the switch --cache:
131
132          cpfind --cache -o output.pto input.pto
133
134       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
139       If you don't need the keyfile longer, the can be deleted automatic by
140
141          cpfind --clean input.pto
142

EXTENDED OPTIONS

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
150       The feature description step can be fine-tuned by the parameters:
151
152       --sieve1width <int>
153           Sieve 1: Number of buckets on width (default: 10)
154
155       --sieve1height <int>
156           Sieve 1: Number of buckets on height (default: 10)
157
158       --sieve1size <int>
159           Sieve 1: Max points per bucket (default: 100)
160
161       --kdtreesteps <int>
162           KDTree: search steps (default: 200)
163
164       --kdtreeseconddist <double>
165
166       KDTree: distance of 2nd match (default: 0.25)
167
168       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
174   Feature matching
175       Fine-tuning of the matching step by the following parameters:
176
177       --ransaciter <int>
178           Ransac: iterations (default: 1000)
179
180       --ransacdist <int>
181           Ransac: homography estimation distance threshold (pixels) (default:
182           25)
183
184       --ransacmode (auto, hom, rpy, rpyv, rpyb)
185           Select the model used in the ransac step.
186
187           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
194           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
201           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
207           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
211           auto: Use homography for images with hfov < 65 degrees and rpy
212           otherwise.
213
214       --minmatches <int>
215           Minimum matches (default: 4)
216
217       --sieve2width <int>
218           Sieve 2: Number of buckets on width (default: 5)
219
220       --sieve2height <int>
221           Sieve 2: Number of buckets on height (default: 5)
222
223       --sieve2size <int>
224           Sieve 2: Max points per bucket (default: 2)
225
226           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

OPTIONS

236       --celesteRadius <int>
237           Radius for celeste (default 20)
238
239       --celesteThreshold <double>
240           Threshold for celeste (default 0.5)
241
242       --celeste
243           Run celeste sky identification after loading images, this ignores
244           all features associated with 'clouds'.
245
246       -p <string, --keypath <string>
247           Path to cache keyfiles
248
249       --clean
250           Clean up cached keyfiles
251
252       -c, --cache
253           Caches keypoints to external file
254
255       --kall
256           Write keyfiles for all images
257
258       -k <int>, --writekeyfile <int>
259           Write a keyfile for this image number (accepted multiple times)
260
261       -o <string>, --output <string>
262           Output file, required
263
264       -n <int>, --ncores <int>
265           Number of CPU/Cores (default:autodetect)
266
267       -t, --test
268           Enables test mode
269
270       --fullscale
271           Uses full scale image to detect keypoints (default:false)
272
273       --sieve1width <int>
274           Sieve 1 : Number of buckets on width (default : 10)
275
276       --sieve1height <int>
277           Sieve 1 : Number of buckets on height (default : 10)
278
279       --sieve1size <int>
280           Sieve 1 : Max points per bucket (default : 100)
281
282       --kdtreesteps <int>
283           KDTree : search steps (default : 200)
284
285       --kdtreeseconddist <double>
286           KDTree : distance of 2nd match (default : 0.15)
287
288       --multirow
289           Enable heuristic multi row matching (default: off)
290
291       --linearmatch
292           Enable linear images matching (default : all pairs)
293
294       --linearmatchlen <int>
295           Number of images to match in linear matching (default:1)
296
297       --minmatches <int>
298           Minimum matches (default : 4)
299
300       --ransaciter <int>
301           Ransac : iterations (default : 1000)
302
303       --ransacdist <int>
304           Ransac : homography estimation distance threshold (pixels) (default
305           : 25)
306
307       --sieve2width <int>
308           Sieve 2 : Number of buckets on width (default : 5)
309
310       --sieve2height <int>
311           Sieve 2 : Number of buckets on height (default : 5)
312
313       --sieve2size <int>
314           Sieve 2 : Max points per bucket (default : 2)
315
316       --, --ignore_rest
317           Ignores the rest of the labeled arguments following this flag.
318
319       --version
320           Displays version information and exits.
321
322       -h, --help
323           Displays usage information and exits.
324

AUTHORS

326       Anael Orlinski, Pablo d'Angelo, Antoine Deleforge, Thomas Modes
327
328
329
330"Version: 2021.0.0"               2022-12-14                         CPFIND(1)
Impressum