| 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 "Ppmhist User Manual" 1 "24 August 2019" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
ppmhist - print a histogram of the colors in a PPM image |
| 10 |
|
| 11 |
.UN synopsis |
| 12 |
.SH SYNOPSIS |
| 13 |
|
| 14 |
\fBppmhist\fP |
| 15 |
[\fB-map\fP | \fB-nomap\fP] |
| 16 |
[\fB-hexcolor\fP | \fB-float\fP | \fB-colorname\fP] |
| 17 |
[\fB-noheader\fP] |
| 18 |
[\fB-sort=\fP{\fBfrequency\fP,\fBrgb\fP}] |
| 19 |
[\fB-forensic\fP] |
| 20 |
[\fIppmfile\fP] |
| 21 |
|
| 22 |
.UN description |
| 23 |
.SH DESCRIPTION |
| 24 |
.PP |
| 25 |
This program is part of |
| 26 |
.BR "Netpbm" (1)\c |
| 27 |
\&. |
| 28 |
.PP |
| 29 |
\fBppmhist\fP reads a PPM image as input and generates a histogram |
| 30 |
of the colors in the image, i.e. a list of all the colors and how many |
| 31 |
pixels of each color are in the image. |
| 32 |
|
| 33 |
.UN output |
| 34 |
.SS Output Format |
| 35 |
.PP |
| 36 |
The output is in one of two basic formats: a report for humans |
| 37 |
and a PPM image for use by programs. The PPM image is actually quite |
| 38 |
readable by humans too. |
| 39 |
|
| 40 |
.B Human Report |
| 41 |
.PP |
| 42 |
You get this format by specifying (or defaulting to) the |
| 43 |
\fB-nomap\fP option. |
| 44 |
.PP |
| 45 |
The format is one line for each color in the input image. |
| 46 |
.PP |
| 47 |
By default, there are two lines of column header and a summary at the top. |
| 48 |
Use the \fB-noheader\fP option to suppress those lines. |
| 49 |
.PP |
| 50 |
The summary tells you whether black or white are present and how many |
| 51 |
shades of gray and color are present. The summary was new in Netpbm 10.82 |
| 52 |
(March 2018). |
| 53 |
|
| 54 |
.PP |
| 55 |
In each line, \fBppmhist\fP identifies the color by red, green, |
| 56 |
and blue components. By default, it lists each of these in decimal, |
| 57 |
using the exact values that are in the PPM input. So if the image has |
| 58 |
a maxval of 255, the numbers in the listing range from 0 to 255. With |
| 59 |
the \fB-hexcolor\fP option, you can change these numbers to |
| 60 |
hexadecimal. With the \fB-float\fP option, the numbers are |
| 61 |
fractional, adjusted to a maxval of 1. |
| 62 |
.PP |
| 63 |
Each line lists the luminosity of the color. It is in decimal |
| 64 |
on the same scale as the rgb values (see above). |
| 65 |
.PP |
| 66 |
Each line lists the number of pixels in the image that have the color. |
| 67 |
This is in decimal. |
| 68 |
|
| 69 |
|
| 70 |
.B PPM Output |
| 71 |
.PP |
| 72 |
You get this format with the \fB-map\fP option. |
| 73 |
.PP |
| 74 |
The output file is a genuine PPM image, but it is PPM Plain format |
| 75 |
and contains comments so that it is not a lot different from the |
| 76 |
human report described above. |
| 77 |
.PP |
| 78 |
As a PPM image, it can be useful as input to other programs that |
| 79 |
need some kind of palette. The image is a single row with one |
| 80 |
column for each distinct color in the image. |
| 81 |
.PP |
| 82 |
The function of PPM output is essentially the same as the output of |
| 83 |
\fBpnmcolormap all\fP. \fBppmhist\fP is much older than \fBpnmcolormap\fP. |
| 84 |
|
| 85 |
|
| 86 |
.UN options |
| 87 |
.SH OPTIONS |
| 88 |
.PP |
| 89 |
In addition to the options common to all programs based on libnetpbm |
| 90 |
(most notably \fB-quiet\fP, see |
| 91 |
.UR index.html#commonoptions |
| 92 |
Common Options |
| 93 |
.UE |
| 94 |
\&), \fBppmhist\fP recognizes the following |
| 95 |
command line options: |
| 96 |
|
| 97 |
|
| 98 |
|
| 99 |
.TP |
| 100 |
\fB-sort=\fP{\fBfrequency\fP,\fBrgb\fP} |
| 101 |
The \fB-sort\fP option determines the order in which the colors are |
| 102 |
listed in the output. \fBrgb\fP means to sort them first by the intensity of |
| 103 |
the red component of the color, then of the green, then of the blue, with the |
| 104 |
least intense first. \fBfrequency\fP means to list them in order of how many |
| 105 |
pixels in the input image have the color, with the most represented colors |
| 106 |
first. Among colors with the same frequency, the order is the same as with |
| 107 |
\fBrgb\fP. |
| 108 |
.sp |
| 109 |
The default is \fBfrequency\fP. |
| 110 |
.sp |
| 111 |
Before Netpbm 10.88 (September 2019), with \fB-sort=frequency\fP, the |
| 112 |
order of colors that have the same frequency is arbitrary. |
| 113 |
|
| 114 |
.TP |
| 115 |
\fB-hexcolor\fP |
| 116 |
Print the color components in hexadecimal. See |
| 117 |
.UR #output |
| 118 |
output format |
| 119 |
.UE |
| 120 |
\&. |
| 121 |
.sp |
| 122 |
You may not specify this option along with \fB-float\fP or \fBmap\fP. |
| 123 |
|
| 124 |
.TP |
| 125 |
\fB-float\fP |
| 126 |
Print the color components and the luminosity as floating point |
| 127 |
numbers in the range [0,1]. See |
| 128 |
.UR #output |
| 129 |
output format |
| 130 |
.UE |
| 131 |
\&. |
| 132 |
.sp |
| 133 |
You may not specify this option along with \fB-hexcolor\fP or \fBmap\fP. |
| 134 |
.sp |
| 135 |
This option was added in Netpbm 10.19 (November 2003). |
| 136 |
|
| 137 |
.TP |
| 138 |
\fB-map\fP |
| 139 |
Generates a PPM file of the colormap for the image, with the |
| 140 |
color histogram as comments. See |
| 141 |
.UR #output |
| 142 |
output format |
| 143 |
.UE |
| 144 |
\&. |
| 145 |
.sp |
| 146 |
You may not specify this option along with \fB-float\fP or \fBhexcolor\fP. |
| 147 |
|
| 148 |
.TP |
| 149 |
\fB-nomap\fP |
| 150 |
Generates the histogram for human reading. This is the default. |
| 151 |
|
| 152 |
.TP |
| 153 |
\fB-colorname\fP |
| 154 |
Add the color name to the output. This is the name from |
| 155 |
the |
| 156 |
.UR libppm.html#dictionary |
| 157 |
system color dictionary |
| 158 |
.UE |
| 159 |
\&. If the |
| 160 |
exact color is not in the color dictionary, it is an asterisk followed by the |
| 161 |
name of the closest color that is in the dictionary. If you don't have a |
| 162 |
system color dictionary, the program fails. |
| 163 |
.sp |
| 164 |
This option was added in Netpbm 10.10 (October 2002). |
| 165 |
|
| 166 |
.TP |
| 167 |
\fB-noheader\fP |
| 168 |
Do not print the column headings. |
| 169 |
|
| 170 |
.TP |
| 171 |
\fB-forensic\fP |
| 172 |
.sp |
| 173 |
With this option, \fBppmhist\fP works on images that contain invalid sample |
| 174 |
values. Normally, like most Netpbm programs, \fBppmhist\fP fails if it |
| 175 |
encounters a sample value greater than the maxval that the image declares. The |
| 176 |
presence of such a value means the image is invalid, so the pixels have no |
| 177 |
meaning. But with \fB-forensic\fP, \fBppmhist\fP produces a histogram |
| 178 |
of the actual sample values without regard to maxval. It issues messages |
| 179 |
summarizing the invalid pixels if there are any. |
| 180 |
.sp |
| 181 |
One use for this is to diagnose the problem that caused the invalid Netpbm |
| 182 |
image to exist. |
| 183 |
.sp |
| 184 |
There is a small exception to the ability of \fBppmhist\fP to process |
| 185 |
invalid pixels even with \fB-forensic\fP: it can never process a sample value |
| 186 |
greater than 65535. Note that in the rarely used Plain PPM format, it is |
| 187 |
possible for a number greater than that to appear where a sample value |
| 188 |
belongs. |
| 189 |
.sp |
| 190 |
This option was new in Netpbm 10.66 (March 2014). But Netpbm older than |
| 191 |
10.66 does not properly reject invalid sample values, so the effect is very |
| 192 |
similar to \fB-forensic\fP. |
| 193 |
|
| 194 |
|
| 195 |
|
| 196 |
.UN seealso |
| 197 |
.SH SEE ALSO |
| 198 |
.BR "ppm" (1)\c |
| 199 |
\&, |
| 200 |
.BR "pgmhist" (1)\c |
| 201 |
\&, |
| 202 |
.BR "pnmcolormap" (1)\c |
| 203 |
\&, |
| 204 |
.BR "pnmhistmap" (1)\c |
| 205 |
\&, |
| 206 |
.BR "ppmchange" (1)\c |
| 207 |
\& |
| 208 |
|
| 209 |
.UN author |
| 210 |
.SH AUTHOR |
| 211 |
|
| 212 |
Copyright (C) 1989 by Jef Poskanzer. |
| 213 |
.SH DOCUMENT SOURCE |
| 214 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 215 |
source. The master documentation is at |
| 216 |
.IP |
| 217 |
.B http://netpbm.sourceforge.net/doc/ppmhist.html |
| 218 |
.PP |