{
    "mode": "man",
    "parameter": "pamfunc",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/pamfunc/1/json",
    "generated": "2026-08-06T16:09:04Z",
    "synopsis": "pamfunc  {  -multiplier=realnum  |  -divisor=realnum | -adder=integer | -subtractor=integer |",
    "sections": {
        "NAME": {
            "content": "pamfunc - Apply a simple monadic arithmetic function to a Netpbm image\n\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "pamfunc  {  -multiplier=realnum  |  -divisor=realnum | -adder=integer | -subtractor=integer |",
            "subsections": [
                {
                    "name": "-min=_ -max=_ -andmask=_ -ormask=_ -xormask=_ -not",
                    "content": ""
                },
                {
                    "name": "-shiftleft=_ -shiftright=_ -changemaxval",
                    "content": "All  options can be abbreviated to their shortest unique prefix.  You may use two hyphens in‐\nstead of one.  You may separate an option name and its value with white space instead  of  an\nequals sign.\n\n"
                }
            ]
        },
        "DESCRIPTION": {
            "content": "This program is part of Netpbm(1).\n\npamfunc  reads  a  Netpbm image as input and produces a Netpbm image as output, with the same\nformat, and dimensions as the input.  pamfunc applies a simple transfer function to each sam‐\nple in the input to generate the corresponding sample in the output.  The  options  determine\nwhat function.\n\nThe  samples  involved are PAM samples.  If the input is PBM, PGM, or PPM, the output will be\nthat same format, but pamfunc applies the functions to the PAM equivalent  samples,  yielding\nPAM equivalent samples.  This can be nonintuitive in the \u001b]8;;#pbmoddness\u001b\\PBM\u001b]8;;\u001b\\  case.\n\n\npamarith is the same thing for binary functions -- it takes two images as input and applies a\nspecified simple arithmetic function (e.g. addition) on pairs of samples from the two to pro‐\nduce the single output image.\n\n\n",
            "subsections": [
                {
                    "name": "Values",
                    "content": "The  functions  fall  into  two categories: arithmetic (such as multiply by 5) and bit string\n(such as and with 01001000).  For the arithmetic functions, the function  arguments  and  re‐\nsults  are the fraction that a sample is of the maxval, i.e. normal interpretation of PAM tu‐\nples.  But for the bit string functions, the value is the the bit string whose value as a bi‐\nnary cipher is the sample value, and the maxval indicates the width of the bit string.\n"
                },
                {
                    "name": "Arithmetic functions",
                    "content": "The arithmetic functions are those selected by the  options  -multiplier,  -divisor,  -adder,"
                },
                {
                    "name": "-subtractor -min -max",
                    "content": "As  an  example, consider an image with maxval 100 and a sample value of 10 and a function of\n\"multiply by 5.\" The argument to the function is 10/100 (0.1) and the result is  5  *  0.1  =\n0.5.   In the simplest case, the maxval of the output is also 100, so the output sample value\nis 0.5 * 100 = 50.  As you can see, we could just talk about the sample values themselves in‐\nstead of these fractions and get the same result (10 * 5 = 50), but we don't.\n\nWhere it makes a practical difference whether we consider the values to be  the  fraction  of\nthe  maxval  or the sample value alone is where pamfunc uses a different maxval in the output\nimage than it finds in the input image.  See -changemaxval.\n\nSo remember in reading the descriptions below that the values are 0.1 and 0.5 in  this  exam‐\nple, not 10 and 50.  All arguments and results are in the range [0,1].\n"
                },
                {
                    "name": "Bit string functions",
                    "content": "The bit string functions are those selected by the options -andmask, -ormask, -xormask, -not,"
                },
                {
                    "name": "-shiftleft -shiftright",
                    "content": "With  these  functions, the maxval has a very different meaning than in normal Netpbm images:\nit tells how wide (how many bits) the bit string is.  The maxval must be a full binary  count\n(a power of two minus one, such as 0xff) and the number of ones in it is the width of the bit\nstring.\n\nAs  an  example,  consider  an image with maxval 15 and a sample value of 5 and a function of\n\"and with 0100\".  The argument to the function is 0101 and the result is 0100.\n\nIn this example, it doesn't make any practical difference what we consider the width  of  the\nstring  to  be, as long as it is at least 3.  If the maxval were 255, the result would be the\nsame.  But with a bit shift operation, it matters.  Consider shifting left by 2 bits.  In the\nexample, where the input value is 0101, the result is 0100.  But if the maxval were 255,  the\nresult would be 00010100.\n\nFor  a  masking function, the mask value you specify must not have more significant bits than\nthe width indicated by the maxval.\n\nFor a shifting operation, the shift count you specify must not be greater than the width  in‐\ndicated by the maxval.\n"
                },
                {
                    "name": "PBM Oddness",
                    "content": "If  you're familiar with the PBM format, you may find pamfunc's operation on PBM images to be\nnonintuitive.  Because in PBM black is represented as 1 and white as 0 (1.0  and  0.0  norml‐\nized), you might be expecting adding 1 to white to yield black.\n\nBut  the  PBM  format is irrelevant, because pamfunc operates on the numbers found in the PAM\nequivalent (see above).  In a PAM black and white image, black is 0 and white is 1  (0.0  and\n1.0 normalized).  So white plus 1 (clipped to the maximum of 1.0) is white.\n\n\n"
                }
            ]
        },
        "OPTIONS": {
            "content": "In  addition  to  the options common to all programs based on libnetpbm (most notably -quiet,\nsee \u001b]8;;index.html#commonoptions\u001b\\ Common Options\u001b]8;;\u001b\\ ), pamfunc recognizes the following command line options:\n\n\n",
            "subsections": [
                {
                    "name": "-multiplier=_",
                    "content": "This option makes the transfer function that of multiplying by\nrealnum.  realnum must be nonnegative.  If the result\nis greater than one, it is clipped to one.\n\nWhere the input is a PGM or PPM image, this has the effect of\ndimming or brightening it.  For a different kind of brightening,\nsee pambrighten(1) and ppmflash(1)\n\nAlso, see ppmdim(1), which does the same\nthing as pamfunc -multiplier on a PPM image with a multiplier\nbetween zero and one, except it uses integer arithmetic, so it may be\nfaster.\n\nAnd ppmfade(1) can generate a whole\nsequence of images of brightness declining to black or increasing to\nwhite, if that's what you want.\n\n"
                },
                {
                    "name": "-divisor=_",
                    "content": "This option makes the transfer function that of dividing by\nrealnum.  realnum must be nonnegative.  If the result\nis greater than one, it is clipped to one.\n\nThis is the same function as you would get with -multiplier,\nspecifying the multiplicative inverse of realnum.\n\n"
                },
                {
                    "name": "-adder=_",
                    "content": "This option makes the transfer function that of adding\ninteger/maxval.  If the result is greater than one, it is\nclipped to one.  If it is less than zero, it is clipped to zero.\n\nNote that in mathematics, this entity is called an \"addend,\"\nand an \"adder\" is a snake.  We use \"adder\" because\nit makes more sense.\n\n"
                },
                {
                    "name": "-subtractor=_",
                    "content": "This option makes the transfer function that of subtracting\ninteger/maxval.  If the result is greater than one, it is\nclipped to one.  If it is less than zero, it is clipped to zero.\n\nNote that in mathematics, this entity is called a\n\"subtrahend\" rather than a \"subtractor.\" We use\n\"subtractor\" because it makes more sense.\n\nThis is the same function as you would get with -adder,\nspecifying the negative of integer.\n\n"
                },
                {
                    "name": "-min=_",
                    "content": "This option makes the transfer function that of taking the maximum of\nthe argument and wholenum/maxval.  I.e the minimum value in\nthe output will be wholenum/maxval.\n\nIf wholenum/maxval is greater than one, though, every value\nin the output will be one.\n\n"
                },
                {
                    "name": "-max=_",
                    "content": "This option makes the transfer function that of taking the minimum of\nthe argument and wholenum/maxval.  I.e the maximum value in\nthe output will be wholenum/maxval.\n\nIf wholenum/maxval is greater than one, the function is\nidempotent -- the output is identical to the input.\n\n"
                },
                {
                    "name": "-andmask=_",
                    "content": "This option makes the transfer function that of bitwise anding\nwith hexmask.\n\nhexmask is in hexadecimal.  Example: 0f\n\nThis option was new in Netpbm 10.40 (September 2007).\n\n"
                },
                {
                    "name": "-ormask=_",
                    "content": "This option makes the transfer function that of bitwise\ninclusive oring with hexmask.\n\nThis is analogous to -andmask.\n\nThis option was new in Netpbm 10.40 (September 2007).\n\n"
                },
                {
                    "name": "-xormask=_",
                    "content": "This option makes the transfer function that of bitwise\nexclusive oring with hexmask.\n\nThis is analogous to -andmask.\n\nThis option was new in Netpbm 10.40 (September 2007).\n\n"
                },
                {
                    "name": "-not",
                    "content": "This option makes the transfer function that of bitwise logical\ninversion (e.g. sample value 0xAA becomes 0x55).\n\npnminvert does the same thing for a bilevel visual image\nwhich has maxval 1 or is of PBM type.\n\nThis option was new in Netpbm 10.40 (September 2007).\n\n"
                },
                {
                    "name": "-shiftleft=_",
                    "content": "This option makes the transfer function that of bitwise shifting\nleft by count bits.\n\nThis option was new in Netpbm 10.40 (September 2007).\n\n"
                },
                {
                    "name": "-shiftright=_",
                    "content": "This option makes the transfer function that of bitwise shifting\nright by count bits.\n\nThis is analogous to -shiftleft.\n\nThis option was new in Netpbm 10.40 (September 2007).\n\n"
                },
                {
                    "name": "-changemaxval",
                    "content": "This option tells pamfunc to use a different maxval in the output image than the  max‐\nval  of  the  input  image,  if it helps.  By default, the maxval of the output is un‐\nchanged from the input and pamfunc modifies the sample values as necessary to  perform\nthe operation.\n\nBut  there  is one case where pamfunc can achieve the same result just by changing the\nmaxval and leaving the sample values unchanged: dividing by a number 1 or greater,  or\nmultiplying  by  a number 1 or less.  For example, to halve all of the values, pamfunc\ncan just double the maxval.\n\nWith -changemaxval, pamfunc will do just that.\n\nAs the Netpbm formats have a maximum maxval of 65535, for large divisors, pamfunc  may\nnot be able to use this method.\n\nAn advantage of dividing by changing the maxval is that you don't lose precision.  The\nhigher maxval means higher precision.  For example, consider an image with a maxval of\n100  and sample value of 10.  You divide by 21 and then multiply by 21 again.  If pam‐\nfunc does this by changing the sample values while retaining maxval 100, the  division\nwill  result  in  a sample value of 0 and the multiplication will also result in zero.\nBut if pamfunc instead keeps the sample value 10 and changes the maxval, the  division\nwill result in a maxval of 2100 and the multiplication will change it back to 100, and\nthe round trip is idempotent.\n\nThis option was new in Netpbm 10.65 (December 2013).\n\n\n\n\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "ppmdim(1),  pambrighten(1),  pamdepth(1), pamarith(1), pamsummcol(1), pamsumm(1), ppmfade(1),\npnminvert(1), pam(1), pnm(1),\n\n",
            "subsections": []
        },
        "HISTORY": {
            "content": "This program was added to Netpbm in Release 10.3 (June 2002).\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/pamfunc.html\n\nnetpbm documentation                      09 September 2020                   Pamfunc User Manual(1)",
            "subsections": []
        }
    },
    "summary": "pamfunc - Apply a simple monadic arithmetic function to a Netpbm image",
    "flags": [
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option makes the transfer function that of multiplying by realnum. realnum must be nonnegative. If the result is greater than one, it is clipped to one. Where the input is a PGM or PPM image, this has the effect of dimming or brightening it. For a different kind of brightening, see pambrighten(1) and ppmflash(1) Also, see ppmdim(1), which does the same thing as pamfunc -multiplier on a PPM image with a multiplier between zero and one, except it uses integer arithmetic, so it may be faster. And ppmfade(1) can generate a whole sequence of images of brightness declining to black or increasing to white, if that's what you want."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option makes the transfer function that of dividing by realnum. realnum must be nonnegative. If the result is greater than one, it is clipped to one. This is the same function as you would get with -multiplier, specifying the multiplicative inverse of realnum."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option makes the transfer function that of adding integer/maxval. If the result is greater than one, it is clipped to one. If it is less than zero, it is clipped to zero. Note that in mathematics, this entity is called an \"addend,\" and an \"adder\" is a snake. We use \"adder\" because it makes more sense."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option makes the transfer function that of subtracting integer/maxval. If the result is greater than one, it is clipped to one. If it is less than zero, it is clipped to zero. Note that in mathematics, this entity is called a \"subtrahend\" rather than a \"subtractor.\" We use \"subtractor\" because it makes more sense. This is the same function as you would get with -adder, specifying the negative of integer."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option makes the transfer function that of taking the maximum of the argument and wholenum/maxval. I.e the minimum value in the output will be wholenum/maxval. If wholenum/maxval is greater than one, though, every value in the output will be one."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option makes the transfer function that of taking the minimum of the argument and wholenum/maxval. I.e the maximum value in the output will be wholenum/maxval. If wholenum/maxval is greater than one, the function is idempotent -- the output is identical to the input."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option makes the transfer function that of bitwise anding with hexmask. hexmask is in hexadecimal. Example: 0f This option was new in Netpbm 10.40 (September 2007)."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option makes the transfer function that of bitwise inclusive oring with hexmask. This is analogous to -andmask. This option was new in Netpbm 10.40 (September 2007)."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option makes the transfer function that of bitwise exclusive oring with hexmask. This is analogous to -andmask. This option was new in Netpbm 10.40 (September 2007)."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option makes the transfer function that of bitwise logical inversion (e.g. sample value 0xAA becomes 0x55). pnminvert does the same thing for a bilevel visual image which has maxval 1 or is of PBM type. This option was new in Netpbm 10.40 (September 2007)."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option makes the transfer function that of bitwise shifting left by count bits. This option was new in Netpbm 10.40 (September 2007)."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option makes the transfer function that of bitwise shifting right by count bits. This is analogous to -shiftleft. This option was new in Netpbm 10.40 (September 2007)."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option tells pamfunc to use a different maxval in the output image than the max‐ val of the input image, if it helps. By default, the maxval of the output is un‐ changed from the input and pamfunc modifies the sample values as necessary to perform the operation. But there is one case where pamfunc can achieve the same result just by changing the maxval and leaving the sample values unchanged: dividing by a number 1 or greater, or multiplying by a number 1 or less. For example, to halve all of the values, pamfunc can just double the maxval. With -changemaxval, pamfunc will do just that. As the Netpbm formats have a maximum maxval of 65535, for large divisors, pamfunc may not be able to use this method. An advantage of dividing by changing the maxval is that you don't lose precision. The higher maxval means higher precision. For example, consider an image with a maxval of 100 and sample value of 10. You divide by 21 and then multiply by 21 again. If pam‐ func does this by changing the sample values while retaining maxval 100, the division will result in a sample value of 0 and the multiplication will also result in zero. But if pamfunc instead keeps the sample value 10 and changes the maxval, the division will result in a maxval of 2100 and the multiplication will change it back to 100, and the round trip is idempotent. This option was new in Netpbm 10.65 (December 2013)."
        }
    ],
    "examples": [],
    "see_also": [
        {
            "name": "ppmdim",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/ppmdim/1/json"
        },
        {
            "name": "pambrighten",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pambrighten/1/json"
        },
        {
            "name": "pamdepth",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pamdepth/1/json"
        },
        {
            "name": "pamarith",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pamarith/1/json"
        },
        {
            "name": "pamsummcol",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pamsummcol/1/json"
        },
        {
            "name": "pamsumm",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pamsumm/1/json"
        },
        {
            "name": "ppmfade",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/ppmfade/1/json"
        },
        {
            "name": "pnminvert",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pnminvert/1/json"
        },
        {
            "name": "pam",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pam/1/json"
        },
        {
            "name": "pnm",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pnm/1/json"
        }
    ],
    "tldr": {
        "source": "official",
        "description": "Apply a simple arithmetic function to a Netpbm image.",
        "examples": [
            {
                "description": "Apply the specified arithmetic function with `n` as the second argument to each sample in the specified PAM image",
                "command": "pamfunc -{{multiplier|divisor|adder|subtractor|min|max}} {{n}} {{path/to/input.pam}} > {{path/to/output.pam}}"
            },
            {
                "description": "Apply the specified bit string function with `n` as the second argument to each sample in the specified PAM image",
                "command": "pamfunc -{{andmask|ormask|xormask|shiftleft|shiftright}} {{n}} {{path/to/input.pam}} > {{path/to/output.pam}}"
            }
        ]
    }
}