pamhomography(1)

1Pamhomography User Manual(0)                      Pamhomography User Manual(0)
2
3
4

NAME

6       pamhomography - map one arbitrary quadrilateral image region to another
7
8
9

SYNOPSIS

11       pamhomography
12         [-from=coords]
13         [-to=coords]
14         [-mapfile=map_file]
15         [-view=coords]
16         [-fill=color]
17         [pam_file]
18
19       You  can  abbreviate  any option to its shortest unique prefix. You can
20       use two hyphens instead of one to delimit an option. You  can  separate
21       an option from its value with whitespace instead of =.
22
23
24

DESCRIPTION

26       This program is part of Netpbm ⟨http://netpbm.sourceforge.net/⟩ .
27
28       pamhomography  transforms  a quadrilateral-not necessarily rectangular-
29       region of an image, producing a new image.
30
31       You     can      do      any      affine      image      transformation
32       ⟨https://en.wikipedia.org/wiki/Affine_transformation#Image_transformation⟩
33       : translation, reflection,  scaling,  rotation,  and  shearing/skewing.
34       However,  pamhomography  additionally can do bilinear transforms, which
35       means it can warp any quadrilateral to any  other  quadrilateral,  even
36       when  this  mapping  cannot  be  described using a single set of linear
37       equations. This can be useful, for example,  for  creating  perspective
38       views  of  rectangular images or for reverse-mapping a perspective view
39       back to a rectangular projection.
40
41
42

OPTIONS

