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
104

ARGUMENTS

106       The overlay_file argument is the name of the file containing the
107         overly image, while underlying_file is the name of the file
108         containing the underlying image.  For either, you may specify '-'
109         to indicate Standard Input, and underlying file defaults to Standard
110         Input.  Make sure you  aren't  specifying  (or  defaulting)  Standard
111       Input as
112         both.
113
114       Note  that there may be a third input file, identified by an -alphafile
115       option.
116
117       The output_file argument is the name of the file to which
118         pamcomp writes the output, creating or truncating it first.  You may
119         specify '-' to indicate Standard Output, in which
120         case pamcomp does not truncate it.  Note that pamcomp is
121         unusual among Netpbm programs, as a historical accident, in having an
122       output
123         file  argument;  Netpbm  programs  normally  write to Standard Output
124       only.
125
126
127

OPTIONS

129       In addition to the options common to all programs  based  on  libnetpbm
130       (most notably -quiet, see
131        Common  Options  ⟨index.html#commonoptions⟩  ), pamcomp recognizes the
132       following command line options:
133
134
135
136       -align=alignment
137              This option selects the basic horizontal position of the overlay
138              image  with  respect to the underlying image, in syntax reminis‐
139              cent of HTML.  left means flush left, center means centered, and
140              right means flush right.
141
142              The -xoff option modifies this position.
143
144              beyondleft means just out of frame to the left -- the right edge
145              of the overlay is flush with the left  edge  of  the  underlying
146              image.  beyondright means just out of frame to the right.  These
147              alignments are useful only if you add a -xoff  option.     These
148              two values were added in Netpbm 10.10 (October 2002).
149
150              The default is left.
151
152
153       -valign=alignment
154              This  option  selects the basic vertical position of the overlay
155              image with respect to the underlying image, in  syntax  reminis‐
156              cent  of  HTML.  top means flush top, middle means centered, and
157              bottom means flush bottom.
158
159              The -yoff option modifies this position.
160
161              above means just out of frame to the top -- the bottom  edge  of
162              the  overlay is flush with the top edge of the underlying image.
163              below means just out of frame to the bottom.   These  alignments
164              are  useful  only  if  you add a -yoff option.  These two values
165              were added in Netpbm 10.10 (October 2002).
166
167              The default is top.
168
169
170       -xoff=x
171              This option modifies the horizontal positioning of  the  overlay
172              image  with  respect  to the underlying image as selected by the
173              -align option.  pamcomp shifts the overlay image from that basic
174              position  x  pixels to the right.  x can be negative to indicate
175              shifting to the left.
176
177              The overlay need not fit entirely (or at all) on the  underlying
178              image.  pamcomp uses only the parts that lie over the underlying
179              image.
180
181              Before Netpbm 10.10 (October 2002), -xoff was mutually exclusive
182              with -align and always measured from the left edge.
183
184
185       -yoff=y
186              This  option  modifies  the  vertical positioning of the overlay
187              image with respect to the underlying image as  selected  by  the
188              -valign  option.   pamcomp  shifts  the  overlay image from that
189              basic position y pixels downward.  y can be negative to indicate
190              shifting upward.
191
192              The  overlay need not fit entirely (or at all) on the underlying
193              image.  pamcomp uses only the parts that lie over the underlying
194              image.
195
196              Before Netpbm 10.10 (October 2002), -xoff was mutually exclusive
197              with -valign and always measured from the top edge.
198
199
200       -alpha=alpha-pgmfile
201              This option names a file that contains  the  transparency  mask.
202              If you don't specify this option, there is no transparency mask,
203              which is equivalent to having a transparency mask specify  total
204              opaqueness everywhere.
205
206              You  can  specify  -  as the value of this option and the trans‐
207              parency mask will come from Standard Input.   If  you  do  this,
208              don't  specify  Standard  Input as the source of any other input
209              image.
210
211
212       -invert
213              This option inverts the sense of the values in the  transparency
214              mask,  which effectively switches the roles of the overlay image
215              and the underlying image in places where the two intersect.
216
217
218       -opacity=opacity
219              This option tells how opaque the overlay image is  to  be,  i.e.
220              how  much  of  the  composite  image  should be from the overlay
221              image, as opposed to the underlying image.  opacity is a  float‐
222              ing  point number, with 1.0 meaning the overlay image is totally
223              opaque and 0.0 meaning it is totally transparent.   The  default
224              is 1.0.
225
226              If  you specify a transparency mask (the -alpha option), pamcomp
227              uses the product of the opacity indicated  by  the  transparency
228              mask (as modified by the -invert option, as a fraction, and this
229              opacity value.  The -invert option does not apply to this  opac‐
230              ity value.
231
232              As  a  simple opacity value, the value makes sense only if it is
233              between 0 and 1, inclusive.  However, pamcomp accepts all values
234              and  performs  the  same  arithmetic  computation using whatever
235              value you provide.  An opacity value less than  zero  means  the
236              underlay  image  is  intensified  and  then the overlay image is
237              "subtracted" from it.  An opacity value greater than unity means
238              the  overlay  image  is  intensified and the underlay image sub‐
239              tracted from it.  In either case, pamcomp  clips  the  resulting
240              color  component  intensities  so they are nonnegative and don't
241              exceed the output image's maxval.
242
243              This may seem like a strange thing to do, but it has uses.   You
244              can use it to brighten or darken or saturate or desaturate areas
245              of the underlay image.  See  this description(1)  of  the  tech‐
246              nique.
247
248              This option was added in Netpbm 10.6 (July 2002).  Before Netpbm
249              10.15 (April 2003), values less than zero or greater than  unity
250              were not allowed.
251
252
253       -mixtransparency
254              This option controls what pamcomp does where both the underlying
255              and overlay image are non-opaque.
256
257              By default, the output image has the same  transparency  as  the
258              underlying  image  and  the transparency of the underlying image
259              has no effect on the composition of color.
260
261              But with this option, pamcomp composes the image according to  a
262              plastic transparency metaphor: the underlying and overlay images
263              are plastic slides.  The output image is the slide you get  when
264              you  stack up those two slides.  So the transparency of the out‐
265              put is a combination of the transparency of the inputs  and  the
266              transparency  of  the  underlying  image  affects the underlying
267              image's contribution to the output image's color.
268
269              Unlike the metaphorical slide, a PAM  pixel  has  a  color  even
270              where  it is completely transparent, so pamcomp departs from the
271              metaphor in that case and makes the output  color  identical  to
272              the underlying image.
273
274              This  option  was  new in Netpbm 10.56 (September 2011).  Before
275              that, the output is always opaque and the  pamcomp  ignores  the
276              transparency of the underlying image.
277
278
279       -linear
280              This option indicates that the inputs are not true Netpbm images
281              but rather a  light-intesity-proportional  variation.   This  is
282              relevant  only when you mix pixels, using the -opacity option or
283              a transparency mask (the -alpha option).
284
285              The transparency mask and -opacity values indicate a fraction of
286              the  light intensity of a pixel.  But the PNM and PNM-equivalent
287              PAM image formats represent intensities with gamma-adjusted num‐
288              bers  that  are not linearly proportional to intensity.  So pam‐
289              comp, by default, performs a calculation  on  each  sample  read
290              from  its input and each sample written to its output to convert
291              between these gamma-adjusted numbers and internal intensity-pro‐
292              portional numbers.
293
294              Sometimes  you  are not working with true PNM or PAM images, but
295              rather a variation in  which  the  sample  values  are  in  fact
296              directly  proportional  to  intensity.   If  so, use the -linear
297              option to tell pamcomp this.  pamcomp then will skip the conver‐
298              sions.
299
300              The  conversion  takes  time.  And the difference between inten‐
301              sity-proportional values and gamma-adjusted values may be  small
302              enough  that  you would barely see a difference in the result if
303              you just pretended that the gamma-adjusted values were  in  fact
304              intensity-proportional.  So just to save time, at the expense of
305              some image quality, you can specify -linear even when  you  have
306              true PPM input and expect true PPM output.
307
308              For  the  first  13  years  of Netpbm's life, until Netpbm 10.20
309              (January 2004), pamcomp's predecessor pnmcomp always treated the
310              PPM samples as intensity-proportional even though they were not,
311              and drew few complaints.  So using -linear as a lie is a reason‐
312              able thing to do if speed is important to you.
313
314              Another  technique  to  consider is to convert your PNM image to
315              the linear variation with pnmgamma, run pamcomp on it and  other
316              transformations  that  like linear PNM, and then convert it back
317              to true PNM with pnmgamma -ungamma.  pnmgamma  is  often  faster
318              than pamcomp in doing the conversion.
319
320
321
322
323

SEE ALSO

325       pammixmulti.html(1) mixes together two or more images of the same size,
326       in various ways.
327
328       ppmmix(1) and pnmpaste(1) are simpler, less  general  versions  of  the
329       same tool.
330
331       ppmcolormask(1) and pbmmask(1), and pambackground(1) can help with gen‐
332       erating a transparency mask.
333
334       pnmcomp(1) is an older program that runs faster, but has less function.
335
336       pnm(1)
337
338
339

HISTORY

341       pamcomp was new in Netpbm 10.21 (March 2004).   Its  predecessor,  pnm‐
342       comp,  was  one  of the first programs added to Netpbm when the project
343       went global in 1993.
344
345
346

AUTHOR

348       Copyright (C) 1992 by David Koblas (koblas@mips.com).
349

DOCUMENT SOURCE

351       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
352       source.  The master documentation is at
353
354              http://netpbm.sourceforge.net/doc/pamcomp.html
355
356netpbm documentation            13 August 2011          Pamcomp User Manual(0)
Impressum