Pamcomp User Manual(0)					Pamcomp User Manual(0)



NAME
       pamcomp - composite (overlay) two Netpbm images together


SYNOPSIS
       pamcomp

       [-align={left|center|right| beyondleft|beyondright}] [-valign={top|mid-
       dle|bottom| above|below}]  [-xoff=X]  [-yoff=Y]	[-alpha=alpha-pgmfile]
       [-invert]  [-opacity=opacity]  [-linear]	 overlay_file [underlying_file
       [output_file]]

       Minimum unique abbreviation of option is acceptable.  You may use  dou-
       ble  hyphens  instead  of single hyphen to denote options.  You may use
       white space in place of the equals sign to separate an option name from
       its value.


DESCRIPTION
       This program is part of Netpbm(1).

       pamcomp reads two images and produces a composite image with one of the
       images overlayed on top of  the	other,	possible  translucently.   The
       images  need  not  be  the same size.  The input and outputs are Netpbm
       format image files.

       In its simplest use, pamcomp simply places the image in the file	 over-
       lay_file	 on top of the image in the file underlying_file, blocking out
       the part of underlying_file beneath it.

       If you add the -alpha option, then  pamcomp  uses  the  image  in  file
       alpha-pgmfile  as an alpha mask, which means it determines the level of
       transparency of each point in the overlay image.	 The alpha  mask  must
       have  the  same	dimensions  as the overlay image.  In places where the
       alpha mask defines the overlay image to be opaque, the composite output
       contains	 only  the contents of the overlay image; the underlying image
       is totally blocked out.	In places where the  alpha  mask  defines  the
       overlay	image to be transparent, the composite output contains none of
       the overlay image; the underlying image shows through  completely.   In
       places  where the alpha mask shows a value in between opaque and trans-
       parent (translucence), the composite image contains a  mixture  of  the
       overlay	image  and  the underlying image and the level of translucence
       determines how much of each.

       The alpha mask is a PGM file in which a white pixel represents  opaque-
       ness  and  a black pixel transparency.  Anything in between is translu-
       cent.  (Like any Netpbm program, pamcomp will see a PBM file as	if  it
       is PGM).

       If  the	overlay	 image	is  a  PAM  image  of  tuple type RGB_ALPHA or
       GRAYSCALE_ALPHA, then the overlay image contains transparency  informa-
       tion  itself  and  pamcomp  uses	 it  the  same	way  as the alpha mask
       described above.	 If you supply both an overlay image that  has	trans-
       parency information and an alpha mask, pamcomp multiplies the two opac-
       ities to get the opacity of the overlay pixel.

       Before Netpbm 10.25 (October  2004),  pamcomp  did  not	recognize  the
       transparency information in a PAM image -- it just ignored it.  So peo-
       ple had to make appropriate alpha masks in order to have	 a  non-opaque
       overlay.	  Some Netpbm programs that convert from image formats such as
       PNG that contain	 transparency  information  are	 not  able  to	create
       RGB_ALPHA  or  GRAYSCALE_ALPHA  PAM  output, so you have to use the old
       method -- extract the transparency information from the original into a
       separate alpha mask and use that as input to pamcomp.

       The  output  image  is  always of the same dimensions as the underlying
       image.  pamcomp uses only parts of the overlay image  that  fit	within
       the underlying image.

       To  specify  where  on the underlying image to place the overlay image,
       use the -align, -valign,	 -xoff,	 and  -yoff  options.	Without	 these
       options,	 the default horizontal position is flush left and the default
       vertical position is flush top.

       The overlay image, in the position you specify, need not	 fit  entirely
       within  the underlying image.  pamcomp uses only the parts of the over-
       lay image that appear above the underlying image.  It  is  possible  to
       specify	positioning  such  that	 none of the overlay image is over the
       underlying image -- i.e. the overlay is out of frame.  If you do	 that,
       pamcomp issues a warning.

	The  overlay  and  underlying images may be of different formats (e.g.
       overlaying a PBM text image over a full color PPM image) and have  dif-
       ferent maxvals.	The output image has the more general of the two input
       formats and a maxval that is the least common multiple the two  maxvals
       (or the maximum maxval allowable by the format, if the LCM is more than
       that).


