Debian Codegraph @

upstream/debian-unstable/man1/pamrubber.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pamrubber User Manual" 1 "February 2011" "netpbm documentation"
7
8 .SH NAME
9 pamrubber - a rubber-sheeting utility that stretches an image
10 based on control points
11
12 .UN synopsis
13 .SH SYNOPSIS
14 \fBpamrubber\fP
15 {\fB-tri | -quad\fP}
16 [\fB-linear\fP]
17 [\fB-frame\fP]
18 [\fB-randomseed=\fP\fIN\fP]
19 \fIcp1x cp1y\fP [\fIcp2x cp2y\fP [\fIcp3x cp3y\fP [\fIcp4x cp4y\fP]]]
20 \fIcp1x cp1y\fP [\fIcp2x cp2y\fP [\fIcp3x cp3y\fP [\fIcp4x cp4y\fP]]]
21 [\fIfilename\fP]
22 .PP
23 Minimum unique abbreviation of options is acceptable. You may use double
24 hyphens instead of single hyphen to denote options.
25
26 .UN description
27 .SH DESCRIPTION
28 .PP
29 This program is part of
30 .BR "Netpbm" (1)\c
31 \&.
32 .PP
33 The \fBpamrubber\fP utility converts a pam image into a new image with the
34 contents moved around. The transformation is often called "rubber
35 sheeting": you identify control points (CP) on the source image and
36 specify new positions for those points in the new image. \fBpamrubber\fP
37 moves all the pixels around, stretching and compressing as necessary, as
38 if the original image were on a sheet of rubber and you pulled on the sheet
39 to make the control points move to their new locations.
40 .PP
41 The new image has the same dimensions and format as the original.
42 .PP
43 The transformation can happen in two very different ways, called
44 "quad" and "tri." With the former, you must specify four
45 control points (for both source and target). These are the corners of two
46 quadrilaterals that will act as the coordinate system for both source and
47 target images. Consider them as non-orthogonal (0,0), (0,1), (1,0) and (1,1)
48 points. This transformation comes close to the one \fBpamperspective\fP
49 does, however that program does other corrections as well.
50 .PP
51 When you specify less than four control points, the program adds control
52 points in the following way. With three control points, \fBpamrubber\fP
53 chooses the fourth one such that the four points form a parallelogram. With
54 two points, \fBpamrubber\fP considers them the opposite corners of a
55 rectangle. When you specify only one control point, \fBpamrubber\fP uses a
56 rectangle from the top left corner of the image to the single control
57 point.
58 .PP
59 In "tri" mode, \fBpamrubber\fP conceptually cuts up the source
60 and target image into triangles. It Transforms within each corresponding pair
61 of triangles in a stretching fashion. It's like pulling on the three corners
62 of the triangle. In this mode, each pixel in the source image gets mapped to
63 a position in the target image. No pixels are lost.
64 .PP
65 When, in "tri" mode, you specify only a single control point in
66 the source and target image, \fBpamrubber\fP creates four triangles from this
67 point to the four corners of the image. With two points, the program creates
68 six triangles from the two endpoints of the line connecting the two points,
69 again to the four corners of the image. Three control points is in a way the
70 core of this utility in "tri" mode. Between the three edges of the
71 central triangle and the four edges of the image, \fBpamrubber\fP constructs
72 another seven triangles. Four control points define two central connected
73 triangles. In total this results in cutting the source and target image up
74 into ten triangles.
75 .PP
76 In this case clearly a picture says more than a thousand words. There is a
77 graphical illustration of these various modes at
78 .UR http://www.schaik.com/netpbm/rubber
79 www.schaik.com/netpbm/rubber
80 .UE
81 \&. An example of how to use this type of
82 rubber sheeting in cartography is in the article
83 .UR http://www.isprs.org/proceedings/XXXVI/5-W1/papers/21.pdf
84 Visualizing the Landscape of Old-Time Tokyo
85 .UE
86 \&.
87
88
89 .UN parameters
90 .SH PARAMETERS
91 .PP
92 The parameters are control points (\fIcp\fP) in pairs of \fIx\fP
93 and \fIy\fP. The source and target image must have the same number of
94 control points. The minimum number of values specified here is 4 for a single
95 control point in the source and target image. The maximum is 16 for four
96 control points in each image.
97 .PP
98 \fIfilename\fP is the name of the input file. If you don't specify
99 this, \fBpamrubber\fP reads the image from Standard Input.
100
101
102 .UN options
103 .SH OPTIONS
104 .PP
105 In addition to the options common to all programs based on libnetpbm
106 (most notably \fB-quiet\fP, see
107 .UR index.html#commonoptions
108 Common Options
109 .UE
110 \&), \fBpamrubber\fP recognizes the following
111 command line options:
112
113
114
115 .TP
116 \fB-tri\fP | \fB-quad\fP
117 .sp
118 This selects the type of rubber sheeting done.
119 You must specify exactly one of these options.
120
121
122 .TP
123 \fB-linear\fP
124 .sp
125 This determines whether \fBpamrubber\fP uses nearest neighbor
126 interpolation or bilinear interpolation of four source pixels.
127
128
129
130 .TP
131 \fB-frame\fP
132 .sp
133 This option causes \fBpamrubber\fP to overlay the target image with the
134 edges of the quadrilaterals, respectively the triangles used for the rubber
135 sheeting. To get the same overlay for the source image, use a \fBpamrubber\fP
136 transformation with identical control points for source and target.
137
138
139 .TP
140 \fB-randomseed=\fP\fIN\fP
141 .sp
142 \fBpamrubber\fP randomizes some of its output. So that you can produce
143 repeatable results, you can choose the seed of the random number generator
144 with this option. If you use the same input image and the same random number
145 generator seed, you should always get the exact same output. By default,
146 \fBpamrubber\fP uses the time of day as the seed, so you get slightly
147 different output when you run the program twice on the same input.
148 .sp
149 Before Netpbm 10.61 (December 2012), this was called \fB-randseed\fP,
150 and that still works.
151
152
153
154
155
156 .UN seealso
157 .SH SEE ALSO
158 .BR "pam" (1)\c
159 \& and
160 .BR "pamperspective" (1)\c
161 \&
162
163 .UN history
164 .SH HISTORY
165 .PP
166 \fBpamrubber\fP was new in Netpbm 10.54 (March 2011).
167
168
169 .UN authors
170 .SH AUTHORS
171 .PP
172 \fIWillem van Schaik\fP wrote this program
173 in February 2011 and contributed it to Netpbm.
174 .SH DOCUMENT SOURCE
175 This manual page was generated by the Netpbm tool 'makeman' from HTML
176 source. The master documentation is at
177 .IP
178 .B http://netpbm.sourceforge.net/doc/pamrubber.html
179 .PP