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 obsolete (at least since Netpbm 9.25 (March 2002)). Use
174 pm_proginit() ⟨libpm.html#initialization⟩ instead.
175 ppm_init() is identical to pm_proginit.
177 MEMORY MANAGEMENT
181 ppm_allocarray() allocates an array of pixels.
182 ppm_allocrow() allocates a row of the given number of pixels.
184 ppm_freearray() frees the array allocated with ppm_allocarray() con‐
186 taining the given number of rows.
187 ppm_freerow() frees a row of pixelss allocated with ppm_allocrow().
189 READING FILES
192 If a function in this section is called on a PBM or PGM format file, it
193 translates the PBM or PGM file into a PPM file on the fly and functions
194 as if it were called on the equivalent PPM file. The format value
195 returned by ppm_readppminit() is, however, not translated. It repre‐
196 sents the actual format of the PBM or PGM file.
197 ppm_readppminit() reads the header of a PPM file, returning all the
199 information from the header and leaving the file positioned just after
200 the header.
201 ppm_readppmrow() reads a row of pixels into the pixelrow array. for‐
203 mat, cols, and maxval are the values returned by ppm_readppminit().
204 ppm_readppm() reads an entire PPM image into memory, returning the
206 allocated array as its return value and returning the information from
207 the header as rows, cols, and maxval. This function combines
208 ppm_readppminit(), ppm_allocarray(), and ppm_readppmrow().
209 WRITING FILES
213 ppm_writeppminit() writes the header for a PPM file and leaves it posi‐
214 tioned just after the header.
215 forceplain is a logical value that tells ppm_writeppminit() to write a
217 header for a plain PPM format file, as opposed to a raw PPM format
218 file.
219 ppm_writeppmrow() writes the row pixelrow to a PPM file. For meaning‐
221 ful results, cols, maxval, and forceplain must be the same as was used
222 with ppm_writeppminit().
223 ppm_writeppm() write the header and all data for a PPM image. This
225 function combines ppm_writeppminit() and ppm_writeppmrow().
226 MISCELLANEOUS
229 ppm_nextimage() positions a PPM input file to the next image in it (so
230 that a subsequent ppm_readppminit() reads its header).
231 ppm_nextimage() is analogous to pbm_nextimage(), but works on PPM, PGM,
233 and PBM files.
234 ppm_check() checks for the common file integrity error where the file
236 is the wrong size to contain all the image data.
237 ppm_check() is analogous to pbm_check(), but works on PPM, PGM, and
239 PBM files.
240 COLOR
244 Luminance, Chrominance (YcbCr)
245 float PPM_LUMIN(pixel p);
247 float PPM_CHROM_B(pixel p);
248 float PPM_CHROM_R(pixel p);
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 pixel
259 ppm_color_from_ycbcr(unsigned int y,
260 int cb,
261 int cr);
262 ppm_color_from_ycbcr() converts in the other direction. Given lumi‐
264 nance and chrominance, it returns a pixel value.
265 Hue, Saturation, Value (HSV)
267 struct hsv {
269 double h; /* hue (degrees) 0..360 */
270 double s; /* saturation (0-1) */
271 double v; /* value (0-1) */
272 };
273 pixel
275 ppm_color_from_hsv(struct hsv const hsv,
276 pixval const maxval);
277 struct hsv
279 ppm_hsv_from_color(pixel const color,
280 pixval const maxval);
281 These convert a color between from pixel (RGB) form and HSV.
283 pixval
285 ppm_saturation(pixel const p,
286 pixval const maxval);
287 This gives you the saturation of a color, as a pixval. (e.g. if the
289 saturation of p is 50% and maxval is 100, ppm_saturation() returns 50).
290 Berlin-Kay Color
293 Brent Berlin and Paul Kay in 1969 did a study which identified a set of
295 11 basic colors people universally recognize. They are:
296 · black
300 · gray
302 · white
304 · red
306 · orange
308 · yellow
310 · green
312 · blue
314 · violet
316 · purple
318 · brown
320 The bk_color type represents a color from this set:
323 typedef enum {
325 BKCOLOR_BLACK = 0,
326 BKCOLOR_GRAY,
327 BKCOLOR_WHITE,
328 BKCOLOR_RED,
329 BKCOLOR_ORANGE,
330 BKCOLOR_YELLOW,
331 BKCOLOR_GREEN,
332 BKCOLOR_BLUE,
333 BKCOLOR_VIOLET,
334 BKCOLOR_PURPLE,
335 BKCOLOR_BROWN
336 } bk_color;
337 You can use this as an index of an array, in which case you might also
339 want macro BKCOLOR_COUNT, which is the number of colors in the set
340 (11).
341 To translate between the bk_color type and the English names of the
343 colors, use ppm_bk_color_from_name() and ppm_name_from_bk_color():
344 bk_color
346 ppm_bk_color_from_name(const char * name);
347 const char *
349 ppm_name_from_bk_color(bk_color bkColor);
350 ppm_bk_color_from_color() tells you to which Berlin-Kay color a certain
352 color is closest, by way of a fuzzy color matching algorithm:
353 bk_color
355 ppm_bk_color_from_color(pixel color,
356 pixval maxval);
357 maxval is the maxval on which color is based.
359 ppm_color_from_bk_color() converts the opposite way: given a Berlin-Kay
361 color, it gives the color, in pixel form, that best represents it.
362 pixel
364 ppm_color_from_bk_color(bk_color bkColor,
365 pixval maxval);
366 maxval is the maxval on which the returned color is based.
368 All of the facilities in this section were new in Netpbm 10.34 (June
370 2006).
371 COLOR NAMES
374 System Color Dictionary
375 Netpbm uses the system's X11 color dictionary (usually in
377 /usr/lib/X11/rgb.txt). This is the same file the X Window System typi‐
378 cally uses to associate colors with their names.
379 The color dictionary that Netpbm uses is in the file whose name is the
381 value of the RGBDEF environment variable. If RGBDEF is not set, Netpbm
382 defaults to the first existing file from this list:
383 · /usr/lib/X11/rgb.txt
387 · /usr/openwinlib/rgb.txt
389 · /usr/X11R6/lib/X11/rgb.txt
391 You can see the color names from a typical X11 color dictionary, which
394 is probably very close to what is on your system, along with the col‐
395 ors, here ⟨http://www.swiss.ai.mit.edu/~jaffer/Color/x11.pdf⟩ . This
396 website" (1) shows a bunch of other versions you could use.
397 Netpbm is packaged with a color dictionary. A standard Netpbm instal‐
399 lation installs this file as "misc/rgb.txt" in the Netpbm directory.
400 This color dictionary has colors from everywhere the Netpbm maintainer
401 could find them, and is a superset of XFree 86's color dictionary.
402 ppm_parsecolor
404 ppm_parsecolor() interprets a color specification and returns a pixel
406 of the color that it indicates. The color specification is ASCII text,
407 in one of these formats:
408 · a name, as defined in the system color dictionary ⟨#rgb.txt⟩ .
413 ·
416 An X11-style hexadecimal specifier: rgb:r/g/b, where r, g, and
417 b are each 1- to 4-digit hexadecimal numbers. For each, the
418 maxval is the maximum number that can be represented in the num‐
419 ber of hexadecimal digits given. Example: rgb:01/ff/8000 speci‐
420 fies 1/255 red intensity, maximum green intensity, and about
421 half blue intensity.
422 ·
425 An X11-style decimal specifier: rgbi:r/g/b, where r, g, and b
426 are floating point numbers from 0 to 1. Example:
427 rgbi:1.0/0.5/.25.
428 · an old-X11-style hexadecimal triple: #rgb, #rrggbb, #rrrgggbbb,
431 or #rrrrggggbbbb.
432 · A triplet of decimal floating point numbers from 0.0 to 1.0,
435 representing red, green, and blue intensities respectively, sep‐
436 arated by commas. Example: 1.0,0.5,.25. This is for backwards
437 compatibility; it was in use before MIT came up with the similar
438 and preferred rgbi style).
439 If the color specification does not conform to any of these formats,
443 including the case that it is a name, but is not in the system color
444 dictionary, ppm_parsecolor() throws an error(1).
445 ppm_colorname
447 ppm_colorname() returns a string that describes the color of the given
449 pixel. If a system color dictionary ⟨#rgb.txt⟩ is available and the
450 color appears in it, ppm_colorname() returns the name of the color from
451 the file. If the color does not appear in a system color dictionary
452 and hexok is true, ppm_colorname() returns a hexadecimal color specifi‐
453 cation triple (#rrggbb). If a system color dictionary is available but
454 the color does not appear in it and hexok is false, ppm_colorname()
455 returns the name of the closest matching color in the color file.
456 Finally, if there is no system color dictionary available and hexok is
457 false, ppm_colorname() fails and throws an error ⟨liberror.html#error⟩
458 .
459 The string returned is in static libppm library storage which is over‐
461 written by every call to ppm_colorname().
462 ppm_readcolornamefile
465 ppm_readcolornamefile() reads the entire contents of the color dictio‐
467 nary in the file named fileName into data structures you can use to
468 access it easily.
469 The function returns all the color names as an array of null-terminated
471 strings. It mallocs the space for this array and returns its address
472 at colornamesP. (*colornamesP)[i] is the address of the first charac‐
473 ter in the null-terminated string that is the name of the ith color in
474 the dictionary.
475 The function also returns a colorhash_table (see COLOR INDEXING
477 ⟨#colorindex⟩ ) that matches all these color names up to the colors
478 they represent. It mallocs the space for the colorhash_table and
479 returns its address at chtP. The number that the colorhash_table asso‐
480 ciates with each color is the index into the color name array described
481 above of the name of that color.
482 You may specify a null pointer for fileName to indicate the default
484 color dictionary.
485 mustOpen is a boolean. If it is nonzero, the function fails and aborts
487 the program if it is unable to open the specified color dictionary
488 file. If it is zero, though, it simply treats an unopenable color dic‐
489 tionary as an empty one. The colorhash and color name array it returns
490 contain no colors or names.
491 ppm_readcolornamefile() was new in Netpbm 10.15 (April 2003).
493 COLOR INDEXING
497 Sometimes in processing images, you want to associate a value with a
498 particular color. Most often, that's because you're generating a color
499 mapped graphics format. In a color mapped graphics format, the raster
500 contains small numbers, and the file contains a color map that tells
501 what color each of those small numbers refers to. If your image has
502 only 256 colors, but each color takes 24 bits to describe, this can
503 make your output file much smaller than a straightforward RGB raster
504 would.
505 So, continuing the above example, say you have a pixel value for char‐
507 treuse and in your output file and you are going to represent char‐
508 treuse by the number 12. You need a data structure that allows your
509 program quickly to find out that the number for a chartreuse pixel is
510 12. Netpbm's color indexing data types and functions give you that.
511 colorhash_table is a C data type that associates an integer with each
513 of an arbitrary number of colors. It is a hash table, so it uses far
514 less space than an array indexed by the color's RGB values would.
515 The problem with a colorhash_table is that you can only look things up
517 in it. You can't find out what colors are in it. So Netpbm has
518 another data type for representing the same information, the poorly but
519 historically named colorhist_vector. A colorhist_vector is just an
520 array. Each entry represents a color and contains the color's value
521 (as a pixel) and the integer value associated with it. The entries are
522 filled in starting with subscript 0 and going consecutively up for the
523 number of colors in the histogram.
524 (The reason the name is poor is because a color histogram is only one
526 of many things that could be represented by it).
527 colorhash_table ppm_alloccolorhash()
529 This creates a colorhash_table using dynamically allocated storage.
531 There are no colors in it. If there is not enough storage, throws an
532 error ⟨liberror.html#error⟩ .
533 void ppm_freecolorhash()
535 This destroys a ppm_freecolorhash and frees all the storage associated
537 with it.
538 int ppm_addtocolorhash( colorhash_table cht, const pixel * const col‐
540 orP, const int value)
541 This adds the specified color to the specified colorhash_table
543 and associates the specified value with it.
544 You must ensure that the color you are adding isn't already present in
546 the colorhash_table.
547 There is no way to update an entry or delete an entry from a col‐
549 orhash_table.
550 int ppm_lookupcolor( const colorhash_table cht, const pixel * const
552 colorP )
553 This looks up the specified color in the specified colorhash_table. It
555 returns the integer value associated with that color.
556 If the specified color is not in the hash table, the function returns
558 -1. (So if you assign the value -1 to a color, the return value is
559 ambiguous).
560 colorhist_vector ppm_colorhashtocolorhist( const colorhash_table cht,
562 const int ncolors )
564 This converts a colorhash_table to a colorhist_vector. The return
566 value is a new colorhist_vector which you must eventually free with
567 ppm_freecolorhist().
568 ncolors is the number of colors in cht. If it has more colors than
570 that, ppm_colorhashtocolorhist does not create a colorhist_vector and
571 returns NULL.
572 colorhash_table ppm_colorhisttocolorhash( const colorhist_vector chv,
574 const int ncolors )
575 This poorly named function does not convert from a colorhist_vector to
577 a colorhash_table.
578 It does create a colorhash_table based on a colorhist_vector input, but
580 the integer value for a given color in the output is not the same as
581 the integer value for that same color in the input. ppm_colorhistto‐
582 colorhash() ignores the integer values in the input. In the output,
583 the integer value for a color is the index in the input colorhist_vec‐
584 tor for that color.
585 You can easily create a color map for an image by running ppm_compute‐
587 colorhist() over the image, then ppm_colorhisttocolorhash() over the
588 result. Now you can use ppm_lookupcolor() to find a unique color index
589 for any pixel in the input.
590 If the same color appears twice in the input, ppm_colorhisttocol‐
592 orhash() throws an error ⟨liberror.html#error⟩ .
593 ncolors is the number of colors in chv.
595 The return value is a new colorhash_table which you must eventually
597 free with ppm_freecolorhash().
598 COLOR HISTOGRAMS
601 The Netpbm libraries give you functions to examine a Netpbm image and
602 determine what colors are in it and how many pixels of each color are
603 in it. This information is known as a color histogram. Netpbm uses
604 its colorhash_table data type to represent a color histogram.
605 colorhash_table ppm_computecolorhash( pixel ** const pixels, const int
607 cols, const int rows, const int maxcolors, int* const colorsP )
608 This poorly but historically named function generates a colorhash_table
610 whose value for each color is the number of pixels in a specified image
611 that have that color. (I.e. a color histogram). As a bonus, it
612 returns the number of colors in the image.
613 (It's poorly named because not all colorhash_tables are color his‐
615 tograms, but that's all it generates).
616 pixels, cols, and rows describe the input image.
618 maxcolors is the maximum number of colors you want processed. If there
620 are more colors that that in the input image, ppm_computecolorhash()
621 returns NULL as its return value and stops processing as soon as it
622 discovers this. This makes it run faster and use less memory. One use
623 for maxcolors is when you just want to find out whether or not the
624 image has more than N colors and don't want to wait to generate a huge
625 color table if so. If you don't want any limit on the number of col‐
626 ors, specify maxcolors=0.
627 ppm_computecolorhash() returns the actual number of colors in the image
629 as *colorsP, but only if it is less than or equal to maxcolors.
630 colorhash_table ppm_computecolorhash2( FILE * const ifp, const int
632 cols, const int rows, const pixval maxval, const int format,
633 const int maxcolors, int* const colorsP )
635 This is the same as ppm_computecolorhash() except that instead of feed‐
637 ing it an array of pixels in storage, you give it an open file stream
638 and it reads the image from the file. The file must be positioned
639 after the header, at the raster. Upon return, the file is still open,
640 but its position is undefined.
641 maxval and format are the values for the image (i.e. information from
643 the file's header).
644 colorhist_vector ppm_computecolorhist( pixel ** pixels, int cols, int
646 rows, int maxcolors, int * colorsP )
647 This is like ppm_computecolorhash() except that it creates a col‐
649 orhist_vector instead of a colorhash_table.
650 If you supply a nonzero maxcolors argument, that is the maximum number
652 of colors you expect to find in the input image. If there are more
653 colors than you say in the image, ppm_computecolorhist() returns a null
654 pointer as its return value and nothing meaningful as *colorsP.
655 If not, the function returns the new colorhist_vector as its return
657 value and the actual number of colors in the image as *colorsP. The
658 returned array has space allocated for the specified number of colors
659 regardless of how many actually exist. The extra space is at the high
660 end of the array and is available for your use in expanding the col‐
661 orhist_vector.
662 If you specify maxcolors=0, there is no limit on the number of colors
664 returned and the return array has space for 5 extra colors at the high
665 end for your use in expanding the colorhist_vector.
666 colorhist_vector ppm_computecolorhist2( FILE * ifp, int cols, int rows,
668 int maxcolors, pixval maxval, int format, int * colorsP )
669 This is the same as ppm_computecolorhist() except that instead of feed‐
671 ing it an array of pixels in storage, you give it an open file stream
672 and it reads the image from the file. The file must be positioned
673 after the header, at the raster. Upon return, the file is still open,
674 but its position is undefined.
675
678 pbm(1), pgm(1), libpbm(1)
679
682 Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.
683
685 This manual page was generated by the Netpbm tool 'makeman' from HTML
686 source. The master documentation is at
687 http://netpbm.sourceforge.net/doc/libppm.html
689netpbm documentation 8 May 200U9ser manual for old ppm functions(3)