Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

[fe774a]: doc / cpfind.1 Maximize Restore History

Download this file

cpfind.1    370 lines (369 with data), 16.1 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CPFIND ""1"""
.TH CPFIND "1" "2010-12-26" """Version: 2010.5.0""" "HUGIN"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
cpfind \- Feature matching for panoramic stitching
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBcpfind\fR [options] \-o \fIoutput_project\fR \fIproject.pto\fR
.PP
\&\fBcpfind\fR [options] \-k i0 \-k i1 [...] \fIproject.pto\fR
.PP
\&\fBcpfind\fR [options] \-\-kall \fIproject.pto\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBcpfind\fR 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.
.PP
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. \fBcpfind\fR uses a gradient based descriptor
for the feature description of the keypoints.
.PP
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.
.SH "USAGE"
.IX Header "USAGE"
.SS "Rectilinear and fisheye images"
.IX Subsection "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.
.SS "Using celeste"
.IX Subsection "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
.PP
.Vb 1
\& cpfind \-\-celeste \-o output.pto input.pto
.Ve
.PP
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.
.PP
So running cpfind with celeste leads to a better \*(L"control point quality\*(R" 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).
.PP
The celeste step can be fine tuned by the parameters \-\-celesteRadius and \-\-celesteThreshold.
.SS "Matching strategy"
.IX Subsection "Matching strategy"
\fIAll pairs\fR
.IX Subsection "All pairs"
.PP
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
.PP
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.
.PP
\fILinear match\fR
.IX Subsection "Linear match"
.PP
This matching strategy works best for single row panoramas:
.PP
.Vb 1
\& cpfind \-\-linearmatch \-o output.pto input.pto
.Ve
.PP
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.
.PP
\fIMultirow matching\fR
.IX Subsection "Multirow matching"
.PP
This is an optimized matching strategy for single and multi-row panorama:
.PP
.Vb 1
\& cpfind \-\-multirow \-o output.pto input.pto
.Ve
.PP
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.
.PP
\fIKeypoints caching to disc\fR
.IX Subsection "Keypoints caching to disc"
.PP
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:
.PP
.Vb 2
\& cpfind \-\-kall input.pto
\& cpfind \-k 0 \-k 1 input.pto
.Ve
.PP
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.
.PP
This procedure can also be automate with the switch \-\-cache:
.PP
.Vb 1
\& cpfind \-\-cache \-o output.pto input.pto
.Ve
.PP
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.
.PP
If you don't need the keyfile longer, the can be deleted automatic by
.PP
.Vb 1
\& cpfind \-\-clean input.pto
.Ve
.SH "EXTENDED OPTIONS"
.IX Header "EXTENDED OPTIONS"
.SS "Feature description"
.IX Subsection "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 \*(L"better\*(R" and/or more control points.
.PP
The feature description step can be fine-tuned by the parameters:
.IP "\fB\-\-sieve1width\fR <int>" 4
.IX Item "--sieve1width <int>"
Sieve 1: Number of buckets on width (default: 10)
.IP "\fB\-\-sieve1height\fR <int>" 4
.IX Item "--sieve1height <int>"
Sieve 1: Number of buckets on height (default: 10)
.IP "\fB\-\-sieve1size\fR <int>" 4
.IX Item "--sieve1size <int>"
Sieve 1: Max points per bucket (default: 30)
.IP "\fB\-\-kdtreesteps\fR <int>" 4
.IX Item "--kdtreesteps <int>"
KDTree: search steps (default: 40)
.IP "\fB\-\-kdtreeseconddist\fR <double>" 4
.IX Item "--kdtreeseconddist <double>"
.PP
KDTree: distance of 2nd match (default: 0.15)
.PP
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.
.SS "Feature matching"
.IX Subsection "Feature matching"
Fine-tuning of the matching step by the following parameters:
.IP "\fB\-\-ransaciter\fR <int>" 4
.IX Item "--ransaciter <int>"
Ransac: iterations (default: 1000)
.IP "\fB\-\-ransacdist\fR <int>" 4
.IX Item "--ransacdist <int>"
Ransac: homography estimation distance threshold (pixels) (default: 25)
.IP "\fB\-\-minmatches\fR <int>" 4
.IX Item "--minmatches <int>"
Minimum matches (default: 4)
.IP "\fB\-\-sieve2width\fR <int>" 4
.IX Item "--sieve2width <int>"
Sieve 2: Number of buckets on width (default: 5)
.IP "\fB\-\-sieve2height\fR <int>" 4
.IX Item "--sieve2height <int>"
Sieve 2: Number of buckets on height (default: 5)
.IP "\fB\-\-sieve2size\fR <int>" 4
.IX Item "--sieve2size <int>"
Sieve 2: Max points per bucket (default: 2)
.Sp
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.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-\-celesteRadius\fR <int>" 4
.IX Item "--celesteRadius <int>"
Radius for celeste (default 20)
.IP "\fB\-\-celesteThreshold\fR <double>" 4
.IX Item "--celesteThreshold <double>"
Threshold for celeste (default 0.5)
.IP "\fB\-\-celeste\fR" 4
.IX Item "--celeste"
Run celeste sky identification after loading images, this ignores all features
associated with 'clouds'.
.IP "\fB\-p <string\fR, \fB\-\-keypath\fR <string>" 4
.IX Item "-p <string, --keypath <string>"
Path to cache keyfiles
.IP "\fB\-\-clean\fR" 4
.IX Item "--clean"
Clean up cached keyfiles
.IP "\fB\-c\fR, \fB\-\-cache\fR" 4
.IX Item "-c, --cache"
Caches keypoints to external file
.IP "\fB\-\-kall\fR" 4
.IX Item "--kall"
Write keyfiles for all images
.IP "\fB\-k\fR <int>, \fB\-\-writekeyfile\fR <int>" 4
.IX Item "-k <int>, --writekeyfile <int>"
Write a keyfile for this image number (accepted multiple times)
.IP "\fB\-o\fR <string>, \fB\-\-output\fR <string>" 4
.IX Item "-o <string>, --output <string>"
Output file, required
.IP "\fB\-n\fR <int>, \fB\-\-ncores\fR <int>" 4
.IX Item "-n <int>, --ncores <int>"
Number of CPU/Cores (default:autodetect)
.IP "\fB\-t\fR, \fB\-\-test\fR" 4
.IX Item "-t, --test"
Enables test mode
.IP "\fB\-\-fullscale\fR" 4
.IX Item "--fullscale"
Uses full scale image to detect keypoints (default:false)
.IP "\fB\-\-sieve1width\fR <int>" 4
.IX Item "--sieve1width <int>"
Sieve 1 : Number of buckets on width (default : 10)
.IP "\fB\-\-sieve1height\fR <int>" 4
.IX Item "--sieve1height <int>"
Sieve 1 : Number of buckets on height (default : 10)
.IP "\fB\-\-sieve1size\fR <int>" 4
.IX Item "--sieve1size <int>"
Sieve 1 : Max points per bucket (default : 30)
.IP "\fB\-\-kdtreesteps\fR <int>" 4
.IX Item "--kdtreesteps <int>"
KDTree : search steps (default : 40)
.IP "\fB\-\-kdtreeseconddist\fR <double>" 4
.IX Item "--kdtreeseconddist <double>"
KDTree : distance of 2nd match (default : 0.15)
.IP "\fB\-\-multirow\fR" 4
.IX Item "--multirow"
Enable heuristic multi row matching (default: off)
.IP "\fB\-\-linearmatch\fR" 4
.IX Item "--linearmatch"
Enable linear images matching (default : all pairs)
.IP "\fB\-\-linearmatchlen\fR <int>" 4
.IX Item "--linearmatchlen <int>"
Number of images to match in linear matching (default:1)
.IP "\fB\-\-minmatches\fR <int>" 4
.IX Item "--minmatches <int>"
Minimum matches (default : 4)
.IP "\fB\-\-ransaciter\fR <int>" 4
.IX Item "--ransaciter <int>"
Ransac : iterations (default : 1000)
.IP "\fB\-\-ransacdist\fR <int>" 4
.IX Item "--ransacdist <int>"
Ransac : homography estimation distance threshold (pixels) (default : 25)
.IP "\fB\-\-sieve2width\fR <int>" 4
.IX Item "--sieve2width <int>"
Sieve 2 : Number of buckets on width (default : 5)
.IP "\fB\-\-sieve2height\fR <int>" 4
.IX Item "--sieve2height <int>"
Sieve 2 : Number of buckets on height (default : 5)
.IP "\fB\-\-sieve2size\fR <int>" 4
.IX Item "--sieve2size <int>"
Sieve 2 : Max points per bucket (default : 2)
.IP "\fB\-\-\fR, \fB\-\-ignore_rest\fR" 4
.IX Item "--, --ignore_rest"
Ignores the rest of the labeled arguments following this flag.
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
Displays version information and exits.
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
Displays usage information and exits.
.SH "AUTHORS"
.IX Header "AUTHORS"
Anael Orlinski, Pablo d'Angelo, Antoine Deleforge, Thomas Modes