1Pamcomp User Manual(0)                                  Pamcomp User Manual(0)
2
3
4

NAME

6       pamcomp - composite (overlay) two Netpbm images together
7
8

SYNOPSIS

10       pamcomp
11
12       [-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
17       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
22

DESCRIPTION

24       This program is part of Netpbm(1).
25
26       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
31       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
35       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
49       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
54       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
61       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
70       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
74       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
79       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
84       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
89       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
96        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
103

OPTIONS

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
111              The -xoff option modifies this position.
112
113              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
119              The default is left.
120
121
122       -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
128              The -yoff option modifies this position.
129
130              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
136              The default is top.
137
138
139       -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
146              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
150              Before Netpbm 10.10 (October 2002), -xoff was mutually exclusive
151              with -align and always measured from the left edge.
152
153
154       -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
161              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
165              Before Netpbm 10.10 (October 2002), -xoff was mutually exclusive
166              with -valign and always measured from the top edge.
167
168
169       -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
175              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
180
181       -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
186
187       -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
195              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
201              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
212              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
217              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
221
222       -mixtransparency
223              This option controls what pamcomp does where both the underlying
224              and overlay image are non-opaque.
225
226              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
230              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
238              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
243              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
247
248       -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
254              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
263              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
269              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
277              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
283              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
289
290
291
292

SEE ALSO

294       pammixmulti.html(1) mixes together two or more images of the same size,
295       in various ways.
296
297       ppmmix(1) and pnmpaste(1) are simpler, less  general  versions  of  the
298       same tool.
299
300       ppmcolormask(1) and pbmmask(1), and pambackground(1) can help with gen‐
301       erating a transparency mask.
302
303       pnmcomp(1) is an older program that runs faster, but has less function.
304
305       pnm(1)
306
307
308

HISTORY

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
314
315

AUTHOR

317       Copyright (C) 1992 by David Koblas (koblas@mips.com).
318

DOCUMENT SOURCE

320       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
321       source.  The master documentation is at
322
323              http://netpbm.sourceforge.net/doc/pamcomp.html
324
325netpbm documentation            13 August 2011          Pamcomp User Manual(0)
Impressum