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}] [-valign={top|mid‐
13 dle|bottom| above|below}] [-xoff=X] [-yoff=Y] [-alpha=alpha-pgmfile]
14 [-invert] [-opacity=opacity] [-linear] overlay_file [underlying_file
15 [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 an alpha mask, which means it determines the level of
37 transparency of each point in the overlay image. The alpha mask must
38 have the same dimensions as the overlay image. In places where the
39 alpha mask defines the overlay image to be opaque, the composite output
40 contains only the contents of the overlay image; the underlying image
41 is totally blocked out. In places where the alpha mask defines the
42 overlay image to be transparent, the composite output contains none of
43 the overlay image; the underlying image shows through completely. In
44 places where the alpha mask shows a value in between opaque and trans‐
45 parent (translucence), the composite image contains a mixture of the
46 overlay image and the underlying image and the level of translucence
47 determines how much of each.
48 The alpha mask is a PGM file in which a white pixel represents opaque‐
50 ness and a black pixel transparency. Anything in between is translu‐
51 cent. (Like any Netpbm program, pamcomp will see a PBM file as if it
52 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 alpha mask
57 described above. If you supply both an overlay image that has trans‐
58 parency information and an alpha mask, pamcomp multiplies the two opac‐
59 ities 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 alpha masks in order to have a non-opaque
64 overlay. Some Netpbm programs that convert from image formats such as
65 PNG that contain transparency information are not able to create
66 RGB_ALPHA or GRAYSCALE_ALPHA PAM output, so you have to use the old
67 method -- extract the transparency information from the original into a
68 separate alpha 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 To specify where on the underlying image to place the overlay image,
75 use the -align, -valign, -xoff, and -yoff options. Without these
76 options, the default horizontal position is flush left and the default
77 vertical position is flush top.
78 The overlay image, in the position you specify, need not fit entirely
80 within the underlying image. pamcomp uses only the parts of the over‐
81 lay image that appear above the underlying image. It is possible to
82 specify positioning such that none of the overlay image is over the
83 underlying image -- i.e. the overlay is out of frame. If you do that,
84 pamcomp issues a warning.
85 The overlay and underlying images may be of different formats (e.g.
87 overlaying a PBM text image over a full color PPM image) and have dif‐
88 ferent maxvals. The output image has the more general of the two input
89 formats and a maxval that is the least common multiple the two maxvals
90 (or the maximum maxval allowable by the format, if the LCM is more than
91 that).
92
95 -align=alignment
96 This option selects the basic horizontal position of the overlay
97 image with respect to the underlying image, in syntax reminis‐
98 cent of HTML. left means flush left, center means centered, and
99 right means flush right.
100 The -xoff option modifies this position.
102 beyondleft means just out of frame to the left -- the right edge
104 of the overlay is flush with the left edge of the underlying
105 image. beyondright means just out of frame to the right. These
106 alignments are useful only if you add a -xoff option. These
107 two values were added in Netpbm 10.10 (October 2002).
108 The default is left.
110 -valign=alignment
113 This option selects the basic vertical position of the overlay
114 image with respect to the underlying image, in syntax reminis‐
115 cent of HTML. top means flush top, middle means centered, and
116 bottom means flush bottom.
117 The -yoff option modifies this position.
119 above means just out of frame to the top -- the bottom edge of
121 the overlay is flush with the top edge of the underlying image.
122 below means just out of frame to the bottom. These alignments
123 are useful only if you add a -yoff option. These two values
124 were added in Netpbm 10.10 (October 2002).
125 The default is top.
127 -xoff=x
130 This option modifies the horizontal positioning of the overlay
131 image with respect to the underlying image as selected by the
132 -align option. pamcomp shifts the overlay image from that basic
133 position x pixels to the right. x can be negative to indicate
134 shifting to the left.
135 The overlay need not fit entirely (or at all) on the underlying
137 image. pamcomp uses only the parts that lie over the underlying
138 image.
139 Before Netpbm 10.10 (October 2002), -xoff was mutually exclusive
141 with -align and always measured from the left edge.
142 -yoff=y
145 This option modifies the vertical positioning of the overlay
146 image with respect to the underlying image as selected by the
147 -valign option. pamcomp shifts the overlay image from that
148 basic position y pixels downward. y can be negative to indicate
149 shifting upward.
150 The overlay need not fit entirely (or at all) on the underlying
152 image. pamcomp uses only the parts that lie over the underlying
153 image.
154 Before Netpbm 10.10 (October 2002), -xoff was mutually exclusive
156 with -valign and always measured from the top edge.
157 -alpha=alpha-pgmfile
160 This option names a file that contains the alpha mask. If you
161 don't specify this option, there is no alpha mask, which is
162 equivalent to having an alpha mask specify total opaqueness
163 everywhere.
164 You can specify - as the value of this option and the alpha mask
166 will come from Standard Input. If you do this, don't specify
167 Standard Input as the source of any other input image.
168 -invert
171 This option inverts the sense of the values in the alpha mask,
172 which effectively switches the roles of the overlay image and
173 the underlying image in places where the two intersect.
174 -opacity=opacity
177 This option tells how opaque the overlay image is to be, i.e.
178 how much of the composite image should be from the overlay
179 image, as opposed to the underlying image. opacity is a float‐
180 ing point number, with 1.0 meaning the overlay image is totally
181 opaque and 0.0 meaning it is totally transparent. The default
182 is 1.0.
183 If you specify an alpha mask (the -alpha option), pamcomp uses
185 the product of the opacity indicated by the alpha mask (as modi‐
186 fied by the -invert option, as a fraction, and this opacity
187 value. The -invert option does not apply to this opacity value.
188 As a simple opacity value, the value makes sense only if it is
190 between 0 and 1, inclusive. However, pamcomp accepts all values
191 and performs the same arithmetic computation using whatever
192 value you provide. An opacity value less than zero means the
193 underlay image is intensified and then the overlay image is
194 "subtracted" from it. An opacity value greater than unity means
195 the overlay image is intensified and the underlaying image sub‐
196 tracted from it. In either case, pamcomp clips the resulting
197 color component intensities so they are nonnegative and don't
198 exceed the output image's maxval.
199 This may seem like a strange thing to do, but it has uses. You
201 can use it to brighten or darken or saturate or desaturate areas
202 of the underlaying image. See this description (1) of the
203 technique.
204 This option was added in Netpbm 10.6 (July 2002). Before Netpbm
206 10.15 (April 2003), values less than zero or greater than unity
207 were not allowed.
208 -linear
211 This option indicates that the inputs are not true Netpbm images
212 but rather a non-gamma-adjusted variation. This is relevant
213 only when you mix pixels, using the -opacity option or an alpha
214 mask (the -alpha option).
215 The alpha mask and -opacity values indicate a fraction of the
217 light intensity of a pixel. But the PNM and PNM-equivalent PAM
218 image formats represent intensities with gamma-adjusted numbers
219 that are not linearly proportional to intensity. So pamcomp, by
220 default, performs a calculation on each sample read from its
221 input and each sample written to its output to convert between
222 these gamma-adjusted numbers and internal intensity-proportional
223 numbers.
224 Sometimes you are not working with true PNM or PAM images, but
226 rather a variation in which the sample values are in fact
227 directly proportional to intensity. If so, use the -linear
228 option to tell pamcomp this. pamcomp then will skip the conver‐
229 sions.
230 The conversion takes time. And the difference between inten‐
232 sity-proportional values and gamma-adjusted values may be small
233 enough that you would barely see a difference in the result if
234 you just pretended that the gamma-adjusted values were in fact
235 intensity-proportional. So just to save time, at the expense of
236 some image quality, you can specify -linear even when you have
237 true PPM input and expect true PPM output.
238 For the first 13 years of Netpbm's life, until Netpbm 10.20
240 (January 2004), pamcomp's predecessor pnmcomp always treated the
241 PPM samples as intensity-proportional even though they were not,
242 and drew few complaints. So using -linear as a lie is a reason‐
243 able thing to do if speed is important to you.
244 Another technique to consider is to convert your PNM image to
246 the linear variation with pnmgamma, run pamcomp on it and other
247 transformations that like linear PNM, and then convert it back
248 to true PNM with pnmgamma -ungamma. pnmgamma is often faster
249 than pamcomp in doing the conversion.
250
256 ppmmix(1)and pnmpaste(1)aresimpler,lessgeneral versions of the same
257 tool.
258 ppmcolormask(1)and pbmmask(1),and pambackground(1)canhelpwith generat‐
260 ing an alpha mask.
261 pnmcomp(1)isanolderprogramthat runs faster, but has less function.
263 pnm(1)
265
269 pamcomp was new in Netpbm 10.21 (March 2004). Its predecessor, pnm‐
270 comp, was one of the first programs added to Netpbm when the project
271 went global in 1993.
272
276 Copyright (C) 1992 by David Koblas (koblas@mips.com).
277netpbm documentation 17 July 2004 Pamcomp User Manual(0)