Pnmremap User Manual(1) General Commands Manual Pnmremap User Manual(1)
NAME
pnmremap - replace colors in a PNM image with colors from another set
SYNOPSIS
pnmremap
-mapfile=palettefile
[-floyd|-fs|-nfloyd|-nofs]
{[-norandom]|randomseed=n}
[-firstisdefault]
[-verbose]
[-missingcolor=colorspec]
[pnmfile]
All options can be abbreviated to their shortest unique prefix. You may
use two hyphens instead of one to designate an option. You may use ei-
ther white space or an equals sign between an option name and its value.
DESCRIPTION
This program is part of Netpbm(1).
pnmremap replaces the colors in an input image with those from a palette
you specify. Where colors in the input are present in the palette, they
just stay the same in the output. But where the input contains a color
that is not in the palette, pnmremap gives you these choices:
• Choose the closest color from the palette.
• Choose the first color from the palette.
• Use a color specified by a command option (-missing).
• Dither. This means rather than mapping pixel by pixel, pnmremap
uses colors from the palette to try to make multi-pixel regions
of the output have the same average color as the input (for an-
other kind of dithering, see ppmdither).
Two reasons to use this program are: 1) you want to reduce the number of
colors in the input image; and 2) you need to feed the image to some-
thing that can handle only certain colors.
To reduce colors, you can generate the palette with pnmcolormap.
By default, pnmremap maps an input color that is not in the palette to
the closest color that is in the palette. Closest means with the small-
est Cartesian distance in the red, green, blue brightness space (small-
est sum of the squares of the differences in red, green, and blue ITU-R
Recommendation BT.709 gamma-adjusted intensities).
You can instead specify a single default color for pnmremap to use for
any color in the input image that is not in the palette. Use the -miss-
ing option for this.
You can also specify that the first color in the palette image is the
default. Use the -firstisdefault option for this.
The palette is simply a PNM image. The colors of the pixels in the im-
age are the colors in the palette. Where the pixels appear in the im-
age, and the dimensions of the image, are irrelevant. Multiple pixels
of the same color are fine. However, a palette image is typically a
single row with one pixel per color.
If you specify -missing, the color you so specify is in the palette in
addition to whatever is in the palette image.
For historical reasons, Netpbm sometimes calls the palette a "colormap."
But it doesn't really map anything. pnmremap creates its own map, based
on the palette, to map colors from the input image to output colors.
Palette/Image Type Mismatch
In the simple case, the palette image is of the same depth (number of
planes, i.e. number of components in each tuple (pixel)) as the input
image and pnmremap just does a straightforward search of the palette for
each input tuple (pixel). In fact, pnmremap doesn't even care if the
image is a visual image.
But what about when the depths differ? In that case, pnmremap converts
the input image (in its own memory) to match the palette and then pro-
ceeds as above.
There are only two such cases in which pnmremap knows how to do the con-
version: when one of them is tuple type RGB, depth 3, and the other is
tuple type GRAYSCALE or BLACKANDWHITE, depth 1; and vice versa.
In any other case, pnmremap issues and error message and fails.
Note that as long as your input and palette images are PNM, they'll al-
ways fall into one of the cases pnmremap can handle. There's an issue
only if you're using some exotic PAM image.
Before Netpbm 10.27 (March 2005), pnmremap could not handle the case of
a palette of greater depth than the input image. (It would issue an er-
ror message and fail in that case). You can use ppmtoppm to increase
the depth of the input image to work around this limitation.
In any case, the output image has the same tuple type and depth as the
palette image.
Multiple Image Stream
pnmremap handles a multiple image input stream, producing a multiple im-
age output stream. The input images need not be similar in any way.
Before Netpbm 10.30 (October 2005), pnmremap ignored any image after the
first.
Examples
pnmcolormap testimg.ppm 256 >palette.ppm
pnmremap -map=palette.ppm testimg.ppm >reduced_testimg.ppm
To limit colors to a certain set, a typical example is to create an im-
age for posting on the World Wide Web, where different browsers know
different colors. But all browsers are supposed to know the 216 "web
safe" colors which are essentially all the colors you can represent in a
PPM image with a maxval of 5. So you can do this:
pamseq 3 5 >websafe.pam
pnmremap -map=websafe.pam testimg.ppm >websafe_testimg.ppm
Another useful palette is one for the 8 color IBM TTL color set, which
you can create with
pamseq 3 1 >ibmttl.pam
If you want to quantize one image to use the colors in another one, just
use the second one as the palette. You don't have to reduce it down to
only one pixel of each color, just use it as is.
The output image has the same type and maxval as the palette image.
PARAMETERS
There is one parameter, which is required: The file specification of the
input PNM file.
OPTIONS
In addition to the options common to all programs based on libnetpbm
(most notably -quiet, see ]8;;index.html#commonoptions\ Common Options]8;;\ ), pnmremap recognizes the
following command line options:
-mapfile=palettefilename
This names the file that contains the palette image.
This option is mandatory.
-floyd
-fs
-nofloyd
-nofs These options determine whether pnmremap does Floyd-Steinberg
dithering. Without Floyd-Steinberg, pnmremap selects the output
color of a pixel based on the color of only the corresponding in-
put 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 un-
modified 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.
-norandom
This option affects a detail of the Floyd-Steinberg dithering
process. It has no effect if you aren't doing Floyd-Steinberg
dithering.
By default, pnmremap initializes the error propagation accumula-
tor to random values to avoid the appearance of unwanted pat-
terns. This is an extension of the original Floyd-Steinberg al-
gorithm.
A drawback of this is that the same pnmremap on the same input
produces slightly different output every time, which makes com-
parison 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).
-randomseed=n
This option affects a detail of the Floyd-Steinberg dithering
process. It has no effect if you aren't doing Floyd-Steinberg
dithering.
This option supplies the seed for the random number generator
used in the randomization process described in the explanation of
the -norandom option. If you run pnmremap 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).
-firstisdefault
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 image)
See ]8;;#description\DESCRIPTION]8;;\ .
If you specify -firstisdefault, the maxval of your input must
match the maxval of your palette image.
-missingcolor=colorspec
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 regard-
less.
colorspec is as described for the ]8;;libnetpbm_image.html#colorname\argument of the pnm_parsec-
olor() library routine]8;;\ .
If you specify -missingcolor, the maxval of your input must match
the maxval of your palette image.
-verbose
Display helpful messages about the mapping process.
SEE ALSO
pnmcolormap(1), pamlookup(1), pnmquant(1), ppmquantall(1), pamdepth(1),
ppmdither(1), ppmquant(1), pamseq(1), ppm(1)
HISTORY
pnmremap first appeared in Netpbm 9.23 (January 2002). Before that, its
function was available only as part of the function of pnmquant (which
was derived from the much older ppmquant). Color quantization really
has two main subfunctions, so Netpbm 9.23 split it out into two separate
programs: pnmcolormap and pnmremap and then Netpbm 9.24 replaced pn-
mquant with a program that simply calls pnmcolormap and pnmremap.
AUTHOR
Copyright (C) 1989, 1991 by Jef Poskanzer.
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/pnmremap.html
netpbm documentation 13 November 2014 Pnmremap User Manual(1)
Generated by dwww version 1.16 on Tue Dec 16 04:34:57 CET 2025.