Debian Codegraph @

upstream/debian-unstable/man1/pamcomp.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 "Pamcomp User Manual" 1 "13 August 2011" "netpbm documentation"
7 .PP
8 .SH NAME
9 pamcomp - composite (overlay) two Netpbm images together
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpamcomp\fP
15
16 [\fB-align=\fP{\fBleft\fP | \fBcenter\fP | \fBright\fP |
17 \fBbeyondleft\fP | \fBbeyondright\fP}]
18 [\fB-valign=\fP{\fBtop\fP | \fBmiddle\fP | \fBbottom\fP|
19 \fBabove\fP | \fBbelow\fP}]
20 [\fB-xoff=\fP\fIX\fP]
21 [\fB-yoff=\fP\fIY\fP]
22 [\fB-alpha=\fP\fIalpha-pgmfile\fP]
23 [\fB-invert\fP]
24 [\fB-opacity=\fP\fIopacity\fP]
25 [\fB-mixtransparency\fP]
26 [\fB-linear\fP]
27 \fIoverlay_file\fP
28 [\fIunderlying_file\fP [\fIoutput_file\fP]]
29 .PP
30 Minimum unique abbreviation of option is acceptable. You may use double
31 hyphens instead of single hyphen to denote options. You may use white
32 space in place of the equals sign to separate an option name from its value.
33
34 .UN description
35 .SH DESCRIPTION
36 .PP
37 This program is part of
38 .BR "Netpbm" (1)\c
39 \&.
40
41 \fBpamcomp\fP reads two images and produces a composite image with
42 one of the images overlayed on top of the other, possible
43 translucently. The images need not be the same size. The input and
44 outputs are Netpbm format image files.
45 .PP
46 In its simplest use, \fBpamcomp\fP simply places the image in the
47 file \fIoverlay_file\fP on top of the image in the file
48 \fIunderlying_file\fP, blocking out the part of \fIunderlying_file\fP
49 beneath it.
50 .PP
51 If you add the \fB-alpha\fP option, then \fBpamcomp\fP uses the
52 image in file \fIalpha-pgmfile\fP as a transparency mask, which means it
53 determines the level of transparency of each point in the overlay
54 image. The transparency mask must have the same dimensions as the overlay
55 image. In places where the transparency mask defines the overlay image to be
56 opaque, the composite output contains only the contents of the overlay
57 image; the underlying image is totally blocked out. In places where
58 the transparency mask defines the overlay image to be transparent, the
59 composite output contains none of the overlay image; the underlying
60 image shows through completely. In places where the transparency mask shows
61 a value in between opaque and transparent (translucence), the
62 composite image contains a mixture of the overlay image and the
63 underlying image and the level of translucence determines how much of
64 each.
65 .PP
66 The transparency mask is a PGM file in which a white pixel represents
67 opaqueness and a black pixel transparency. Anything in between is
68 translucent. (Like any Netpbm program, \fBpamcomp\fP will see a PBM
69 file as if it is PGM).
70 .PP
71 If the overlay image is a PAM image of tuple type RGB_ALPHA or
72 GRAYSCALE_ALPHA, then the overlay image contains transparency
73 information itself and \fBpamcomp\fP uses it the same way as the
74 transparency mask described above. If you supply both an overlay image that
75 has transparency information and a transparency mask, \fBpamcomp\fP
76 multiplies the two opacities to get the opacity of the overlay pixel.
77 .PP
78 Before Netpbm 10.25 (October 2004), \fBpamcomp\fP did not recognize the
79 transparency information in a PAM image -- it just ignored it. So people had
80 to make appropriate transparency masks in order to have a non-opaque overlay. Some
81 Netpbm programs that convert from image formats that contain transparency
82 information are not able to create RGB_ALPHA or GRAYSCALE_ALPHA PAM output, so
83 you have to use the old method -- extract the transparency information from
84 the original into a separate transparency mask and use that as input to
85 \fBpamcomp\fP.
86 .PP
87 The output image is always of the same dimensions as the underlying
88 image. \fBpamcomp\fP uses only parts of the overlay image that fit
89 within the underlying image.
90 .PP
91 The output image is a PAM image. Its tuples are color, grayscale, or black
92 and white, whichever is the "highest" format between the two input
93 images. The maxval of the output is the least common multiple of the maxvals
94 of the input, up to the maximum possible PAM maxval, 65535.
95 .PP
96 The output has an opacity channel if and only if the underlying image does,
97 and then the opacities are as described under the \fB-mixtransparency\fP
98 option. Before Netpbm 10.56 (September 2011), the output never has an opacity
99 channel.
100 .PP
101 To specify where on the underlying image to place the overlay
102 image, use the \fB-align\fP, \fB-valign\fP, \fB-xoff\fP, and
103 \fB-yoff\fP options. Without these options, the default horizontal
104 position is flush left and the default vertical position is flush top.
105 .PP
106 The overlay image, in the position you specify, need not fit entirely
107 within the underlying image. \fBpamcomp\fP uses only the parts of the
108 overlay image that appear above the underlying image. It is possible to
109 specify positioning such that \fInone\fP of the overlay image is
110 over the underlying image -- i.e. the overlay is out of frame. If you
111 do that, \fBpamcomp\fP issues a warning.
112 .PP
113 The overlay and underlying images may be of different formats
114 (e.g. overlaying a PBM text image over a full color PPM image) and
115 have different maxvals. The output image has the more general of the
116 two input formats and a maxval that is the least common multiple the
117 two maxvals (or the maximum maxval allowable by the format, if the LCM
118 is more than that).
119
120
121 .UN arguments
122 .SH ARGUMENTS
123 .PP
124 The \fIoverlay_file\fP argument is the name of the file containing the
125 overly image, while \fIunderlying_file\fP is the name of the file
126 containing the underlying image. For either, you may specify '-'
127 to indicate Standard Input, and \fIunderlying\fP file defaults to Standard
128 Input. Make sure you aren't specifying (or defaulting) Standard Input as
129 both.
130 .PP
131 Note that there may be a third input file, identified by an
132 \fB-alphafile\fP option.
133 .PP
134 The \fIoutput_file\fP argument is the name of the file to which
135 \fBpamcomp\fP writes the output, creating or truncating it first. You may
136 specify '-' to indicate Standard Output, in which
137 case \fBpamcomp\fP does not truncate it. Note that \fBpamcomp\fP is
138 unusual among Netpbm programs, as a historical accident, in having an output
139 file argument; Netpbm programs normally write to Standard Output only.
140
141
142 .UN options
143 .SH OPTIONS
144 .PP
145 In addition to the options common to all programs based on libnetpbm
146 (most notably \fB-quiet\fP, see
147 .UR index.html#commonoptions
148 Common Options
149 .UE
150 \&), \fBpamcomp\fP recognizes the following
151 command line options:
152
153
154 .TP
155 \fB-align=\fP\fIalignment\fP
156 This option selects the basic horizontal position of the overlay image
157 with respect to the underlying image, in syntax reminiscent of HTML.
158 \fBleft\fP means flush left, \fBcenter\fP means centered, and \fBright\fP
159 means flush right.
160 .sp
161 The \fB-xoff\fP option modifies this position.
162
163 \fBbeyondleft\fP means just out of frame to the left -- the right edge of
164 the overlay is flush with the left edge of the underlying image.
165 \fBbeyondright\fP means just out of frame to the right. These alignments
166 are useful only if you add a \fB-xoff\fP option. These two values were
167 added in Netpbm 10.10 (October 2002).
168 .sp
169 The default is \fBleft\fP.
170
171 .TP
172 \fB-valign=\fP\fIalignment\fP
173 This option selects the basic vertical position of the overlay image
174 with respect to the underlying image, in syntax reminiscent of HTML.
175 \fBtop\fP means flush top, \fBmiddle\fP means centered, and \fBbottom\fP
176 means flush bottom.
177 .sp
178 The \fB-yoff\fP option modifies this position.
179
180 \fBabove\fP means just out of frame to the top -- the bottom edge of
181 the overlay is flush with the top edge of the underlying image.
182 \fBbelow\fP means just out of frame to the bottom. These alignments
183 are useful only if you add a \fB-yoff\fP option. These two values were
184 added in Netpbm 10.10 (October 2002).
185 .sp
186 The default is \fBtop\fP.
187
188 .TP
189 \fB-xoff=\fP\fIx\fP
190 This option modifies the horizontal positioning of the overlay
191 image with respect to the underlying image as selected by the
192 \fB-align\fP option. \fBpamcomp\fP shifts the overlay image from
193 that basic position \fIx\fP pixels to the right. \fIx\fP can be
194 negative to indicate shifting to the left.
195 .sp
196 The overlay need not fit entirely (or at all) on the underlying image.
197 \fBpamcomp\fP uses only the parts that lie over the underlying image.
198 .sp
199 Before Netpbm 10.10 (October 2002), \fB-xoff\fP was mutually
200 exclusive with \fB-align\fP and always measured from the left edge.
201
202 .TP
203 \fB-yoff=\fP\fIy\fP
204 This option modifies the vertical positioning of the overlay
205 image with respect to the underlying image as selected by the
206 \fB-valign\fP option. \fBpamcomp\fP shifts the overlay image from
207 that basic position \fIy\fP pixels downward. \fIy\fP can be
208 negative to indicate shifting upward.
209 .sp
210 The overlay need not fit entirely (or at all) on the underlying image.
211 \fBpamcomp\fP uses only the parts that lie over the underlying image.
212 .sp
213 Before Netpbm 10.10 (October 2002), \fB-xoff\fP was mutually
214 exclusive with \fB-valign\fP and always measured from the top edge.
215
216 .TP
217 \fB-alpha=\fP\fIalpha-pgmfile\fP
218 This option names a file that contains the transparency mask. If you don't
219 specify this option, there is no transparency mask, which is equivalent to
220 having a transparency mask specify total opaqueness everywhere.
221 .sp
222 You can specify \fB-\fP as the value of this option and the transparency
223 mask will come from Standard Input. If you do this, don't specify
224 Standard Input as the source of any other input image.
225
226 .TP
227 \fB-invert\fP
228 This option inverts the sense of the values in the transparency mask, which
229 effectively switches the roles of the overlay image and the underlying
230 image in places where the two intersect.
231
232 .TP
233 \fB-opacity=\fP\fIopacity\fP
234 This option tells how opaque the overlay image is to be, i.e. how much
235 of the composite image should be from the overlay image, as opposed to
236 the underlying image. \fIopacity\fP is a floating point number, with
237 1.0 meaning the overlay image is totally opaque and 0.0 meaning it is
238 totally transparent. The default is 1.0.
239 .sp
240 If you specify a transparency mask (the \fB-alpha\fP option),
241 \fBpamcomp\fP uses the product of the opacity indicated by the transparency
242 mask (as modified by the \fB-invert\fP option, as a fraction, and
243 this opacity value. The \fB-invert\fP option does not apply to this
244 opacity value.
245 .sp
246 As a simple opacity value, the value makes sense only if it is
247 between 0 and 1, inclusive. However, \fBpamcomp\fP accepts all
248 values and performs the same arithmetic computation using whatever
249 value you provide. An opacity value less than zero means the underlay
250 image is intensified and then the overlay image is "subtracted" from
251 it. An opacity value greater than unity means the overlay image is
252 intensified and the underlay image subtracted from it. In either
253 case, \fBpamcomp\fP clips the resulting color component intensities
254 so they are nonnegative and don't exceed the output image's maxval.
255 .sp
256 This may seem like a strange thing to do, but it has uses. You can use it
257 to brighten or darken or saturate or desaturate areas of the underlay image.
258 See
259 .BR " this description" (1)\c
260 \& of the technique.
261 .sp
262 This option was added in Netpbm 10.6 (July 2002). Before Netpbm 10.15
263 (April 2003), values less than zero or greater than unity were not allowed.
264
265 .TP
266 \fB-mixtransparency\fP
267 This option controls what \fBpamcomp\fP does where both the underlying and
268 overlay image are non-opaque.
269 .sp
270 By default, the output image has the same transparency as the underlying
271 image and the transparency of the underlying image has no effect on the
272 composition of color.
273 .sp
274 But with this option, \fBpamcomp\fP composes the image according to a
275 plastic transparency metaphor: the underlying and overlay images are plastic
276 slides. The output image is the slide you get when you stack up those two
277 slides. So the transparency of the output is a combination of the
278 transparency of the inputs and the transparency of the underlying image
279 affects the underlying image's contribution to the output image's color.
280 .sp
281 Unlike the metaphorical slide, a PAM pixel has a color even where it is
282 completely transparent, so \fBpamcomp\fP departs from the metaphor in that
283 case and makes the output color identical to the underlying image.
284 .sp
285 This option was new in Netpbm 10.56 (September 2011). Before that, the
286 output is always opaque and the \fBpamcomp\fP ignores the transparency of the
287 underlying image.
288
289 .TP
290 \fB-linear\fP
291 This option indicates that the inputs are not true Netpbm images but
292 rather a light-intesity-proportional variation. This is relevant only when
293 you mix pixels, using the \fB-opacity\fP option or a transparency mask
294 (the \fB-alpha\fP option).
295 .sp
296 The transparency mask and \fB-opacity\fP values indicate a fraction of
297 the light intensity of a pixel. But the PNM and PNM-equivalent PAM
298 image formats represent intensities with gamma-adjusted numbers that
299 are not linearly proportional to intensity. So \fBpamcomp\fP, by
300 default, performs a calculation on each sample read from its input and
301 each sample written to its output to convert between these
302 gamma-adjusted numbers and internal intensity-proportional numbers.
303 .sp
304 Sometimes you are not working with true PNM or PAM images, but
305 rather a variation in which the sample values are in fact directly
306 proportional to intensity. If so, use the \fB-linear\fP option to
307 tell \fBpamcomp\fP this. \fBpamcomp\fP then will skip the
308 conversions.
309 .sp
310 The conversion takes time. And the difference between
311 intensity-proportional values and gamma-adjusted values may be small
312 enough that you would barely see a difference in the result if you
313 just pretended that the gamma-adjusted values were in fact
314 intensity-proportional. So just to save time, at the expense of some
315 image quality, you can specify \fB-linear\fP even when you have true
316 PPM input and expect true PPM output.
317 .sp
318 For the first 13 years of Netpbm's life, until Netpbm 10.20
319 (January 2004), \fBpamcomp\fP's predecessor \fBpnmcomp\fP always
320 treated the PPM samples as intensity-proportional even though they
321 were not, and drew few complaints. So using \fB-linear\fP as a lie
322 is a reasonable thing to do if speed is important to you.
323 .sp
324 Another technique to consider is to convert your PNM image to the
325 linear variation with \fBpnmgamma\fP, run \fBpamcomp\fP on it and
326 other transformations that like linear PNM, and then convert it back
327 to true PNM with \fBpnmgamma -ungamma\fP. \fBpnmgamma\fP is often
328 faster than \fBpamcomp\fP in doing the conversion.
329
330
331
332
333 .UN seealso
334 .SH SEE ALSO
335 .PP
336 .BR "pammixmulti.html" (1)\c
337 \& mixes together
338 two or more images of the same size, in various ways.
339 .PP
340 .BR "ppmmix" (1)\c
341 \& and
342 .BR "pnmpaste" (1)\c
343 \& are simpler, less general
344 versions of the same tool.
345 .PP
346 .BR "ppmcolormask" (1)\c
347 \& and
348 .BR "pbmmask" (1)\c
349 \&, and
350 .BR "\fBpambackground\fP" (1)\c
351 \& can help with
352 generating a transparency mask.
353 .PP
354 .BR "pnmcomp" (1)\c
355 \& is an older program that
356 runs faster, but has less function.
357 .PP
358 .BR "pnm" (1)\c
359 \&
360
361
362 .UN history
363 .SH HISTORY
364 .PP
365 \fBpamcomp\fP was new in Netpbm 10.21 (March 2004). Its predecessor,
366 \fBpnmcomp\fP, was one of the first programs added to Netpbm when the
367 project went global in 1993.
368
369
370 .UN author
371 .SH AUTHOR
372
373 Copyright (C) 1992 by David Koblas (\[email protected]\fP).
374 .SH DOCUMENT SOURCE
375 This manual page was generated by the Netpbm tool 'makeman' from HTML
376 source. The master documentation is at
377 .IP
378 .B http://netpbm.sourceforge.net/doc/pamcomp.html
379 .PP