Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 | middle |	bottom|	above |	 below}]  [-xoff=X]  [-yoff=Y]
       [-alpha=alpha-pgmfile]  [-invert] [-opacity=opacity] [-mixtransparency]
       [-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  im-
       ages  need not be the same size.	 The input and outputs are Netpbm for-
       mat 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  al-
       pha-pgmfile as a	transparency mask, which means it determines the level
       of transparency of each point in	the overlay image.   The  transparency
       mask  must  have	 the  same dimensions as the overlay image.  In	places
       where the transparency 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 transpar-
       ency  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 transparency mask shows a
       value in	between	opaque and transparent (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 transparency	mask is	a PGM file in which a white  pixel  represents
       opaqueness  and	a  black  pixel	 transparency.	Anything in between is
       translucent.  (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 transparency mask
       described above.	 If you	supply both an overlay image that  has	trans-
       parency information and a transparency mask, pamcomp multiplies the two
       opacities 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 transparency	masks in order to have a  non-
       opaque  overlay.	  Some Netpbm programs that convert from image formats
       that contain transparency information are not able to create  RGB_ALPHA
       or GRAYSCALE_ALPHA PAM output, so you have to use the old method	-- ex-
       tract the transparency information from the original  into  a  separate
       transparency mask and use that as input to pamcomp.

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

       The  output  image is a PAM image.  Its tuples are color, grayscale, or
       black and white,	whichever is the "highest" format between the two  in-
       put  images.   The maxval of the	output is the least common multiple of
       the maxvals of the input, up to the maximum possible PAM	maxval,	65535.

       The output has an opacity channel if and	only if	the  underlying	 image
       does,  and  then	 the  opacities	 are as	described under	the -mixtrans-
       parency option.	Before Netpbm 10.56 (September 2011), the output never
       has an opacity channel.

       To  specify  where  on the underlying image to place the	overlay	image,
       use the -align, -valign,	-xoff, and -yoff options.  Without  these  op-
       tions,  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 un-
       derlying	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 im-
	      age.   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 im-
	      age with respect to the underlying  image	 as  selected  by  the
	      -valign  option.	pamcomp	shifts the overlay image from that ba-
	      sic 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  transparency	 mask.
	      If you don't specify this	option,	there is no transparency mask,
	      which is equivalent to having a transparency mask	specify	 total
	      opaqueness everywhere.

	      You  can specify - as the	value of this option and the transpar-
	      ency 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 transparency
	      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  im-
	      age,  as opposed to the underlying image.	 opacity is a floating
	      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 a transparency mask (the -alpha option),  pamcomp
	      uses  the	 product  of the opacity indicated by the transparency
	      mask (as modified	by the -invert option, as a fraction, and this
	      opacity  value.  The -invert option does not apply to this opac-
	      ity 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	 underlay  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  underlay	 image.	 See  this description(5) of the tech-
	      nique.

	      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.

       -mixtransparency
	      This option controls what	pamcomp	does where both	the underlying
	      and overlay image	are non-opaque.

	      By  default,  the	 output	image has the same transparency	as the
	      underlying image and the transparency of	the  underlying	 image
	      has no effect on the composition of color.

	      But  with	this option, pamcomp composes the image	according to a
	      plastic transparency metaphor: the underlying and	overlay	images
	      are  plastic slides.  The	output image is	the slide you get when
	      you stack	up those two slides.  So the transparency of the  out-
	      put  is  a combination of	the transparency of the	inputs and the
	      transparency of the underlying image affects the underlying  im-
	      age's contribution to the	output image's color.

	      Unlike  the  metaphorical	 slide,	 a  PAM	pixel has a color even
	      where it is completely transparent, so pamcomp departs from  the
	      metaphor	in  that  case and makes the output color identical to
	      the underlying image.

	      This option was new in Netpbm 10.56  (September  2011).	Before
	      that,  the  output  is always opaque and the pamcomp ignores the
	      transparency of the underlying image.

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

	      The transparency 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 num-
	      bers that	are not	linearly proportional to intensity.   So  pam-
	      comp,  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-pro-
	      portional	numbers.

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

	      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
       pammixmulti.html(1) mixes together two or more images of	the same size,
       in various ways.

       ppmmix(1) and pnmpaste(1) are simpler, less  general  versions  of  the
       same tool.

       ppmcolormask(1) and pbmmask(1), and pambackground(1) can	help with gen-
       erating a transparency mask.

       pnmcomp(1) is an	older program that runs	faster,	but has	less function.

       pnm(5)

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).

DOCUMENT SOURCE
       This manual page	was generated by the Netpbm tool 'makeman'  from  HTML
       source.	The master documentation is at

	      http://netpbm.sourceforge.net/doc/pamcomp.html

netpbm documentation		13 August 2011		Pamcomp	User Manual(0)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | SEE ALSO | HISTORY | AUTHOR | DOCUMENT SOURCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pamcomp&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help