| 1 |
\ |
| 2 |
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. |
| 3 |
.\" Do not hand-hack it! If you have bug fixes or improvements, please find |
| 4 |
.\" the corresponding HTML page on the Netpbm website, generate a patch |
| 5 |
.\" against that, and send it to the Netpbm maintainer. |
| 6 |
.TH "Pnmremap User Manual" 1 "13 November 2014" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
pnmremap - replace colors in a PNM image with colors from another set |
| 10 |
|
| 11 |
.UN synopsis |
| 12 |
.SH SYNOPSIS |
| 13 |
|
| 14 |
\fBpnmremap\fP |
| 15 |
|
| 16 |
\fB-mapfile=\fP\fIpalettefile\fP |
| 17 |
|
| 18 |
[\fB-floyd\fP|\fB-fs\fP|\fB-nfloyd\fP|\fB-nofs\fP] |
| 19 |
|
| 20 |
{[\fB-norandom\fP]|\fBrandomseed=\fP\fIn\fP} |
| 21 |
|
| 22 |
[\fB-firstisdefault\fP] |
| 23 |
|
| 24 |
[\fB-verbose\fP] |
| 25 |
|
| 26 |
[\fB-missingcolor=\fP\fIcolorspec\fP] |
| 27 |
|
| 28 |
[\fIpnmfile\fP] |
| 29 |
.PP |
| 30 |
All options can be abbreviated to their shortest unique prefix. |
| 31 |
You may use two hyphens instead of one to designate an option. You |
| 32 |
may use either white space or an equals sign between an option name |
| 33 |
and its value. |
| 34 |
|
| 35 |
.UN description |
| 36 |
.SH DESCRIPTION |
| 37 |
.PP |
| 38 |
This program is part of |
| 39 |
.BR "Netpbm" (1)\c |
| 40 |
\&. |
| 41 |
.PP |
| 42 |
\fBpnmremap\fP replaces the colors in an input image with those |
| 43 |
from a palette you specify. Where colors in the input are present in |
| 44 |
the palette, they just stay the same in the output. But where the |
| 45 |
input contains a color that is not in the palette, \fBpnmremap\fP |
| 46 |
gives you these choices: |
| 47 |
|
| 48 |
|
| 49 |
.IP \(bu |
| 50 |
Choose the closest color from the palette. |
| 51 |
|
| 52 |
.IP \(bu |
| 53 |
Choose the first color from the palette. |
| 54 |
|
| 55 |
.IP \(bu |
| 56 |
Use a color specified by a command option (\fB-missing\fP). |
| 57 |
|
| 58 |
.IP \(bu |
| 59 |
Dither. This means rather than mapping pixel by pixel, |
| 60 |
\fBpnmremap\fP uses colors from the palette to try to make |
| 61 |
multi-pixel regions of the output have the same average color as the |
| 62 |
input (for another kind of dithering, see \fBppmdither\fP). |
| 63 |
|
| 64 |
|
| 65 |
.PP |
| 66 |
Two reasons to use this program are: 1) you want to reduce the |
| 67 |
number of colors in the input image; and 2) you need to feed the image |
| 68 |
to something that can handle only certain colors. |
| 69 |
.PP |
| 70 |
To reduce colors, you can generate the palette with |
| 71 |
\fBpnmcolormap\fP. |
| 72 |
.PP |
| 73 |
By default, \fBpnmremap\fP maps an input color that is not in the |
| 74 |
palette to the closest color that \fIis\fP in the palette. Closest |
| 75 |
means with the smallest Cartesian distance in the red, green, blue |
| 76 |
brightness space (smallest sum of the squares of the differences in |
| 77 |
red, green, and blue ITU-R Recommendation BT.709 gamma-adjusted |
| 78 |
intensities). |
| 79 |
.PP |
| 80 |
You can instead specify a single default color for \fBpnmremap\fP |
| 81 |
to use for any color in the input image that is not in the palette. |
| 82 |
Use the \fB-missing\fP option for this. |
| 83 |
.PP |
| 84 |
You can also specify that the first color in the palette image |
| 85 |
is the default. Use the \fB-firstisdefault\fP option for this. |
| 86 |
.PP |
| 87 |
The palette is simply a PNM image. The colors of the pixels in the |
| 88 |
image are the colors in the palette. Where the pixels appear in the |
| 89 |
image, and the dimensions of the image, are irrelevant. Multiple |
| 90 |
pixels of the same color are fine. However, a palette image is |
| 91 |
typically a single row with one pixel per color. |
| 92 |
.PP |
| 93 |
If you specify \fB-missing\fP, the color you so specify is in |
| 94 |
the palette in addition to whatever is in the palette image. |
| 95 |
.PP |
| 96 |
For historical reasons, Netpbm sometimes calls the palette a |
| 97 |
"colormap." But it doesn't really map anything. |
| 98 |
\fBpnmremap\fP creates its own map, based on the palette, to map |
| 99 |
colors from the input image to output colors. |
| 100 |
|
| 101 |
.UN mismatch |
| 102 |
.SS Palette/Image Type Mismatch |
| 103 |
.PP |
| 104 |
In the simple case, the palette image is of the same depth (number |
| 105 |
of planes, i.e. number of components in each tuple (pixel)) as the |
| 106 |
input image and \fBpnmremap\fP just does a straightforward search of |
| 107 |
the palette for each input tuple (pixel). In fact, \fBpnmremap\fP |
| 108 |
doesn't even care if the image is a visual image. |
| 109 |
.PP |
| 110 |
But what about when the depths differ? In that case, |
| 111 |
\fBpnmremap\fP converts the input image (in its own memory) to match |
| 112 |
the palette and then proceeds as above. |
| 113 |
.PP |
| 114 |
There are only two such cases in which \fBpnmremap\fP knows how to |
| 115 |
do the conversion: when one of them is tuple type RGB, depth 3, and the |
| 116 |
other is tuple type GRAYSCALE or BLACKANDWHITE, depth 1; and vice |
| 117 |
versa. |
| 118 |
.PP |
| 119 |
In any other case, \fBpnmremap\fP issues and error message and fails. |
| 120 |
.PP |
| 121 |
Note that as long as your input and palette images are PNM, they'll |
| 122 |
always fall into one of the cases \fBpnmremap\fP can handle. There's an |
| 123 |
issue only if you're using some exotic PAM image. |
| 124 |
.PP |
| 125 |
Before Netpbm 10.27 (March 2005), \fBpnmremap\fP could not handle |
| 126 |
the case of a palette of greater depth than the input image. (It would |
| 127 |
issue an error message and fail in that case). You can use \fBppmtoppm\fP |
| 128 |
to increase the depth of the input image to work around this limitation. |
| 129 |
.PP |
| 130 |
In any case, the output image has the same tuple type and depth as |
| 131 |
the palette image. |
| 132 |
|
| 133 |
.UN multiple |
| 134 |
.SS Multiple Image Stream |
| 135 |
.PP |
| 136 |
\fBpnmremap\fP handles a multiple image input stream, producing a |
| 137 |
multiple image output stream. The input images need not be similar in |
| 138 |
any way. |
| 139 |
.PP |
| 140 |
Before Netpbm 10.30 (October 2005), \fBpnmremap\fP ignored any image |
| 141 |
after the first. |
| 142 |
|
| 143 |
|
| 144 |
.UN example |
| 145 |
.SS Examples |
| 146 |
|
| 147 |
.nf |
| 148 |
pnmcolormap testimg.ppm 256 >palette.ppm |
| 149 |
|
| 150 |
pnmremap -map=palette.ppm testimg.ppm >reduced_testimg.ppm |
| 151 |
|
| 152 |
.fi |
| 153 |
.PP |
| 154 |
To limit colors to a certain set, a typical example is to create an |
| 155 |
image for posting on the World Wide Web, where different browsers know |
| 156 |
different colors. But all browsers are supposed to know the 216 |
| 157 |
"web safe" colors which are essentially all the colors you |
| 158 |
can represent in a PPM image with a maxval of 5. So you can do this: |
| 159 |
|
| 160 |
.nf |
| 161 |
pamseq 3 5 >websafe.pam |
| 162 |
|
| 163 |
pnmremap -map=websafe.pam testimg.ppm >websafe_testimg.ppm |
| 164 |
|
| 165 |
.fi |
| 166 |
.PP |
| 167 |
Another useful palette is one for the 8 color IBM TTL color set, which |
| 168 |
you can create with |
| 169 |
.nf |
| 170 |
pamseq 3 1 >ibmttl.pam |
| 171 |
|
| 172 |
.fi |
| 173 |
.PP |
| 174 |
If you want to quantize one image to use the colors in another one, |
| 175 |
just use the second one as the palette. You don't have to reduce it |
| 176 |
down to only one pixel of each color, just use it as is. |
| 177 |
.PP |
| 178 |
The output image has the same type and maxval as the palette image. |
| 179 |
|
| 180 |
.UN parameters |
| 181 |
.SH PARAMETERS |
| 182 |
.PP |
| 183 |
There is one parameter, which is required: The file specification of |
| 184 |
the input PNM file. |
| 185 |
|
| 186 |
|
| 187 |
.UN options |
| 188 |
.SH OPTIONS |
| 189 |
.PP |
| 190 |
In addition to the options common to all programs based on libnetpbm |
| 191 |
(most notably \fB-quiet\fP, see |
| 192 |
.UR index.html#commonoptions |
| 193 |
Common Options |
| 194 |
.UE |
| 195 |
\&), \fBpnmremap\fP recognizes the following |
| 196 |
command line options: |
| 197 |
|
| 198 |
|
| 199 |
|
| 200 |
.TP |
| 201 |
\fB-mapfile=\fP\fIpalettefilename\fP |
| 202 |
This names the file that contains the palette image. |
| 203 |
.sp |
| 204 |
This option is mandatory. |
| 205 |
|
| 206 |
.TP |
| 207 |
\fB-floyd\fP |
| 208 |
.TP |
| 209 |
\fB-fs\fP |
| 210 |
.TP |
| 211 |
\fB-nofloyd\fP |
| 212 |
.TP |
| 213 |
\fB-nofs\fP |
| 214 |
These options determine whether \fBpnmremap\fP does Floyd-Steinberg |
| 215 |
dithering. Without Floyd-Steinberg, \fBpnmremap\fP selects the output color |
| 216 |
of a pixel based on the color of only the corresponding input pixel. With |
| 217 |
Floyd-Steinberg, \fBpnmremap\fP considers regions of pixels such that the |
| 218 |
average color of a region is the same in the output as in the input. The |
| 219 |
dithering effect appears as a dot pattern up close, but from a distance, the |
| 220 |
dots blend so that you see more colors than are present in the color map. |
| 221 |
.sp |
| 222 |
As an example, if your color map contains only black and white, and |
| 223 |
the input image has 4 adjacent pixels of gray, \fBpnmremap\fP with |
| 224 |
Floyd-Steinberg would generate output pixels black, white, black, white, |
| 225 |
which from a distance looks gray. But without Floyd-Steinberg, |
| 226 |
\fBpnmremap\fP would generate 4 white pixels, white being the single-pixel |
| 227 |
approximation of gray. |
| 228 |
.sp |
| 229 |
Floyd-Steinberg gives vastly better results on images where |
| 230 |
unmodified quantization has banding or other artifacts, especially |
| 231 |
when going to a small number of colors such as the above IBM set. |
| 232 |
However, it does take substantially more CPU time. |
| 233 |
.sp |
| 234 |
\fB-fs\fP is a synonym for \fB-floyd\fP. \fB-nofs\fP is a |
| 235 |
synonym for \fB-nofloyd\fP. |
| 236 |
.sp |
| 237 |
The default is \fB-nofloyd\fP. |
| 238 |
.sp |
| 239 |
Before Netpbm 10.46 (March 2009), dithering doesn't work quite as you |
| 240 |
expect if the color map has a lower maxval than the input. \fBpnmremap\fP |
| 241 |
reduces the color resolution to the color map's maxval before doing any |
| 242 |
dithering, so the dithering does not have the effect of making the image, |
| 243 |
at a distance, appear to have the original maxval. In current Netpbm, it |
| 244 |
does. |
| 245 |
|
| 246 |
.TP |
| 247 |
\fB-norandom\fP |
| 248 |
This option affects a detail of the Floyd-Steinberg dithering process. |
| 249 |
It has no effect if you aren't doing Floyd-Steinberg dithering. |
| 250 |
.sp |
| 251 |
By default, \fBpnmremap\fP initializes the error propagation |
| 252 |
accumulator to random values to avoid the appearance of unwanted |
| 253 |
patterns. This is an extension of the original Floyd-Steinberg |
| 254 |
algorithm. |
| 255 |
.sp |
| 256 |
A drawback of this is that the same \fBpnmremap\fP on the same |
| 257 |
input produces slightly different output every time, which makes |
| 258 |
comparison difficult. |
| 259 |
.sp |
| 260 |
With \fB-norandom\fP, \fBpnmremap\fP initializes the error |
| 261 |
accumulators to zero and the output is completely predictable. |
| 262 |
.sp |
| 263 |
Alternatively, you can use \fB-randomseed\fP to get randomization |
| 264 |
across the image, but still have repeatable results. |
| 265 |
.sp |
| 266 |
You cannot specify this along with \fB-randomseed\fP. |
| 267 |
.sp |
| 268 |
\fB-norandom\fP was new in Netpbm 10.39 (June 2007). |
| 269 |
|
| 270 |
|
| 271 |
.TP |
| 272 |
\fB-randomseed=\fP\fIn\fP |
| 273 |
This option affects a detail of the Floyd-Steinberg dithering process. |
| 274 |
It has no effect if you aren't doing Floyd-Steinberg dithering. |
| 275 |
.sp |
| 276 |
This option supplies the seed for the random number generator used in the |
| 277 |
randomization process described in the explanation of the \fB-norandom\fP |
| 278 |
option. If you run \fBpnmremap\fP twice with the same \fB-randomseed\fP |
| 279 |
value, you will get identical results. |
| 280 |
.sp |
| 281 |
If you do not specify \fB-randomseed\fP, \fBpnmremap\fP chooses a seed |
| 282 |
at random, adding another level of randomness to the dithering. |
| 283 |
.sp |
| 284 |
You cannot specify this along with \fB-norandom\fP. |
| 285 |
.sp |
| 286 |
This option was new in Netpbm 10.82 (March 2018). |
| 287 |
|
| 288 |
|
| 289 |
.TP |
| 290 |
\fB-firstisdefault\fP |
| 291 |
This tells \fBpnmremap\fP to map any input color that is not in |
| 292 |
the palette to the first color in the palette (the color of the pixel |
| 293 |
in the top left corner of the palette image) |
| 294 |
.sp |
| 295 |
See |
| 296 |
.UR #description |
| 297 |
DESCRIPTION |
| 298 |
.UE |
| 299 |
\&. |
| 300 |
.sp |
| 301 |
If you specify \fB-firstisdefault\fP, the maxval of your input |
| 302 |
must match the maxval of your palette image. |
| 303 |
|
| 304 |
.TP |
| 305 |
\fB-missingcolor=\fP\fIcolorspec\fP |
| 306 |
This specifies the default color for \fBpnmremap\fP to map to a |
| 307 |
color in the input image that isn't in the palette. \fIcolor\fP may |
| 308 |
or may not be in the palette image; it is part of the palette |
| 309 |
regardless. |
| 310 |
.sp |
| 311 |
\fIcolorspec\fP is as described for |
| 312 |
the |
| 313 |
.UR libnetpbm_image.html#colorname |
| 314 |
argument of the \fBpnm_parsecolor()\fP library routine |
| 315 |
.UE |
| 316 |
\&. |
| 317 |
.sp |
| 318 |
If you specify \fB-missingcolor\fP, the maxval of your input must |
| 319 |
match the maxval of your palette image. |
| 320 |
|
| 321 |
.TP |
| 322 |
\fB-verbose\fP |
| 323 |
Display helpful messages about the mapping process. |
| 324 |
|
| 325 |
|
| 326 |
|
| 327 |
|
| 328 |
.UN seealso |
| 329 |
.SH SEE ALSO |
| 330 |
.BR "pnmcolormap" (1)\c |
| 331 |
\&, |
| 332 |
.BR "pamlookup" (1)\c |
| 333 |
\&, |
| 334 |
.BR "pnmquant" (1)\c |
| 335 |
\&, |
| 336 |
.BR "ppmquantall" (1)\c |
| 337 |
\&, |
| 338 |
.BR "pamdepth" (1)\c |
| 339 |
\&, |
| 340 |
.BR "ppmdither" (1)\c |
| 341 |
\&, |
| 342 |
.BR "ppmquant" (1)\c |
| 343 |
\&, |
| 344 |
.BR "pamseq" (1)\c |
| 345 |
\&, |
| 346 |
.BR "ppm" (1)\c |
| 347 |
\& |
| 348 |
|
| 349 |
.UN history |
| 350 |
.SH HISTORY |
| 351 |
.PP |
| 352 |
\fBpnmremap\fP first appeared in Netpbm 9.23 (January 2002). |
| 353 |
Before that, its function was available only as part of the function |
| 354 |
of \fBpnmquant\fP (which was derived from the much older |
| 355 |
\fBppmquant\fP). Color quantization really has two main subfunctions, so |
| 356 |
Netpbm 9.23 split it out into two separate programs: |
| 357 |
\fBpnmcolormap\fP and \fBpnmremap\fP and then Netpbm 9.24 replaced |
| 358 |
\fBpnmquant\fP with a program that simply calls \fBpnmcolormap\fP and |
| 359 |
\fBpnmremap\fP. |
| 360 |
|
| 361 |
.UN author |
| 362 |
.SH AUTHOR |
| 363 |
|
| 364 |
Copyright (C) 1989, 1991 by Jef Poskanzer. |
| 365 |
.SH DOCUMENT SOURCE |
| 366 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 367 |
source. The master documentation is at |
| 368 |
.IP |
| 369 |
.B http://netpbm.sourceforge.net/doc/pnmremap.html |
| 370 |
.PP |