SYNOPSIS
pnmremap

-mapfile=palettefile

[-floyd|-fs|-nfloyd|-nofs]

[-norandom]

[-firstisdefault]

[-verbose]

[-missingcolor=color]

[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 either white space or an equals sign between an option name and
its value.


DESCRIPTION
This program is part of Netpbm.

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, pnm-



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
something 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
smallest cartesian distance in the red, green, blue brightness space
(smallest sum of the squares of the differences in red, green, and
blue ITU-R Recommedation 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
-missing 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
image are the colors in the palette. Where the pixels appear in the
image, and the dimensions of the image, are irrelevant. Multiple pix-
els 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 'col-
ormap.' But it doesn't really map anything. pnmremap creates its own
map, based on the palette, to map colors from the input image to out-
put 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 con-
verts the input image (in its own memory) to match the palette and
then proceeds as above.

There are only two such cases in which pnmremap knows how to do the
conversion: 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
always 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 error message and fail in that case).

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
image 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
image 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
-mapfile=palettefilename



-floyd

-fs

-nofloyd

-nofs These options determine whether Floyd-Steinberg dithering is






-norandom







-firstisdefault




-missingcolor=color



-verbose





SEE ALSO
pnmcolormap, pamseq, pnmquant, ppmquantall, pamdepth,
ppmdither, ppmquant, ppm


AUTHOR
Copyright (C) 1989, 1991 by Jef Poskanzer.



netpbm documentation 01 January 2002 Pnmremap User Manual(0)