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 MANIPULATING PIXELS
144 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 float PPM_LUMIN(pixel p);
245 float PPM_CHROM_B(pixel p);
246 float PPM_CHROM_R(pixel p);
247 PPM_LUMIN takes a pixel as an argument and returns the luminance of
249 that pixel, with the same maxval as the pixel (e.g. if the pixel's max‐
250 val is 255, a PPM_LUMIN value of 255 means fully luminant).
251 PPM_CHROM_B and PPM_CHROM_R are similar, for the red and blue chromi‐
253 nance values.
254 pixel
257 ppm_color_from_ycbcr(unsigned int y,
258 int cb,
259 int cr);
260 ppm_color_from_ycbcr() converts in the other direction. Given lumi‐
262 nance and chrominance, it returns a pixel value.
263 Hue, Saturation, Value (HSV)
265 struct hsv {
267 double h; /* hue (degrees) 0..360 */
268 double s; /* saturation (0-1) */
269 double v; /* value (0-1) */
270 };
271 pixel
273 ppm_color_from_hsv(struct hsv const hsv,
274 pixval const maxval);
275 struct hsv
277 ppm_hsv_from_color(pixel const color,
278 pixval const maxval);
279 These convert a color between from pixel (RGB) form and HSV.
281 pixval
283 ppm_saturation(pixel const p,
284 pixval const maxval);
285 This gives you the saturation of a color, as a pixval. (e.g. if the
287 saturation of p is 50% and maxval is 100, ppm_saturation() returns 50).
288 Berlin-Kay Color
291 Brent Berlin and Paul Kay in 1969 did a study which identified a set of
293 11 basic colors people universally recognize. They are:
294 · black
298 · gray
300 · white
302 · red
304 · orange
306 · yellow
308 · green
310 · blue
312 · violet
314 · purple
316 · brown
318 The bk_color type represents a color from this set:
321 typedef enum {
323 BKCOLOR_BLACK = 0,
324 BKCOLOR_GRAY,
325 BKCOLOR_WHITE,
326 BKCOLOR_RED,
327 BKCOLOR_ORANGE,
328 BKCOLOR_YELLOW,
329 BKCOLOR_GREEN,
330 BKCOLOR_BLUE,
331 BKCOLOR_VIOLET,
332 BKCOLOR_PURPLE,
333 BKCOLOR_BROWN
334 } bk_color;
335 You can use this as an index of an array, in which case you might also
337 want macro BKCOLOR_COUNT, which is the number of colors in the set
338 (11).
339 To translate between the bk_color type and the English names of the
341 colors, use ppm_bk_color_from_name() and ppm_name_from_bk_color():
342 bk_color
344 ppm_bk_color_from_name(const char * name);
345 const char *
347 ppm_name_from_bk_color(bk_color bkColor);
348 ppm_bk_color_from_color() tells you to which Berlin-Kay color a certain
350 color is closest, by way of a fuzzy color matching algorithm:
351 bk_color
353 ppm_bk_color_from_color(pixel color,
354 pixval maxval);
355 maxval is the maxval on which color is based.
357 ppm_color_from_bk_color() converts the opposite way: given a Berlin-Kay
359 color, it gives the color, in pixel form, that best represents it.
360 pixel
362 ppm_color_from_bk_color(bk_color bkColor,
363 pixval maxval);
364 maxval is the maxval on which the returned color is based.
366 All of the facilities in this section were new in Netpbm 10.34 (June
368 2006).
369 COLOR NAMES
372 System Color Dictionary
373 Netpbm uses the system's X11 color dictionary (usually in
375 /usr/lib/X11/rgb.txt). This is the same file the X Window System typi‐
376 cally uses to associate colors with their names.
377 The color dictionary that Netpbm uses is in the file whose name is the
379 value of the RGBDEF environment variable. If RGBDEF is not set, Netpbm
380 defaults to the first existing file from this list:
381 · /usr/lib/X11/rgb.txt
385 · /usr/openwinlib/rgb.txt
387 · /usr/X11R6/lib/X11/rgb.txt
389 You can see the color names from a typical X11 color dictionary, which
392 is probably very close to what is on your system, along with the col‐
393 ors, here ⟨http://www.swiss.ai.mit.edu/~jaffer/Color/x11.pdf⟩ . This
394 website (1) shows a bunch of other versions you could use.
395 Netpbm is packaged with a color dictionary. A standard Netpbm instal‐
397 lation installs this file as "misc/rgb.txt" in the Netpbm directory.
398 This color dictionary has colors from everywhere the Netpbm maintainer
399 could find them, and is a superset of XFree 86's color dictionary.
400 ppm_parsecolor
402 ppm_parsecolor() interprets a color specification and returns a pixel
404 of the color that it indicates. The color specification is ASCII text,
405 in one of these formats:
406 · a name, as defined in the system color dictionary ⟨#rgb.txt⟩ .
411 ·
414 An X11-style hexadecimal specifier: rgb:r/g/b, where r, g, and
415 b are each 1- to 4-digit hexadecimal numbers. For each, the
416 maxval is the maximum number that can be represented in the num‐
417 ber of hexadecimal digits given. Example: rgb:01/ff/8000 speci‐
418 fies 1/255 red intensity, maximum green intensity, and about
419 half blue intensity.
420 ·
423 An X11-style decimal specifier: rgbi:r/g/b, where r, g, and b
424 are floating point numbers from 0 to 1.
425 · an old-X11-style hexadecimal triple: #rgb, #rrggbb, #rrrgggbbb,
428 or #rrrrggggbbbb.
429 · A triplet of decimal floating point numbers from 0.0 to 1.0,
432 representing red, green, and blue intensities respectively, sep‐
433 arated by commas. E.g. 1.0,0.5,.25. This is for backwards com‐
434 patibility; it was in use before MIT came up with the similar
435 and preferred rgbi style).
436 If the color specification does not conform to any of these formats,
440 including the case that it is a name, but is not in the system color
441 dictionary, ppm_parsecolor() throwsanerror(1).
442 ppm_colorname
444 ppm_colorname() returns a string that describes the color of the given
446 pixel. If a system color dictionary ⟨#rgb.txt⟩ is available and the
447 color appears in it, ppm_colorname() returns the name of the color from
448 the file. If the color does not appear in a system color dictionary
449 and hexok is true, ppm_colorname() returns a hexadecimal color specifi‐
450 cation triple (#rrggbb). If a system color dictionary is available but
451 the color does not appear in it and hexok is false, ppm_colorname()
452 returns the name of the closest matching color in the color file.
453 Finally, if there is no system color dictionary available and hexok is
454 false, ppm_colorname() fails and throws an error ⟨liberror.html#error⟩
455 .
456 The string returned is in static libppm library storage which is over‐
458 written by every call to ppm_colorname().
459 ppm_readcolornamefile
462 ppm_readcolornamefile() reads the entire contents of the color dictio‐
464 nary in the file named fileName into data structures you can use to
465 access it easily.
466 The function returns all the color names as an array of null-terminated
468 strings. It mallocs the space for this array and returns its address
469 at colornamesP. (*colornamesP)[i] is the address of the first charac‐
470 ter in the null-terminated string that is the name of the ith color in
471 the dictionary.
472 The function also returns a colorhash_table (see COLOR INDEXING
474 ⟨#colorindex⟩ ) that matches all these color names up to the colors
475 they represent. It mallocs the space for the colorhash_table and
476 returns its address at chtP. The number that the colorhash_table asso‐
477 ciates with each color is the index into the color name array described
478 above of the name of that color.
479 You may specify a null pointer for fileName to indicate the default
481 color dictionary.
482 mustOpen is a boolean. If it is nonzero, the function fails and aborts
484 the program if it is unable to open the specified color dictionary
485 file. If it is zero, though, it simply treats an unopenable color dic‐
486 tionary as an empty one. The colorhash and color name array it returns
487 contain no colors or names.
488 ppm_readcolornamefile() was new in Netpbm 10.15 (April 2003).
490 COLOR INDEXING
494 Sometimes in processing images, you want to associate a value with a
495 particular color. Most often, that's because you're generating a color
496 mapped graphics format. In a color mapped graphics format, the raster
497 contains small numbers, and the file contains a color map that tells
498 what color each of those small numbers refers to. If your image has
499 only 256 colors, but each color takes 24 bits to describe, this can
500 make your output file much smaller than a straightforward RGB raster
501 would.
502 So, continuing the above example, say you have a pixel value for char‐
504 treuse and in your output file and you are going to represent char‐
505 treuse by the number 12. You need a data structure that allows your
506 program quickly to find out that the number for a chartreuse pixel is
507 12. Netpbm's color indexing data types and functions give you that.
508 colorhash_table is a C data type that associates an integer with each
510 of an arbitrary number of colors. It is a hash table, so it uses far
511 less space than an array indexed by the color's RGB values would.
512 The problem with a colorhash_table is that you can only look things up
514 in it. You can't find out what colors are in it. So Netpbm has
515 another data type for representing the same information, the poorly but
516 historically named colorhist_vector. A colorhist_vector is just an
517 array. Each entry represents a color and contains the color's value
518 (as a pixel) and the integer value associated with it. The entries are
519 filled in starting with subscript 0 and going consecutively up for the
520 number of colors in the histogram.
521 (The reason the name is poor is because a color histogram is only one
523 of many things that could be represented by it).
524 colorhash_table ppm_alloccolorhash()
526 This creates a colorhash_table using dynamically allocated storage.
528 There are no colors in it. If there is not enough storage, throws an
529 error ⟨liberror.html#error⟩ .
530 void ppm_freecolorhash()
532 This destroys a ppm_freecolorhash and frees all the storage associated
534 with it.
535 int ppm_addtocolorhash( colorhash_table cht, const pixel * const col‐
537 orP, const int value)
538 This adds the specified color to the specified colorhash_table
540 and associates the specified value with it.
541 You must ensure that the color you are adding isn't already present in
543 the colorhash_table.
544 There is no way to update an entry or delete an entry from a col‐
546 orhash_table.
547 int ppm_lookupcolor( const colorhash_table cht, const pixel * const
549 colorP )
550 This looks up the specified color in the specified colorhash_table. It
552 returns the integer value associated with that color.
553 If the specified color is not in the hash table, the function returns
555 -1. (So if you assign the value -1 to a color, the return value is
556 ambiguous).
557 colorhist_vector ppm_colorhashtocolorhist( const colorhash_table cht,
559 const int ncolors )
561 This converts a colorhash_table to a colorhist_vector. The return
563 value is a new colorhist_vector which you must eventually free with
564 ppm_freecolorhist().
565 ncolors is the number of colors in cht. If it has more colors than
567 that, ppm_colorhashtocolorhist does not create a colorhist_vector and
568 returns NULL.
569 colorhash_table ppm_colorhisttocolorhash( const colorhist_vector chv,
571 const int ncolors )
572 This poorly named function does not convert from a colorhist_vector to
574 a colorhash_table.
575 It does create a colorhash_table based on a colorhist_vector input, but
577 the integer value for a given color in the output is not the same as
578 the integer value for that same color in the input. ppm_colorhistto‐
579 colorhash() ignores the integer values in the input. In the output,
580 the integer value for a color is the index in the input colorhist_vec‐
581 tor for that color.
582 You can easily create a color map for an image by running ppm_compute‐
584 colorhist() over the image, then ppm_colorhisttocolorhash() over the
585 result. Now you can use ppm_lookupcolor() to find a unique color index
586 for any pixel in the input.
587 If the same color appears twice in the input, ppm_colorhisttocol‐
589 orhash() throws an error ⟨liberror.html#error⟩ .
590 ncolors is the number of colors in chv.
592 The return value is a new colorhash_table which you must eventually
594 free with ppm_freecolorhash().
595 COLOR HISTOGRAMS
598 The Netpbm libraries give you functions to examine a Netpbm image and
599 determine what colors are in it and how many pixels of each color are
600 in it. This information is known as a color histogram. Netpbm uses
601 its colorhash_table data type to represent a color histogram.
602 colorhash_table ppm_computecolorhash( pixel ** const pixels, const int
604 cols, const int rows, const int maxcolors, int* const colorsP )
605 This poorly but historically named function generates a colorhash_table
607 whose value for each color is the number of pixels in a specified image
608 that have that color. (I.e. a color histogram). As a bonus, it
609 returns the number of colors in the image.
610 (It's poorly named because not all colorhash_tables are color his‐
612 tograms, but that's all it generates).
613 pixels, cols, and rows describe the input image.
615 maxcolors is the maximum number of colors you want processed. If there
617 are more colors that that in the input image, ppm_computecolorhash()
618 returns NULL as its return value and stops processing as soon as it
619 discovers this. This makes it run faster and use less memory. One use
620 for maxcolors is when you just want to find out whether or not the
621 image has more than N colors and don't want to wait to generate a huge
622 color table if so. If you don't want any limit on the number of col‐
623 ors, specify maxcolors=0.
624 ppm_computecolorhash() returns the actual number of colors in the image
626 as *colorsP, but only if it is less than or equal to maxcolors.
627 colorhash_table ppm_computecolorhash2( FILE * const ifp, const int
629 cols, const int rows, const pixval maxval, const int format,
630 const int maxcolors, int* const colorsP )
632 This is the same as ppm_computecolorhash() except that instead of feed‐
634 ing it an array of pixels in storage, you give it an open file stream
635 and it reads the image from the file. The file must be positioned
636 after the header, at the raster. Upon return, the file is still open,
637 but its position is undefined.
638 maxval and format are the values for the image (i.e. information from
640 the file's header).
641 colorhist_vector ppm_computecolorhist( pixel ** pixels, int cols, int
643 rows, int maxcolors, int * colorsP )
644 This is like ppm_computecolorhash() except that it creates a col‐
646 orhist_vector instead of a colorhash_table.
647 If you supply a nonzero maxcolors argument, that is the maximum number
649 of colors you expect to find in the input image. If there are more
650 colors than you say in the image, ppm_computecolorhist() returns a null
651 pointer as its return value and nothing meaningful as *colorsP.
652 If not, the function returns the new colorhist_vector as its return
654 value and the actual number of colors in the image as *colorsP. The
655 returned array has space allocated for the specified number of colors
656 regardless of how many actually exist. The extra space is at the high
657 end of the array and is available for your use in expanding the col‐
658 orhist_vector.
659 If you specify maxcolors=0, there is no limit on the number of colors
661 returned and the return array has space for 5 extra colors at the high
662 end for your use in expanding the colorhist_vector.
663 colorhist_vector ppm_computecolorhist2( FILE * ifp, int cols, int rows,
665 int maxcolors, pixval maxval, int format, int * colorsP )
666 This is the same as ppm_computecolorhist() except that instead of feed‐
668 ing it an array of pixels in storage, you give it an open file stream
669 and it reads the image from the file. The file must be positioned
670 after the header, at the raster. Upon return, the file is still open,
671 but its position is undefined.
672
675 pbm(1), pgm(1), libpbm(1)
676
679 Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.
680netpbm documentation 8 May 200U9ser manual for old ppm functions(3)