44       In addition to the options common to all programs  based  on  libnetpbm
45       (most        notably       -quiet,       see       Common       Options
46       ⟨http://index.html#commonoptions⟩ ), pamhomography recognizes the  fol‐
47       lowing command line options:
48
49
50
51       <dt id="from-coords">-from=coords
52
53       This defines the source quadrilateral. coords is a list of four
54         integer-valued (x, y) coordinates. If you do not
55         specify -from, the source quadrilateral is taken to be the four
56         corners  of the input image in clockwise order, starting from the up‐
57       per
58         left.
59
60
61       <dt id="to-coords">-to=coords
62
63       This defines the target quadrilateral. coords is a list of  four  inte‐
64       ger-valued  (x,  y)  coordinates. If you do not specify -to, the target
65       quadrilateral is taken to be the four corners of  the  input  image  in
66       clockwise order, starting from the upper left.
67
68
69       <dt id="mapfile-map_file">-mapfile=map_file
70
71       This  names  a  text file that describes the mapping from the source to
72       the target quadrilateral. The file map_file must contain  either  eight
73       integer-valued  (x,  y)  coordinates, being the four source coordinates
74       followed by the corresponding four target coordinates, or only four (x,
75       y)  coordinates,  being only the four target coordinates. In the latter
76       case, the source quadrilateral is taken to be the four corners  of  the
77       input image in clockwise order, starting from the upper left.
78
79
80       <dt id="view-coords">-view=coords
81
82       This  defines  the  target view. coords is a list of two integer-valued
83       (x, y) coordinates: the upper left and lower right boundaries,  respec‐
84       tively,  of  the  pixels  that  will be visible in the output image. If
85       -view is not specified, the target view will fit precisely  the  target
86       quadrilateral.
87
88
89       <dt id="fill-color">-fill=color
90
91       This is the color with which the program fills all pixels that lie out‐
92       side of the target quadrilateral. Specify the color  as  described  for
93       the
94        argument      of      the     pnm_parsecolor()     library     routine
95       ⟨http://libnetpbm_image.html#colorname⟩ .
96
97       The default is black, and for images with a transparency plane,  trans‐
98       parent.
99
100
101
102
103       Cooordinates  should normally be specified in clockwise order. The syn‐
104       tax is fairly flexible: all characters other than the plus sign,  minus
105       sign,  and  digits are treated as separators. Although coordinates need
106       to be integers, they may lie outside the image's boundary.
107
108       If you specify -mapfile along with -from  and/or  -to,  -from  and  -to
109       override the quadrilaterals specified by map_file.
110
111
112

PARAMETERS

114       pamhomography's only parameter, pam_file, is the name of the
115         file containing the input image. If you don't specify pam_file, the
116         image comes from Standard Input.
117
118
119

NOTES

121       The output image uses the same Netpbm format as the input image.
122
123       Simple  transformations are best handled by other Netpbm programs, such
124       as those listed in the 'SEE  ALSO'  ⟨#SEE-ALSO⟩    section  below.  Use
125       pamhomography  for  more sophisticated transformations such as perspec‐
126       tive adjustments, rotations around an arbitrary point in the image, ex‐
127       traction  of  non-rectangular  quadrilaterals, shearings by coordinates
128       rather than by angle, and, in general,  all  transformations  that  are
129       most  easily  expressed  as  mapping  four  points in one image to four
130       points in another image.
131
132

EXAMPLES

134       The following examples use the park_row.ppm ⟨park_row.ppm⟩  test image,
135       which is a
136        photograph     of     New    York    City's    Park    Row    Building
137       ⟨https://commons.wikimedia.org/wiki/File:15_Park_Row_3.JPG⟩ , scaled to
138       441&times;640,  converted  to  a  PPM file, and redistributed under the
139       terms of the
140        GFDL ⟨https://en.wikipedia.org/wiki/GNU_Free_Documentation_License⟩ .
141
142       The first example showcases the real power of bilinear transformations.
143       Assuming park_row_rect.map has the following contents:
144
145             (0,  0) (440,   0) (440, 639)  (0, 639)</pre>
146
147       then
148
149
150       projects the building's facade from a perspective view to a rectilinear
151       front-on view. Remember that pamhomography ignores the parentheses and
152       commas used in park_row_rect.map; they merely make the file more
153       human-readable. We equivalently could have written
154
155
156       or any of myriad other variations.
157
158       pamhomography can warp the image to a trapezoid to make it look like
159       it's leaning backwards in 3-D:
160
161
162       As a very simple example,
163
164
165       flips the image left-to-right. Note that in this case the target
166       quadrilateral's coordinates are listed in counterclockwise order because
167       that represents the correspondence between points (0, 0) &harr; (440, 0) and
168       (0, 639) &harr; (639, 0).
169
170       Scaling is also straightforward. The following command scales down the
171       image from 441&times;640 to 341&times;540:
172
173
174       Let's add 100 pixels of tan border to the above. We use -view and
175       -fill to accomplish that task:
176
177
178       We can add a border without having to scale the image:
179
180
181       The -view option can also be used to extract a rectangle out of an
182       image, discarding the rest of the image:
183
184
185       Specifying the same set of coordinates to -from and -to has
186       the same effect but also allows you to extract non-rectangular quadrilaterals
187       from an image:
188
189
190       Rotation is doable but takes some effort. The challenge is that you need to
191       compute the rotated coordinates yourself. The matrix expression to rotate
192       points \((x_1, y_1)\) \((x_2, y_2)\), \((x_3, y_3)\), and \((x_4, y_4)\)
193       clockwise by \(\theta\) degrees around point \((c_x, c_y)\) is
194
195       \[ \begin{bmatrix} 1 & 0 & c_x \\ 0 & 1 & c_y \\ 0 & 0
196       & 1 \end{bmatrix} \begin{bmatrix} \cos \theta & -\sin \theta & 0
197       \\ \sin \theta & \cos \theta & 0 \\ 0 & 0 & 1 \end{bmatrix}
198       \begin{bmatrix} 1 & 0 & -c_x \\ 0 & 1 & -c_y \\ 0 & 0
199       & 1 \end{bmatrix} \begin{bmatrix} x_1 & x_2 & x_3 & x_4 \\ y_1
200       & y_2 & y_3 & y_4 \\ 1 & 1 & 1 & 1 \end{bmatrix}
201       \quad. \]
202
203       For example, to rotate park_row.ppm 30&deg; clockwise around (220,
204       320) you would compute
205
206       \[ \begin{bmatrix} 1 & 0 & 220 \\ 0 & 1 & 320 \\ 0 & 0
207       & 1 \end{bmatrix} \begin{bmatrix} \cos 30^{\circ} & -\sin 30^{\circ}
208       & 0 \\ \sin 30^{\circ} & \cos 30^{\circ} & 0 \\ 0 & 0 & 1
209       \end{bmatrix} \begin{bmatrix} 1 & 0 & -220 \\ 0 & 1 & -320 \\
210       0 & 0 & 1 \end{bmatrix} \begin{bmatrix} 0 & 440 & 440 & 0
211       \\ 0 & 0 & 639 & 639 \\ 1 & 1 & 1 & 1 \end{bmatrix} =
212       \begin{bmatrix} 189.4744 & 570.5256 & 251.0256 & -130.0256 \\
213       -67.1281 & 152.8719 & 706.2621 & 486.2621 \\ 1.0000 & 1.0000
214       & 1.0000 & 1.0000 \end{bmatrix} \quad, \]
215
216       round these coordinates to integers, transpose the matrix, and produce the
217       following map file, park_row_rot30.map:
218
219            571  153
220            251  706
221           -130  486</pre>
222
223       (These are the 'to' coordinates; we use the default, full-image
224       'from' coordinates.) The mapping then works as in all of the
225       preceding examples:
226
227
228
229

HISTORY

279       pamhomography was new in Netpbm 10.94 (March 2021).
280
281
282

AUTHOR

284       Copyright © 2020 Scott Pakin, scott+pbm@pakin.org
285
286
287

289       •
290
291              SYNOPSIS ⟨#SYNOPSIS⟩
292
293       •
294
295              DESCRIPTION ⟨#DESCRIPTION⟩
296
297       •
298
299              OPTIONS ⟨#OPTIONS⟩
300
301       •
302
303              PARAMETERS ⟨#PARAMETERS⟩
304
305       •
306
307              NOTES ⟨#NOTES⟩
308
309       •
310
311              EXAMPLES ⟨#EXAMPLES⟩
312
313       •
314
315              SEE ALSO ⟨#SEE-ALSO⟩
316
317       •
318
319              HISTORY ⟨#HISTORY⟩
320
321       •
322
323              AUTHOR ⟨#AUTHOR⟩
324

DOCUMENT SOURCE

326       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
327       source.  The master documentation is at
328
329              http://netpbm.sourceforge.net/doc/pamhomography.html
330
331netpbm documentation            03 January 2021   Pamhomography User Manual(0)