1pamhomography(1) General Commands Manual pamhomography(1)
2<script type="text/javascript" src="https://polyfill.io/v3/poly‐
6fill.min.js?features=es6"></script> <script type="text/javascript" id="Math‐
7Jax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-
8chtml.js"></script>
9
11 pamhomography - stretch/shrink a quadrilateral region of an image to
12 another quadrilateral shape
13
17 pamhomography
18 [-from=coords]
19 [-to=coords]
20 [-mapfile=map_file]
21 [-view=coords]
22 [-fill=color]
23 [-verbose
24 [pam_file]
25 You can abbreviate any option to its shortest unique prefix. You can
27 use two hyphens instead of one to delimit an option. You can separate
28 an option from its value with whitespace instead of =.
29
33 This program is part of Netpbm ⟨http://netpbm.sourceforge.net/⟩ .
34 pamhomography stretches and shrinks an arbitrary quadrilateral portion
36 of an input image you specify (not necessarily rectangular), into a new
37 quadrilateral shape you specify, producing a new image.
38 You can do any affine image transformation
40 ⟨https://en.wikipedia.org/wiki/Affine_transformation#Image_transformation⟩
41 : translation, reflection, scaling, rotation, and shearing/skewing.
42 However, pamhomography additionally can do bilinear transforms, which
43 means it can warp any quadrilateral to any other quadrilateral, even
44 when this mapping cannot be described using a single set of linear
45 equations. This can be useful, for example, for creating perspective
46 views of rectangular images or for reverse-mapping a perspective view
47 back to a rectangular projection.
48
52 In addition to the options common to all programs based on libnetpbm
53 (most notably -quiet, see Common Options
54 ⟨http://index.html#commonoptions⟩ ), pamhomography recognizes the fol‐
55 lowing command line options:
56 -from=coords
61 This defines the source quadrilateral. coords is a list of four
63 integer-valued (x, y) coordinates. If you do not specify the
64 source with either -from or -mapfile, the source quadrilateral
65 is the entire input image.
66 -to=coords
70 This defines the target quadrilateral. coords is a list of four
72 integer-valued (x, y) coordinates. If you do not specify the
73 target with either -to or -mapfile, the target quadrilateral is
74 the same as the entire input image.
75 -mapfile=map_file
78 This names a text file that describes the mapping from the
80 source to the target quadrilateral. The file map_file must con‐
81 tain either eight integer-valued (x, y) coordinates, being the
82 four source coordinates followed by the corresponding four tar‐
83 get coordinates, or only four (x, y) coordinates, being only the
84 four target coordinates. In the latter case, the source quadri‐
85 lateral is taken to be the four corners of the input image in
86 clockwise order, starting from the upper left.
87 Anything you specify with -to or -from overrides what is in
89 this file.
90 -view=coords
94 This defines the target view. coords is a list of two integer-
96 valued (x, y) coordinates: the upper left and lower right bound‐
97 aries, respectively, of the pixels that will be visible in the
98 output image. If -view is not specified, the target view will
99 fit precisely the target quadrilateral.
100 -fill=color
104 This is the color with which the program fills all pixels that
106 lie outside of the target quadrilateral. Specify the color as
107 described for the
108 argument of the pnm_parsecolor() library routine
109 ⟨http://libnetpbm_image.html#colorname⟩ .
110 The default is black, and for images with a transparency plane,
112 transparent.
113 -verbose
118 This makes the program issue some informational messages about
119 what it is doing.
120 Cooordinates should normally be specified in clockwise order. The syn‐
124 tax is fairly flexible: all characters other than the plus sign, minus
125 sign, and digits are treated as separators. Although coordinates need
126 to be integers, they may lie outside the image's boundary.
127
130 pamhomography's only parameter, pam_file, is the name of the
131 file containing the input image. If you don't specify pam_file, the
132 image comes from Standard Input.
133
137 The output image uses the same Netpbm format as the input image.
138 Simple transformations are best handled by other Netpbm programs, such
140 as those listed in the 'SEE ALSO' ⟨#SEE-ALSO⟩ section below. Use
141 pamhomography for more sophisticated transformations such as perspec‐
142 tive adjustments, rotations around an arbitrary point in the image, ex‐
143 traction of non-rectangular quadrilaterals, shearings by coordinates
144 rather than by angle, and, in general, all transformations that are
145 most easily expressed as mapping four points in one image to four
146 points in another image.
147
150 The following examples use the park_row.ppm ⟨park_row.ppm⟩ test image,
151 which is a
152 photograph of New York City's Park Row Building
153 ⟨https://commons.wikimedia.org/wiki/File:15_Park_Row_3.JPG⟩ , scaled to
154 441×640, converted to a PPM file, and redistributed under the
155 terms of the
156 GFDL ⟨https://en.wikipedia.org/wiki/GNU_Free_Documentation_License⟩ .
157 The first example showcases the real power of bilinear transformations.
159 Assuming park_row_rect.map has the following contents:
160 (0, 0) (440, 0) (440, 639) (0, 639)
162 then
164 projects the building's facade from a perspective view to a rectilinear
167 front-on view. Remember that pamhomography ignores the parentheses and
168 commas used in park_row_rect.map; they merely make the file more human-
169 readable. We equivalently could have written
170 or any of myriad other variations.
173 pamhomography can warp the image to a trapezoid to make it look like
175 it's leaning backwards in 3-D:
176 As a very simple example,
179 flips the image left-to-right. Note that in this case the target quad‐
182 rilateral's coordinates are listed in counterclockwise order because
183 that represents the correspondence between points (0, 0) ↔ (440,
184 0) and (0, 639) ↔ (639, 0).
185 Scaling is also straightforward. The following command scales down the
187 image from 441×640 to 341×540:
188 Let's add 100 pixels of tan border to the above. We use -view and -fill
191 to accomplish that task:
192 We can add a border without having to scale the image:
195 The -view option can also be used to extract a rectangle out of an im‐
198 age, discarding the rest of the image:
199 Specifying the same set of coordinates to -from and -to has the same
202 effect but also allows you to extract non-rectangular quadrilaterals
203 from an image:
204 Rotation is doable but takes some effort. The challenge is that you
207 need to compute the rotated coordinates yourself. The matrix expression
208 to rotate points \((x_1, y_1)\) \((x_2, y_2)\), \((x_3, y_3)\), and
209 \((x_4, y_4)\) clockwise by \(\theta\) degrees around point \((c_x,
210 c_y)\) is
211 \[ \begin{bmatrix} 1 & 0 & c_x \\ 0 & 1 & c_y \\ 0 & 0 & 1 \end{bma‐
213 trix} \begin{bmatrix} \cos \theta & -\sin \theta & 0 \\ \sin \theta &
214 \cos \theta & 0 \\ 0 & 0 & 1 \end{bmatrix} \begin{bmatrix} 1 & 0 & -c_x
215 \\ 0 & 1 & -c_y \\ 0 & 0 & 1 \end{bmatrix} \begin{bmatrix} x_1 & x_2 &
216 x_3 & x_4 \\ y_1 & y_2 & y_3 & y_4 \\ 1 & 1 & 1 & 1 \end{bmatrix}
217 \quad. \]
218 For example, to rotate park_row.ppm 30° clockwise around (220, 320)
220 you would compute
221 \[ \begin{bmatrix} 1 & 0 & 220 \\ 0 & 1 & 320 \\ 0 & 0 & 1 \end{bma‐
223 trix} \begin{bmatrix} \cos 30^{\circ} & -\sin 30^{\circ} & 0 \\ \sin
224 30^{\circ} & \cos 30^{\circ} & 0 \\ 0 & 0 & 1 \end{bmatrix} \begin{bma‐
225 trix} 1 & 0 & -220 \\ 0 & 1 & -320 \\ 0 & 0 & 1 \end{bmatrix} \be‐
226 gin{bmatrix} 0 & 440 & 440 & 0 \\ 0 & 0 & 639 & 639 \\ 1 & 1 & 1 & 1
227 \end{bmatrix} = \begin{bmatrix} 189.4744 & 570.5256 & 251.0256 &
228 -130.0256 \\ -67.1281 & 152.8719 & 706.2621 & 486.2621 \\ 1.0000 &
229 1.0000 & 1.0000 & 1.0000 \end{bmatrix} \quad, \]
230 round these coordinates to integers, transpose the matrix, and produce
232 the following map file, park_row_rot30.map:
233 571 153
235 251 706
236 -130 486
237 (These are the 'to' coordinates; we use the default, full-image 'from'
239 coordinates.) The mapping then works as in all of the preceding exam‐
240 ples:
241
246 •
247 pamcut(1)
249 •
251 pamenlarge(1)
253 •
255 pamflip(1)
257 •
259 pamperspective(1)
261 •
263 pamscale(1)
265 •
267 pamstretch(1)
269 •
271 pam(1)
273 •
275 pnmmargin(1)
277 •
279 pnmpad(1)
281 •
283 pnmrotate(1)
285 •
287 pnmshear(1)
289
294 pamhomography was new in Netpbm 10.94 (March 2021).
295
299 Copyright © 2020 Scott Pakin, scott+pbm@pakin.org
300
304 •
305 SYNOPSIS ⟨#SYNOPSIS⟩
307 •
309 DESCRIPTION ⟨#DESCRIPTION⟩
311 •
313 OPTIONS ⟨#OPTIONS⟩
315 •
317 PARAMETERS ⟨#PARAMETERS⟩
319 •
321 NOTES ⟨#NOTES⟩
323 •
325 EXAMPLES ⟨#EXAMPLES⟩
327 •
329 SEE ALSO ⟨#SEE-ALSO⟩
331 •
333 HISTORY ⟨#HISTORY⟩
335 •
337 AUTHOR ⟨#AUTHOR⟩
339
341 This manual page was generated by the Netpbm tool 'makeman' from HTML
342 source. The master documentation is at
343 http://netpbm.sourceforge.net/doc/pamhomography.html
345netpbm documentation 04 December 2022 pamhomography(1)