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 re‐
197 turned by ppm_readppminit() is, however, not translated. It represents
198 the actual format of the PBM or PGM file.
199 ppm_readppminit() reads the header of a PPM file, returning all the in‐
201 formation 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 al‐
208 located 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
254 that pixel, with the same maxval as the pixel (e.g. if the pixel's max‐
255 val is 255, a PPM_LUMIN value of 255 means fully luminant).
256 PPM_CHROM_B and PPM_CHROM_R are similar, for the red and blue chromi‐
258 nance values.
259 pixel
262 ppm_color_from_ycbcr(unsigned int y,
263 int cb,
264 int cr);
265 ppm_color_from_ycbcr() converts in the other direction. Given lumi‐
268 nance and chrominance, it returns a pixel value.
269 Hue, Saturation, Value (HSV)
271 struct hsv {
273 double h; /* hue (degrees) 0..360 */
274 double s; /* saturation (0-1) */
275 double v; /* value (0-1) */
276 };
277 pixel
280 ppm_color_from_hsv(struct hsv const hsv,
281 pixval const maxval);
282 struct hsv
285 ppm_hsv_from_color(pixel const color,
286 pixval const maxval);
287 These convert a color between from pixel (RGB) form and HSV.
290 pixval
292 ppm_saturation(pixel const p,
293 pixval const maxval);
294 This gives you the saturation of a color, as a pixval. (e.g. if the
297 saturation of p is 50% and maxval is 100, ppm_saturation() returns 50).
298 Berlin-Kay Color
301 Brent Berlin and Paul Kay in 1969 did a study which identified a set of
303 11 basic colors people universally recognize. They are:
304 • black
308 • gray
310 • white
312 • red
314 • orange
316 • yellow
318 • green
320 • blue
322 • violet
324 • purple
326 • brown
328 The bk_color type represents a color from this set:
331 typedef enum {
333 BKCOLOR_BLACK = 0,
334 BKCOLOR_GRAY,
335 BKCOLOR_WHITE,
336 BKCOLOR_RED,
337 BKCOLOR_ORANGE,
338 BKCOLOR_YELLOW,
339 BKCOLOR_GREEN,
340 BKCOLOR_BLUE,
341 BKCOLOR_VIOLET,
342 BKCOLOR_PURPLE,
343 BKCOLOR_BROWN
344 } bk_color;
345 You can use this as an index of an array, in which case you might also
348 want macro BKCOLOR_COUNT, which is the number of colors in the set
349 (11).
350 To translate between the bk_color type and the English names of the
352 colors, use ppm_bk_color_from_name() and ppm_name_from_bk_color():
353 bk_color
355 ppm_bk_color_from_name(const char * name);
356 const char *
358 ppm_name_from_bk_color(bk_color bkColor);
359 ppm_bk_color_from_color() tells you to which Berlin-Kay color a certain
362 color is closest, by way of a fuzzy color matching algorithm:
363 bk_color
365 ppm_bk_color_from_color(pixel color,
366 pixval maxval);
367 maxval is the maxval on which color is based.
370 ppm_color_from_bk_color() converts the opposite way: given a Berlin-Kay
372 color, it gives the color, in pixel form, that best represents it.
373 pixel
375 ppm_color_from_bk_color(bk_color bkColor,
376 pixval maxval);
377 maxval is the maxval on which the returned color is based.
380 All of the facilities in this section were new in Netpbm 10.34 (June
382 2006).
383 COLOR NAMES
386 System Color Dictionary
387 Netpbm uses the system's X11 color dictionary (usually in
389 /usr/lib/X11/rgb.txt). This is the same file the X Window System typi‐
390 cally uses to associate colors with their names.
391 The color dictionary that Netpbm uses is in the file whose name is the
393 value of the RGBDEF environment variable. If RGBDEF is not set, Netpbm
394 defaults to the first existing file from this list:
395 • /usr/lib/X11/rgb.txt
399 • /usr/openwinlib/rgb.txt
401 • /usr/X11R6/lib/X11/rgb.txt
403 You can see the color names from a typical X11 color dictionary, which
406 is probably very close to what is on your system, along with the col‐
407 ors, here ⟨http://www.swiss.ai.mit.edu/~jaffer/Color/x11.pdf⟩ . This
408 website" (1) shows a bunch of other versions you could use.
409 Netpbm is packaged with a color dictionary. A standard Netpbm instal‐
411 lation installs this file as "misc/rgb.txt" in the Netpbm directory.
412 This color dictionary has colors from everywhere the Netpbm maintainer
413 could find them, and is a superset of XFree 86's color dictionary.
414 ppm_parsecolor
416 ppm_parsecolor() interprets a color specification and returns a pixel
418 of the color that it indicates. It is the same as pnm_parsecolor
419 ⟨libnetpbm_image.html#colorname⟩ , except that it returns a pixel in‐
420 stead of a tuple.
421 ppm_parsecolor2
423 ppm_parsecolor2() interprets a color specification and returns a pixel
425 of the color that it indicates and warns about rounding. It is the
426 same as pnm_parsecolor2 ⟨libnetpbm_image.html#colorname⟩ , except that
427 it returns a pixel instead of a tuple.
428 ppm_colorname
430 ppm_colorname() returns a string that describes the color of the given
432 pixel. If a system color dictionary ⟨#dictionary⟩ is available and
433 the color appears in it, ppm_colorname() returns the name of the color
434 from the file. If the color does not appear in a system color dictio‐
435 nary and hexok is true, ppm_colorname() returns a hexadecimal color
436 specification triple (#rrggbb). If a system color dictionary is avail‐
437 able but the color does not appear in it and hexok is false, ppm_color‐
438 name() returns the name of the closest matching color in the color
439 file. Finally, if there is no system color dictionary available and
440 hexok is false, ppm_colorname() fails and throws an error
441 ⟨liberror.html#error⟩ .
442 The string returned is in static libppm library storage which is over‐
444 written by every call to ppm_colorname().
445 ppm_readcolornamefile
448 ppm_readcolornamefile() reads the entire contents of the color dictio‐
450 nary in the file named fileName into data structures you can use to ac‐
451 cess it easily.
452 The function returns all the color names as an array of null-terminated
454 strings. It mallocs the space for this array and returns its address
455 at colornamesP. (*colornamesP)[i] is the address of the first charac‐
456 ter in the null-terminated string that is the name of the ith color in
457 the dictionary.
458 The function also returns a colorhash_table (see COLOR INDEXING
460 ⟨#colorindex⟩ ) that matches all these color names up to the colors
461 they represent. It mallocs the space for the colorhash_table and re‐
462 turns its address at chtP. The number that the colorhash_table asso‐
463 ciates with each color is the index into the color name array described
464 above of the name of that color.
465 You may specify a null pointer for fileName to indicate the default
467 color dictionary.
468 mustOpen is a boolean. If it is nonzero, the function fails and aborts
470 the program if it is unable to open the specified color dictionary
471 file. If it is zero, though, it simply treats an unopenable color dic‐
472 tionary as an empty one. The colorhash and color name array it returns
473 contain no colors or names.
474 ppm_readcolornamefile() was new in Netpbm 10.15 (April 2003).
476 COLOR INDEXING
480 Sometimes in processing images, you want to associate a value with a
481 particular color. Most often, that's because you're generating a color
482 mapped graphics format. In a color mapped graphics format, the raster
483 contains small numbers, and the file contains a color map that tells
484 what color each of those small numbers refers to. If your image has
485 only 256 colors, but each color takes 24 bits to describe, this can
486 make your output file much smaller than a straightforward RGB raster
487 would.
488 So, continuing the above example, say you have a pixel value for char‐
490 treuse and in your output file and you are going to represent char‐
491 treuse by the number 12. You need a data structure that allows your
492 program quickly to find out that the number for a chartreuse pixel is
493 12. Netpbm's color indexing data types and functions give you that.
494 colorhash_table is a C data type that associates an integer with each
496 of an arbitrary number of colors. It is a hash table, so it uses far
497 less space than an array indexed by the color's RGB values would.
498 The problem with a colorhash_table is that you can only look things up
500 in it. You can't find out what colors are in it. So Netpbm has an‐
501 other data type for representing the same information, the poorly but
502 historically named colorhist_vector. A colorhist_vector is just an ar‐
503 ray. Each entry represents a color and contains the color's value (as
504 a pixel) and the integer value associated with it. The entries are
505 filled in starting with subscript 0 and going consecutively up for the
506 number of colors in the histogram.
507 (The reason the name is poor is because a color histogram is only one
509 of many things that could be represented by it).
510 colorhash_table ppm_alloccolorhash()
512 This creates a colorhash_table using dynamically allocated storage.
514 There are no colors in it. If there is not enough storage, throws an
515 error ⟨liberror.html#error⟩ .
516 void ppm_freecolorhash()
518 This destroys a ppm_freecolorhash and frees all the storage associated
520 with it.
521 int ppm_addtocolorhash( colorhash_table cht, const pixel * const col‐
523 orP, const int value)
524 This adds the specified color to the specified colorhash_table
526 and associates the specified value with it.
527 You must ensure that the color you are adding isn't already present in
529 the colorhash_table.
530 There is no way to update an entry or delete an entry from a col‐
532 orhash_table.
533 int ppm_lookupcolor( const colorhash_table cht, const pixel * const
535 colorP )
536 This looks up the specified color in the specified colorhash_table. It
538 returns the integer value associated with that color.
539 If the specified color is not in the hash table, the function returns
541 -1. (So if you assign the value -1 to a color, the return value is am‐
542 biguous).
543 colorhist_vector ppm_colorhashtocolorhist( const colorhash_table cht,
545 const int ncolors )
547 This converts a colorhash_table to a colorhist_vector. The return
549 value is a new colorhist_vector which you must eventually free with
550 ppm_freecolorhist().
551 ncolors is the number of colors in cht. If it has more colors than
553 that, ppm_colorhashtocolorhist does not create a colorhist_vector and
554 returns NULL.
555 colorhash_table ppm_colorhisttocolorhash( const colorhist_vector chv,
557 const int ncolors )
558 This poorly named function does not convert from a colorhist_vector to
560 a colorhash_table.
561 It does create a colorhash_table based on a colorhist_vector input, but
563 the integer value for a given color in the output is not the same as
564 the integer value for that same color in the input. ppm_colorhistto‐
565 colorhash() ignores the integer values in the input. In the output,
566 the integer value for a color is the index in the input colorhist_vec‐
567 tor for that color.
568 You can easily create a color map for an image by running ppm_compute‐
570 colorhist() over the image, then ppm_colorhisttocolorhash() over the
571 result. Now you can use ppm_lookupcolor() to find a unique color index
572 for any pixel in the input.
573 If the same color appears twice in the input, ppm_colorhisttocol‐
575 orhash() throws an error ⟨liberror.html#error⟩ .
576 ncolors is the number of colors in chv.
578 The return value is a new colorhash_table which you must eventually
580 free with ppm_freecolorhash().
581 COLOR HISTOGRAMS
584 The Netpbm libraries give you functions to examine a Netpbm image and
585 determine what colors are in it and how many pixels of each color are
586 in it. This information is known as a color histogram. Netpbm uses
587 its colorhash_table data type to represent a color histogram.
588 colorhash_table ppm_computecolorhash( pixel ** const pixels, const int
590 cols, const int rows, const int maxcolors, int* const colorsP )
591 This poorly but historically named function generates a colorhash_table
593 whose value for each color is the number of pixels in a specified image
594 that have that color. (I.e. a color histogram). As a bonus, it re‐
595 turns the number of colors in the image.
596 (It's poorly named because not all colorhash_tables are color his‐
598 tograms, but that's all it generates).
599 pixels, cols, and rows describe the input image.
601 maxcolors is the maximum number of colors you want processed. If there
603 are more colors that that in the input image, ppm_computecolorhash()
604 returns NULL as its return value and stops processing as soon as it
605 discovers this. This makes it run faster and use less memory. One use
606 for maxcolors is when you just want to find out whether or not the im‐
607 age has more than N colors and don't want to wait to generate a huge
608 color table if so. If you don't want any limit on the number of col‐
609 ors, specify maxcolors=0.
610 ppm_computecolorhash() returns the actual number of colors in the image
612 as *colorsP, but only if it is less than or equal to maxcolors.
613 colorhash_table ppm_computecolorhash2( FILE * const ifp, const int
615 cols, const int rows, const pixval maxval, const int format,
616 const int maxcolors, int* const colorsP )
618 This is the same as ppm_computecolorhash() except that instead of feed‐
620 ing it an array of pixels in storage, you give it an open file stream
621 and it reads the image from the file. The file must be positioned af‐
622 ter the header, at the raster. Upon return, the file is still open,
623 but its position is undefined.
624 maxval and format are the values for the image (i.e. information from
626 the file's header).
627 colorhist_vector ppm_computecolorhist( pixel ** pixels, int cols, int
629 rows, int maxcolors, int * colorsP )
630 This is like ppm_computecolorhash() except that it creates a col‐
632 orhist_vector instead of a colorhash_table.
633 If you supply a nonzero maxcolors argument, that is the maximum number
635 of colors you expect to find in the input image. If there are more
636 colors than you say in the image, ppm_computecolorhist() returns a null
637 pointer as its return value and nothing meaningful as *colorsP.
638 If not, the function returns the new colorhist_vector as its return
640 value and the actual number of colors in the image as *colorsP. The
641 returned array has space allocated for the specified number of colors
642 regardless of how many actually exist. The extra space is at the high
643 end of the array and is available for your use in expanding the col‐
644 orhist_vector.
645 If you specify maxcolors=0, there is no limit on the number of colors
647 returned and the return array has space for 5 extra colors at the high
648 end for your use in expanding the colorhist_vector.
649 colorhist_vector ppm_computecolorhist2( FILE * ifp, int cols, int rows,
651 int maxcolors, pixval maxval, int format, int * colorsP )
652 This is the same as ppm_computecolorhist() 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 af‐
656 ter the header, at the raster. Upon return, the file is still open,
657 but its position is undefined.
658
661 pbm(1), pgm(1), libpbm(1)
662
665 Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.
666
668 This manual page was generated by the Netpbm tool 'makeman' from HTML
669 source. The master documentation is at
670 http://netpbm.sourceforge.net/doc/libppm.html
672netpbm documentation 08 May 20U0s9er manual for old ppm functions(3)