Debian Codegraph @

upstream/debian-unstable/man1/pgmtoppm.1

raw
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