1User manual for old ppm funcLtiibornasr(y3)FunctionUsseMranmuaanlual for old ppm functions(3)
2
6 libppm - functions for PPM programs
7
10 #include <netpbm/ppm.h>
11 void ppm_init(int * argcP,
13 char * argv[]);
14 pixel ** ppm_allocarray(
16 int cols,int rows);
18 pixel * ppm_allocrow(int cols);
20 void ppm_freearray(pixel ** pixels,
22 int rows);
23 void ppm_freerow(pixel * pixelrow);
25 void ppm_readppminit(FILE * fp,
27 int * colsP,
28 int * rowsP,
29 pixval * maxvalP,int * formatP );
31 void ppm_readppmrow(FILE *fp,
33 pixel * pixelrow,
34 int cols,
35 pixval maxval,
36 int format);
37 pixel ** ppm_readppm(FILE * fp,
39 int * colsP,
40 int * rowsP,
41 pixvalP * maxvalP);
42 void ppm_writeppminit(FILE * fp,
44 int cols,
45 int rows,
46 pixval maxval,
47 int forceplain);
48 void ppm_writeppmrow(FILE * fp,
50 pixel * pixelrow,
51 int cols,
52 pixval maxval,
53 int forceplain);
54 void ppm_writeppm(FILE * fp,
56 pixel ** pixels,
57 int cols,
58 int rows,
59 pixval maxval,
60 int forceplain);
61 void ppm_writeppm(FILE * fp,
63 pixel ** pixels,
64 int cols,
65 int rows,
66 pixval maxval,
67 int forceplain);
68 void ppm_nextimage(FILE * file,
70 int * const eofP);
71 void ppm_check(FILE * file,
73 const enum pm_check_type check_type,
74 const int format,
75 const int cols,
76 const int rows,
77 const int maxval, enum pm_check_code * const retval);
78 typedef ... pixel;
80 typedef ... pixval;
82 #define PPM_MAXMAXVAL ...
84 #define PPM_OVERALLMAXVAL ...
86 #define PPM_FORMAT ...
88 #define RPPM_FORMAT ...
90 #define PPM_TYPE PPM_FORMAT
92 #define PPM_FORMAT_TYPE(format) ...
94 pixval PPM_GETR(pixel p)
96 pixval PPM_GETG(pixel p)
98 pixval PPM_GETB(pixel p)
100 void PPM_ASSIGN(pixel p,
102 pixval red,
103 pixval grn,
104 pixval blu)
105 int PPM_EQUAL(pixel p,
107 pixel q)
108 int PPM_ISGRAY(pixel p)
110 void
112 PPM_DEPTH(pixel newp,
113 pixel p,
114 pixval oldmaxval,
115 pixval newmaxval)
116 pixel ppm_parsecolor(char * colorname,
118 pixval maxval)
119 char * ppm_colorname(pixel * colorP,
121 pixval maxval,
122 int hexok)
123 void ppm_readcolornamefile(
125 const char *fileName,
126 int mustOpen,
127 colorhash_table * chtP,
128 const char *** colornamesP
129 )
130
134 These library functions are part of Netpbm(1).
135 TYPES AND CONSTANTS
138 Each pixel contains three pixvals, each of which should contain only
139 the values between 0 and PPM_MAXMAXVAL.
140 <H3 id="manipulating_pixels">MANIPULATING PIXELS</H3>
143 The macros PPM_GETR, PPM_GETG, and PPM_GETB retrieve the red, green, or
145 blue sample, respectively, from the given pixel.
146 The PPM_ASSIGN macro assigns the given values to the red, green, and
148 blue samples of the given pixel.
149 The PPM_EQUAL macro tests two pixels for equality.
151 The PPM_ISGRAY macro tests a pixel for being gray. It returns true if
153 and only if the color of pixel p is black, white, or gray.
154 The PPM_DEPTH macro scales the colors of pixel p according the old and
156 new maxvals and assigns the new values to newp. It is intended to make
157 writing ppmtowhatever easier.
158 The PPM_LUMIN, PPM_CHROM_R, and PPM_CHROM_B macros determine the lumi‐
160 nance, red chrominance, and blue chrominance, respectively, of the
161 pixel p. The scale of all these values is the same as the scale of the
162 input samples (i.e. 0 to maxval for luminance, -maxval/2 to maxval/2
163 for chrominance).
164 Note that the macros do it by floating point multiplication. If you
166 are computing these values over an entire image, it may be signifi‐
167 cantly faster to do it with multiplication tables instead. Compute all
168 the possible products once up front, then for each pixel, just look up
169 the products in the tables.
170 INITIALIZATION
173 ppm_init() is identical to pm_proginit.
174 ppm_init() is obsolete. Use pm_proginit() instead.
176 MEMORY MANAGEMENT
179 ppm_allocarray() allocates an array of pixels.
180 ppm_allocrow() allocates a row of the given number of pixels.
182 ppm_freearray() frees the array allocated with ppm_allocarray() con‐
184 taining the given number of rows.
185 ppm_freerow() frees a row of pixelss allocated with ppm_allocrow().
187 READING FILES
190 If a function in this section is called on a PBM or PGM format file, it
191 translates the PBM or PGM file into a PPM file on the fly and functions
192 as if it were called on the equivalent PPM file. The format value
193 returned by ppm_readppminit() is, however, not translated. It repre‐
194 sents the actual format of the PBM or PGM file.
195 ppm_readppminit() reads the header of a PPM file, returning all the
197 information from the header and leaving the file positioned just after
198 the header.
199 ppm_readppmrow() reads a row of pixels into the pixelrow array. for‐
201 mat, cols, and maxval are the values returned by ppm_readppminit().
202 ppm_readppm() reads an entire PPM image into memory, returning the
204 allocated array as its return value and returning the information from
205 the header as rows, cols, and maxval. This function combines
206 ppm_readppminit(), ppm_allocarray(), and ppm_readppmrow().
207 WRITING FILES
211 ppm_writeppminit() writes the header for a PPM file and leaves it posi‐
212 tioned just after the header.
213 forceplain is a logical value that tells ppm_writeppminit() to write a
215 header for a plain PPM format file, as opposed to a raw PPM format
216 file.
217 ppm_writeppmrow() writes the row pixelrow to a PPM file. For meaning‐
219 ful results, cols, maxval, and forceplain must be the same as was used
220 with ppm_writeppminit().
221 ppm_writeppm() write the header and all data for a PPM image. This
223 function combines ppm_writeppminit() and ppm_writeppmrow().
224 MISCELLANEOUS
227 ppm_nextimage() positions a PPM input file to the next image in it (so
228 that a subsequent ppm_readppminit() reads its header).
229 ppm_nextimage() is analogous to pbm_nextimage(), but works on PPM, PGM,
231 and PBM files.
232 ppm_check() checks for the common file integrity error where the file
234 is the wrong size to contain all the image data.
235 ppm_check() is analogous to pbm_check(), but works on PPM, PGM, and
237 PBM files.
238 COLOR
242 Luminance, Chrominance (YcbCr)
243 <code>
245 float PPM_LUMIN(pixel p);
246 float PPM_CHROM_B(pixel p);
247 float PPM_CHROM_R(pixel p);
248 </code>
249 PPM_LUMIN takes a pixel as an argument and returns the luminance of
251 that pixel, with the same maxval as the pixel (e.g. if the pixel's max‐
252 val is 255, a PPM_LUMIN value of 255 means fully luminant).
253 PPM_CHROM_B and PPM_CHROM_R are similar, for the red and blue chromi‐
255 nance values.
256 <CODE>
259 pixel
260 ppm_color_from_ycbcr(unsigned int y,
261 int cb,
262 int cr);
263 </CODE>
264 ppm_color_from_ycbcr() converts in the other direction. Given lumi‐
266 nance and chrominance, it returns a pixel value.
267 Hue, Saturation, Value (HSV)
269 <code>
271 struct hsv {
272 double h; /* hue (degrees) 0..360 */
273 double s; /* saturation (0-1) */
274 double v; /* value (0-1) */
275 };
276 </code>
277 <code>
279 pixel
280 ppm_color_from_hsv(struct hsv const hsv,
281 pixval const maxval);
282 </code>
283 <code>
285 struct hsv
286 ppm_hsv_from_color(pixel const color,
287 pixval const maxval);
288 </code>
289 These convert a color between from pixel (RGB) form and HSV.
291 <code>
293 pixval
294 ppm_saturation(pixel const p,
295 pixval const maxval);
296 </code>
297 This gives you the saturation of a color, as a pixval. (e.g. if the
299 saturation of p is 50% and maxval is 100, ppm_saturation() returns 50).
300 Berlin-Kay Color
303 Brent Berlin and Paul Kay in 1969 did a study which identified a set of
305 11 basic colors people universally recognize. They are:
306 · black
310 · gray
312 · white
314 · red
316 · orange
318 · yellow
320 · green
322 · blue
324 · violet
326 · purple
328 · brown
330 The bk_color type represents a color from this set:
333 <code>
335 typedef enum {
336 BKCOLOR_BLACK = 0,
337 BKCOLOR_GRAY,
338 BKCOLOR_WHITE,
339 BKCOLOR_RED,
340 BKCOLOR_ORANGE,
341 BKCOLOR_YELLOW,
342 BKCOLOR_GREEN,
343 BKCOLOR_BLUE,
344 BKCOLOR_VIOLET,
345 BKCOLOR_PURPLE,
346 BKCOLOR_BROWN
347 } bk_color;
348 </code>
349 You can use this as an index of an array, in which case you might also
351 want macro BKCOLOR_COUNT, which is the number of colors in the set
352 (11).
353 To translate between the bk_color type and the English names of the
355 colors, use ppm_bk_color_from_name() and ppm_name_from_bk_color():
356 <code>
358 bk_color
359 ppm_bk_color_from_name(const char * name);
360 const char *
362 ppm_name_from_bk_color(bk_color bkColor);
363 </code>
364 ppm_bk_color_from_color() tells you to which Berlin-Kay color a certain
366 color is closest, by way of a fuzzy color matching algorithm:
367 <code>
369 bk_color
370 ppm_bk_color_from_color(pixel color,
371 pixval maxval);
372 </code>
373 maxval is the maxval on which color is based.
375 ppm_color_from_bk_color() converts the opposite way: given a Berlin-Kay
377 color, it gives the color, in pixel form, that best represents it.
378 <code>
380 pixel
381 ppm_color_from_bk_color(bk_color bkColor,
382 pixval maxval);
383 </code>
384 maxval is the maxval on which the returned color is based.
386 All of the facilities in this section were new in Netpbm 10.34 (June
388 2006).
389 COLOR NAMES
392 System Color Dictionary
393 Netpbm uses the system's X11 color dictionary (usually in
395 /usr/lib/X11/rgb.txt). This is the same file the X Window System typi‐
396 cally uses to associate colors with their names.
397 The color dictionary that Netpbm uses is in the file whose name is the
399 value of the RGBDEF environment variable. If RGBDEF is not set, Netpbm
400 defaults to the first existing file from this list:
401 · /usr/lib/X11/rgb.txt
405 · /usr/openwinlib/rgb.txt
407 · /usr/X11R6/lib/X11/rgb.txt
409 You can see the color names from a typical X11 color dictionary, which
412 is probably very close to what is on your system, along with the col‐
413 ors, here ⟨http://www.swiss.ai.mit.edu/~jaffer/Color/x11.pdf⟩ . This
414 website (1) shows a bunch of other versions you could use.
415 Netpbm is packaged with a color dictionary. A standard Netpbm instal‐
417 lation installs this file as "misc/rgb.txt" in the Netpbm directory.
418 This color dictionary has colors from everywhere the Netpbm maintainer
419 could find them, and is a superset of XFree 86's color dictionary.
420 <H4 id="ppm_parsecolor">ppm_parsecolor</H4>
422 ppm_parsecolor() interprets a color specification and returns a pixel
424 of the color that it indicates. The color specification is ASCII text,
425 in one of these formats:
426 · a name, as defined in the system color dictionary ⟨#rgb.txt⟩ .
431 ·
434 An X11-style hexadecimal specifier: rgb:r/g/b, where r, g, and
435 b are each 1- to 4-digit hexadecimal numbers. For each, the
436 maxval is the maximum number that can be represented in the num‐
437 ber of hexadecimal digits given. Example: rgb:01/ff/8000 speci‐
438 fies 1/255 red intensity, maximum green intensity, and about
439 half blue intensity.
440 ·
443 An X11-style decimal specifier: rgbi:r/g/b, where r, g, and b
444 are floating point numbers from 0 to 1.
445 · an old-X11-style hexadecimal triple: #rgb, #rrggbb, #rrrgggbbb,
448 or #rrrrggggbbbb.
449 · A triplet of decimal floating point numbers from 0.0 to 1.0,
452 representing red, green, and blue intensities respectively, sep‐
453 arated by commas. E.g. 1.0,0.5,.25. This is for backwards com‐
454 patibility; it was in use before MIT came up with the similar
455 and preferred rgbi style).
456 If the color specification does not conform to any of these formats,
460 including the case that it is a name, but is not in the system color
461 dictionary, ppm_parsecolor() throwsanerror(1).
462 <h4 id="ppm_colorname">ppm_colorname</h4>
464 ppm_colorname() returns a string that describes the color of the given
466 pixel. If a system color dictionary ⟨#rgb.txt⟩ is available and the
467 color appears in it, ppm_colorname() returns the name of the color from
468 the file. If the color does not appear in a system color dictionary
469 and hexok is true, ppm_colorname() returns a hexadecimal color specifi‐
470 cation triple (#rrggbb). If a system color dictionary is available but
471 the color does not appear in it and hexok is false, ppm_colorname()
472 returns the name of the closest matching color in the color file.
473 Finally, if there is no system color dictionary available and hexok is
474 false, ppm_colorname() fails and throws an error ⟨liberror.html#error⟩
475 .
476 The string returned is in static libppm library storage which is over‐
478 written by every call to ppm_colorname().
479 <h4 id="ppm_readcolornamefile">ppm_readcolornamefile</h4>
482 ppm_readcolornamefile() reads the entire contents of the color dictio‐
484 nary in the file named fileName into data structures you can use to
485 access it easily.
486 The function returns all the color names as an array of null-terminated
488 strings. It mallocs the space for this array and returns its address
489 at colornamesP. (*colornamesP)[i] is the address of the first charac‐
490 ter in the null-terminated string that is the name of the ith color in
491 the dictionary.
492 The function also returns a colorhash_table (see COLOR INDEXING
494 ⟨#colorindex⟩ ) that matches all these color names up to the colors
495 they represent. It mallocs the space for the colorhash_table and
496 returns its address at chtP. The number that the colorhash_table asso‐
497 ciates with each color is the index into the color name array described
498 above of the name of that color.
499 You may specify a null pointer for fileName to indicate the default
501 color dictionary.
502 mustOpen is a boolean. If it is nonzero, the function fails and aborts
504 the program if it is unable to open the specified color dictionary
505 file. If it is zero, though, it simply treats an unopenable color dic‐
506 tionary as an empty one. The colorhash and color name array it returns
507 contain no colors or names.
508 ppm_readcolornamefile() was new in Netpbm 10.15 (April 2003).
510 COLOR INDEXING
514 Sometimes in processing images, you want to associate a value with a
515 particular color. Most often, that's because you're generating a color
516 mapped graphics format. In a color mapped graphics format, the raster
517 contains small numbers, and the file contains a color map that tells
518 what color each of those small numbers refers to. If your image has
519 only 256 colors, but each color takes 24 bits to describe, this can
520 make your output file much smaller than a straightforward RGB raster
521 would.
522 So, continuing the above example, say you have a pixel value for char‐
524 treuse and in your output file and you are going to represent char‐
525 treuse by the number 12. You need a data structure that allows your
526 program quickly to find out that the number for a chartreuse pixel is
527 12. Netpbm's color indexing data types and functions give you that.
528 colorhash_table is a C data type that associates an integer with each
530 of an arbitrary number of colors. It is a hash table, so it uses far
531 less space than an array indexed by the color's RGB values would.
532 The problem with a colorhash_table is that you can only look things up
534 in it. You can't find out what colors are in it. So Netpbm has
535 another data type for representing the same information, the poorly but
536 historically named colorhist_vector. A colorhist_vector is just an
537 array. Each entry represents a color and contains the color's value
538 (as a pixel) and the integer value associated with it. The entries are
539 filled in starting with subscript 0 and going consecutively up for the
540 number of colors in the histogram.
541 (The reason the name is poor is because a color histogram is only one
543 of many things that could be represented by it).
544 colorhash_table ppm_alloccolorhash()
546 This creates a colorhash_table using dynamically allocated storage.
548 There are no colors in it. If there is not enough storage, throws an
549 error ⟨liberror.html#error⟩ .
550 void ppm_freecolorhash()
552 This destroys a ppm_freecolorhash and frees all the storage associated
554 with it.
555 int ppm_addtocolorhash( colorhash_table cht, const pixel * const col‐
557 orP, const int value)
558 This adds the specified color to the specified colorhash_table
560 and associates the specified value with it.
561 You must ensure that the color you are adding isn't already present in
563 the colorhash_table.
564 There is no way to update an entry or delete an entry from a col‐
566 orhash_table.
567 int ppm_lookupcolor( const colorhash_table cht, const pixel * const
569 colorP )
570 This looks up the specified color in the specified colorhash_table. It
572 returns the integer value associated with that color.
573 If the specified color is not in the hash table, the function returns
575 -1. (So if you assign the value -1 to a color, the return value is
576 ambiguous).
577 colorhist_vector ppm_colorhashtocolorhist( const colorhash_table cht,
579 const int ncolors )
581 This converts a colorhash_table to a colorhist_vector. The return
583 value is a new colorhist_vector which you must eventually free with
584 ppm_freecolorhist().
585 ncolors is the number of colors in cht. If it has more colors than
587 that, ppm_colorhashtocolorhist does not create a colorhist_vector and
588 returns NULL.
589 colorhash_table ppm_colorhisttocolorhash( const colorhist_vector chv,
591 const int ncolors )
592 This poorly named function does not convert from a colorhist_vector to
594 a colorhash_table.
595 It does create a colorhash_table based on a colorhist_vector input, but
597 the integer value for a given color in the output is not the same as
598 the integer value for that same color in the input. ppm_colorhistto‐
599 colorhash() ignores the integer values in the input. In the output,
600 the integer value for a color is the index in the input colorhist_vec‐
601 tor for that color.
602 You can easily create a color map for an image by running ppm_compute‐
604 colorhist() over the image, then ppm_colorhisttocolorhash() over the
605 result. Now you can use ppm_lookupcolor() to find a unique color index
606 for any pixel in the input.
607 If the same color appears twice in the input, ppm_colorhisttocol‐
609 orhash() throws an error ⟨liberror.html#error⟩ .
610 ncolors is the number of colors in chv.
612 The return value is a new colorhash_table which you must eventually
614 free with ppm_freecolorhash().
615 COLOR HISTOGRAMS
618 The Netpbm libraries give you functions to examine a Netpbm image and
619 determine what colors are in it and how many pixels of each color are
620 in it. This information is known as a color histogram. Netpbm uses
621 its colorhash_table data type to represent a color histogram.
622 colorhash_table ppm_computecolorhash( pixel ** const pixels, const int
624 cols, const int rows, const int maxcolors, int* const colorsP )
625 This poorly but historically named function generates a colorhash_table
627 whose value for each color is the number of pixels in a specified image
628 that have that color. (I.e. a color histogram). As a bonus, it
629 returns the number of colors in the image.
630 (It's poorly named because not all colorhash_tables are color his‐
632 tograms, but that's all it generates).
633 pixels, cols, and rows describe the input image.
635 maxcolors is the maximum number of colors you want processed. If there
637 are more colors that that in the input image, ppm_computecolorhash()
638 returns NULL as its return value and stops processing as soon as it
639 discovers this. This makes it run faster and use less memory. One use
640 for maxcolors is when you just want to find out whether or not the
641 image has more than N colors and don't want to wait to generate a huge
642 color table if so. If you don't want any limit on the number of col‐
643 ors, specify maxcolors=0.
644 ppm_computecolorhash() returns the actual number of colors in the image
646 as *colorsP, but only if it is less than or equal to maxcolors.
647 colorhash_table ppm_computecolorhash2( FILE * const ifp, const int
649 cols, const int rows, const pixval maxval, const int format,
650 const int maxcolors, int* const colorsP )
652 This is the same as ppm_computecolorhash() except that instead of feed‐
654 ing it an array of pixels in storage, you give it an open file stream
655 and it reads the image from the file. The file must be positioned
656 after the header, at the raster. Upon return, the file is still open,
657 but its position is undefined.
658 maxval and format are the values for the image (i.e. information from
660 the file's header).
661 colorhist_vector ppm_computecolorhist( pixel ** pixels, int cols, int
663 rows, int maxcolors, int * colorsP )
664 This is like ppm_computecolorhash() except that it creates a col‐
666 orhist_vector instead of a colorhash_table.
667 If you supply a nonzero maxcolors argument, that is the maximum number
669 of colors you expect to find in the input image. If there are more
670 colors than you say in the image, ppm_computecolorhist() returns a null
671 pointer as its return value and nothing meaningful as *colorsP.
672 If not, the function returns the new colorhist_vector as its return
674 value and the actual number of colors in the image as *colorsP. The
675 returned array has space allocated for the specified number of colors
676 regardless of how many actually exist. The extra space is at the high
677 end of the array and is available for your use in expanding the col‐
678 orhist_vector.
679 If you specify maxcolors=0, there is no limit on the number of colors
681 returned and the return array has space for 5 extra colors at the high
682 end for your use in expanding the colorhist_vector.
683 colorhist_vector ppm_computecolorhist2( FILE * ifp, int cols, int rows,
685 int maxcolors, pixval maxval, int format, int * colorsP )
686 This is the same as ppm_computecolorhist() except that instead of feed‐
688 ing it an array of pixels in storage, you give it an open file stream
689 and it reads the image from the file. The file must be positioned
690 after the header, at the raster. Upon return, the file is still open,
691 but its position is undefined.
692
695 pbm(1), pgm(1), libpbm(1)
696
699 Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.
700netpbm documentation 8 SeptemberU2s0e0r7manual for old ppm functions(3)