OPTIONS
       -align=alignment
	      This option selects the basic horizontal position of the overlay
	      image  with  respect to the underlying image, in syntax reminis-
	      cent of HTML.  left means flush left, center means centered, and
	      right means flush right.

	      The -xoff option modifies this position.

	      beyondleft means just out of frame to the left -- the right edge
	      of the overlay is flush with the left  edge  of  the  underlying
	      image.  beyondright means just out of frame to the right.	 These
	      alignments are useful only if you add a -xoff  option.	 These
	      two values were added in Netpbm 10.10 (October 2002).

	      The default is left.


       -valign=alignment
	      This  option  selects the basic vertical position of the overlay
	      image with respect to the underlying image, in  syntax  reminis-
	      cent  of	HTML.  top means flush top, middle means centered, and
	      bottom means flush bottom.

	      The -yoff option modifies this position.

	      above means just out of frame to the top -- the bottom  edge  of
	      the  overlay is flush with the top edge of the underlying image.
	      below means just out of frame to the bottom.   These  alignments
	      are  useful  only	 if  you add a -yoff option.  These two values
	      were added in Netpbm 10.10 (October 2002).

	      The default is top.


       -xoff=x
	      This option modifies the horizontal positioning of  the  overlay
	      image  with  respect  to the underlying image as selected by the
	      -align option.  pamcomp shifts the overlay image from that basic
	      position	x  pixels to the right.	 x can be negative to indicate
	      shifting to the left.

	      The overlay need not fit entirely (or at all) on the  underlying
	      image.  pamcomp uses only the parts that lie over the underlying
	      image.

	      Before Netpbm 10.10 (October 2002), -xoff was mutually exclusive
	      with -align and always measured from the left edge.


       -yoff=y
	      This  option  modifies  the  vertical positioning of the overlay
	      image with respect to the underlying image as  selected  by  the
	      -valign  option.	 pamcomp  shifts  the  overlay image from that
	      basic position y pixels downward.	 y can be negative to indicate
	      shifting upward.

	      The  overlay need not fit entirely (or at all) on the underlying
	      image.  pamcomp uses only the parts that lie over the underlying
	      image.

	      Before Netpbm 10.10 (October 2002), -xoff was mutually exclusive
	      with -valign and always measured from the top edge.


       -alpha=alpha-pgmfile
	      This option names a file that contains the alpha mask.   If  you
	      don't  specify  this  option,  there  is no alpha mask, which is
	      equivalent to having an  alpha  mask  specify  total  opaqueness
	      everywhere.

	      You can specify - as the value of this option and the alpha mask
	      will come from Standard Input.  If you do	 this,	don't  specify
	      Standard Input as the source of any other input image.


       -invert
	      This  option  inverts the sense of the values in the alpha mask,
	      which effectively switches the roles of the  overlay  image  and
	      the underlying image in places where the two intersect.


       -opacity=opacity
	      This  option  tells  how opaque the overlay image is to be, i.e.
	      how much of the composite	 image	should	be  from  the  overlay
	      image,  as opposed to the underlying image.  opacity is a float-
	      ing point number, with 1.0 meaning the overlay image is  totally
	      opaque  and  0.0 meaning it is totally transparent.  The default
	      is 1.0.

	      If you specify an alpha mask (the -alpha option),	 pamcomp  uses
	      the product of the opacity indicated by the alpha mask (as modi-
	      fied by the -invert option, as  a	 fraction,  and	 this  opacity
	      value.  The -invert option does not apply to this opacity value.

	      As  a  simple opacity value, the value makes sense only if it is
	      between 0 and 1, inclusive.  However, pamcomp accepts all values
	      and  performs  the  same	arithmetic  computation using whatever
	      value you provide.  An opacity value less than  zero  means  the
	      underlay	image  is  intensified	and  then the overlay image is
	      "subtracted" from it.  An opacity value greater than unity means
	      the  overlay image is intensified and the underlaying image sub-
	      tracted from it.	In either case, pamcomp	 clips	the  resulting
	      color  component	intensities  so they are nonnegative and don't
	      exceed the output image's maxval.

	      This may seem like a strange thing to do, but it has uses.   You
	      can use it to brighten or darken or saturate or desaturate areas
	      of the underlaying image.	 See   this  description  (1)  of  the
	      technique.

	      This option was added in Netpbm 10.6 (July 2002).	 Before Netpbm
	      10.15 (April 2003), values less than zero or greater than	 unity
	      were not allowed.


       -linear
	      This option indicates that the inputs are not true Netpbm images
	      but rather a non-gamma-adjusted  variation.   This  is  relevant
	      only  when you mix pixels, using the -opacity option or an alpha
	      mask (the -alpha option).

	      The alpha mask and -opacity values indicate a  fraction  of  the
	      light  intensity of a pixel.  But the PNM and PNM-equivalent PAM
	      image formats represent intensities with gamma-adjusted  numbers
	      that are not linearly proportional to intensity.	So pamcomp, by
	      default, performs a calculation on each  sample  read  from  its
	      input  and  each sample written to its output to convert between
	      these gamma-adjusted numbers and internal intensity-proportional
	      numbers.

	      Sometimes	 you  are not working with true PNM or PAM images, but
	      rather a variation in  which  the	 sample	 values	 are  in  fact
	      directly	proportional  to  intensity.   If  so, use the -linear
	      option to tell pamcomp this.  pamcomp then will skip the conver-
	      sions.

	      The  conversion  takes  time.  And the difference between inten-
	      sity-proportional values and gamma-adjusted values may be	 small
	      enough  that  you would barely see a difference in the result if
	      you just pretended that the gamma-adjusted values were  in  fact
	      intensity-proportional.  So just to save time, at the expense of
	      some image quality, you can specify -linear even when  you  have
	      true PPM input and expect true PPM output.

	      For  the	first  13  years  of Netpbm's life, until Netpbm 10.20
	      (January 2004), pamcomp's predecessor pnmcomp always treated the
	      PPM samples as intensity-proportional even though they were not,
	      and drew few complaints.	So using -linear as a lie is a reason-
	      able thing to do if speed is important to you.

	      Another  technique  to  consider is to convert your PNM image to
	      the linear variation with pnmgamma, run pamcomp on it and	 other
	      transformations  that  like linear PNM, and then convert it back
	      to true PNM with pnmgamma -ungamma.  pnmgamma  is	 often	faster
	      than pamcomp in doing the conversion.





SEE ALSO
       ppmmix(1)and  pnmpaste(1)aresimpler,lessgeneral	versions  of  the same
       tool.

       ppmcolormask(1)and pbmmask(1),and pambackground(1)canhelpwith  generat-
       ing an alpha mask.

       pnmcomp(1)isanolderprogramthat runs faster, but has less function.

       pnm(1)



HISTORY
       pamcomp	was  new  in Netpbm 10.21 (March 2004).	 Its predecessor, pnm-
       comp, was one of the first programs added to Netpbm  when  the  project
       went global in 1993.



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



netpbm documentation		 17 July 2004		Pamcomp User Manual(0)