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 pixel ppm_parsecolor2( char * colorname, pixval maxval, int closeOk )
121 char * ppm_colorname(pixel * colorP,
123 pixval maxval,
124 int hexok)
125 void ppm_readcolornamefile(
127 const char *fileName,
128 int mustOpen,
129 colorhash_table * chtP,
130 const char *** colornamesP
131 )
132
136 These library functions are part of Netpbm(1).
137 TYPES AND CONSTANTS
140 Each pixel contains three pixvals, each of which should contain only
141 the values between 0 and PPM_MAXMAXVAL.
142 MANIPULATING PIXELS
146 The macros PPM_GETR, PPM_GETG, and PPM_GETB retrieve the red, green, or
147 blue sample, respectively, from the given pixel.
148 The PPM_ASSIGN macro assigns the given values to the red, green, and
150 blue samples of the given pixel.
151 The PPM_EQUAL macro tests two pixels for equality.
153 The PPM_ISGRAY macro tests a pixel for being gray. It returns true if
155 and only if the color of pixel p is black, white, or gray.
156 The PPM_DEPTH macro scales the colors of pixel p according the old and
158 new maxvals and assigns the new values to newp. It is intended to make
159 writing ppmtowhatever easier.
160 The PPM_LUMIN, PPM_CHROM_R, and PPM_CHROM_B macros determine the lumi‐
162 nance, red chrominance, and blue chrominance, respectively, of the
163 pixel p. The scale of all these values is the same as the scale of the
164 input samples (i.e. 0 to maxval for luminance, -maxval/2 to maxval/2
165 for chrominance).
166 Note that the macros do it by floating point multiplication. If you
168 are computing these values over an entire image, it may be signifi‐
169 cantly faster to do it with multiplication tables instead. Compute all
170 the possible products once up front, then for each pixel, just look up
171 the products in the tables.
172 INITIALIZATION
175 ppm_init() is obsolete (at least since Netpbm 9.25 (March 2002)). Use
176 pm_proginit() ⟨libpm.html#initialization⟩ instead.
177 ppm_init() is identical to pm_proginit.
179 MEMORY MANAGEMENT
183 ppm_allocarray() allocates an array of pixels.
184 ppm_allocrow() allocates a row of the given number of pixels.
186 ppm_freearray() frees the array allocated with ppm_allocarray() con‐
188 taining the given number of rows.
189 ppm_freerow() frees a row of pixelss allocated with ppm_allocrow().
191 READING FILES
194 If a function in this section is called on a PBM or PGM format file, it
195 translates the PBM or PGM file into a PPM file on the fly and functions
196 as if it were called on the equivalent PPM file. The format value
197 returned by ppm_readppminit() is, however, not translated. It repre‐
198 sents the actual format of the PBM or PGM file.
199 ppm_readppminit() reads the header of a PPM file, returning all the
201 information from the header and leaving the file positioned just after
202 the header.
203 ppm_readppmrow() reads a row of pixels into the pixelrow array. for‐
205 mat, cols, and maxval are the values returned by ppm_readppminit().
206 ppm_readppm() reads an entire PPM image into memory, returning the
208 allocated array as its return value and returning the information from
209 the header as rows, cols, and maxval. This function combines
210 ppm_readppminit(), ppm_allocarray(), and ppm_readppmrow().
211 WRITING FILES
215 ppm_writeppminit() writes the header for a PPM file and leaves it posi‐
216 tioned just after the header.
217 forceplain is a logical value that tells ppm_writeppminit() to write a
219 header for a plain PPM format file, as opposed to a raw PPM format
220 file.
221 ppm_writeppmrow() writes the row pixelrow to a PPM file. For meaning‐
223 ful results, cols, maxval, and forceplain must be the same as was used
224 with ppm_writeppminit().
225 ppm_writeppm() write the header and all data for a PPM image. This
227 function combines ppm_writeppminit() and ppm_writeppmrow().
228 MISCELLANEOUS
231 ppm_nextimage() positions a PPM input file to the next image in it (so
232 that a subsequent ppm_readppminit() reads its header).
233 ppm_nextimage() is analogous to pbm_nextimage(), but works on PPM, PGM,
235 and PBM files.
236 ppm_check() checks for the common file integrity error where the file
238 is the wrong size to contain all the image data.
239 ppm_check() is analogous to pbm_check(), but works on PPM, PGM, and
241 PBM files.
242 COLOR
246 Luminance, Chrominance (YcbCr)
247 float PPM_LUMIN(pixel p);
249 float PPM_CHROM_B(pixel p);
250 float PPM_CHROM_R(pixel p);
251 PPM_LUMIN takes a pixel as an argument and returns the luminance of
253 that pixel, with the same maxval as the pixel (e.g. if the pixel's max‐
254 val is 255, a PPM_LUMIN value of 255 means fully luminant).
255 PPM_CHROM_B and PPM_CHROM_R are similar, for the red and blue chromi‐
257 nance values.
258 pixel
261 ppm_color_from_ycbcr(unsigned int y,
262 int cb,
263 int cr);
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 struct hsv {
271 double h; /* hue (degrees) 0..360 */
272 double s; /* saturation (0-1) */
273 double v; /* value (0-1) */
274 };
275 pixel
277 ppm_color_from_hsv(struct hsv const hsv,
278 pixval const maxval);
279 struct hsv
281 ppm_hsv_from_color(pixel const color,
282 pixval const maxval);
283 These convert a color between from pixel (RGB) form and HSV.
285 pixval
287 ppm_saturation(pixel const p,
288 pixval const maxval);
289 This gives you the saturation of a color, as a pixval. (e.g. if the
291 saturation of p is 50% and maxval is 100, ppm_saturation() returns 50).
292 Berlin-Kay Color
295 Brent Berlin and Paul Kay in 1969 did a study which identified a set of
297 11 basic colors people universally recognize. They are:
298 · black
302 · gray
304 · white
306 · red
308 · orange
310 · yellow
312 · green
314 · blue
316 · violet
318 · purple
320 · brown
322 The bk_color type represents a color from this set:
325 typedef enum {
327 BKCOLOR_BLACK = 0,
328 BKCOLOR_GRAY,
329 BKCOLOR_WHITE,
330 BKCOLOR_RED,
331 BKCOLOR_ORANGE,
332 BKCOLOR_YELLOW,
333 BKCOLOR_GREEN,
334 BKCOLOR_BLUE,
335 BKCOLOR_VIOLET,
336 BKCOLOR_PURPLE,
337 BKCOLOR_BROWN
338 } bk_color;
339 You can use this as an index of an array, in which case you might also
341 want macro BKCOLOR_COUNT, which is the number of colors in the set
342 (11).
343 To translate between the bk_color type and the English names of the
345 colors, use ppm_bk_color_from_name() and ppm_name_from_bk_color():
346 bk_color
348 ppm_bk_color_from_name(const char * name);
349 const char *
351 ppm_name_from_bk_color(bk_color bkColor);
352 ppm_bk_color_from_color() tells you to which Berlin-Kay color a certain
354 color is closest, by way of a fuzzy color matching algorithm:
355 bk_color
357 ppm_bk_color_from_color(pixel color,
358 pixval maxval);
359 maxval is the maxval on which color is based.
361 ppm_color_from_bk_color() converts the opposite way: given a Berlin-Kay
363 color, it gives the color, in pixel form, that best represents it.
364 pixel
366 ppm_color_from_bk_color(bk_color bkColor,
367 pixval maxval);
368 maxval is the maxval on which the returned color is based.
370 All of the facilities in this section were new in Netpbm 10.34 (June
372 2006).
373 COLOR NAMES
376 System Color Dictionary
377 Netpbm uses the system's X11 color dictionary (usually in
379 /usr/lib/X11/rgb.txt). This is the same file the X Window System typi‐
380 cally uses to associate colors with their names.
381 The color dictionary that Netpbm uses is in the file whose name is the
383 value of the RGBDEF environment variable. If RGBDEF is not set, Netpbm
384 defaults to the first existing file from this list:
385 · /usr/lib/X11/rgb.txt
389 · /usr/openwinlib/rgb.txt
391 · /usr/X11R6/lib/X11/rgb.txt
393 You can see the color names from a typical X11 color dictionary, which
396 is probably very close to what is on your system, along with the col‐
397 ors, here ⟨http://www.swiss.ai.mit.edu/~jaffer/Color/x11.pdf⟩ . This
398 website" (1) shows a bunch of other versions you could use.
399 Netpbm is packaged with a color dictionary. A standard Netpbm instal‐
401 lation installs this file as "misc/rgb.txt" in the Netpbm directory.
402 This color dictionary has colors from everywhere the Netpbm maintainer
403 could find them, and is a superset of XFree 86's color dictionary.
404 ppm_parsecolor
406 ppm_parsecolor() interprets a color specification and returns a pixel
408 of the color that it indicates. It is the same as pnm_parsecolor
409 ⟨libnetbm_image.html#colorname⟩ , except that it returns a pixel
410 instead of a tuple.
411 ppm_parsecolor2
413 ppm_parsecolor2() interprets a color specification and returns a pixel
415 of the color that it indicates and warns about rounding. It is the
416 same as pnm_parsecolor2 ⟨libnetbm_image.html#colorname⟩ , except that
417 it returns a pixel instead of a tuple.
418 ppm_colorname
420 ppm_colorname() returns a string that describes the color of the given
422 pixel. If a system color dictionary ⟨#rgb.txt⟩ is available and the
423 color appears in it, ppm_colorname() returns the name of the color from
424 the file. If the color does not appear in a system color dictionary
425 and hexok is true, ppm_colorname() returns a hexadecimal color specifi‐
426 cation triple (#rrggbb). If a system color dictionary is available but
427 the color does not appear in it and hexok is false, ppm_colorname()
428 returns the name of the closest matching color in the color file.
429 Finally, if there is no system color dictionary available and hexok is
430 false, ppm_colorname() fails and throws an error ⟨liberror.html#error⟩
431 .
432 The string returned is in static libppm library storage which is over‐
434 written by every call to ppm_colorname().
435 ppm_readcolornamefile
438 ppm_readcolornamefile() reads the entire contents of the color dictio‐
440 nary in the file named fileName into data structures you can use to
441 access it easily.
442 The function returns all the color names as an array of null-terminated
444 strings. It mallocs the space for this array and returns its address
445 at colornamesP. (*colornamesP)[i] is the address of the first charac‐
446 ter in the null-terminated string that is the name of the ith color in
447 the dictionary.
448 The function also returns a colorhash_table (see COLOR INDEXING
450 ⟨#colorindex⟩ ) that matches all these color names up to the colors
451 they represent. It mallocs the space for the colorhash_table and
452 returns its address at chtP. The number that the colorhash_table asso‐
453 ciates with each color is the index into the color name array described
454 above of the name of that color.
455 You may specify a null pointer for fileName to indicate the default
457 color dictionary.
458 mustOpen is a boolean. If it is nonzero, the function fails and aborts
460 the program if it is unable to open the specified color dictionary
461 file. If it is zero, though, it simply treats an unopenable color dic‐
462 tionary as an empty one. The colorhash and color name array it returns
463 contain no colors or names.
464 ppm_readcolornamefile() was new in Netpbm 10.15 (April 2003).
466 COLOR INDEXING
470 Sometimes in processing images, you want to associate a value with a
471 particular color. Most often, that's because you're generating a color
472 mapped graphics format. In a color mapped graphics format, the raster
473 contains small numbers, and the file contains a color map that tells
474 what color each of those small numbers refers to. If your image has
475 only 256 colors, but each color takes 24 bits to describe, this can
476 make your output file much smaller than a straightforward RGB raster
477 would.
478 So, continuing the above example, say you have a pixel value for char‐
480 treuse and in your output file and you are going to represent char‐
481 treuse by the number 12. You need a data structure that allows your
482 program quickly to find out that the number for a chartreuse pixel is
483 12. Netpbm's color indexing data types and functions give you that.
484 colorhash_table is a C data type that associates an integer with each
486 of an arbitrary number of colors. It is a hash table, so it uses far
487 less space than an array indexed by the color's RGB values would.
488 The problem with a colorhash_table is that you can only look things up
490 in it. You can't find out what colors are in it. So Netpbm has
491 another data type for representing the same information, the poorly but
492 historically named colorhist_vector. A colorhist_vector is just an
493 array. Each entry represents a color and contains the color's value
494 (as a pixel) and the integer value associated with it. The entries are
495 filled in starting with subscript 0 and going consecutively up for the
496 number of colors in the histogram.
497 (The reason the name is poor is because a color histogram is only one
499 of many things that could be represented by it).
500 colorhash_table ppm_alloccolorhash()
502 This creates a colorhash_table using dynamically allocated storage.
504 There are no colors in it. If there is not enough storage, throws an
505 error ⟨liberror.html#error⟩ .
506 void ppm_freecolorhash()
508 This destroys a ppm_freecolorhash and frees all the storage associated
510 with it.
511 int ppm_addtocolorhash( colorhash_table cht, const pixel * const col‐
513 orP, const int value)
514 This adds the specified color to the specified colorhash_table
516 and associates the specified value with it.
517 You must ensure that the color you are adding isn't already present in
519 the colorhash_table.
520 There is no way to update an entry or delete an entry from a col‐
522 orhash_table.
523 int ppm_lookupcolor( const colorhash_table cht, const pixel * const
525 colorP )
526 This looks up the specified color in the specified colorhash_table. It
528 returns the integer value associated with that color.
529 If the specified color is not in the hash table, the function returns
531 -1. (So if you assign the value -1 to a color, the return value is
532 ambiguous).
533 colorhist_vector ppm_colorhashtocolorhist( const colorhash_table cht,
535 const int ncolors )
537 This converts a colorhash_table to a colorhist_vector. The return
539 value is a new colorhist_vector which you must eventually free with
540 ppm_freecolorhist().
541 ncolors is the number of colors in cht. If it has more colors than
543 that, ppm_colorhashtocolorhist does not create a colorhist_vector and
544 returns NULL.
545 colorhash_table ppm_colorhisttocolorhash( const colorhist_vector chv,
547 const int ncolors )
548 This poorly named function does not convert from a colorhist_vector to
550 a colorhash_table.
551 It does create a colorhash_table based on a colorhist_vector input, but
553 the integer value for a given color in the output is not the same as
554 the integer value for that same color in the input. ppm_colorhistto‐
555 colorhash() ignores the integer values in the input. In the output,
556 the integer value for a color is the index in the input colorhist_vec‐
557 tor for that color.
558 You can easily create a color map for an image by running ppm_compute‐
560 colorhist() over the image, then ppm_colorhisttocolorhash() over the
561 result. Now you can use ppm_lookupcolor() to find a unique color index
562 for any pixel in the input.
563 If the same color appears twice in the input, ppm_colorhisttocol‐
565 orhash() throws an error ⟨liberror.html#error⟩ .
566 ncolors is the number of colors in chv.
568 The return value is a new colorhash_table which you must eventually
570 free with ppm_freecolorhash().
571 COLOR HISTOGRAMS
574 The Netpbm libraries give you functions to examine a Netpbm image and
575 determine what colors are in it and how many pixels of each color are
576 in it. This information is known as a color histogram. Netpbm uses
577 its colorhash_table data type to represent a color histogram.
578 colorhash_table ppm_computecolorhash( pixel ** const pixels, const int
580 cols, const int rows, const int maxcolors, int* const colorsP )
581 This poorly but historically named function generates a colorhash_table
583 whose value for each color is the number of pixels in a specified image
584 that have that color. (I.e. a color histogram). As a bonus, it
585 returns the number of colors in the image.
586 (It's poorly named because not all colorhash_tables are color his‐
588 tograms, but that's all it generates).
589 pixels, cols, and rows describe the input image.
591 maxcolors is the maximum number of colors you want processed. If there
593 are more colors that that in the input image, ppm_computecolorhash()
594 returns NULL as its return value and stops processing as soon as it
595 discovers this. This makes it run faster and use less memory. One use
596 for maxcolors is when you just want to find out whether or not the
597 image has more than N colors and don't want to wait to generate a huge
598 color table if so. If you don't want any limit on the number of col‐
599 ors, specify maxcolors=0.
600 ppm_computecolorhash() returns the actual number of colors in the image
602 as *colorsP, but only if it is less than or equal to maxcolors.
603 colorhash_table ppm_computecolorhash2( FILE * const ifp, const int
605 cols, const int rows, const pixval maxval, const int format,
606 const int maxcolors, int* const colorsP )
608 This is the same as ppm_computecolorhash() except that instead of feed‐
610 ing it an array of pixels in storage, you give it an open file stream
611 and it reads the image from the file. The file must be positioned
612 after the header, at the raster. Upon return, the file is still open,
613 but its position is undefined.
614 maxval and format are the values for the image (i.e. information from
616 the file's header).
617 colorhist_vector ppm_computecolorhist( pixel ** pixels, int cols, int
619 rows, int maxcolors, int * colorsP )
620 This is like ppm_computecolorhash() except that it creates a col‐
622 orhist_vector instead of a colorhash_table.
623 If you supply a nonzero maxcolors argument, that is the maximum number
625 of colors you expect to find in the input image. If there are more
626 colors than you say in the image, ppm_computecolorhist() returns a null
627 pointer as its return value and nothing meaningful as *colorsP.
628 If not, the function returns the new colorhist_vector as its return
630 value and the actual number of colors in the image as *colorsP. The
631 returned array has space allocated for the specified number of colors
632 regardless of how many actually exist. The extra space is at the high
633 end of the array and is available for your use in expanding the col‐
634 orhist_vector.
635 If you specify maxcolors=0, there is no limit on the number of colors
637 returned and the return array has space for 5 extra colors at the high
638 end for your use in expanding the colorhist_vector.
639 colorhist_vector ppm_computecolorhist2( FILE * ifp, int cols, int rows,
641 int maxcolors, pixval maxval, int format, int * colorsP )
642 This is the same as ppm_computecolorhist() except that instead of feed‐
644 ing it an array of pixels in storage, you give it an open file stream
645 and it reads the image from the file. The file must be positioned
646 after the header, at the raster. Upon return, the file is still open,
647 but its position is undefined.
648
651 pbm(1), pgm(1), libpbm(1)
652
655 Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.
656
658 This manual page was generated by the Netpbm tool 'makeman' from HTML
659 source. The master documentation is at
660 http://netpbm.sourceforge.net/doc/libppm.html
662netpbm documentation 8 May 200U9ser manual for old ppm functions(3)