| 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 "Pgmtoppm User Manual" 1 "02 October 2021" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
|
| 10 |
pgmtoppm - colorize a PGM (grayscale) image into a PPM (color) image |
| 11 |
|
| 12 |
.UN synopsis |
| 13 |
.SH SYNOPSIS |
| 14 |
|
| 15 |
\fBpgmtoppm\fP |
| 16 |
[\fB-black=\fP\fIcolorspec1\fP] |
| 17 |
[\fB-white=\fP\fIcolorspec2\fP] |
| 18 |
[\fIpgmfile\fP] |
| 19 |
\fBpgmtoppm\fP \fB-map=\fP\fIfilename\fP [\fIpgmfile\fP] |
| 20 |
\fBpgmtoppm\fP \fIcolorspec\fP [\fIpgmfile\fP] |
| 21 |
\fBpgmtoppm\fP \fIcolorspec1\fP\fB-\fP\fIcolorspec2\fP [\fIpgmfile\fP] |
| 22 |
.PP |
| 23 |
Minimum unique abbreviation of option is acceptable. You may use double |
| 24 |
hyphens instead of single hyphen to denote options. You may use white |
| 25 |
space in place of the equals sign to separate an option name from its value. |
| 26 |
|
| 27 |
.UN description |
| 28 |
.SH DESCRIPTION |
| 29 |
.PP |
| 30 |
This program is part of |
| 31 |
.BR "Netpbm" (1)\c |
| 32 |
\&. |
| 33 |
.PP |
| 34 |
If all you want to do is convert PGM to PPM, keeping the same gray pixels, |
| 35 |
you may not need to. All Netpbm programs that expect PPM input also |
| 36 |
recognize PGM. And if you must have a PPM file, use \fBppmtoppm\fP |
| 37 |
instead. It is more efficient and easier to use. |
| 38 |
.PP |
| 39 |
\fBpgmtoppm\fP reads a PGM as input and produces a PPM file as |
| 40 |
output with a specific color assigned to each gray value in the input. |
| 41 |
.PP |
| 42 |
You can specify the color in the output to which black in the input maps, |
| 43 |
and the color to which white maps. All the gray values in between map |
| 44 |
linearly (across a three dimensional space) to colors between the black and |
| 45 |
white colors you specify. |
| 46 |
.PP |
| 47 |
Use the \fB-black\fP and \fB-white\fP options for this. For historical |
| 48 |
reasons, you can alternatively use a non-option argument to specify the |
| 49 |
colors. If you do that, \fBpgmtoppm\fP interprets the color argument |
| 50 |
like this: if the argument takes the form \fIblack\fP-\fIwhite\fP, |
| 51 |
it has the effect of \fB-black=\fP\fIblack\fP \fB-white=\fP\fIwhite\fP |
| 52 |
If instead there is no hyphen in the color argument, it has the effect of |
| 53 |
\fB-white=\fP\fIcolor_argument\fP. |
| 54 |
.PP |
| 55 |
Because of the historical syntax, it is not possible to let both |
| 56 |
\fB-black\fP and \fB-white\fP default (but you shouldn't want to -- |
| 57 |
see below for advice on making such a null conversion). |
| 58 |
|
| 59 |
.PP |
| 60 |
You can alternatively specify an entire colormap with the \fB-map\fP |
| 61 |
option. |
| 62 |
|
| 63 |
.PP |
| 64 |
A more direct way to specify a particular color to replace each |
| 65 |
particular gray level is to use \fBpamlookup\fP. You make an index |
| 66 |
file that explicitly associates a color with each possible gray level. |
| 67 |
|
| 68 |
|
| 69 |
.UN options |
| 70 |
.SH OPTIONS |
| 71 |
.PP |
| 72 |
In addition to the options common to all programs based on libnetpbm |
| 73 |
(most notably \fB-quiet\fP, see |
| 74 |
.UR index.html#commonoptions |
| 75 |
Common Options |
| 76 |
.UE |
| 77 |
\&), \fBpgmtoppm\fP recognizes the following |
| 78 |
command line options: |
| 79 |
|
| 80 |
|
| 81 |
|
| 82 |
.TP |
| 83 |
\fB-black=\fP\fIcolorspec\fP |
| 84 |
The program maps black pixels in the input to this color in the output. |
| 85 |
The default is black. |
| 86 |
.sp |
| 87 |
Specify the color (\fIcolor\fP) as described for |
| 88 |
the |
| 89 |
.UR libnetpbm_image.html#colorname |
| 90 |
argument of the \fBpnm_parsecolor()\fP library routine |
| 91 |
.UE |
| 92 |
\&. |
| 93 |
.sp |
| 94 |
You cannot specify this together with \fB-map\fP. |
| 95 |
.sp |
| 96 |
This option was new in Netpbm 10.97 (December 2021). Before that, |
| 97 |
use the color argument. |
| 98 |
|
| 99 |
.TP |
| 100 |
\fB-white=\fP\fIcolorspec\fP |
| 101 |
The program maps white pixels in the input to this color in the output. |
| 102 |
The default is white. |
| 103 |
.sp |
| 104 |
Specify the color (\fIcolor\fP) as described for |
| 105 |
the |
| 106 |
.UR libnetpbm_image.html#colorname |
| 107 |
argument of the \fBpnm_parsecolor()\fP library routine |
| 108 |
.UE |
| 109 |
\&. |
| 110 |
.sp |
| 111 |
You cannot specify this together with \fB-map\fP. |
| 112 |
.sp |
| 113 |
This option was new in Netpbm 10.97 (December 2021). Before that, |
| 114 |
use the color argument. |
| 115 |
|
| 116 |
.TP |
| 117 |
\fB-map=\fP\fIfilename\fP |
| 118 |
This option specifies a complete mapping of gray values in the input to |
| 119 |
color values in the output. The map file (named \fIfilename\fP) is just |
| 120 |
a \fBppm\fP file; it can be any shape, all that matters is the colors in |
| 121 |
it and their order. In this case, black gets mapped into the first color |
| 122 |
in the map file, and white gets mapped to the last and gray values in |
| 123 |
between are mapped linearly onto the sequence of colors in between. The |
| 124 |
maxval of the output image is the maxval of the map image. |
| 125 |
|
| 126 |
|
| 127 |
|
| 128 |
|
| 129 |
.UN maxval |
| 130 |
.SH NOTE - MAXVAL |
| 131 |
.PP |
| 132 |
When you don't use \fB-map\fP, the "maxval," or depth, |
| 133 |
of the output image is the same as that of the input image. The |
| 134 |
maxval affects the color resolution, which may cause quantization |
| 135 |
errors you don't anticipate in your output. For example, you have a |
| 136 |
simple black and white image as a PGM with maxval 1. Run this image |
| 137 |
through \fBpgmtoppm 0f/00/00\fP to try to make the image black and |
| 138 |
faint red. Because the output image will also have maxval 1, there is |
| 139 |
no such thing as faint red. It has to be either full-on red or black. |
| 140 |
\fBpgmtoppm\fP rounds the color 0f/00/00 down to black, and you get |
| 141 |
an output image that is nothing but black. |
| 142 |
.PP |
| 143 |
The fix is easy: Pass the input through \fBpamdepth\fP on the way |
| 144 |
into \fBpgmtoppm\fP to increase its depth to something that would |
| 145 |
give you the resolution you need to get your desired color. In this |
| 146 |
case, \fBpamdepth 16\fP would do it. Or spare yourself the |
| 147 |
unnecessary thinking and just say \fBpamdepth 255\fP. |
| 148 |
.PP |
| 149 |
PBM input is a special case. While you might think this would be |
| 150 |
equivalent to a PGM with maxval 1 since only two gray levels are |
| 151 |
necessary to represent a PBM image, \fBpgmtoppm\fP, like all Netpbm |
| 152 |
programs, in fact treats it as a maxval of 255. |
| 153 |
|
| 154 |
.UN seealso |
| 155 |
.SH SEE ALSO |
| 156 |
.BR "ppmtoppm" (1)\c |
| 157 |
\&, |
| 158 |
.BR "pamdepth" (1)\c |
| 159 |
\&, |
| 160 |
.BR "rgb3toppm" (1)\c |
| 161 |
\&, |
| 162 |
.BR "ppmtopgm" (1)\c |
| 163 |
\&, |
| 164 |
.BR "ppmtorgb3" (1)\c |
| 165 |
\&, |
| 166 |
.BR "ppm" (1)\c |
| 167 |
\&, |
| 168 |
.BR "pgm" (1)\c |
| 169 |
\& |
| 170 |
|
| 171 |
.UN author |
| 172 |
.SH AUTHOR |
| 173 |
|
| 174 |
Copyright (C) 1991 by Jef Poskanzer. |
| 175 |
.SH DOCUMENT SOURCE |
| 176 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 177 |
source. The master documentation is at |
| 178 |
.IP |
| 179 |
.B http://netpbm.sourceforge.net/doc/pgmtoppm.html |
| 180 |
.PP |