{
    "mode": "man",
    "parameter": "pnmremap",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/pnmremap/1/json",
    "generated": "2026-08-08T22:53:29Z",
    "synopsis": "",
    "sections": {
        "NAME": {
            "content": "pnmremap - replace colors in a PNM image with colors from another set\n\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "",
            "subsections": [
                {
                    "name": "pnmremap",
                    "content": ""
                },
                {
                    "name": "-mapfile=_",
                    "content": "[-floyd|-fs|-nfloyd|-nofs]\n\n{[-norandom]|randomseed=n}\n\n[-firstisdefault]\n\n[-verbose]\n\n[-missingcolor=colorspec]\n\n[pnmfile]\n\nAll  options can be abbreviated to their shortest unique prefix.  You may use two hyphens in‐\nstead of one to designate an option.  You may use either white space or an  equals  sign  be‐\ntween an option name and its value.\n\n"
                }
            ]
        },
        "DESCRIPTION": {
            "content": "This program is part of Netpbm(1).\n\npnmremap  replaces the colors in an input image with those from a palette you specify.  Where\ncolors in the input are present in the palette, they just stay the same in the  output.   But\nwhere  the  input  contains  a  color  that  is  not in the palette, pnmremap gives you these\nchoices:\n\n\n\n•      Choose the closest color from the palette.\n\n\n•      Choose the first color from the palette.\n\n\n•      Use a color specified by a command option (-missing).\n\n\n•      Dither.  This means rather than mapping pixel by pixel, pnmremap uses colors from  the\npalette  to  try to make multi-pixel regions of the output have the same average color\nas the input (for another kind of dithering, see ppmdither).\n\n\n\nTwo reasons to use this program are: 1) you want to reduce the number of colors in the  input\nimage; and 2) you need to feed the image to something that can handle only certain colors.\n\nTo reduce colors, you can generate the palette with pnmcolormap.\n\nBy default, pnmremap maps an input color that is not in the palette to the closest color that\nis  in  the  palette.   Closest means with the smallest Cartesian distance in the red, green,\nblue brightness space (smallest sum of the squares of the differences in red, green, and blue\nITU-R Recommendation BT.709 gamma-adjusted intensities).\n\nYou can instead specify a single default color for pnmremap to use for any color in the input\nimage that is not in the palette.  Use the -missing option for this.\n\nYou can also specify that the first color in the palette  image  is  the  default.   Use  the",
            "subsections": [
                {
                    "name": "-firstisdefault",
                    "content": "The  palette  is simply a PNM image.  The colors of the pixels in the image are the colors in\nthe palette.  Where the pixels appear in the image, and the dimensions of the image, are  ir‐\nrelevant.  Multiple pixels of the same color are fine.  However, a palette image is typically\na single row with one pixel per color.\n\nIf  you  specify -missing, the color you so specify is in the palette in addition to whatever\nis in the palette image.\n\nFor historical reasons, Netpbm sometimes calls the palette a \"colormap.\" But it  doesn't  re‐\nally  map  anything.   pnmremap creates its own map, based on the palette, to map colors from\nthe input image to output colors.\n\n"
                },
                {
                    "name": "Palette/Image Type Mismatch",
                    "content": "In the simple case, the palette image is of the same depth (number of planes, i.e. number  of\ncomponents in each tuple (pixel)) as the input image and pnmremap just does a straightforward\nsearch  of  the palette for each input tuple (pixel).  In fact, pnmremap doesn't even care if\nthe image is a visual image.\n\nBut what about when the depths differ?  In that case, pnmremap converts the input  image  (in\nits own memory) to match the palette and then proceeds as above.\n\nThere  are only two such cases in which pnmremap knows how to do the conversion:  when one of\nthem is tuple type RGB, depth 3, and the other is  tuple  type  GRAYSCALE  or  BLACKANDWHITE,\ndepth 1; and vice versa.\n\nIn any other case, pnmremap issues and error message and fails.\n\nNote  that  as long as your input and palette images are PNM, they'll always fall into one of\nthe cases pnmremap can handle.  There's an issue only if you're using some exotic PAM image.\n\nBefore Netpbm 10.27 (March 2005), pnmremap could not handle the case of a palette of  greater\ndepth  than  the  input image.  (It would issue an error message and fail in that case).  You\ncan use ppmtoppm to increase the depth of the input image to work around this limitation.\n\nIn any case, the output image has the same tuple type and depth as the palette image.\n\n"
                },
                {
                    "name": "Multiple Image Stream",
                    "content": "pnmremap handles a multiple image input stream, producing a  multiple  image  output  stream.\nThe input images need not be similar in any way.\n\nBefore Netpbm 10.30 (October 2005), pnmremap ignored any image after the first.\n\n\n"
                },
                {
                    "name": "Examples",
                    "content": "pnmcolormap testimg.ppm 256 >palette.ppm\n\npnmremap -map=palette.ppm testimg.ppm >reducedtestimg.ppm\n\n\nTo  limit colors to a certain set, a typical example is to create an image for posting on the\nWorld Wide Web, where different browsers know different colors.  But all  browsers  are  sup‐\nposed  to  know the 216 \"web safe\" colors which are essentially all the colors you can repre‐\nsent in a PPM image with a maxval of 5.  So you can do this:\n\npamseq 3 5 >websafe.pam\n\npnmremap -map=websafe.pam testimg.ppm >websafetestimg.ppm\n\n\nAnother useful palette is one for the 8 color IBM TTL color set, which you can create with\npamseq 3 1 >ibmttl.pam\n\n\nIf you want to quantize one image to use the colors in another one, just use the  second  one\nas  the  palette.  You don't have to reduce it down to only one pixel of each color, just use\nit as is.\n\nThe output image has the same type and maxval as the palette image.\n\n"
                }
            ]
        },
        "PARAMETERS": {
            "content": "There is one parameter, which is required: The file specification of the input PNM file.\n\n\n",
            "subsections": []
        },
        "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\\ ), pnmremap recognizes the following command line options:\n\n\n\n",
            "subsections": [
                {
                    "name": "-mapfile=_",
                    "content": "This names the file that contains the palette image.\n\nThis option is mandatory.\n\n"
                },
                {
                    "name": "-floyd",
                    "content": ""
                },
                {
                    "name": "-fs",
                    "content": ""
                },
                {
                    "name": "-nofloyd",
                    "content": ""
                },
                {
                    "name": "-nofs",
                    "content": "Floyd-Steinberg, pnmremap selects the output color of a pixel based on  the  color  of\nonly  the corresponding input pixel.  With Floyd-Steinberg, pnmremap considers regions\nof pixels such that the average color of a region is the same in the output as in  the\ninput.   The  dithering effect appears as a dot pattern up close, but from a distance,\nthe dots blend so that you see more colors than are present in the color map.\n\nAs an example, if your color map contains only black and white, and  the  input  image\nhas  4  adjacent  pixels  of gray, pnmremap with Floyd-Steinberg would generate output\npixels black, white, black, white, which from a  distance  looks  gray.   But  without\nFloyd-Steinberg,  pnmremap would generate 4 white pixels, white being the single-pixel\napproximation of gray.\n\nFloyd-Steinberg gives vastly better results on images  where  unmodified  quantization\nhas banding or other artifacts, especially when going to a small number of colors such\nas the above IBM set.  However, it does take substantially more CPU time.\n\n-fs is a synonym for -floyd.  -nofs is a synonym for -nofloyd.\n\nThe default is -nofloyd.\n\nBefore  Netpbm  10.46  (March 2009), dithering doesn't work quite as you expect if the\ncolor map has a lower maxval than the input.  pnmremap reduces the color resolution to\nthe color map's maxval before doing any dithering, so the dithering does not have  the\neffect  of  making  the  image, at a distance, appear to have the original maxval.  In\ncurrent Netpbm, it does.\n\n"
                },
                {
                    "name": "-norandom",
                    "content": "This option affects a detail of the Floyd-Steinberg dithering process.  It has no  ef‐\nfect if you aren't doing Floyd-Steinberg dithering.\n\nBy default, pnmremap initializes the error propagation accumulator to random values to\navoid  the  appearance  of  unwanted  patterns.   This is an extension of the original\nFloyd-Steinberg algorithm.\n\nA drawback of this is that the same pnmremap on the same input produces slightly  dif‐\nferent output every time, which makes comparison difficult.\n\nWith  -norandom, pnmremap initializes the error accumulators to zero and the output is\ncompletely predictable.\n\nAlternatively, you can use -randomseed to get  randomization  across  the  image,  but\nstill have repeatable results.\n\nYou cannot specify this along with -randomseed.\n\n-norandom was new in Netpbm 10.39 (June 2007).\n\n\n"
                },
                {
                    "name": "-randomseed=_",
                    "content": "This  option affects a detail of the Floyd-Steinberg dithering process.  It has no ef‐\nfect if you aren't doing Floyd-Steinberg dithering.\n\nThis option supplies the seed for the random number generator used in  the  randomiza‐\ntion  process  described  in the explanation of the -norandom option.  If you run pnm‐\nremap twice with the same -randomseed value, you will get identical results.\n\nIf you do not specify -randomseed, pnmremap chooses a seed at random,  adding  another\nlevel of randomness to the dithering.\n\nYou cannot specify this along with -norandom.\n\nThis option was new in Netpbm 10.82 (March 2018).\n\n\n"
                },
                {
                    "name": "-firstisdefault",
                    "content": "This  tells  pnmremap  to  map any input color that is not in the palette to the first\ncolor in the palette (the color of the pixel in the top left corner of the palette im‐\nage)\n\nSee \u001b]8;;#description\u001b\\DESCRIPTION\u001b]8;;\u001b\\ .\n\nIf you specify -firstisdefault, the maxval of your input must match the maxval of your\npalette image.\n\n"
                },
                {
                    "name": "-missingcolor=_",
                    "content": "This specifies the default color for pnmremap to map to a color  in  the  input  image\nthat  isn't  in the palette.  color may or may not be in the palette image; it is part\nof the palette regardless.\n\ncolorspec is as described for the \u001b]8;;libnetpbmimage.html#colorname\u001b\\argument of the pnmparsecolor() library routine\u001b]8;;\u001b\\ .\n\nIf you specify -missingcolor, the maxval of your input must match the maxval  of  your\npalette image.\n\n"
                },
                {
                    "name": "-verbose",
                    "content": "Display helpful messages about the mapping process.\n\n\n\n\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "pnmcolormap(1),  pamlookup(1),  pnmquant(1),  ppmquantall(1),  pamdepth(1), ppmdither(1), pp‐\nmquant(1), pamseq(1), ppm(1)\n\n",
            "subsections": []
        },
        "HISTORY": {
            "content": "pnmremap first appeared in Netpbm 9.23 (January 2002).  Before that, its function was  avail‐\nable  only  as  part  of  the function of pnmquant (which was derived from the much older pp‐\nmquant).  Color quantization really has two main subfunctions, so Netpbm 9.23  split  it  out\ninto  two  separate programs: pnmcolormap and pnmremap and then Netpbm 9.24 replaced pnmquant\nwith a program that simply calls pnmcolormap and pnmremap.\n\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Copyright (C) 1989, 1991 by Jef Poskanzer.\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/pnmremap.html\n\nnetpbm documentation                      13 November 2014                   Pnmremap User Manual(1)",
            "subsections": []
        }
    },
    "summary": "pnmremap - replace colors in a PNM image with colors from another set",
    "flags": [
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This names the file that contains the palette image. This option is mandatory."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": ""
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": ""
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": ""
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Floyd-Steinberg, pnmremap selects the output color of a pixel based on the color of only the corresponding input pixel. With Floyd-Steinberg, pnmremap considers regions of pixels such that the average color of a region is the same in the output as in the input. The dithering effect appears as a dot pattern up close, but from a distance, the dots blend so that you see more colors than are present in the color map. As an example, if your color map contains only black and white, and the input image has 4 adjacent pixels of gray, pnmremap with Floyd-Steinberg would generate output pixels black, white, black, white, which from a distance looks gray. But without Floyd-Steinberg, pnmremap would generate 4 white pixels, white being the single-pixel approximation of gray. Floyd-Steinberg gives vastly better results on images where unmodified quantization has banding or other artifacts, especially when going to a small number of colors such as the above IBM set. However, it does take substantially more CPU time. -fs is a synonym for -floyd. -nofs is a synonym for -nofloyd. The default is -nofloyd. Before Netpbm 10.46 (March 2009), dithering doesn't work quite as you expect if the color map has a lower maxval than the input. pnmremap reduces the color resolution to the color map's maxval before doing any dithering, so the dithering does not have the effect of making the image, at a distance, appear to have the original maxval. In current Netpbm, it does."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option affects a detail of the Floyd-Steinberg dithering process. It has no ef‐ fect if you aren't doing Floyd-Steinberg dithering. By default, pnmremap initializes the error propagation accumulator to random values to avoid the appearance of unwanted patterns. This is an extension of the original Floyd-Steinberg algorithm. A drawback of this is that the same pnmremap on the same input produces slightly dif‐ ferent output every time, which makes comparison difficult. With -norandom, pnmremap initializes the error accumulators to zero and the output is completely predictable. Alternatively, you can use -randomseed to get randomization across the image, but still have repeatable results. You cannot specify this along with -randomseed. -norandom was new in Netpbm 10.39 (June 2007)."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This option affects a detail of the Floyd-Steinberg dithering process. It has no ef‐ fect if you aren't doing Floyd-Steinberg dithering. This option supplies the seed for the random number generator used in the randomiza‐ tion process described in the explanation of the -norandom option. If you run pnm‐ remap twice with the same -randomseed value, you will get identical results. If you do not specify -randomseed, pnmremap chooses a seed at random, adding another level of randomness to the dithering. You cannot specify this along with -norandom. This option was new in Netpbm 10.82 (March 2018)."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This tells pnmremap to map any input color that is not in the palette to the first color in the palette (the color of the pixel in the top left corner of the palette im‐ age) See \u001b]8;;#description\u001b\\DESCRIPTION\u001b]8;;\u001b\\ . If you specify -firstisdefault, the maxval of your input must match the maxval of your palette image."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This specifies the default color for pnmremap to map to a color in the input image that isn't in the palette. color may or may not be in the palette image; it is part of the palette regardless. colorspec is as described for the \u001b]8;;libnetpbmimage.html#colorname\u001b\\argument of the pnmparsecolor() library routine\u001b]8;;\u001b\\ . If you specify -missingcolor, the maxval of your input must match the maxval of your palette image."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Display helpful messages about the mapping process."
        }
    ],
    "examples": [],
    "see_also": [
        {
            "name": "pnmcolormap",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pnmcolormap/1/json"
        },
        {
            "name": "pamlookup",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pamlookup/1/json"
        },
        {
            "name": "pnmquant",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pnmquant/1/json"
        },
        {
            "name": "ppmquantall",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/ppmquantall/1/json"
        },
        {
            "name": "pamdepth",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pamdepth/1/json"
        },
        {
            "name": "ppmdither",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/ppmdither/1/json"
        },
        {
            "name": "mquant",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/mquant/1/json"
        },
        {
            "name": "pamseq",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pamseq/1/json"
        },
        {
            "name": "ppm",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/ppm/1/json"
        }
    ],
    "tldr": {
        "source": "official",
        "description": "Replace the colors in a PNM image.",
        "examples": [
            {
                "description": "Replace the colors in an image with those in the specified color palette",
                "command": "pnmremap {{-ma|-mapfile}} {{path/to/palette_file.ppm}} {{path/to/input.pnm}} > {{path/to/output.pnm}}"
            },
            {
                "description": "Use Floyd-Steinberg dithering for representing colors missing in the color palette",
                "command": "pnmremap {{-ma|-mapfile}} {{path/to/palette_file.ppm}} {{-fs|-floyd}} {{path/to/input.pnm}} > {{path/to/output.pnm}}"
            },
            {
                "description": "Use the first color in the palette for representing colors missing in the color palette",
                "command": "pnmremap {{-ma|-mapfile}} {{path/to/palette_file.ppm}} {{-fi|-firstisdefault}} {{path/to/input.pnm}} > {{path/to/output.pnm}}"
            },
            {
                "description": "Use the specified color for representing colors missing in the color palette",
                "command": "pnmremap {{-ma|-mapfile}} {{path/to/palette_file.ppm}} {{-m|-missingcolor}} {{color}} {{path/to/input.pnm}} > {{path/to/output.pnm}}"
            }
        ]
    }
}