{
    "mode": "man",
    "parameter": "pamcomp",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/man/pamcomp/json",
    "generated": "2026-10-05T01:22:09Z",
    "synopsis": "",
    "sections": {
        "NAME": {
            "content": "pamcomp - composite (overlay) two Netpbm images together\n\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "",
            "subsections": [
                {
                    "name": "pamcomp",
                    "content": "[-align={left  | center | right | beyondleft | beyondright}] [-valign={top | middle | bottom|\nabove |  below}]  [-xoff=X]  [-yoff=Y]  [-alpha=alpha-pgmfile]  [-invert]  [-opacity=opacity]\n[-mixtransparency] [-linear] overlayfile [underlyingfile [outputfile]]\n\nMinimum  unique  abbreviation of option is acceptable.  You may use double hyphens instead of\nsingle hyphen to denote options.  You may use white space in place of the equals sign to sep‐\narate an option name from its value.\n\n"
                }
            ]
        },
        "DESCRIPTION": {
            "content": "This program is part of Netpbm(1).\n\npamcomp reads two images and produces a composite image with one of the images  overlayed  on\ntop  of  the other, possible translucently.  The images need not be the same size.  The input\nand outputs are Netpbm format image files.\n\nIn its simplest use, pamcomp simply places the image in the file overlayfile on top  of  the\nimage in the file underlyingfile, blocking out the part of underlyingfile beneath it.\n\nIf  you  add the -alpha option, then pamcomp uses the image in file alpha-pgmfile as a trans‐\nparency mask, which means it determines the level of transparency of each point in the  over‐\nlay  image.   The  transparency  mask must have the same dimensions as the overlay image.  In\nplaces where the transparency mask defines the overlay image to be opaque, the composite out‐\nput contains only the contents of the overlay image; the underlying image is totally  blocked\nout.   In places where the transparency mask defines the overlay image to be transparent, the\ncomposite output contains none of the overlay image; the underlying image shows through  com‐\npletely.  In places where the transparency mask shows a value in between opaque and transpar‐\nent  (translucence),  the composite image contains a mixture of the overlay image and the un‐\nderlying image and the level of translucence determines how much of each.\n\nThe transparency mask is a PGM file in which a white pixel represents opaqueness and a  black\npixel  transparency.   Anything in between is translucent.  (Like any Netpbm program, pamcomp\nwill see a PBM file as if it is PGM).\n\nIf the overlay image is a PAM image of tuple type  RGBALPHA  or  GRAYSCALEALPHA,  then  the\noverlay  image  contains  transparency information itself and pamcomp uses it the same way as\nthe transparency mask described above.  If you supply both an overlay image that  has  trans‐\nparency  information and a transparency mask, pamcomp multiplies the two opacities to get the\nopacity of the overlay pixel.\n\nBefore Netpbm 10.25 (October 2004), pamcomp did not recognize the transparency information in\na PAM image -- it just ignored it.  So people had to make appropriate transparency  masks  in\norder  to  have  a  non-opaque overlay.  Some Netpbm programs that convert from image formats\nthat contain transparency information are not able to create RGBALPHA or GRAYSCALEALPHA PAM\noutput, so you have to use the old method -- extract the transparency  information  from  the\noriginal into a separate transparency mask and use that as input to pamcomp.\n\nThe output image is always of the same dimensions as the underlying image.  pamcomp uses only\nparts of the overlay image that fit within the underlying image.\n\nThe  output  image  is  a  PAM  image.   Its tuples are color, grayscale, or black and white,\nwhichever is the \"highest\" format between the two input images.  The maxval of the output  is\nthe least common multiple of the maxvals of the input, up to the maximum possible PAM maxval,\n65535.\n\nThe  output  has  an  opacity  channel if and only if the underlying image does, and then the\nopacities are as described under the -mixtransparency option.  Before Netpbm 10.56 (September\n2011), the output never has an opacity channel.\n\nTo specify where on the underlying image to place the overlay image, use the -align, -valign,",
            "subsections": [
                {
                    "name": "-xoff -yoff",
                    "content": "left and the default vertical position is flush top.\n\nThe  overlay  image, in the position you specify, need not fit entirely within the underlying\nimage.  pamcomp uses only the parts of the overlay image that appear above the underlying im‐\nage.  It is possible to specify positioning such that none of the overlay image is  over  the\nunderlying image -- i.e. the overlay is out of frame.  If you do that, pamcomp issues a warn‐\ning.\n\nThe  overlay  and  underlying images may be of different formats (e.g. overlaying a PBM text\nimage over a full color PPM image) and have different maxvals.  The output image has the more\ngeneral of the two input formats and a maxval that is the least common multiple the two  max‐\nvals (or the maximum maxval allowable by the format, if the LCM is more than that).\n\n\n"
                }
            ]
        },
        "ARGUMENTS": {
            "content": "The overlayfile argument is the name of the file containing the\noverly image, while underlyingfile is the name of the file\ncontaining the underlying image.  For either, you may specify '-'\nto indicate Standard Input, and underlying file defaults to Standard\nInput.  Make sure you aren't specifying (or defaulting) Standard Input as\nboth.\n\nNote that there may be a third input file, identified by an -alphafile option.\n\nThe outputfile argument is the name of the file to which\npamcomp writes the output, creating or truncating it first.  You may\nspecify '-' to indicate Standard Output, in which\ncase pamcomp does not truncate it.  Note that pamcomp is\nunusual among Netpbm programs, as a historical accident, in having an output\nfile argument; Netpbm programs normally write to Standard Output only.\n\n\n",
            "subsections": []
        },
        "OPTIONS": {
            "content": "In  addition  to  the options common to all programs based on libnetpbm (most notably -quiet,\nsee  Common Options ), pamcomp recognizes the following command line options:\n\n\n",
            "subsections": [
                {
                    "name": "-align=_",
                    "content": "This option selects the basic horizontal position of the overlay image with respect to\nthe underlying image, in syntax reminiscent of HTML.  left means  flush  left,  center\nmeans centered, and right means flush right.\n\nThe -xoff option modifies this position.\n\nbeyondleft  means  just  out  of frame to the left -- the right edge of the overlay is\nflush with the left edge of the underlying image.  beyondright means just out of frame\nto the right.  These alignments are useful only if you add a  -xoff  option.     These\ntwo values were added in Netpbm 10.10 (October 2002).\n\nThe default is left.\n\n"
                },
                {
                    "name": "-valign=_",
                    "content": "This  option  selects the basic vertical position of the overlay image with respect to\nthe underlying image, in syntax reminiscent of HTML.   top  means  flush  top,  middle\nmeans centered, and bottom means flush bottom.\n\nThe -yoff option modifies this position.\n\nabove  means  just  out of frame to the top -- the bottom edge of the overlay is flush\nwith the top edge of the underlying image.  below means just out of frame to the  bot‐\ntom.   These  alignments  are useful only if you add a -yoff option.  These two values\nwere added in Netpbm 10.10 (October 2002).\n\nThe default is top.\n\n"
                },
                {
                    "name": "-xoff=_",
                    "content": "This option modifies the horizontal positioning of the overlay image with  respect  to\nthe underlying image as selected by the -align option.  pamcomp shifts the overlay im‐\nage  from  that  basic  position x pixels to the right.  x can be negative to indicate\nshifting to the left.\n\nThe overlay need not fit entirely (or at all) on the underlying image.   pamcomp  uses\nonly the parts that lie over the underlying image.\n\nBefore  Netpbm  10.10 (October 2002), -xoff was mutually exclusive with -align and al‐\nways measured from the left edge.\n\n"
                },
                {
                    "name": "-yoff=_",
                    "content": "This option modifies the vertical positioning of the overlay image with respect to the\nunderlying image as selected by the -valign option.  pamcomp shifts the overlay  image\nfrom  that  basic  position y pixels downward.  y can be negative to indicate shifting\nupward.\n\nThe overlay need not fit entirely (or at all) on the underlying image.   pamcomp  uses\nonly the parts that lie over the underlying image.\n\nBefore  Netpbm 10.10 (October 2002), -xoff was mutually exclusive with -valign and al‐\nways measured from the top edge.\n\n"
                },
                {
                    "name": "-alpha=_",
                    "content": "This option names a file that contains the transparency mask.  If  you  don't  specify\nthis  option,  there  is  no transparency mask, which is equivalent to having a trans‐\nparency mask specify total opaqueness everywhere.\n\nYou can specify - as the value of this option and the transparency mask will come from\nStandard Input.  If you do this, don't specify Standard Input as  the  source  of  any\nother input image.\n\n"
                },
                {
                    "name": "-invert",
                    "content": "This  option  inverts  the  sense of the values in the transparency mask, which effec‐\ntively switches the roles of the overlay image and  the  underlying  image  in  places\nwhere the two intersect.\n\n"
                },
                {
                    "name": "-opacity=_",
                    "content": "This  option tells how opaque the overlay image is to be, i.e. how much of the compos‐\nite image should be from the overlay image, as opposed to the underlying image.  opac‐\nity is a floating point number, with 1.0 meaning the overlay image is  totally  opaque\nand 0.0 meaning it is totally transparent.  The default is 1.0.\n\nIf  you  specify  a transparency mask (the -alpha option), pamcomp uses the product of\nthe opacity indicated by the transparency mask (as modified by the -invert option,  as\na fraction, and this opacity value.  The -invert option does not apply to this opacity\nvalue.\n\nAs a simple opacity value, the value makes sense only if it is between 0 and 1, inclu‐\nsive.   However,  pamcomp accepts all values and performs the same arithmetic computa‐\ntion using whatever value you provide.  An opacity value less than zero means the  un‐\nderlay  image  is  intensified and then the overlay image is \"subtracted\" from it.  An\nopacity value greater than unity means the overlay image is intensified and the under‐\nlay image subtracted from it.  In either case, pamcomp clips the resulting color  com‐\nponent intensities so they are nonnegative and don't exceed the output image's maxval.\n\nThis may seem like a strange thing to do, but it has uses.  You can use it to brighten\nor  darken  or saturate or desaturate areas of the underlay image.  See  this descrip‐\ntion(1) of the technique.\n\nThis option was added in Netpbm 10.6 (July 2002).  Before Netpbm 10.15  (April  2003),\nvalues less than zero or greater than unity were not allowed.\n\n"
                },
                {
                    "name": "-mixtransparency",
                    "content": "This option controls what pamcomp does where both the underlying and overlay image are\nnon-opaque.\n\nBy default, the output image has the same transparency as the underlying image and the\ntransparency of the underlying image has no effect on the composition of color.\n\nBut  with  this option, pamcomp composes the image according to a plastic transparency\nmetaphor: the underlying and overlay images are plastic slides.  The output  image  is\nthe slide you get when you stack up those two slides.  So the transparency of the out‐\nput is a combination of the transparency of the inputs and the transparency of the un‐\nderlying  image  affects  the  underlying  image's  contribution to the output image's\ncolor.\n\nUnlike the metaphorical slide, a PAM pixel has a color even  where  it  is  completely\ntransparent,  so  pamcomp  departs from the metaphor in that case and makes the output\ncolor identical to the underlying image.\n\nThis option was new in Netpbm 10.56 (September 2011).  Before that, the output is  al‐\nways opaque and the pamcomp ignores the transparency of the underlying image.\n\n"
                },
                {
                    "name": "-linear",
                    "content": "This  option  indicates that the inputs are not true Netpbm images but rather a light-\nintesity-proportional variation.  This is relevant only when you mix pixels, using the\n-opacity option or a transparency mask (the -alpha option).\n\nThe transparency mask and -opacity values indicate a fraction of the  light  intensity\nof  a  pixel.   But the PNM and PNM-equivalent PAM image formats represent intensities\nwith gamma-adjusted numbers that are not linearly proportional to intensity.  So  pam‐\ncomp,  by  default, performs a calculation on each sample read from its input and each\nsample written to its output to convert between these gamma-adjusted numbers  and  in‐\nternal intensity-proportional numbers.\n\nSometimes  you  are not working with true PNM or PAM images, but rather a variation in\nwhich the sample values are in fact directly proportional to intensity.   If  so,  use\nthe -linear option to tell pamcomp this.  pamcomp then will skip the conversions.\n\nThe  conversion  takes time.  And the difference between intensity-proportional values\nand gamma-adjusted values may be small enough that you would barely see  a  difference\nin the result if you just pretended that the gamma-adjusted values were in fact inten‐\nsity-proportional.   So  just  to save time, at the expense of some image quality, you\ncan specify -linear even when you have true PPM input and expect true PPM output.\n\nFor the first 13 years of Netpbm's life, until Netpbm 10.20 (January 2004),  pamcomp's\npredecessor  pnmcomp  always  treated  the  PPM samples as intensity-proportional even\nthough they were not, and drew few complaints.  So using -linear as a lie is a reason‐\nable thing to do if speed is important to you.\n\nAnother technique to consider is to convert your PNM image  to  the  linear  variation\nwith  pnmgamma,  run pamcomp on it and other transformations that like linear PNM, and\nthen convert it back to true PNM with pnmgamma -ungamma.   pnmgamma  is  often  faster\nthan pamcomp in doing the conversion.\n\n\n\n\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "pammixmulti.html(1) mixes together two or more images of the same size, in various ways.\n\nppmmix(1) and pnmpaste(1) are simpler, less general versions of the same tool.\n\nppmcolormask(1)  and pbmmask(1), and pambackground(1) can help with generating a transparency\nmask.\n\npnmcomp(1) is an older program that runs faster, but has less function.\n\npnm(1)\n\n\n",
            "subsections": []
        },
        "HISTORY": {
            "content": "pamcomp was new in Netpbm 10.21 (March 2004).  Its predecessor, pnmcomp, was one of the first\nprograms added to Netpbm when the project went global in 1993.\n\n\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Copyright (C) 1992 by David Koblas (koblas@mips.com).\n",
            "subsections": []
        },
        "DOCUMENT SOURCE": {
            "content": "This manual page was generated by the Netpbm tool 'makeman' from  HTML  source.   The  master\ndocumentation is at\n\nhttp://netpbm.sourceforge.net/doc/pamcomp.html\n\nnetpbm documentation                       13 August 2011                     Pamcomp User Manual(1)",
            "subsections": []
        }
    },
    "summary": "pamcomp - composite (overlay) two Netpbm images together",
    "flags": [
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "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."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "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."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "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."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "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."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "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."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "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."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "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) 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."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "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."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "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."
        }
    ],
    "examples": [],
    "see_also": [
        {
            "name": "pammixmulti.html",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pammixmulti.html/1/json"
        },
        {
            "name": "ppmmix",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/ppmmix/1/json"
        },
        {
            "name": "pnmpaste",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pnmpaste/1/json"
        },
        {
            "name": "ppmcolormask",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/ppmcolormask/1/json"
        },
        {
            "name": "pbmmask",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pbmmask/1/json"
        },
        {
            "name": "pambackground",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pambackground/1/json"
        },
        {
            "name": "pnmcomp",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pnmcomp/1/json"
        },
        {
            "name": "pnm",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pnm/1/json"
        }
    ],
    "tldr": {
        "source": "official",
        "description": "Overlay two PAM images.",
        "examples": [
            {
                "description": "Overlay two images such with the overlay blocking parts of the underlay",
                "command": "pamcomp {{path/to/overlay.pam}} {{path/to/underlay.pam}} > {{path/to/output.pam}}"
            },
            {
                "description": "Set the horizontal alignment of the overlay",
                "command": "pamcomp {{-ali|-align}} {{left|center|right|beyondleft|beyondright}} {{-x|-xoff}} {{x_offset}} {{path/to/overlay.pam}} {{path/to/underlay.pam}} > {{path/to/output.pam}}"
            },
            {
                "description": "Set the vertical alignment of the overlay",
                "command": "pamcomp {{-va|-valign}} {{top|middle|bottom|above|below}} {{-y|-yoff}} {{y_offset}} {{path/to/overlay.pam}} {{path/to/underlay.pam}} > {{path/to/output.pam}}"
            },
            {
                "description": "Set the opacity of the overlay",
                "command": "pamcomp {{-o|-opacity}} {{0.7}} {{path/to/overlay.pam}} {{path/to/underlay.pam}} > {{path/to/output.pam}}"
            }
        ]
    }
}