1Pamcomp User Manual(0) Pamcomp User Manual(0)
2
6 pamcomp - composite (overlay) two Netpbm images together
7
10 pamcomp
11 [-align={left | center | right | beyondleft | beyondright}]
13 [-valign={top | middle | bottom| above | below}] [-xoff=X] [-yoff=Y]
14 [-alpha=alpha-pgmfile] [-invert] [-opacity=opacity] [-mixtransparency]
15 [-linear] overlay_file [underlying_file [output_file]]
16 Minimum unique abbreviation of option is acceptable. You may use dou‐
18 ble hyphens instead of single hyphen to denote options. You may use
19 white space in place of the equals sign to separate an option name from
20 its value.
21
24 This program is part of Netpbm(1).
25 pamcomp reads two images and produces a composite image with one of the
27 images overlayed on top of the other, possible translucently. The
28 images need not be the same size. The input and outputs are Netpbm
29 format image files.
30 In its simplest use, pamcomp simply places the image in the file over‐
32 lay_file on top of the image in the file underlying_file, blocking out
33 the part of underlying_file beneath it.
34 If you add the -alpha option, then pamcomp uses the image in file
36 alpha-pgmfile as a transparency mask, which means it determines the
37 level of transparency of each point in the overlay image. The trans‐
38 parency mask must have the same dimensions as the overlay image. In
39 places where the transparency mask defines the overlay image to be
40 opaque, the composite output contains only the contents of the overlay
41 image; the underlying image is totally blocked out. In places where
42 the transparency mask defines the overlay image to be transparent, the
43 composite output contains none of the overlay image; the underlying
44 image shows through completely. In places where the transparency mask
45 shows a value in between opaque and transparent (translucence), the
46 composite image contains a mixture of the overlay image and the under‐
47 lying image and the level of translucence determines how much of each.
48 The transparency mask is a PGM file in which a white pixel represents
50 opaqueness and a black pixel transparency. Anything in between is
51 translucent. (Like any Netpbm program, pamcomp will see a PBM file as
52 if it is PGM).
53 If the overlay image is a PAM image of tuple type RGB_ALPHA or
55 GRAYSCALE_ALPHA, then the overlay image contains transparency informa‐
56 tion itself and pamcomp uses it the same way as the transparency mask
57 described above. If you supply both an overlay image that has trans‐
58 parency information and a transparency mask, pamcomp multiplies the two
59 opacities to get the opacity of the overlay pixel.
60 Before Netpbm 10.25 (October 2004), pamcomp did not recognize the
62 transparency information in a PAM image -- it just ignored it. So peo‐
63 ple had to make appropriate transparency masks in order to have a non-
64 opaque overlay. Some Netpbm programs that convert from image formats
65 that contain transparency information are not able to create RGB_ALPHA
66 or GRAYSCALE_ALPHA PAM output, so you have to use the old method --
67 extract the transparency information from the original into a separate
68 transparency mask and use that as input to pamcomp.
69 The output image is always of the same dimensions as the underlying
71 image. pamcomp uses only parts of the overlay image that fit within
72 the underlying image.
73 The output image is a PAM image. Its tuples are color, grayscale, or
75 black and white, whichever is the "highest" format between the two
76 input images. The maxval of the output is the least common multiple of
77 the maxvals of the input, up to the maximum possible PAM maxval, 65535.
78 The output has an opacity channel if and only if the underlying image
80 does, and then the opacities are as described under the -mixtrans‐
81 parency option. Before Netpbm 10.56 (September 2011), the output never
82 has an opacity channel.
83 To specify where on the underlying image to place the overlay image,
85 use the -align, -valign, -xoff, and -yoff options. Without these
86 options, the default horizontal position is flush left and the default
87 vertical position is flush top.
88 The overlay image, in the position you specify, need not fit entirely
90 within the underlying image. pamcomp uses only the parts of the over‐
91 lay image that appear above the underlying image. It is possible to
92 specify positioning such that none of the overlay image is over the
93 underlying image -- i.e. the overlay is out of frame. If you do that,
94 pamcomp issues a warning.
95 The overlay and underlying images may be of different formats (e.g.
97 overlaying a PBM text image over a full color PPM image) and have dif‐
98 ferent maxvals. The output image has the more general of the two input
99 formats and a maxval that is the least common multiple the two maxvals
100 (or the maximum maxval allowable by the format, if the LCM is more than
101 that).
102
105 -align=alignment
106 This option selects the basic horizontal position of the overlay
107 image with respect to the underlying image, in syntax reminis‐
108 cent of HTML. left means flush left, center means centered, and
109 right means flush right.
110 The -xoff option modifies this position.
112 beyondleft means just out of frame to the left -- the right edge
114 of the overlay is flush with the left edge of the underlying
115 image. beyondright means just out of frame to the right. These
116 alignments are useful only if you add a -xoff option. These
117 two values were added in Netpbm 10.10 (October 2002).
118 The default is left.
120 -valign=alignment
123 This option selects the basic vertical position of the overlay
124 image with respect to the underlying image, in syntax reminis‐
125 cent of HTML. top means flush top, middle means centered, and
126 bottom means flush bottom.
127 The -yoff option modifies this position.
129 above means just out of frame to the top -- the bottom edge of
131 the overlay is flush with the top edge of the underlying image.
132 below means just out of frame to the bottom. These alignments
133 are useful only if you add a -yoff option. These two values
134 were added in Netpbm 10.10 (October 2002).
135 The default is top.
137 -xoff=x
140 This option modifies the horizontal positioning of the overlay
141 image with respect to the underlying image as selected by the
142 -align option. pamcomp shifts the overlay image from that basic
143 position x pixels to the right. x can be negative to indicate
144 shifting to the left.
145 The overlay need not fit entirely (or at all) on the underlying
147 image. pamcomp uses only the parts that lie over the underlying
148 image.
149 Before Netpbm 10.10 (October 2002), -xoff was mutually exclusive
151 with -align and always measured from the left edge.
152 -yoff=y
155 This option modifies the vertical positioning of the overlay
156 image with respect to the underlying image as selected by the
157 -valign option. pamcomp shifts the overlay image from that
158 basic position y pixels downward. y can be negative to indicate
159 shifting upward.
160 The overlay need not fit entirely (or at all) on the underlying
162 image. pamcomp uses only the parts that lie over the underlying
163 image.
164 Before Netpbm 10.10 (October 2002), -xoff was mutually exclusive
166 with -valign and always measured from the top edge.
167 -alpha=alpha-pgmfile
170 This option names a file that contains the transparency mask.
171 If you don't specify this option, there is no transparency mask,
172 which is equivalent to having a transparency mask specify total
173 opaqueness everywhere.
174 You can specify - as the value of this option and the trans‐
176 parency mask will come from Standard Input. If you do this,
177 don't specify Standard Input as the source of any other input
178 image.
179 -invert
182 This option inverts the sense of the values in the transparency
183 mask, which effectively switches the roles of the overlay image
184 and the underlying image in places where the two intersect.
185 -opacity=opacity
188 This option tells how opaque the overlay image is to be, i.e.
189 how much of the composite image should be from the overlay
190 image, as opposed to the underlying image. opacity is a float‐
191 ing point number, with 1.0 meaning the overlay image is totally
192 opaque and 0.0 meaning it is totally transparent. The default
193 is 1.0.
194 If you specify a transparency mask (the -alpha option), pamcomp
196 uses the product of the opacity indicated by the transparency
197 mask (as modified by the -invert option, as a fraction, and this
198 opacity value. The -invert option does not apply to this opac‐
199 ity value.
200 As a simple opacity value, the value makes sense only if it is
202 between 0 and 1, inclusive. However, pamcomp accepts all values
203 and performs the same arithmetic computation using whatever
204 value you provide. An opacity value less than zero means the
205 underlay image is intensified and then the overlay image is
206 "subtracted" from it. An opacity value greater than unity means
207 the overlay image is intensified and the underlay image sub‐
208 tracted from it. In either case, pamcomp clips the resulting
209 color component intensities so they are nonnegative and don't
210 exceed the output image's maxval.
211 This may seem like a strange thing to do, but it has uses. You
213 can use it to brighten or darken or saturate or desaturate areas
214 of the underlay image. See this description(1) of the tech‐
215 nique.
216 This option was added in Netpbm 10.6 (July 2002). Before Netpbm
218 10.15 (April 2003), values less than zero or greater than unity
219 were not allowed.
220 -mixtransparency
223 This option controls what pamcomp does where both the underlying
224 and overlay image are non-opaque.
225 By default, the output image has the same transparency as the
227 underlying image and the transparency of the underlying image
228 has no effect on the composition of color.
229 But with this option, pamcomp composes the image according to a
231 plastic transparency metaphor: the underlying and overlay images
232 are plastic slides. The output image is the slide you get when
233 you stack up those two slides. So the transparency of the out‐
234 put is a combination of the transparency of the inputs and the
235 transparency of the underlying image affects the underlying
236 image's contribution to the output image's color.
237 Unlike the metaphorical slide, a PAM pixel has a color even
239 where it is completely transparent, so pamcomp departs from the
240 metaphor in that case and makes the output color identical to
241 the underlying image.
242 This option was new in Netpbm 10.56 (September 2011). Before
244 that, the output is always opaque and the pamcomp ignores the
245 transparency of the underlying image.
246 -linear
249 This option indicates that the inputs are not true Netpbm images
250 but rather a light-intesity-proportional variation. This is
251 relevant only when you mix pixels, using the -opacity option or
252 a transparency mask (the -alpha option).
253 The transparency mask and -opacity values indicate a fraction of
255 the light intensity of a pixel. But the PNM and PNM-equivalent
256 PAM image formats represent intensities with gamma-adjusted num‐
257 bers that are not linearly proportional to intensity. So pam‐
258 comp, by default, performs a calculation on each sample read
259 from its input and each sample written to its output to convert
260 between these gamma-adjusted numbers and internal intensity-pro‐
261 portional numbers.
262 Sometimes you are not working with true PNM or PAM images, but
264 rather a variation in which the sample values are in fact
265 directly proportional to intensity. If so, use the -linear
266 option to tell pamcomp this. pamcomp then will skip the conver‐
267 sions.
268 The conversion takes time. And the difference between inten‐
270 sity-proportional values and gamma-adjusted values may be small
271 enough that you would barely see a difference in the result if
272 you just pretended that the gamma-adjusted values were in fact
273 intensity-proportional. So just to save time, at the expense of
274 some image quality, you can specify -linear even when you have
275 true PPM input and expect true PPM output.
276 For the first 13 years of Netpbm's life, until Netpbm 10.20
278 (January 2004), pamcomp's predecessor pnmcomp always treated the
279 PPM samples as intensity-proportional even though they were not,
280 and drew few complaints. So using -linear as a lie is a reason‐
281 able thing to do if speed is important to you.
282 Another technique to consider is to convert your PNM image to
284 the linear variation with pnmgamma, run pamcomp on it and other
285 transformations that like linear PNM, and then convert it back
286 to true PNM with pnmgamma -ungamma. pnmgamma is often faster
287 than pamcomp in doing the conversion.
288
294 pammixmulti.html(1) mixes together two or more images of the same size,
295 in various ways.
296 ppmmix(1) and pnmpaste(1) are simpler, less general versions of the
298 same tool.
299 ppmcolormask(1) and pbmmask(1), and pambackground(1) can help with gen‐
301 erating a transparency mask.
302 pnmcomp(1) is an older program that runs faster, but has less function.
304 pnm(1)
306
310 pamcomp was new in Netpbm 10.21 (March 2004). Its predecessor, pnm‐
311 comp, was one of the first programs added to Netpbm when the project
312 went global in 1993.
313
317 Copyright (C) 1992 by David Koblas (koblas@mips.com).
318
320 This manual page was generated by the Netpbm tool 'makeman' from HTML
321 source. The master documentation is at
322 http://netpbm.sourceforge.net/doc/pamcomp.html
324netpbm documentation 13 August 2011 Pamcomp User Manual(0)