Debian Codegraph @

upstream/debian-unstable/man1/pamhomography.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "pamhomography" 1 "04 December 2022" "netpbm documentation"
7
8
9
10
11 <script type="text/javascript" src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
12 <script type="text/javascript" id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
13 .SH NAME
14 .PP
15 pamhomography - stretch/shrink a quadrilateral region of an image to
16 another quadrilateral shape
17
18
19 .UN SYNOPSIS
20 .SH SYNOPSIS
21 .PP
22 \fBpamhomography\fP
23 [\fB-from\fP=\fIcoords\fP]
24 [\fB-to\fP=\fIcoords\fP]
25 [\fB-mapfile\fP=\fImap_file\fP]
26 [\fB-view\fP=\fIcoords\fP]
27 [\fB-fill\fP=\fIcolor\fP]
28 [\fB-verbose\fP
29 [\fIpam_file\fP]
30 .PP
31 You can abbreviate any option to its shortest unique prefix. You can use
32 two hyphens instead of one to delimit an option. You can separate an option
33 from its value with whitespace instead of \f(CW=\fP.
34
35
36 .UN DESCRIPTION
37 .SH DESCRIPTION
38 .PP
39 This program is part
40 of
41 .UR http://netpbm.sourceforge.net/
42 Netpbm
43 .UE
44 \&.
45 .PP
46 \fBpamhomography\fP stretches and shrinks an arbitrary quadrilateral
47 portion of an input image you specify (not necessarily rectangular), into a
48 new quadrilateral shape you specify, producing a new image.
49 .PP
50 You can do any
51 .UR https://en.wikipedia.org/wiki/Affine_transformation#Image_transformation
52 affine image transformation
53 .UE
54 \&: translation, reflection, scaling,
55 rotation, and shearing/skewing. However, \fBpamhomography\fP additionally can
56 do \fIbilinear\fP transforms, which means it can warp any quadrilateral to any
57 other quadrilateral, even when this mapping cannot be described using a single
58 set of linear equations. This can be useful, for example, for creating
59 perspective views of rectangular images or for reverse-mapping a perspective
60 view back to a rectangular projection.
61
62
63 .UN OPTIONS
64 .SH OPTIONS
65 .PP
66 In addition to the options common to all programs based on libnetpbm (most
67 notably \fB-quiet\fP, see
68 .UR index.html#commonoptions
69 Common Options
70 .UE
71 \&), \fBpamhomography\fP recognizes the following command line
72 options:
73
74
75
76 .TP
77 \fB-from\fP=\fIcoords\fP
78 .sp
79 This defines the source quadrilateral. \fIcoords\fP is a list of four
80 integer-valued (\fIx\fP, \fIy\fP) coordinates. If you do not specify the
81 source with either \fB-from\fP or \fB-mapfile\fP, the source quadrilateral
82 is the entire input image.
83
84
85 .TP
86 \fB-to\fP=\fIcoords\fP
87 .sp
88 This defines the target quadrilateral. \fIcoords\fP is a list of four
89 integer-valued (\fIx\fP, \fIy\fP) coordinates. If you do not specify the
90 target with either \fB-to\fP or \fB-mapfile\fP, the target quadrilateral is
91 the same as the entire input image.
92
93 .TP
94 \fB-mapfile\fP=\fImap_file\fP
95 .sp
96 This names a text file that describes the mapping from the source to the
97 target quadrilateral. The file \fImap_file\fP must contain either eight
98 integer-valued (\fIx\fP, \fIy\fP) coordinates, being the four source
99 coordinates followed by the corresponding four target coordinates, or only
100 four (\fIx\fP, \fIy\fP) coordinates, being only the four target
101 coordinates. In the latter case, the source quadrilateral is taken to be the
102 four corners of the input image in clockwise order, starting from the upper
103 left.
104 .sp
105 Anything you specify with \fB-to\fP or \fB-from\fP overrides what is in
106 this file.
107
108
109 .TP
110 \fB-view\fP=\fIcoords\fP
111 .sp
112 This defines the target view. \fIcoords\fP is a list of two integer-valued
113 (\fIx\fP, \fIy\fP) coordinates: the upper left and lower right boundaries,
114 respectively, of the pixels that will be visible in the output image. If
115 \fB-view\fP is not specified, the target view will fit precisely the target
116 quadrilateral.
117
118
119 .TP
120 \fB-fill\fP=\fIcolor\fP
121 .sp
122 This is the color with which the program fills all pixels that lie outside
123 of the target quadrilateral. Specify the color as described for the
124 .UR libnetpbm_image.html#colorname
125 argument of the pnm_parsecolor() library routine
126 .UE
127 \&.
128 .sp
129 The default is black, and for images with a transparency plane, transparent.
130
131
132
133 .TP
134 \fB-verbose\fP
135 This makes the program issue some informational messages about what it is
136 doing.
137
138
139 .PP
140 Cooordinates should normally be specified in clockwise order. The syntax is
141 fairly flexible: all characters other than the plus sign, minus sign, and
142 digits are treated as separators. Although coordinates need to be integers,
143 they may lie outside the image's boundary.
144
145 .UN PARAMETERS
146 .SH PARAMETERS
147 .PP
148 \fBpamhomography\fP's only parameter, \fIpam_file\fP, is the name of the
149 file containing the input image. If you don't specify \fIpam_file\fP, the
150 image comes from Standard Input.
151
152
153 .UN NOTES
154 .SH NOTES
155 .PP
156 The output image uses the same Netpbm format as the input image.
157 .PP
158 Simple transformations are best handled by other Netpbm programs, such as
159 those listed in the
160 .UR #SEE-ALSO
161 \&'SEE ALSO'
162 .UE
163 \& section
164 below. Use \fBpamhomography\fP for more sophisticated transformations such as
165 perspective adjustments, rotations around an arbitrary point in the image,
166 extraction of non-rectangular quadrilaterals, shearings by coordinates rather
167 than by angle, and, in general, all transformations that are most easily
168 expressed as mapping four points in one image to four points in another
169 image.
170
171 .UN EXAMPLES
172 .SH EXAMPLES
173 .PP
174 The following examples use the
175 .UR park_row.ppm
176 park_row.ppm
177 .UE
178 \& test image, which is a
179 .UR https://commons.wikimedia.org/wiki/File:15_Park_Row_3.JPG
180 photograph of New York City's Park Row Building
181 .UE
182 \&, scaled to
183 441&times;640, converted to a PPM file, and redistributed under the terms of
184 the
185 .UR https://en.wikipedia.org/wiki/GNU_Free_Documentation_License
186 GFDL
187 .UE
188 \&.
189 .PP
190 The first example showcases the real power of bilinear transformations.
191 Assuming \fIpark_row_rect.map\fP has the following contents:
192
193 .nf\f(CW (147, 51) (316, 105) (402, 595) (92, 560)
194 (0, 0) (440, 0) (440, 639) (0, 639)\fP
195 .fi
196 .PP
197 then
198
199 .nf\f(CW pamhomography -mapfile park_row_rect.map park_row.ppm > park_row_rect.ppm\fP
200 .fi
201 .PP
202 projects the building's facade from a perspective view to a rectilinear
203 front-on view. Remember that \fBpamhomography\fP ignores the parentheses and
204 commas used in \fIpark_row_rect.map\fP; they merely make the file more
205 human-readable. We equivalently could have written
206
207 .nf\f(CW 147 51 316 105 402 595 92 560 0 0 440 0 440 639 0 639\fP
208 .fi
209 .PP
210 or any of myriad other variations.
211 .PP
212 \fBpamhomography\fP can warp the image to a trapezoid to make it look like
213 it's leaning backwards in 3-D:
214
215 .nf\f(CW pamhomography -to '50,0 390,0 440,200 0,200' park_row.ppm > park_row_trap.ppm\fP
216 .fi
217 .PP
218 As a very simple example,
219
220 .nf\f(CW pamhomography -to '440,0 0,0 0,639 440,639' park_row.ppm > park_row_flip.ppm\fP
221 .fi
222 .PP
223 flips the image left-to-right. Note that in this case the target
224 quadrilateral's coordinates are listed in counterclockwise order because
225 that represents the correspondence between points (0, 0) &harr; (440, 0) and
226 (0, 639) &harr; (639, 0).
227 .PP
228 Scaling is also straightforward. The following command scales down the
229 image from 441&times;640 to 341&times;540:
230
231 .nf\f(CW pamhomography -to '0,0 340,0 340,539 0,539' park_row.ppm > park_row_small.ppm\fP
232 .fi
233 .PP
234 Let's add 100 pixels of tan border to the above. We use \fB-view\fP and
235 \fB-fill\fP to accomplish that task:
236
237 .nf\f(CW pamhomography -to '0,0 340,0 340,539 0,539' -view '-100,-100 440,639' -fill tan park_row.ppm > park_row_small_border.ppm\fP
238 .fi
239 .PP
240 We can add a border without having to scale the image:
241
242 .nf\f(CW pamhomography -view '-100,-100 540,739' -fill tan park_row.ppm > park_row_border.ppm\fP
243 .fi
244 .PP
245 The \fB-view\fP option can also be used to extract a rectangle out of an
246 image, discarding the rest of the image:
247
248 .nf\f(CW pamhomography -view '130,10 205,80' park_row.ppm > park_row_cut.ppm\fP
249 .fi
250 .PP
251 Specifying the same set of coordinates to \fB-from\fP and \fB-to\fP has
252 the same effect but also allows you to extract non-rectangular quadrilaterals
253 from an image:
254
255 .nf\f(CW pamhomography -from '185,300 310,325 320,425 180,405' -to '185,300 310,325 320,425 180,405' park_row.ppm > park_row_cut_2.ppm\fP
256 .fi
257 .PP
258 Rotation is doable but takes some effort. The challenge is that you need to
259 compute the rotated coordinates yourself. The matrix expression to rotate
260 points \e((x_1, y_1)\e) \e((x_2, y_2)\e), \e((x_3, y_3)\e), and \e((x_4, y_4)\e)
261 clockwise by \e(\etheta\e) degrees around point \e((c_x, c_y)\e) is
262 .PP
263 \e[ \ebegin{bmatrix} 1 & 0 & c_x \e\e 0 & 1 & c_y \e\e 0 & 0
264 & 1 \eend{bmatrix} \ebegin{bmatrix} \ecos \etheta & -\esin \etheta & 0
265 \e\e \esin \etheta & \ecos \etheta & 0 \e\e 0 & 0 & 1 \eend{bmatrix}
266 \ebegin{bmatrix} 1 & 0 & -c_x \e\e 0 & 1 & -c_y \e\e 0 & 0
267 & 1 \eend{bmatrix} \ebegin{bmatrix} x_1 & x_2 & x_3 & x_4 \e\e y_1
268 & y_2 & y_3 & y_4 \e\e 1 & 1 & 1 & 1 \eend{bmatrix}
269 \equad. \e]
270 .PP
271 For example, to rotate \fIpark_row.ppm\fP 30&deg; clockwise around (220,
272 320) you would compute
273 .PP
274 \e[ \ebegin{bmatrix} 1 & 0 & 220 \e\e 0 & 1 & 320 \e\e 0 & 0
275 & 1 \eend{bmatrix} \ebegin{bmatrix} \ecos 30^{\ecirc} & -\esin 30^{\ecirc}
276 & 0 \e\e \esin 30^{\ecirc} & \ecos 30^{\ecirc} & 0 \e\e 0 & 0 & 1
277 \eend{bmatrix} \ebegin{bmatrix} 1 & 0 & -220 \e\e 0 & 1 & -320 \e\e
278 0 & 0 & 1 \eend{bmatrix} \ebegin{bmatrix} 0 & 440 & 440 & 0
279 \e\e 0 & 0 & 639 & 639 \e\e 1 & 1 & 1 & 1 \eend{bmatrix} =
280 \ebegin{bmatrix} 189.4744 & 570.5256 & 251.0256 & -130.0256 \e\e
281 -67.1281 & 152.8719 & 706.2621 & 486.2621 \e\e 1.0000 & 1.0000
282 & 1.0000 & 1.0000 \eend{bmatrix} \equad, \e]
283 .PP
284 round these coordinates to integers, transpose the matrix, and produce the
285 following map file, \fIpark_row_rot30.map\fP:
286
287 .nf\f(CW 189 -67
288 571 153
289 251 706
290 -130 486\fP
291 .fi
292 .PP
293 (These are the 'to' coordinates; we use the default, full-image
294 \&'from' coordinates.) The mapping then works as in all of the
295 preceding examples:
296
297 .nf\f(CW pamhomography -mapfile park_row_rot30.map park_row.ppm > park_row_rot30.ppm\fP
298 .fi
299
300
301 .UN SEE-ALSO
302 .SH SEE ALSO
303
304
305 .IP \(bu
306 .BR "pamcut" (1)\c
307 \&
308 .IP \(bu
309 .BR "pamenlarge" (1)\c
310 \&
311 .IP \(bu
312 .BR "pamflip" (1)\c
313 \&
314 .IP \(bu
315 .BR "pamperspective" (1)\c
316 \&
317 .IP \(bu
318 .BR "pamscale" (1)\c
319 \&
320 .IP \(bu
321 .BR "pamstretch" (1)\c
322 \&
323 .IP \(bu
324 .BR "pam" (1)\c
325 \&
326 .IP \(bu
327 .BR "pnmmargin" (1)\c
328 \&
329 .IP \(bu
330 .BR "pnmpad" (1)\c
331 \&
332 .IP \(bu
333 .BR "pnmrotate" (1)\c
334 \&
335 .IP \(bu
336 .BR "pnmshear" (1)\c
337 \&
338
339
340
341 .UN HISTORY
342 .SH HISTORY
343 .PP
344 \fBpamhomography\fP was new in Netpbm 10.94 (March 2021).
345
346
347 .UN AUTHOR
348 .SH AUTHOR
349 .PP
350 Copyright \(co 2020 Scott
351 Pakin, \[email protected]\fP
352
353
354 .UN index
355 .SH Table of Contents
356
357
358 .IP \(bu
359 .UR #SYNOPSIS
360 SYNOPSIS
361 .UE
362 \&
363 .IP \(bu
364 .UR #DESCRIPTION
365 DESCRIPTION
366 .UE
367 \&
368 .IP \(bu
369 .UR #OPTIONS
370 OPTIONS
371 .UE
372 \&
373 .IP \(bu
374 .UR #PARAMETERS
375 PARAMETERS
376 .UE
377 \&
378 .IP \(bu
379 .UR #NOTES
380 NOTES
381 .UE
382 \&
383 .IP \(bu
384 .UR #EXAMPLES
385 EXAMPLES
386 .UE
387 \&
388 .IP \(bu
389 .UR #SEE-ALSO
390 SEE ALSO
391 .UE
392 \&
393 .IP \(bu
394 .UR #HISTORY
395 HISTORY
396 .UE
397 \&
398 .IP \(bu
399 .UR #AUTHOR
400 AUTHOR
401 .UE
402 \&
403 .SH DOCUMENT SOURCE
404 This manual page was generated by the Netpbm tool 'makeman' from HTML
405 source. The master documentation is at
406 .IP
407 .B http://netpbm.sourceforge.net/doc/pamhomography.html
408 .PP