1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.3//EN">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>pamhomography</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<script type="text/javascript" src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script type="text/javascript" id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
</head>
<body>
<h1>pamhomography</h1>
Updated: 03 January 2021
<br>
<a href="#index">Table of Contents</a>
<h2>NAME</h2>
<p>pamhomography - map one arbitrary quadrilateral image region to another</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><b>pamhomography</b>
[<b>-from</b>=<i>coords</i>]
[<b>-to</b>=<i>coords</i>]
[<b>-mapfile</b>=<i>map_file</i>]
[<b>-view</b>=<i>coords</i>]
[<b>-fill</b>=<i>color</i>]
[<i>pam_file</i>]
<p>You can abbreviate any option to its shortest unique prefix. You can use
two hyphens instead of one to delimit an option. You can separate an option
from its value with whitespace instead of <code>=</code>.</p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p>This program is part
of <a href="http://netpbm.sourceforge.net/">Netpbm</a>.</p>
<p><b>pamhomography</b> transforms a quadrilateral—not necessarily
rectangular—region of an image, producing a new image.
<p>You can do any
<a href="https://en.wikipedia.org/wiki/Affine_transformation#Image_transformation">affine image transformation</a>: translation, reflection, scaling,
rotation, and shearing/skewing. However, <b>pamhomography</b> additionally can
do <i>bilinear</i> transforms, which means it can warp any quadrilateral to any
other quadrilateral, even when this mapping cannot be described using a single
set of linear equations. This can be useful, for example, for creating
perspective views of rectangular images or for reverse-mapping a perspective
view back to a rectangular projection.</p>
<h2 id="OPTIONS">OPTIONS</h2>
<p>In addition to the options common to all programs based on libnetpbm (most
notably <b>-quiet</b>, see <a href="http://index.html#commonoptions">Common
Options</a>), <b>pamhomography</b> recognizes the following command line
options:</p>
<dl>
<dt><b>-from</b>=<i>coords</i></dt>
<dd>
<p>This defines the source quadrilateral. <i>coords</i> is a list of four
integer-valued (<i>x</i>, <i>y</i>) coordinates. If you do not
specify <b>-from</b>, the source quadrilateral is taken to be the four
corners of the input image in clockwise order, starting from the upper
left.</p>
</dd>
<dt><b>-to</b>=<i>coords</i></dt>
<dd>
<p>This defines the target quadrilateral. <i>coords</i> is a list of four
integer-valued (<i>x</i>, <i>y</i>) coordinates. If you do not
specify <b>-to</b>, the target quadrilateral is taken to be the four corners
of the input image in clockwise order, starting from the upper left.</p>
</dd>
<dt><b>-mapfile</b>=<i>map_file</i></dt>
<dd>
<p>This names a text file that describes the mapping from the source to the
target quadrilateral. The file <i>map_file</i> must contain either eight
integer-valued (<i>x</i>, <i>y</i>) coordinates, being the four source
coordinates followed by the corresponding four target coordinates, or only
four (<i>x</i>, <i>y</i>) coordinates, being only the four target
coordinates. In the latter case, the source quadrilateral is taken to be the
four corners of the input image in clockwise order, starting from the upper
left.</p>
</dd>
<dt><b>-view</b>=<i>coords</i></dt>
<dd>
<p>This defines the target view. <i>coords</i> is a list of two integer-valued
(<i>x</i>, <i>y</i>) coordinates: the upper left and lower right boundaries,
respectively, of the pixels that will be visible in the output image. If
<b>-view</b> is not specified, the target view will fit precisely the target
quadrilateral.</p>
</dd>
<dt><b>-fill</b>=<i>color</i></dt>
<dd>
<p>This is the color with which the program fills all pixels that lie outside
of the target quadrilateral. Specify the color as described for the
<a href="http://libnetpbm_image.html#colorname">
argument of the pnm_parsecolor() library routine</a>.
<p>The default is black, and for images with a transparency plane, transparent.
</dd>
</dl>
<p>Cooordinates should normally be specified in clockwise order. The syntax is
fairly flexible: all characters other than the plus sign, minus sign, and
digits are treated as separators. Although coordinates need to be integers,
they may lie outside the image's boundary.</p>
<p>If you specify <b>-mapfile</b> along with <b>-from</b> and/or <b>-to</b>,
<b>-from</b> and <b>-to</b> override the quadrilaterals specified
by <i>map_file</i>.</p>
<h2 id="PARAMETERS">PARAMETERS</h2>
<p><b>pamhomography</b>'s only parameter, <i>pam_file</i>, is the name of the
file containing the input image. If you don't specify <i>pam_file</i>, the
image comes from Standard Input.
<h2 id="NOTES">NOTES</h2>
<p>The output image uses the same Netpbm format as the input image.</p>
<p>Simple transformations are best handled by other Netpbm programs, such as
those listed in the <a href="#SEE-ALSO">"SEE ALSO"</a> section
below. Use <b>pamhomography</b> for more sophisticated transformations such as
perspective adjustments, rotations around an arbitrary point in the image,
extraction of non-rectangular quadrilaterals, shearings by coordinates rather
than by angle, and, in general, all transformations that are most easily
expressed as mapping four points in one image to four points in another
image.</p>
<h2 id="EXAMPLES">EXAMPLES</h2>
<p>The following examples use the
<a href="park_row.ppm">park_row.ppm </a> test image, which is a
<a href="https://commons.wikimedia.org/wiki/File:15_Park_Row_3.JPG">
photograph of New York City's Park Row Building</a>, scaled to
441×640, converted to a PPM file, and redistributed under the terms of
the <a href="https://en.wikipedia.org/wiki/GNU_Free_Documentation_License">
GFDL</a>.</p>
<p>The first example showcases the real power of bilinear transformations.
Assuming <i>park_row_rect.map</i> has the following contents:</p>
<pre><code> (147, 51) (316, 105) (402, 595) (92, 560)
(0, 0) (440, 0) (440, 639) (0, 639)</code></pre>
<p>then</p>
<pre><code> pamhomography -mapfile park_row_rect.map park_row.ppm > park_row_rect.ppm</code></pre>
<p>projects the building's facade from a perspective view to a rectilinear
front-on view. Remember that <b>pamhomography</b> ignores the parentheses and
commas used in <i>park_row_rect.map</i>; they merely make the file more
human-readable. We equivalently could have written</p>
<pre><code> 147 51 316 105 402 595 92 560 0 0 440 0 440 639 0 639</code></pre>
<p>or any of myriad other variations.</p>
<p><b>pamhomography</b> can warp the image to a trapezoid to make it look like
it's leaning backwards in 3-D:</p>
<pre><code> pamhomography -to "50,0 390,0 440,200 0,200" park_row.ppm > park_row_trap.ppm</code></pre>
<p>As a very simple example,</p>
<pre><code> pamhomography -to "440,0 0,0 0,639 440,639" park_row.ppm > park_row_flip.ppm</code></pre>
<p>flips the image left-to-right. Note that in this case the target
quadrilateral's coordinates are listed in counterclockwise order because
that represents the correspondence between points (0, 0) ↔ (440, 0) and
(0, 639) ↔ (639, 0).</p>
<p>Scaling is also straightforward. The following command scales down the
image from 441×640 to 341×540:</p>
<pre><code> pamhomography -to "0,0 340,0 340,539 0,539" park_row.ppm > park_row_small.ppm</code></pre>
<p>Let's add 100 pixels of tan border to the above. We use <b>-view</b> and
<b>-fill</b> to accomplish that task:</p>
<pre><code> 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</code></pre>
<p>We can add a border without having to scale the image:</p>
<pre><code> pamhomography -view "-100,-100 540,739" -fill tan park_row.ppm > park_row_border.ppm</code></pre>
<p>The <b>-view</b> option can also be used to extract a rectangle out of an
image, discarding the rest of the image:</p>
<pre><code> pamhomography -view "130,10 205,80" park_row.ppm > park_row_cut.ppm</code></pre>
<p>Specifying the same set of coordinates to <b>-from</b> and <b>-to</b> has
the same effect but also allows you to extract non-rectangular quadrilaterals
from an image:</p>
<pre><code> 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</code></pre>
<p>Rotation is doable but takes some effort. The challenge is that you need to
compute the rotated coordinates yourself. The matrix expression to rotate
points \((x_1, y_1)\) \((x_2, y_2)\), \((x_3, y_3)\), and \((x_4, y_4)\)
clockwise by \(\theta\) degrees around point \((c_x, c_y)\) is</p>
<p>\[ \begin{bmatrix} 1 & 0 & c_x \\ 0 & 1 & c_y \\ 0 & 0
& 1 \end{bmatrix} \begin{bmatrix} \cos \theta & -\sin \theta & 0
\\ \sin \theta & \cos \theta & 0 \\ 0 & 0 & 1 \end{bmatrix}
\begin{bmatrix} 1 & 0 & -c_x \\ 0 & 1 & -c_y \\ 0 & 0
& 1 \end{bmatrix} \begin{bmatrix} x_1 & x_2 & x_3 & x_4 \\ y_1
& y_2 & y_3 & y_4 \\ 1 & 1 & 1 & 1 \end{bmatrix}
\quad. \]</p>
<p>For example, to rotate <i>park_row.ppm</i> 30° clockwise around (220,
320) you would compute</p>
<p>\[ \begin{bmatrix} 1 & 0 & 220 \\ 0 & 1 & 320 \\ 0 & 0
& 1 \end{bmatrix} \begin{bmatrix} \cos 30^{\circ} & -\sin 30^{\circ}
& 0 \\ \sin 30^{\circ} & \cos 30^{\circ} & 0 \\ 0 & 0 & 1
\end{bmatrix} \begin{bmatrix} 1 & 0 & -220 \\ 0 & 1 & -320 \\
0 & 0 & 1 \end{bmatrix} \begin{bmatrix} 0 & 440 & 440 & 0
\\ 0 & 0 & 639 & 639 \\ 1 & 1 & 1 & 1 \end{bmatrix} =
\begin{bmatrix} 189.4744 & 570.5256 & 251.0256 & -130.0256 \\
-67.1281 & 152.8719 & 706.2621 & 486.2621 \\ 1.0000 & 1.0000
& 1.0000 & 1.0000 \end{bmatrix} \quad, \]</p>
<p>round these coordinates to integers, transpose the matrix, and produce the
following map file, <i>park_row_rot30.map</i>:</p>
<pre><code> 189 -67
571 153
251 706
-130 486</code></pre>
<p>(These are the "to" coordinates; we use the default, full-image
"from" coordinates.) The mapping then works as in all of the
preceding examples:</p>
<pre><code> pamhomography -mapfile park_row_rot30.map park_row.ppm > park_row_rot30.ppm</code></pre>
<h2 id="SEE-ALSO">SEE ALSO</h2>
<ul>
<li><a href="http://pamcut.html">pamcut</a>
<li><a href="http://pamenlarge.html">pamenlarge</a>
<li><a href="http://pamflip.html">pamflip</a>
<li><a href="http://pamperspective.html">pamperspective</a>
<li><a href="http://pamscale.html">pamscale</a>
<li><a href="http://pamstretch.html">pamstretch</a>
<li><a href="http://pam.html">pam</a>
<li><a href="http://pnmmargin.html">pnmmargin</a>
<li><a href="http://pnmpad.html">pnmpad</a>
<li><a href="http://pnmrotate.html">pnmrotate</a>
<li><a href="http://pnmshear.html">pnmshear</a>
</ul>
<h2 id="HISTORY">HISTORY</h2>
<p><b>pamhomography</b> was new in Netpbm 10.94 (March 2021).
<h2 id="AUTHOR">AUTHOR</h2>
<p>Copyright © 2020 Scott
Pakin, <a href="mailto:scott+pbm@pakin.org">scott+pbm@pakin.org</a></p>
<h2 id="index">Table of Contents</h2>
<ul>
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#OPTIONS">OPTIONS</a></li>
<li><a href="#PARAMETERS">PARAMETERS</a></li>
<li><a href="#NOTES">NOTES</a></li>
<li><a href="#EXAMPLES">EXAMPLES</a></li>
<li><a href="#SEE-ALSO">SEE ALSO</a></li>
<li><a href="#HISTORY">HISTORY</a></li>
<li><a href="#AUTHOR">AUTHOR</a></li>
</ul>
</body>
</html>
|
