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 <dt id="from-coords">-from=coords
57 This defines the source quadrilateral. coords is a list of four
59 integer-valued (x, y) coordinates. If you do not
60 specify -from, the source quadrilateral is taken to be the four
61 corners of the input image in clockwise order, starting from the
62 upper
63 left.
64 <dt id="to-coords">-to=coords
67 This defines the target quadrilateral. coords is a list of four inte‐
69 ger-valued (x, y) coordinates. If you do not specify -to, the target
70 quadrilateral is taken to be the four corners of the input image in
71 clockwise order, starting from the upper left.
72 <dt id="mapfile-map_file">-mapfile=map_file
75 This names a text file that describes the mapping from the source to
77 the target quadrilateral. The file map_file must contain either eight
78 integer-valued (x, y) coordinates, being the four source coordinates
79 followed by the corresponding four target coordinates, or only four (x,
80 y) coordinates, being only the four target coordinates. In the latter
81 case, the source quadrilateral is taken to be the four corners of the
82 input image in clockwise order, starting from the upper left.
83 <dt id="view-coords">-view=coords
86 This defines the target view. coords is a list of two integer-valued
88 (x, y) coordinates: the upper left and lower right boundaries, respec‐
89 tively, of the pixels that will be visible in the output image. If
90 -view is not specified, the target view will fit precisely the target
91 quadrilateral.
92 <dt id="fill-color">-fill=color
95 This is the color with which the program fills all pixels that lie out‐
97 side of the target quadrilateral. Specify the color as described for
98 the
99 argument of the pnm_parsecolor() library routine
100 ⟨http://libnetpbm_image.html#colorname⟩ .
101 The default is black, and for images with a transparency plane, trans‐
103 parent.
104 Cooordinates should normally be specified in clockwise order. The syn‐
109 tax is fairly flexible: all characters other than the plus sign, minus
110 sign, and digits are treated as separators. Although coordinates need
111 to be integers, they may lie outside the image's boundary.
112 If you specify -mapfile along with -from and/or -to, -from and -to
114 override the quadrilaterals specified by map_file.
115
119 pamhomography's only parameter, pam_file, is the name of the
120 file containing the input image. If you don't specify pam_file, the
121 image comes from Standard Input.
122
126 The output image uses the same Netpbm format as the input image.
127 Simple transformations are best handled by other Netpbm programs, such
129 as those listed in the 'SEE ALSO' ⟨#SEE-ALSO⟩ section below. Use
130 pamhomography for more sophisticated transformations such as perspec‐
131 tive adjustments, rotations around an arbitrary point in the image,
132 extraction of non-rectangular quadrilaterals, shearings by coordinates
133 rather than by angle, and, in general, all transformations that are
134 most easily expressed as mapping four points in one image to four
135 points in another image.
136
139 The following examples use the park_row.ppm ⟨park_row.ppm⟩ test image,
140 which is a
141 photograph of New York City's Park Row Building
142 ⟨https://commons.wikimedia.org/wiki/File:15_Park_Row_3.JPG⟩ , scaled to
143 441×640, converted to a PPM file, and redistributed under the
144 terms of the
145 GFDL ⟨https://en.wikipedia.org/wiki/GNU_Free_Documentation_License⟩ .
146 The first example showcases the real power of bilinear transformations.
148 Assuming park_row_rect.map has the following contents:
149 (0, 0) (440, 0) (440, 639) (0, 639)</pre>
151 then
153 projects the building's facade from a perspective view to a rectilinear
156 front-on view. Remember that pamhomography ignores the parentheses and
157 commas used in park_row_rect.map; they merely make the file more
158 human-readable. We equivalently could have written
159 or any of myriad other variations.
162 pamhomography can warp the image to a trapezoid to make it look like
164 it's leaning backwards in 3-D:
165 As a very simple example,
168 flips the image left-to-right. Note that in this case the target
171 quadrilateral's coordinates are listed in counterclockwise order because
172 that represents the correspondence between points (0, 0) ↔ (440, 0) and
173 (0, 639) ↔ (639, 0).
174 Scaling is also straightforward. The following command scales down the
176 image from 441×640 to 341×540:
177 Let's add 100 pixels of tan border to the above. We use -view and
180 -fill to accomplish that task:
181 We can add a border without having to scale the image:
184 The -view option can also be used to extract a rectangle out of an
187 image, discarding the rest of the image:
188 Specifying the same set of coordinates to -from and -to has
191 the same effect but also allows you to extract non-rectangular quadrilaterals
192 from an image:
193 Rotation is doable but takes some effort. The challenge is that you need to
196 compute the rotated coordinates yourself. The matrix expression to rotate
197 points \((x_1, y_1)\) \((x_2, y_2)\), \((x_3, y_3)\), and \((x_4, y_4)\)
198 clockwise by \(\theta\) degrees around point \((c_x, c_y)\) is
199 \[ \begin{bmatrix} 1 & 0 & c_x \\ 0 & 1 & c_y \\ 0 & 0
201 & 1 \end{bmatrix} \begin{bmatrix} \cos \theta & -\sin \theta & 0
202 \\ \sin \theta & \cos \theta & 0 \\ 0 & 0 & 1 \end{bmatrix}
203 \begin{bmatrix} 1 & 0 & -c_x \\ 0 & 1 & -c_y \\ 0 & 0
204 & 1 \end{bmatrix} \begin{bmatrix} x_1 & x_2 & x_3 & x_4 \\ y_1
205 & y_2 & y_3 & y_4 \\ 1 & 1 & 1 & 1 \end{bmatrix}
206 \quad. \]
207 For example, to rotate park_row.ppm 30° clockwise around (220,
209 320) you would compute
210 \[ \begin{bmatrix} 1 & 0 & 220 \\ 0 & 1 & 320 \\ 0 & 0
212 & 1 \end{bmatrix} \begin{bmatrix} \cos 30^{\circ} & -\sin 30^{\circ}
213 & 0 \\ \sin 30^{\circ} & \cos 30^{\circ} & 0 \\ 0 & 0 & 1
214 \end{bmatrix} \begin{bmatrix} 1 & 0 & -220 \\ 0 & 1 & -320 \\
215 0 & 0 & 1 \end{bmatrix} \begin{bmatrix} 0 & 440 & 440 & 0
216 \\ 0 & 0 & 639 & 639 \\ 1 & 1 & 1 & 1 \end{bmatrix} =
217 \begin{bmatrix} 189.4744 & 570.5256 & 251.0256 & -130.0256 \\
218 -67.1281 & 152.8719 & 706.2621 & 486.2621 \\ 1.0000 & 1.0000
219 & 1.0000 & 1.0000 \end{bmatrix} \quad, \]
220 round these coordinates to integers, transpose the matrix, and produce the
222 following map file, park_row_rot30.map:
223 571 153
225 251 706
226 -130 486</pre>
227 (These are the 'to' coordinates; we use the default, full-image
229 'from' coordinates.) The mapping then works as in all of the
230 preceding examples:
231
236 ·
237 pamcut(1)
239 ·
241 pamenlarge(1)
243 ·
245 pamflip(1)
247 ·
249 pamperspective(1)
251 ·
253 pamscale(1)
255 ·
257 pamstretch(1)
259 ·
261 pam(1)
263 ·
265 pnmmargin(1)
267 ·
269 pnmpad(1)
271 ·
273 pnmrotate(1)
275 ·
277 pnmshear(1)
279
284 pamhomography was new in Netpbm 10.94 (March 2021).
285
289 Copyright © 2020 Scott Pakin, scott+pbm@pakin.org
290
294 ·
295 SYNOPSIS ⟨#SYNOPSIS⟩
297 ·
299 DESCRIPTION ⟨#DESCRIPTION⟩
301 ·
303 OPTIONS ⟨#OPTIONS⟩
305 ·
307 PARAMETERS ⟨#PARAMETERS⟩
309 ·
311 NOTES ⟨#NOTES⟩
313 ·
315 EXAMPLES ⟨#EXAMPLES⟩
317 ·
319 SEE ALSO ⟨#SEE-ALSO⟩
321 ·
323 HISTORY ⟨#HISTORY⟩
325 ·
327 AUTHOR ⟨#AUTHOR⟩
329
331 This manual page was generated by the Netpbm tool 'makeman' from HTML
332 source. The master documentation is at
333 http://netpbm.sourceforge.net/doc/pamhomography.html
335netpbm documentation 03 January 2021 pamhomography(1)