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 - map one arbitrary quadrilateral image region to another
12
16 pamhomography
17 [-from=coords]
18 [-to=coords]
19 [-mapfile=map_file]
20 [-view=coords]
21 [-fill=color]
22 [pam_file]
23 You can abbreviate any option to its shortest unique prefix. You can
25 use two hyphens instead of one to delimit an option. You can separate
26 an option from its value with whitespace instead of =.
27
31 This program is part of Netpbm ⟨http://netpbm.sourceforge.net/⟩ .
32 pamhomography transforms a quadrilateral-not necessarily rectangular-
34 region of an image, producing a new image.
35 You can do any affine image transformation
37 ⟨https://en.wikipedia.org/wiki/Affine_transformation#Image_transformation⟩
38 : translation, reflection, scaling, rotation, and shearing/skewing.
39 However, pamhomography additionally can do bilinear transforms, which
40 means it can warp any quadrilateral to any other quadrilateral, even
41 when this mapping cannot be described using a single set of linear
42 equations. This can be useful, for example, for creating perspective
43 views of rectangular images or for reverse-mapping a perspective view
44 back to a rectangular projection.
45
49 In addition to the options common to all programs based on libnetpbm
50 (most notably -quiet, see Common Options
51 ⟨http://index.html#commonoptions⟩ ), pamhomography recognizes the fol‐
52 lowing command line options:
53 -from=coords
58 This defines the source quadrilateral. coords is a list of four
60 integer-valued (x, y) coordinates. If you do not
61 specify -from, the source quadrilateral is taken to be the
62 four
63 corners of the input image in clockwise order, starting from
64 the upper
65 left.
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 -to,
73 the target quadrilateral is taken to be the four corners of the
74 input image in clockwise order, starting from the upper left.
75 -mapfile=map_file
79 This names a text file that describes the mapping from the
81 source to the target quadrilateral. The file map_file must con‐
82 tain either eight integer-valued (x, y) coordinates, being the
83 four source coordinates followed by the corresponding four tar‐
84 get coordinates, or only four (x, y) coordinates, being only the
85 four target coordinates. In the latter case, the source quadri‐
86 lateral is taken to be the four corners of the input image in
87 clockwise order, starting from the upper left.
88 -view=coords
92 This defines the target view. coords is a list of two integer-
94 valued (x, y) coordinates: the upper left and lower right bound‐
95 aries, respectively, of the pixels that will be visible in the
96 output image. If -view is not specified, the target view will
97 fit precisely the target quadrilateral.
98 -fill=color
102 This is the color with which the program fills all pixels that
104 lie outside of the target quadrilateral. Specify the color as
105 described for the
106 argument of the pnm_parsecolor() library routine
107 ⟨http://libnetpbm_image.html#colorname⟩ .
108 The default is black, and for images with a transparency plane,
110 transparent.
111 Cooordinates should normally be specified in clockwise order. The syn‐
116 tax is fairly flexible: all characters other than the plus sign, minus
117 sign, and digits are treated as separators. Although coordinates need
118 to be integers, they may lie outside the image's boundary.
119 If you specify -mapfile along with -from and/or -to, -from and -to
121 override the quadrilaterals specified by map_file.
122
126 pamhomography's only parameter, pam_file, is the name of the
127 file containing the input image. If you don't specify pam_file, the
128 image comes from Standard Input.
129
133 The output image uses the same Netpbm format as the input image.
134 Simple transformations are best handled by other Netpbm programs, such
136 as those listed in the 'SEE ALSO' ⟨#SEE-ALSO⟩ section below. Use
137 pamhomography for more sophisticated transformations such as perspec‐
138 tive adjustments, rotations around an arbitrary point in the image, ex‐
139 traction of non-rectangular quadrilaterals, shearings by coordinates
140 rather than by angle, and, in general, all transformations that are
141 most easily expressed as mapping four points in one image to four
142 points in another image.
143
146 The following examples use the park_row.ppm ⟨park_row.ppm⟩ test image,
147 which is a
148 photograph of New York City's Park Row Building
149 ⟨https://commons.wikimedia.org/wiki/File:15_Park_Row_3.JPG⟩ , scaled to
150 441×640, converted to a PPM file, and redistributed under the
151 terms of the
152 GFDL ⟨https://en.wikipedia.org/wiki/GNU_Free_Documentation_License⟩ .
153 The first example showcases the real power of bilinear transformations.
155 Assuming park_row_rect.map has the following contents:
156 (0, 0) (440, 0) (440, 639) (0, 639)
158 then
160 projects the building's facade from a perspective view to a rectilinear
163 front-on view. Remember that pamhomography ignores the parentheses and
164 commas used in park_row_rect.map; they merely make the file more human-
165 readable. We equivalently could have written
166 or any of myriad other variations.
169 pamhomography can warp the image to a trapezoid to make it look like
171 it's leaning backwards in 3-D:
172 As a very simple example,
175 flips the image left-to-right. Note that in this case the target quad‐
178 rilateral's coordinates are listed in counterclockwise order because
179 that represents the correspondence between points (0, 0) ↔ (440,
180 0) and (0, 639) ↔ (639, 0).
181 Scaling is also straightforward. The following command scales down the
183 image from 441×640 to 341×540:
184 Let's add 100 pixels of tan border to the above. We use -view and -fill
187 to accomplish that task:
188 We can add a border without having to scale the image:
191 The -view option can also be used to extract a rectangle out of an im‐
194 age, discarding the rest of the image:
195 Specifying the same set of coordinates to -from and -to has the same
198 effect but also allows you to extract non-rectangular quadrilaterals
199 from an image:
200 Rotation is doable but takes some effort. The challenge is that you
203 need to compute the rotated coordinates yourself. The matrix expression
204 to rotate points \((x_1, y_1)\) \((x_2, y_2)\), \((x_3, y_3)\), and
205 \((x_4, y_4)\) clockwise by \(\theta\) degrees around point \((c_x,
206 c_y)\) is
207 \[ \begin{bmatrix} 1 & 0 & c_x \\ 0 & 1 & c_y \\ 0 & 0 & 1 \end{bma‐
209 trix} \begin{bmatrix} \cos \theta & -\sin \theta & 0 \\ \sin \theta &
210 \cos \theta & 0 \\ 0 & 0 & 1 \end{bmatrix} \begin{bmatrix} 1 & 0 & -c_x
211 \\ 0 & 1 & -c_y \\ 0 & 0 & 1 \end{bmatrix} \begin{bmatrix} x_1 & x_2 &
212 x_3 & x_4 \\ y_1 & y_2 & y_3 & y_4 \\ 1 & 1 & 1 & 1 \end{bmatrix}
213 \quad. \]
214 For example, to rotate park_row.ppm 30° clockwise around (220, 320)
216 you would compute
217 \[ \begin{bmatrix} 1 & 0 & 220 \\ 0 & 1 & 320 \\ 0 & 0 & 1 \end{bma‐
219 trix} \begin{bmatrix} \cos 30^{\circ} & -\sin 30^{\circ} & 0 \\ \sin
220 30^{\circ} & \cos 30^{\circ} & 0 \\ 0 & 0 & 1 \end{bmatrix} \begin{bma‐
221 trix} 1 & 0 & -220 \\ 0 & 1 & -320 \\ 0 & 0 & 1 \end{bmatrix} \be‐
222 gin{bmatrix} 0 & 440 & 440 & 0 \\ 0 & 0 & 639 & 639 \\ 1 & 1 & 1 & 1
223 \end{bmatrix} = \begin{bmatrix} 189.4744 & 570.5256 & 251.0256 &
224 -130.0256 \\ -67.1281 & 152.8719 & 706.2621 & 486.2621 \\ 1.0000 &
225 1.0000 & 1.0000 & 1.0000 \end{bmatrix} \quad, \]
226 round these coordinates to integers, transpose the matrix, and produce
228 the following map file, park_row_rot30.map:
229 571 153
231 251 706
232 -130 486
233 (These are the 'to' coordinates; we use the default, full-image 'from'
235 coordinates.) The mapping then works as in all of the preceding exam‐
236 ples:
237
242 •
243 pamcut(1)
245 •
247 pamenlarge(1)
249 •
251 pamflip(1)
253 •
255 pamperspective(1)
257 •
259 pamscale(1)
261 •
263 pamstretch(1)
265 •
267 pam(1)
269 •
271 pnmmargin(1)
273 •
275 pnmpad(1)
277 •
279 pnmrotate(1)
281 •
283 pnmshear(1)
285
290 pamhomography was new in Netpbm 10.94 (March 2021).
291
295 Copyright © 2020 Scott Pakin, scott+pbm@pakin.org
296
300 •
301 SYNOPSIS ⟨#SYNOPSIS⟩
303 •
305 DESCRIPTION ⟨#DESCRIPTION⟩
307 •
309 OPTIONS ⟨#OPTIONS⟩
311 •
313 PARAMETERS ⟨#PARAMETERS⟩
315 •
317 NOTES ⟨#NOTES⟩
319 •
321 EXAMPLES ⟨#EXAMPLES⟩
323 •
325 SEE ALSO ⟨#SEE-ALSO⟩
327 •
329 HISTORY ⟨#HISTORY⟩
331 •
333 AUTHOR ⟨#AUTHOR⟩
335
337 This manual page was generated by the Netpbm tool 'makeman' from HTML
338 source. The master documentation is at
339 http://netpbm.sourceforge.net/doc/pamhomography.html
341netpbm documentation 03 January 2021 pamhomography(1)