# pamcomp - composite (overlay) two Netpbm images together - man(1) - [phpMan] > **TLDR:** Overlay two PAM images. > - Overlay two images such with the overlay blocking parts of the underlay: `pamcomp {{path/to/overlay.pam}} {{path/to/underlay.pam}} > {{path/to/output.pam}}` - Set the horizontal alignment of the overlay: `pamcomp {{-ali|-align}} {{left|center|right|beyondleft|beyondright}} {{-x|-xoff}} {{x_offset}} {{path/to/overlay.pam}} {{path/to/underlay.pam}} > {{path/to/output.pam}}` - Set the vertical alignment of the overlay: `pamcomp {{-va|-valign}} {{top|middle|bottom|above|below}} {{-y|-yoff}} {{y_offset}} {{path/to/overlay.pam}} {{path/to/underlay.pam}} > {{path/to/output.pam}}` - Set the opacity of the overlay: `pamcomp {{-o|-opacity}} {{0.7}} {{path/to/overlay.pam}} {{path/to/underlay.pam}} > {{path/to/output.pam}}` *Source: tldr-pages* --- _Pamcomp_ _User_ [_Manual_(1)](https://www.chedong.com/phpMan.php/man/Manual/1/markdown) General Commands Manual _Pamcomp_ _User_ [_Manual_(1)](https://www.chedong.com/phpMan.php/man/Manual/1/markdown) ## 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 double hyphens instead of single hyphen to denote options. You may use white space in place of the equals sign to sep‐ arate an option name from its value. ## DESCRIPTION This program is part of [**Netpbm**(1)](https://www.chedong.com/phpMan.php/man/Netpbm/1/markdown). **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 _overlay_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 a trans‐ parency mask, which means it determines the level of transparency of each point in the over‐ lay 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 out‐ put contains only the contents of the overlay image; the underlying image is totally blocked out. In places where the transparency mask defines the overlay image to be transparent, the composite output contains none of the overlay image; the underlying image shows through com‐ pletely. In places where the transparency mask shows a value in between opaque and transpar‐ ent (translucence), the composite image contains a mixture of the overlay image and the un‐ derlying 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 information 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 people 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 -- extract 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 image. **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 input 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 **-mixtransparency **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 -yoff 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 overlay image that appear above the underlying im‐ age. 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 warn‐ ing. 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 different maxvals. The output image has the more general of the two input formats and a maxval that is the least common multiple the two max‐ vals (or the maximum maxval allowable by the format, if the LCM is more than that). ## ARGUMENTS The _overlay_file_ argument is the name of the file containing the overly image, while _underlying_file_ is the name of the file containing the underlying image. For either, you may specify '-' to indicate Standard Input, and _underlying_ file defaults to Standard Input. Make sure you aren't specifying (or defaulting) Standard Input as both. Note that there may be a third input file, identified by an **-alphafile **option. The _output_file_ argument is the name of the file to which **pamcomp **writes the output, creating or truncating it first. You may specify '-' to indicate Standard Output, in which case **pamcomp **does not truncate it. Note that **pamcomp **is unusual among Netpbm programs, as a historical accident, in having an output file argument; Netpbm programs normally write to Standard Output only. ## OPTIONS In addition to the options common to all programs based on libnetpbm (most notably **-quiet**, see [ Common Options](index.html#commonoptions) ), **pamcomp **recognizes the following command line options: ### -align=_ This option selects the basic horizontal position of the overlay image with respect to the underlying image, in syntax reminiscent 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=_ This option selects the basic vertical position of the overlay image with respect to the underlying image, in syntax reminiscent 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 bot‐ tom. 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=_ 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 im‐ age 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 al‐ ways measured from the left edge. ### -yoff=_ 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 al‐ ways measured from the top edge. ### -alpha=_ 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 trans‐ parency mask specify total opaqueness everywhere. You can specify **- **as the value of this option and the transparency 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 effec‐ tively switches the roles of the overlay image and the underlying image in places where the two intersect. ### -opacity=_ This option tells how opaque the overlay image is to be, i.e. how much of the compos‐ ite image should be from the overlay image, as opposed to the underlying image. _opac‐_ _ity_ 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 opacity value. As a simple opacity value, the value makes sense only if it is between 0 and 1, inclu‐ sive. However, **pamcomp **accepts all values and performs the same arithmetic computa‐ tion using whatever value you provide. An opacity value less than zero means the un‐ derlay 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 under‐ lay image subtracted from it. In either case, **pamcomp **clips the resulting color com‐ ponent 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 descrip‐** [**tion**(1)](https://www.chedong.com/phpMan.php/man/tion/1/markdown) 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. ### -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 un‐ derlying image affects the underlying image'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 al‐ ways 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 numbers 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 in‐ ternal 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 conversions. The conversion takes time. And the difference between intensity-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 inten‐ sity-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)](https://www.chedong.com/phpMan.php/man/pammixmulti.html/1/markdown) mixes together two or more images of the same size, in various ways. [**ppmmix**(1)](https://www.chedong.com/phpMan.php/man/ppmmix/1/markdown) and [**pnmpaste**(1)](https://www.chedong.com/phpMan.php/man/pnmpaste/1/markdown) are simpler, less general versions of the same tool. [**ppmcolormask**(1)](https://www.chedong.com/phpMan.php/man/ppmcolormask/1/markdown) and [**pbmmask**(1)](https://www.chedong.com/phpMan.php/man/pbmmask/1/markdown), and [**pambackground**(1)](https://www.chedong.com/phpMan.php/man/pambackground/1/markdown) can help with generating a transparency mask. [**pnmcomp**(1)](https://www.chedong.com/phpMan.php/man/pnmcomp/1/markdown) is an older program that runs faster, but has less function. [**pnm**(1)](https://www.chedong.com/phpMan.php/man/pnm/1/markdown) ## HISTORY **pamcomp **was new in Netpbm 10.21 (March 2004). Its predecessor, **pnmcomp**, 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 **** netpbm documentation 13 August 2011 _Pamcomp_ _User_ [_Manual_(1)](https://www.chedong.com/phpMan.php/man/Manual/1/markdown)