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
|
\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it! If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "Pamrubber User Manual" 1 "February 2011" "netpbm documentation"
.SH NAME
pamrubber - a rubber-sheeting utility that stretches an image
based on control points
.UN synopsis
.SH SYNOPSIS
\fBpamrubber\fP
{\fB-tri | -quad\fP}
[\fB-linear\fP]
[\fB-frame\fP]
[\fB-randomseed=\fP\fIN\fP]
\fIcp1x cp1y\fP [\fIcp2x cp2y\fP [\fIcp3x cp3y\fP [\fIcp4x cp4y\fP]]]
\fIcp1x cp1y\fP [\fIcp2x cp2y\fP [\fIcp3x cp3y\fP [\fIcp4x cp4y\fP]]]
[\fIfilename\fP]
.PP
Minimum unique abbreviation of options is acceptable. You may use double
hyphens instead of single hyphen to denote options.
.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
The \fBpamrubber\fP utility converts a pam image into a new image with the
contents moved around. The transformation is often called "rubber
sheeting": you identify control points (CP) on the source image and
specify new positions for those points in the new image. \fBpamrubber\fP
moves all the pixels around, stretching and compressing as necessary, as
if the original image were on a sheet of rubber and you pulled on the sheet
to make the control points move to their new locations.
.PP
The new image has the same dimensions and format as the original.
.PP
The transformation can happen in two very different ways, called
"quad" and "tri." With the former, you must specify four
control points (for both source and target). These are the corners of two
quadrilaterals that will act as the coordinate system for both source and
target images. Consider them as non-orthogonal (0,0), (0,1), (1,0) and (1,1)
points. This transformation comes close to the one \fBpamperspective\fP
does, however that program does other corrections as well.
.PP
When you specify less than four control points, the program adds control
points in the following way. With three control points, \fBpamrubber\fP
chooses the fourth one such that the four points form a parallelogram. With
two points, \fBpamrubber\fP considers them the opposite corners of a
rectangle. When you specify only one control point, \fBpamrubber\fP uses a
rectangle from the top left corner of the image to the single control
point.
.PP
In "tri" mode, \fBpamrubber\fP conceptually cuts up the source
and target image into triangles. It Transforms within each corresponding pair
of triangles in a stretching fashion. It's like pulling on the three corners
of the triangle. In this mode, each pixel in the source image gets mapped to
a position in the target image. No pixels are lost.
.PP
When, in "tri" mode, you specify only a single control point in
the source and target image, \fBpamrubber\fP creates four triangles from this
point to the four corners of the image. With two points, the program creates
six triangles from the two endpoints of the line connecting the two points,
again to the four corners of the image. Three control points is in a way the
core of this utility in "tri" mode. Between the three edges of the
central triangle and the four edges of the image, \fBpamrubber\fP constructs
another seven triangles. Four control points define two central connected
triangles. In total this results in cutting the source and target image up
into ten triangles.
.PP
In this case clearly a picture says more than a thousand words. There is a
graphical illustration of these various modes at
.UR http://www.schaik.com/netpbm/rubber
www.schaik.com/netpbm/rubber
.UE
\&. An example of how to use this type of
rubber sheeting in cartography is in the article
.UR http://www.isprs.org/proceedings/XXXVI/5-W1/papers/21.pdf
Visualizing the Landscape of Old-Time Tokyo
.UE
\&.
.UN parameters
.SH PARAMETERS
.PP
The parameters are control points (\fIcp\fP) in pairs of \fIx\fP
and \fIy\fP. The source and target image must have the same number of
control points. The minimum number of values specified here is 4 for a single
control point in the source and target image. The maximum is 16 for four
control points in each image.
.PP
\fIfilename\fP is the name of the input file. If you don't specify
this, \fBpamrubber\fP reads the image from Standard Input.
.UN options
.SH OPTIONS
.PP
In addition to the options common to all programs based on libnetpbm
(most notably \fB-quiet\fP, see
.UR index.html#commonoptions
Common Options
.UE
\&), \fBpamrubber\fP recognizes the following
command line options:
.TP
\fB-tri\fP | \fB-quad\fP
.sp
This selects the type of rubber sheeting done.
You must specify exactly one of these options.
.TP
\fB-linear\fP
.sp
This determines whether \fBpamrubber\fP uses nearest neighbor
interpolation or bilinear interpolation of four source pixels.
.TP
\fB-frame\fP
.sp
This option causes \fBpamrubber\fP to overlay the target image with the
edges of the quadrilaterals, respectively the triangles used for the rubber
sheeting. To get the same overlay for the source image, use a \fBpamrubber\fP
transformation with identical control points for source and target.
.TP
\fB-randomseed=\fP\fIN\fP
.sp
\fBpamrubber\fP randomizes some of its output. So that you can produce
repeatable results, you can choose the seed of the random number generator
with this option. If you use the same input image and the same random number
generator seed, you should always get the exact same output. By default,
\fBpamrubber\fP uses the time of day as the seed, so you get slightly
different output when you run the program twice on the same input.
.sp
Before Netpbm 10.61 (December 2012), this was called \fB-randseed\fP,
and that still works.
.UN seealso
.SH SEE ALSO
.BR "pam" (1)\c
\& and
.BR "pamperspective" (1)\c
\&
.UN history
.SH HISTORY
.PP
\fBpamrubber\fP was new in Netpbm 10.54 (March 2011).
.UN authors
.SH AUTHORS
.PP
\fIWillem van Schaik\fP wrote this program
in February 2011 and contributed it to Netpbm.
.SH DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source. The master documentation is at
.IP
.B http://netpbm.sourceforge.net/doc/pamrubber.html
.PP
|
