diff options
| author | giraffedata <giraffedata@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2020-08-08 18:18:08 +0000 |
|---|---|---|
| committer | giraffedata <giraffedata@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2020-08-08 18:18:08 +0000 |
| commit | 31ea43d06c92da53cedcfc2031d190abebe80ccd (patch) | |
| tree | 38cd707f7b4eb88763349156e7d3aa95e1aa0e43 /libppm.html | |
| parent | ad48d09aa16cf2c106ba4d0e232c703a75ab5c49 (diff) | |
| download | netpbm-mirror-31ea43d06c92da53cedcfc2031d190abebe80ccd.tar.gz netpbm-mirror-31ea43d06c92da53cedcfc2031d190abebe80ccd.tar.xz netpbm-mirror-31ea43d06c92da53cedcfc2031d190abebe80ccd.zip | |
miscellaneous update
git-svn-id: http://svn.code.sf.net/p/netpbm/code/userguide@3906 9d0c8265-081b-0410-96cb-a4ca84ce46f8
Diffstat (limited to 'libppm.html')
| -rw-r--r-- | libppm.html | 664 |
1 files changed, 332 insertions, 332 deletions
diff --git a/libppm.html b/libppm.html index a2b06db0..2b4fdceb 100644 --- a/libppm.html +++ b/libppm.html @@ -1,178 +1,178 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> -<HTML> -<HEAD> -<TITLE>User manual for old ppm functions</TITLE> -<META NAME="manual_section" CONTENT="3"> -</HEAD> -<BODY> -<H1>libppm</H1> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.3//EN"> +<html> +<head> +<title>User manual for old ppm functions</title> +<meta name="manual_section" content="3"> +</head> +<body> +<h1>libppm</h1> Updated: 8 May 2009 -<BR> -<A HREF="#index">Table Of Contents</A> +<br> +<a href="#index">Table Of Contents</a> -<H2>NAME</H2> +<h2>NAME</h2> libppm - functions for PPM programs -<H2 id="synopsis">SYNOPSIS</H2> +<h2 id="synopsis">SYNOPSIS</h2> -<B>#include <netpbm/ppm.h></B> +<b>#include <netpbm/ppm.h></b> -<P> -<B>void ppm_init(</B><B>int *</B> <I>argcP</I><B>,</B> - <B>char *</B> <I>argv</I><B>[]</B><B>);</B> +<p> +<b>void ppm_init(</b><b>int *</b> <i>argcP</i><b>,</b> + <b>char *</b> <i>argv</i><b>[]</b><b>);</b> + +<p> +<b>pixel ** ppm_allocarray(</b> + +<b>int </b><i>cols</i><b>,</b><b>int</b> <i>rows</i><b>);</b> + +<p> +<b>pixel * ppm_allocrow(</b><b>int</b> <i>cols</i><b>);</b> + +<p> +<b>void ppm_freearray(</b><b>pixel **</b> <i>pixels</i><b>,</b> + <b>int</b> <i>rows</i><b>);</b> + +<p> +<b>void ppm_freerow(</b><b>pixel *</b> <i>pixelrow</i><b>);</b> + +<p> +<b>void ppm_readppminit(</b><b>FILE *</b> <i>fp</i><b>,</b> + <b>int *</b> <i>colsP</i><b>,</b> + <b>int *</b> <i>rowsP</i><b>,</b> -<P> -<B>pixel ** ppm_allocarray(</B> +<b>pixval *</b> <i>maxvalP</i><b>,</b><b>int *</b> <i>formatP</i><b> );</b> -<B>int </B><I>cols</I><B>,</B><B>int</B> <I>rows</I><B>);</B> +<p> +<b>void ppm_readppmrow(</b><b>FILE *</b><i>fp</i><b>,</b> + <b>pixel *</b> <i>pixelrow</i><b>,</b> + <b>int </b><i>cols</i><b>,</b> + <b>pixval </b><i>maxval</i><b>,</b> + <b>int </b><i>format</i><b>);</b> -<P> -<B>pixel * ppm_allocrow(</B><B>int</B> <I>cols</I><B>);</B> +<p> +<b>pixel ** ppm_readppm(</b><b>FILE *</b> <i>fp</i><b>,</b> + <b>int *</b> <i>colsP</i><b>,</b> + <b>int *</b> <i>rowsP</i><b>,</b> + <b>pixvalP *</b> <i>maxvalP</i><b>);</b> -<P> -<B>void ppm_freearray(</B><B>pixel **</B> <I>pixels</I><B>,</B> - <B>int</B> <I>rows</I><B>);</B> +<p> +<b>void ppm_writeppminit(</b><b>FILE * <i>fp</i>,</b> + <b>int</b> <i>cols</i><b>,</b> + <b>int</b> <i>rows</i><b>,</b> + <b>pixval</b> <i>maxval</i><b>,</b> + <b>int</b> <i>forceplain</i><b>);</b> -<P> -<B>void ppm_freerow(</B><B>pixel *</B> <I>pixelrow</I><B>);</B> +<p> +<b>void ppm_writeppmrow(</b><b>FILE *</b> <i>fp</i><b>,</b> + <b>pixel *</b> <i>pixelrow</i><b>,</b> + <b>int</b> <i>cols</i><b>,</b> + <b>pixval</b> <i>maxval</i><b>,</b> + <b>int</b> <i>forceplain</i><b>);</b> -<P> -<B>void ppm_readppminit(</B><B>FILE *</B> <I>fp</I><B>,</B> - <B>int *</B> <I>colsP</I><B>,</B> - <B>int *</B> <I>rowsP</I><B>,</B> +<p> +<b>void ppm_writeppm(</b><b>FILE *</b> <i>fp</i><b>,</b> + <b>pixel **</b> <i>pixels</i><b>,</b> + <b>int</b> <i>cols</i><b>,</b> + <b>int</b> <i>rows</i><b>,</b> + <b>pixval</b> <i>maxval</i><b>,</b> + <b>int</b> <i>forceplain</i><b>);</b> -<B>pixval *</B> <I>maxvalP</I><B>,</B><B>int *</B> <I>formatP</I><B> );</B> +<p> +<b>void ppm_writeppm(</b><b>FILE *</b> <i>fp</i><b>,</b> + <b>pixel **</b> <i>pixels</i><b>,</b> + <b>int</b> <i>cols</i><b>,</b> + <b>int</b> <i>rows</i><b>,</b> + <b>pixval</b> <i>maxval</i><b>,</b> + <b>int</b> <i>forceplain</i><b>);</b> -<P> -<B>void ppm_readppmrow(</B><B>FILE *</B><I>fp</I><B>,</B> - <B>pixel *</B> <I>pixelrow</I><B>,</B> - <B>int </B><I>cols</I><B>,</B> - <B>pixval </B><I>maxval</I><B>,</B> - <B>int </B><I>format</I><B>);</B> +<p> +<b>void ppm_nextimage(</b><b>FILE *</b> <i>file</i><b>,</b> + <b>int * const</b> <i>eofP</i><b>);</b> -<P> -<B>pixel ** ppm_readppm(</B><B>FILE *</B> <I>fp</I><B>,</B> - <B>int *</B> <I>colsP</I><B>,</B> - <B>int *</B> <I>rowsP</I><B>,</B> - <B>pixvalP *</B> <I>maxvalP</I><B>);</B> +<p> +<b>void ppm_check(</b><b>FILE *</b> <i>file</i><b>,</b> + <b>const enum pm_check_type</b> <i>check_type</i><b>,</b> + <b>const int</b> <i>format</i><b>,</b> + <b>const int</b> <i>cols</i><b>,</b> + <b>const int</b> <i>rows</i><b>,</b> + <b>const int</b> <i>maxval</i><b>,</b> -<P> -<B>void ppm_writeppminit(</B><B>FILE * <i>fp</i>,</B> - <B>int</B> <I>cols</I><B>,</B> - <B>int</B> <I>rows</I><B>,</B> - <B>pixval</B> <I>maxval</I><B>,</B> - <B>int</B> <I>forceplain</I><B>);</B> +<br> -<P> -<B>void ppm_writeppmrow(</B><B>FILE *</B> <I>fp</I><B>,</B> - <B>pixel *</B> <I>pixelrow</I><B>,</B> - <B>int</b> <i>cols</i><B>,</B> - <B>pixval</B> <I>maxval</I><B>,</B> - <B>int</B> <I>forceplain</I><B>);</B> +<b>enum pm_check_code * const</b> <i>retval</i><b>);</b> + +<p> +<b>typedef ... pixel;</b> -<P> -<B>void ppm_writeppm(</B><B>FILE *</B> <I>fp</I><B>,</B> - <B>pixel **</B> <I>pixels</I><B>,</B> - <B>int</B> <I>cols</I><B>,</B> - <B>int</B> <I>rows</I><B>,</B> - <B>pixval</B> <I>maxval</I><B>,</B> - <B>int</B> <I>forceplain</I><B>);</B> +<b>typedef ... pixval;</b> -<P> -<B>void ppm_writeppm(</B><B>FILE *</B> <I>fp</I><B>,</B> - <B>pixel **</B> <I>pixels</I><B>,</B> - <B>int</B> <I>cols</I><B>,</B> - <B>int</B> <I>rows</I><B>,</B> - <B>pixval</B> <I>maxval</I><B>,</B> - <B>int</B> <I>forceplain</I><B>);</B> +<p> +<b>#define PPM_MAXMAXVAL ...</b> -<P> -<B>void ppm_nextimage(</B><B>FILE *</B> <I>file</I><B>,</B> - <B>int * const</B> <I>eofP</I><B>);</B> +<p> +<b>#define PPM_OVERALLMAXVAL ...</b> -<P> -<B>void ppm_check(</B><B>FILE *</B> <I>file</I><B>,</B> - <B>const enum pm_check_type</B> <I>check_type</I><B>,</B> - <B>const int</B> <I>format</I><B>,</B> - <B>const int</B> <I>cols</I><B>,</B> - <B>const int</B> <I>rows</I><B>,</B> - <B>const int</B> <I>maxval</I><B>,</B> +<p> +<b>#define PPM_FORMAT ...</b> -<BR> +<p> +<b>#define RPPM_FORMAT ...</b> -<B>enum pm_check_code * const</B> <I>retval</I><B>);</B> +<p> +<b>#define PPM_TYPE PPM_FORMAT</b> -<P> -<B>typedef ... pixel;</B> +<p> +<b>#define</b> <b>PPM_FORMAT_TYPE(</b><i>format</i><b>)</b> <b>...</b> -<B>typedef ... pixval;</B> +<p> +<b>pixval PPM_GETR(pixel</b> <i>p</i><b>)</b> -<P> -<B>#define PPM_MAXMAXVAL ...</B> +<p> +<b>pixval PPM_GETG(pixel</b> <i>p</i><b>)</b> -<P> -<B>#define PPM_OVERALLMAXVAL ...</B> +<p> +<b>pixval PPM_GETB(pixel</b> <i>p</i><b>)</b> -<P> -<B>#define PPM_FORMAT ...</B> +<p> +<b>void PPM_ASSIGN(pixel</b> <i>p</i><b>,</b> + <b>pixval</b> <i>red</i><b>,</b> + <b>pixval</b> <i>grn</i><b>,</b> + <b>pixval</b> <i>blu</i><b>)</b> -<P> -<B>#define RPPM_FORMAT ...</B> +<p> +<b>int PPM_EQUAL(pixel</b> <i>p</i><b>,</b> + <b>pixel</b> <i>q</i><b>)</b> -<P> -<B>#define PPM_TYPE PPM_FORMAT</B> +<p> +<b>int PPM_ISGRAY(pixel</b> <i>p</i><b>)</b> -<P> -<B>#define</B> <B>PPM_FORMAT_TYPE(</B><I>format</I><B>)</B> <B>...</B> - -<P> -<B>pixval PPM_GETR(pixel</B> <I>p</I><B>)</B> - -<p> -<B>pixval PPM_GETG(pixel</B> <I>p</I><B>)</B> - -<p> -<B>pixval PPM_GETB(pixel</B> <I>p</I><B>)</B> - -<P> -<B>void PPM_ASSIGN(pixel</B> <I>p</I><B>,</B> - <B>pixval</B> <I>red</I><B>,</b> - <b>pixval</B> <I>grn</I><B>,</b> - <b>pixval</B> <I>blu</I><B>)</B> - -<P> -<B>int PPM_EQUAL(pixel</B> <I>p</I><B>,</b> - <b>pixel</B> <I>q</I><B>)</B> - -<P> -<B>int PPM_ISGRAY(pixel</B> <I>p</I><B>)</B> - -<P> -<B>void</b> - <b>PPM_DEPTH(pixel</B> <I>newp</I><B>,</b> - <b>pixel</B> <I>p</I><B>,</B> - <B>pixval</B> <I>oldmaxval</I><B>,</b> - <b>pixval</B> <I>newmaxval</I><B>)</B> +<p> +<b>void</b> + <b>PPM_DEPTH(pixel</b> <i>newp</i><b>,</b> + <b>pixel</b> <i>p</i><b>,</b> + <b>pixval</b> <i>oldmaxval</i><b>,</b> + <b>pixval</b> <i>newmaxval</i><b>)</b> -<P> -<B>pixel ppm_parsecolor(char *</B> <I>colorname</I><B>,</b> - <b>pixval</B> <I>maxval</I><B>)</B> +<p> +<b>pixel ppm_parsecolor(char *</b> <i>colorname</i><b>,</b> + <b>pixval</b> <i>maxval</i><b>)</b> -<P> -<B>pixel ppm_parsecolor2(</B> -<b>char *</b> <I>colorname</I><B>,</b> -<b>pixval</B> <I>maxval</I><B>,</B> -<b>int</B> <I>closeOk</I> -<B>)</B> +<p> +<b>pixel ppm_parsecolor2(</b> +<b>char *</b> <i>colorname</i><b>,</b> +<b>pixval</b> <i>maxval</i><b>,</b> +<b>int</b> <i>closeOk</i> +<b>)</b> -<P> -<B>char * ppm_colorname(pixel *</B> <I>colorP</I><B>,</b> - <b>pixval</B> <I>maxval</I><B>,</b> - <b>int</B> <I>hexok</I><B>)</B> +<p> +<b>char * ppm_colorname(pixel *</b> <i>colorP</i><b>,</b> + <b>pixval</b> <i>maxval</i><b>,</b> + <b>int</b> <i>hexok</i><b>)</b> -<P> -<B>void ppm_readcolornamefile(</b> +<p> +<b>void ppm_readcolornamefile(</b> <b>const char *</b><i>fileName</i>, <b>int</b> <i>mustOpen</i>, <b>colorhash_table *</b> <i>chtP</i>, @@ -180,129 +180,129 @@ libppm - functions for PPM programs <b>)</b> -<H2 id="description">DESCRIPTION</H2> +<h2 id="description">DESCRIPTION</h2> <p>These library functions are part of <a href="index.html">Netpbm</a>. -<H3 id="types">TYPES AND CONSTANTS</H3> +<h3 id="types">TYPES AND CONSTANTS</h3> -Each <B>pixel</B> contains three <B>pixval</B>s, each of which should -contain only the values between <B>0</B> and <B>PPM_MAXMAXVAL</B>. +Each <b>pixel</b> contains three <b>pixval</b>s, each of which should +contain only the values between <b>0</b> and <b>PPM_MAXMAXVAL</b>. -<H3 id="manipulating_pixels">MANIPULATING PIXELS</H3> +<h3 id="manipulating_pixels">MANIPULATING PIXELS</h3> -<p>The macros <B>PPM_GETR</B>, <B>PPM_GETG</B>, and <B>PPM_GETB</B> +<p>The macros <b>PPM_GETR</b>, <b>PPM_GETG</b>, and <b>PPM_GETB</b> retrieve the red, green, or blue sample, respectively, from the given pixel. -<P>The <B>PPM_ASSIGN</B> macro assigns the given values to the red, +<p>The <b>PPM_ASSIGN</b> macro assigns the given values to the red, green, and blue samples of the given pixel. -<P>The <B>PPM_EQUAL</B> macro tests two pixels for equality. +<p>The <b>PPM_EQUAL</b> macro tests two pixels for equality. -<P>The <B>PPM_ISGRAY</B> macro tests a pixel for being gray. It +<p>The <b>PPM_ISGRAY</b> macro tests a pixel for being gray. It returns true if and only if the color of pixel <i>p</i> is black, white, or gray. -<P>The <B>PPM_DEPTH</B> macro scales the colors of pixel <I>p</I> +<p>The <b>PPM_DEPTH</b> macro scales the colors of pixel <i>p</i> according the old and new maxvals and assigns the new values to -<I>newp</I>. It is intended to make writing ppmtowhatever easier. +<i>newp</i>. It is intended to make writing ppmtowhatever easier. -<P>The <B>PPM_LUMIN</B>, <B>PPM_CHROM_R</B>, and <B>PPM_CHROM_B</B> +<p>The <b>PPM_LUMIN</b>, <b>PPM_CHROM_R</b>, and <b>PPM_CHROM_B</b> macros determine the luminance, red chrominance, and blue chrominance, -respectively, of the pixel <I>p</I>. The scale of all these values is +respectively, of the pixel <i>p</i>. The scale of all these values is the same as the scale of the input samples (i.e. 0 to maxval for luminance, -maxval/2 to maxval/2 for chrominance). -<P>Note that the macros do it by floating point multiplication. If +<p>Note that the macros do it by floating point multiplication. If you are computing these values over an entire image, it may be significantly faster to do it with multiplication tables instead. Compute all the possible products once up front, then for each pixel, just look up the products in the tables. -<H3 id="initialization">INITIALIZATION</H3> +<h3 id="initialization">INITIALIZATION</h3> <p><b>ppm_init()</b> is obsolete (at least since Netpbm 9.25 (March 2002)). Use <a href="libpm.html#initialization"><b>pm_proginit()</b></a> instead. -<P><b>ppm_init()</b> is identical to <b>pm_proginit</b>. +<p><b>ppm_init()</b> is identical to <b>pm_proginit</b>. -<H3 id="memorymanagement">MEMORY MANAGEMENT</H3> +<h3 id="memorymanagement">MEMORY MANAGEMENT</h3> -<B>ppm_allocarray()</B> allocates an array of pixels. +<b>ppm_allocarray()</b> allocates an array of pixels. -<P><B>ppm_allocrow()</B> allocates a row of the given number of +<p><b>ppm_allocrow()</b> allocates a row of the given number of pixels. -<P><B>ppm_freearray()</B> frees the array allocated with -<B>ppm_allocarray()</B> containing the given number of rows. +<p><b>ppm_freearray()</b> frees the array allocated with +<b>ppm_allocarray()</b> containing the given number of rows. -<P><B>ppm_freerow()</B> frees a row of pixelss allocated with -<B>ppm_allocrow()</B>. +<p><b>ppm_freerow()</b> frees a row of pixelss allocated with +<b>ppm_allocrow()</b>. -<H3 id="readingfiles">READING FILES</H3> +<h3 id="readingfiles">READING FILES</h3> -<P>If a function in this section is called on a PBM or PGM format +<p>If a function in this section is called on a PBM or PGM format file, it translates the PBM or PGM file into a PPM file on the fly and functions as if it were called on the equivalent PPM file. The -<I>format</I> value returned by <B>ppm_readppminit()</B> is, however, +<i>format</i> value returned by <b>ppm_readppminit()</b> is, however, not translated. It represents the actual format of the PBM or PGM file. -<P><B>ppm_readppminit()</B> reads the header of a PPM file, returning +<p><b>ppm_readppminit()</b> reads the header of a PPM file, returning all the information from the header and leaving the file positioned just after the header. -<P><B>ppm_readppmrow()</B> reads a row of pixels into the -<I>pixelrow</I> array. <I>format</I>, <I>cols</I>, and <I>maxval</I> -are the values returned by <B>ppm_readppminit()</B>. +<p><b>ppm_readppmrow()</b> reads a row of pixels into the +<i>pixelrow</i> array. <i>format</i>, <i>cols</i>, and <i>maxval</i> +are the values returned by <b>ppm_readppminit()</b>. -<P><B>ppm_readppm()</B> reads an entire PPM image into memory, +<p><b>ppm_readppm()</b> reads an entire PPM image into memory, returning the allocated array as its return value and returning the -information from the header as <I>rows</I>, <I>cols</I>, and -<I>maxval</I>. This function combines <B>ppm_readppminit()</B>, -<B>ppm_allocarray()</B>, and <B>ppm_readppmrow()</B>. +information from the header as <i>rows</i>, <i>cols</i>, and +<i>maxval</i>. This function combines <b>ppm_readppminit()</b>, +<b>ppm_allocarray()</b>, and <b>ppm_readppmrow()</b>. -<H3 id="writingfiles">WRITING FILES</H3> +<h3 id="writingfiles">WRITING FILES</h3> -<B>ppm_writeppminit()</B> writes the header for a PPM file and leaves +<b>ppm_writeppminit()</b> writes the header for a PPM file and leaves it positioned just after the header. -<P><I>forceplain</I> is a logical value that tells -<B>ppm_writeppminit() </B> to write a header for a plain PPM format +<p><i>forceplain</i> is a logical value that tells +<b>ppm_writeppminit() </b> to write a header for a plain PPM format file, as opposed to a raw PPM format file. -<P><B>ppm_writeppmrow()</B> writes the row <I>pixelrow</I> to a PPM -file. For meaningful results, <I>cols</I>, <I>maxval</I>, and -<I>forceplain</I> must be the same as was used with -<B>ppm_writeppminit()</B>. +<p><b>ppm_writeppmrow()</b> writes the row <i>pixelrow</i> to a PPM +file. For meaningful results, <i>cols</i>, <i>maxval</i>, and +<i>forceplain</i> must be the same as was used with +<b>ppm_writeppminit()</b>. -<P><B>ppm_writeppm()</B> write the header and all data for a PPM -image. This function combines <B>ppm_writeppminit()</B> and -<B>ppm_writeppmrow()</B>. +<p><b>ppm_writeppm()</b> write the header and all data for a PPM +image. This function combines <b>ppm_writeppminit()</b> and +<b>ppm_writeppmrow()</b>. -<H3 id="miscellaneous">MISCELLANEOUS</H3> +<h3 id="miscellaneous">MISCELLANEOUS</h3> -<P><B>ppm_nextimage()</B> positions a PPM input file to the next image -in it (so that a subsequent <B>ppm_readppminit()</B> reads its +<p><b>ppm_nextimage()</b> positions a PPM input file to the next image +in it (so that a subsequent <b>ppm_readppminit()</b> reads its header). -<P><B>ppm_nextimage()</B> is analogous to <B>pbm_nextimage()</B>, but +<p><b>ppm_nextimage()</b> is analogous to <b>pbm_nextimage()</b>, but works on PPM, PGM, and PBM files. -<P><B>ppm_check() </B> checks for the common file integrity error +<p><b>ppm_check() </b> checks for the common file integrity error where the file is the wrong size to contain all the image data. -<P><B>ppm_check() </B> is analogous to <B>pbm_check()</B>, but works +<p><b>ppm_check() </b> is analogous to <b>pbm_check()</b>, but works on PPM, PGM, and PBM files. <h3 id="color">COLOR</h3> -<H4 id="luminance">Luminance, Chrominance (YcbCr)</H4> +<h4 id="luminance">Luminance, Chrominance (YcbCr)</h4> <pre> <code> @@ -312,7 +312,7 @@ on PPM, PGM, and PBM files. </code> </pre> -<p><B>PPM_LUMIN</B> takes a <b>pixel</b> as an argument and returns +<p><b>PPM_LUMIN</b> takes a <b>pixel</b> as an argument and returns the luminance of that pixel, with the same maxval as the pixel (e.g. if the pixel's maxval is 255, a <b>PPM_LUMIN</b> value of 255 means fully luminant). @@ -321,14 +321,14 @@ means fully luminant). and blue chrominance values. -<PRE> -<CODE> +<pre> +<code> pixel ppm_color_from_ycbcr(unsigned int y, int cb, int cr); -</CODE> -</PRE> +</code> +</pre> <p><b>ppm_color_from_ycbcr()</b> converts in the other direction. Given luminance and chrominance, it returns a pixel value. @@ -464,16 +464,16 @@ represents it. <p>All of the facilities in this section were new in Netpbm 10.34 (June 2006). -<H3 id="colorname">COLOR NAMES</H3> +<h3 id="colorname">COLOR NAMES</h3> <h4 id="dictionary">System Color Dictionary</h4> -<P>Netpbm uses the system's X11 color dictionary (usually in +<p>Netpbm uses the system's X11 color dictionary (usually in <b>/usr/lib/X11/rgb.txt</b>). This is the same file the X Window System typically uses to associate colors with their names. <p>The color dictionary that Netpbm uses is in the file whose name is -the value of the <B>RGBDEF</B> environment variable. If <B>RGBDEF</B> +the value of the <b>RGBDEF</b> environment variable. If <b>RGBDEF</b> is not set, Netpbm defaults to the first existing file from this list: <ol> @@ -482,55 +482,55 @@ is not set, Netpbm defaults to the first existing file from this list: <li><b>/usr/X11R6/lib/X11/rgb.txt</b> </ol> -<P>You can see the color names from a typical X11 color dictionary, +<p>You can see the color names from a typical X11 color dictionary, which is probably very close to what is on your system, along with the colors, <a href="http://www.swiss.ai.mit.edu/~jaffer/Color/x11.pdf">here</a>. <a href="http://www.swiss.ai.mit.edu/~jaffer/Color/Dictionaries.html">This website</a> shows a bunch of other versions you could use. -<P>Netpbm is packaged with a color dictionary. A standard Netpbm +<p>Netpbm is packaged with a color dictionary. A standard Netpbm installation installs this file as "misc/rgb.txt" in the Netpbm directory. This color dictionary has colors from everywhere the Netpbm maintainer could find them, and is a superset of XFree 86's color dictionary. -<H4 id="ppm_parsecolor">ppm_parsecolor</H4> +<h4 id="ppm_parsecolor">ppm_parsecolor</h4> -<p><B>ppm_parsecolor()</B> interprets a color specification and returns a +<p><b>ppm_parsecolor()</b> interprets a color specification and returns a pixel of the color that it indicates. It is the same as <a href="libnetpbm_image.html#colorname">pnm_parsecolor</a>, except that it returns a <b>pixel</b> instead of a <b>tuple</b>. -<H4 id="ppm_parsecolor2">ppm_parsecolor2</H4> +<h4 id="ppm_parsecolor2">ppm_parsecolor2</h4> -<p><B>ppm_parsecolor2()</B> interprets a color specification and returns a +<p><b>ppm_parsecolor2()</b> interprets a color specification and returns a pixel of the color that it indicates and warns about rounding. It is the same as <a href="libnetpbm_image.html#colorname">pnm_parsecolor2</a>, except that it returns a <b>pixel</b> instead of a <b>tuple</b>. <h4 id="ppm_colorname">ppm_colorname</h4> -<P><B>ppm_colorname()</B> returns a string that describes the color +<p><b>ppm_colorname()</b> returns a string that describes the color of the given pixel. If a <a href="#dictionary">system color dictionary</a> -is available and the color appears in it, <B>ppm_colorname()</B> +is available and the color appears in it, <b>ppm_colorname()</b> returns the name of the color from the file. If the color does not -appear in a system color dictionary and <I>hexok</I> is true, -<B>ppm_colorname()</B> returns a hexadecimal color specification +appear in a system color dictionary and <i>hexok</i> is true, +<b>ppm_colorname()</b> returns a hexadecimal color specification triple (#rrggbb). If a system color dictionary is available but the -color does not appear in it and <I>hexok</I> is false, -<B>ppm_colorname()</B> returns the name of the closest matching color +color does not appear in it and <i>hexok</i> is false, +<b>ppm_colorname()</b> returns the name of the closest matching color in the color file. Finally, if there is no system color dictionary -available and <I>hexok</I> is false, <B>ppm_colorname()</B> fails and +available and <i>hexok</i> is false, <b>ppm_colorname()</b> fails and <a href="liberror.html#error">throws an error</a>. -<P>The string returned is in static libppm library storage which is -overwritten by every call to <B>ppm_colorname()</B>. +<p>The string returned is in static libppm library storage which is +overwritten by every call to <b>ppm_colorname()</b>. <h4 id="ppm_readcolornamefile">ppm_readcolornamefile</h4> -<P><b>ppm_readcolornamefile()</b> reads the entire contents of the color +<p><b>ppm_readcolornamefile()</b> reads the entire contents of the color dictionary in the file named <i>fileName</i> into data structures you can use to access it easily. @@ -561,9 +561,9 @@ colors or names. <p><b>ppm_readcolornamefile()</b> was new in Netpbm 10.15 (April 2003). -<H3 id="colorindex">COLOR INDEXING</H3> +<h3 id="colorindex">COLOR INDEXING</h3> -<P>Sometimes in processing images, you want to associate a value with +<p>Sometimes in processing images, you want to associate a value with a particular color. Most often, that's because you're generating a color mapped graphics format. In a color mapped graphics format, the raster contains small numbers, and the file contains a color map that @@ -572,219 +572,219 @@ has only 256 colors, but each color takes 24 bits to describe, this can make your output file much smaller than a straightforward RGB raster would. -<P>So, continuing the above example, say you have a <B>pixel</B> value +<p>So, continuing the above example, say you have a <b>pixel</b> value for chartreuse and in your output file and you are going to represent chartreuse by the number 12. You need a data structure that allows your program quickly to find out that the number for a chartreuse -<B>pixel</B> is 12. Netpbm's color indexing data types and functions +<b>pixel</b> is 12. Netpbm's color indexing data types and functions give you that. -<P><B>colorhash_table</B> is a C data type that associates an integer +<p><b>colorhash_table</b> is a C data type that associates an integer with each of an arbitrary number of colors. It is a hash table, so it uses far less space than an array indexed by the color's RGB values would. -<P>The problem with a <B>colorhash_table</B> is that you can only look +<p>The problem with a <b>colorhash_table</b> is that you can only look things up in it. You can't find out what colors are in it. So Netpbm has another data type for representing the same information, the -poorly but historically named <B>colorhist_vector</B>. A -<B>colorhist_vector</B> is just an array. Each entry represents a -color and contains the color's value (as a <B>pixel</B>) and the +poorly but historically named <b>colorhist_vector</b>. A +<b>colorhist_vector</b> is just an array. Each entry represents a +color and contains the color's value (as a <b>pixel</b>) and the integer value associated with it. The entries are filled in starting with subscript 0 and going consecutively up for the number of colors in the histogram. -<P>(The reason the name is poor is because a color histogram is only +<p>(The reason the name is poor is because a color histogram is only one of many things that could be represented by it). -<P><B>colorhash_table ppm_alloccolorhash()</B> +<p><b>colorhash_table ppm_alloccolorhash()</b> -<P>This creates a <B>colorhash_table</B> using dynamically allocated +<p>This creates a <b>colorhash_table</b> using dynamically allocated storage. There are no colors in it. If there is not enough storage, <a href="liberror.html#error">throws an error</a>. -<P><B>void ppm_freecolorhash()</B> +<p><b>void ppm_freecolorhash()</b> -<P>This destroys a <B>ppm_freecolorhash </B> and frees all the storage +<p>This destroys a <b>ppm_freecolorhash </b> and frees all the storage associated with it. -<P><B>int ppm_addtocolorhash( colorhash_table cht, const pixel * const -colorP, const int value)</B> +<p><b>int ppm_addtocolorhash( colorhash_table cht, const pixel * const +colorP, const int value)</b> -<P>This adds the specified color to the specified <B>colorhash_table -</B> and associates the specified value with it. +<p>This adds the specified color to the specified <b>colorhash_table +</b> and associates the specified value with it. -<P>You must ensure that the color you are adding isn't already present -in the <B>colorhash_table</B>. +<p>You must ensure that the color you are adding isn't already present +in the <b>colorhash_table</b>. -<P>There is no way to update an entry or delete an entry from a -<B>colorhash_table</B>. +<p>There is no way to update an entry or delete an entry from a +<b>colorhash_table</b>. -<P><B>int ppm_lookupcolor( const colorhash_table cht, const pixel * -const colorP )</B> +<p><b>int ppm_lookupcolor( const colorhash_table cht, const pixel * +const colorP )</b> -<P>This looks up the specified color in the specified -<B>colorhash_table</B>. It returns the integer value associated with +<p>This looks up the specified color in the specified +<b>colorhash_table</b>. It returns the integer value associated with that color. -<P>If the specified color is not in the hash table, the function +<p>If the specified color is not in the hash table, the function returns -1. (So if you assign the value -1 to a color, the return value is ambiguous). -<P><B>colorhist_vector ppm_colorhashtocolorhist( const colorhash_table cht,</B> +<p><b>colorhist_vector ppm_colorhashtocolorhist( const colorhash_table cht,</b> -<B>const int ncolors )</B> +<b>const int ncolors )</b> -<P>This converts a <B>colorhash_table</B> to a -<B>colorhist_vector</B>. The return value is a new -<B>colorhist_vector</B> which you must eventually free with -<B>ppm_freecolorhist()</B>. +<p>This converts a <b>colorhash_table</b> to a +<b>colorhist_vector</b>. The return value is a new +<b>colorhist_vector</b> which you must eventually free with +<b>ppm_freecolorhist()</b>. -<P><B>ncolors</B> is the number of colors in <B>cht</B>. If it has -more colors than that, <B>ppm_colorhashtocolorhist</B> does not create -a <B>colorhist_vector</B> and returns NULL. +<p><b>ncolors</b> is the number of colors in <b>cht</b>. If it has +more colors than that, <b>ppm_colorhashtocolorhist</b> does not create +a <b>colorhist_vector</b> and returns NULL. -<P><B>colorhash_table ppm_colorhisttocolorhash( const colorhist_vector chv, -const int ncolors ) </B> +<p><b>colorhash_table ppm_colorhisttocolorhash( const colorhist_vector chv, +const int ncolors ) </b> -<P>This poorly named function does <em>not</em> convert from a -<B>colorhist_vector</B> to a <B>colorhash_table</B>. +<p>This poorly named function does <em>not</em> convert from a +<b>colorhist_vector</b> to a <b>colorhash_table</b>. -<P>It does create a <B>colorhash_table</B> based on a -<B>colorhist_vector</B> input, but the integer value for a given color +<p>It does create a <b>colorhash_table</b> based on a +<b>colorhist_vector</b> input, but the integer value for a given color in the output is not the same as the integer value for that same color -in the input. <B>ppm_colorhisttocolorhash()</B> ignores the integer +in the input. <b>ppm_colorhisttocolorhash()</b> ignores the integer values in the input. In the output, the integer value for a color is -the index in the input <B>colorhist_vector</B> for that color. +the index in the input <b>colorhist_vector</b> for that color. -<P>You can easily create a color map for an image by running -<B>ppm_computecolorhist() </B> over the image, then -<B>ppm_colorhisttocolorhash()</B> over the result. Now you can use -<B>ppm_lookupcolor()</B> to find a unique color index for any pixel in +<p>You can easily create a color map for an image by running +<b>ppm_computecolorhist() </b> over the image, then +<b>ppm_colorhisttocolorhash()</b> over the result. Now you can use +<b>ppm_lookupcolor()</b> to find a unique color index for any pixel in the input. -<P>If the same color appears twice in the input, -<B>ppm_colorhisttocolorhash()</B> <a href="liberror.html#error">throws an +<p>If the same color appears twice in the input, +<b>ppm_colorhisttocolorhash()</b> <a href="liberror.html#error">throws an error</a>. -<P><B>ncolors</B> is the number of colors in <B>chv</B>. +<p><b>ncolors</b> is the number of colors in <b>chv</b>. -<P>The return value is a new <B>colorhash_table</B> which you must -eventually free with <B>ppm_freecolorhash()</B>. +<p>The return value is a new <b>colorhash_table</b> which you must +eventually free with <b>ppm_freecolorhash()</b>. -<H3 id="histogram">COLOR HISTOGRAMS</H3> +<h3 id="histogram">COLOR HISTOGRAMS</h3> -<P>The Netpbm libraries give you functions to examine a Netpbm image +<p>The Netpbm libraries give you functions to examine a Netpbm image and determine what colors are in it and how many pixels of each color are in it. This information is known as a color histogram. Netpbm -uses its <B>colorhash_table</B> data type to represent a color +uses its <b>colorhash_table</b> data type to represent a color histogram. -<P><B>colorhash_table ppm_computecolorhash( pixel ** const pixels, -const int cols, const int rows, const int maxcolors, int* const colorsP )</B> +<p><b>colorhash_table ppm_computecolorhash( pixel ** const pixels, +const int cols, const int rows, const int maxcolors, int* const colorsP )</b> -<P>This poorly but historically named function generates a -<B>colorhash_table</B> whose value for each color is the number of +<p>This poorly but historically named function generates a +<b>colorhash_table</b> whose value for each color is the number of pixels in a specified image that have that color. (I.e. a color histogram). As a bonus, it returns the number of colors in the image. -<P>(It's poorly named because not all <B>colorhash_table</B>s are +<p>(It's poorly named because not all <b>colorhash_table</b>s are color histograms, but that's all it generates). -<P><B>pixels</B>, <B>cols</B>, and <B>rows</B> describe the input +<p><b>pixels</b>, <b>cols</b>, and <b>rows</b> describe the input image. -<P><B>maxcolors</B> is the maximum number of colors you want +<p><b>maxcolors</b> is the maximum number of colors you want processed. If there are more colors that that in the input image, -<B>ppm_computecolorhash()</B> returns NULL as its return value and +<b>ppm_computecolorhash()</b> returns NULL as its return value and stops processing as soon as it discovers this. This makes it run -faster and use less memory. One use for <B>maxcolors</B> is when you +faster and use less memory. One use for <b>maxcolors</b> is when you just want to find out whether or not the image has more than N colors and don't want to wait to generate a huge color table if so. If you don't want any limit on the number of colors, specify -<B>maxcolors</B>=<B>0</B>. +<b>maxcolors</b>=<b>0</b>. -<P><B>ppm_computecolorhash()</B> returns the actual number of colors -in the image as <B>*colorsP</B>, but only if it is less than or equal -to <B>maxcolors</B>. +<p><b>ppm_computecolorhash()</b> returns the actual number of colors +in the image as <b>*colorsP</b>, but only if it is less than or equal +to <b>maxcolors</b>. -<P><B>colorhash_table ppm_computecolorhash2( FILE * const ifp, -const int cols, const int rows, const pixval maxval, const int format,</B> +<p><b>colorhash_table ppm_computecolorhash2( FILE * const ifp, +const int cols, const int rows, const pixval maxval, const int format,</b> -<B>const int maxcolors, int* const colorsP )</B> +<b>const int maxcolors, int* const colorsP )</b> -<P>This is the same as <B>ppm_computecolorhash()</B> except that +<p>This is the same as <b>ppm_computecolorhash()</b> except that instead of feeding it an array of pixels in storage, you give it an open file stream and it reads the image from the file. The file must be positioned after the header, at the raster. Upon return, the file is still open, but its position is undefined. -<P><B>maxval</B> and <B>format</B> are the values for the image +<p><b>maxval</b> and <b>format</b> are the values for the image (i.e. information from the file's header). -<P><B>colorhist_vector ppm_computecolorhist( pixel ** pixels, -int cols, int rows, int maxcolors, int * colorsP )</B> +<p><b>colorhist_vector ppm_computecolorhist( pixel ** pixels, +int cols, int rows, int maxcolors, int * colorsP )</b> -<P>This is like <B>ppm_computecolorhash()</B> except that it creates a -<B>colorhist_vector</B> instead of a <B>colorhash_table</B>. +<p>This is like <b>ppm_computecolorhash()</b> except that it creates a +<b>colorhist_vector</b> instead of a <b>colorhash_table</b>. -<P>If you supply a nonzero <B>maxcolors</B> argument, that is the +<p>If you supply a nonzero <b>maxcolors</b> argument, that is the maximum number of colors you expect to find in the input image. If there are more colors than you say in the image, -<B>ppm_computecolorhist()</B> returns a null pointer as its return -value and nothing meaningful as <B>*colorsP</B>. +<b>ppm_computecolorhist()</b> returns a null pointer as its return +value and nothing meaningful as <b>*colorsP</b>. -<P>If not, the function returns the new <B>colorhist_vector </B> as +<p>If not, the function returns the new <b>colorhist_vector </b> as its return value and the actual number of colors in the image as -<B>*colorsP</B>. The returned array has space allocated for the +<b>*colorsP</b>. The returned array has space allocated for the specified number of colors regardless of how many actually exist. The extra space is at the high end of the array and is available for your -use in expanding the <B>colorhist_vector</B>. +use in expanding the <b>colorhist_vector</b>. -<P>If you specify <B>maxcolors</B>=<B>0</B>, there is no limit on the +<p>If you specify <b>maxcolors</b>=<b>0</b>, there is no limit on the number of colors returned and the return array has space for 5 extra colors at the high end for your use in expanding the -<B>colorhist_vector</B>. +<b>colorhist_vector</b>. -<P><B>colorhist_vector ppm_computecolorhist2( FILE * ifp, +<p><b>colorhist_vector ppm_computecolorhist2( FILE * ifp, int cols, int rows, int maxcolors, pixval maxval, int format, -int * colorsP )</B> +int * colorsP )</b> -<P>This is the same as <B>ppm_computecolorhist()</B> except that +<p>This is the same as <b>ppm_computecolorhist()</b> except that instead of feeding it an array of pixels in storage, you give it an open file stream and it reads the image from the file. The file must be positioned after the header, at the raster. Upon return, the file is still open, but its position is undefined. -<H2 id="seealso">SEE ALSO</H2> +<h2 id="seealso">SEE ALSO</h2> -<B><A HREF="pbm.html">pbm</A></B>, -<B><A HREF="pgm.html">pgm</A></B>, -<B><A HREF="libpbm.html">libpbm</A></B> +<b><a href="pbm.html">pbm</a></b>, +<b><a href="pgm.html">pgm</a></b>, +<b><a href="libpbm.html">libpbm</a></b> -<H2 id="author">AUTHOR</H2> +<h2 id="author">AUTHOR</h2> Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer. -<HR> -<H2 id="index">Table Of Contents</H2> -<UL> -<LI><A HREF="#synopsis">SYNOPSIS</A> -<LI><A HREF="#description">DESCRIPTION</A> - <UL> - <LI><A HREF="#types">TYPES AND CONSTANTS</A> - <LI><A HREF="#manipulating_pixels">MANIPULATING PIXELS</A> - <LI><A HREF="#initialization">INITIALIZATION</A> - <LI><A HREF="#memorymanagement">MEMORY MANAGEMENT</A> - <LI><A HREF="#readingfiles">READING FILES</A> - <LI><A HREF="#writingfiles">WRITING FILES</A> - <LI><A HREF="#miscellaneous">MISCELLANEOUS</A> - <LI><A HREF="#color">COLOR</A> +<hr> +<h2 id="index">Table Of Contents</h2> +<ul> +<li><a href="#synopsis">SYNOPSIS</a> +<li><a href="#description">DESCRIPTION</a> + <ul> + <li><a href="#types">TYPES AND CONSTANTS</a> + <li><a href="#manipulating_pixels">MANIPULATING PIXELS</a> + <li><a href="#initialization">INITIALIZATION</a> + <li><a href="#memorymanagement">MEMORY MANAGEMENT</a> + <li><a href="#readingfiles">READING FILES</a> + <li><a href="#writingfiles">WRITING FILES</a> + <li><a href="#miscellaneous">MISCELLANEOUS</a> + <li><a href="#color">COLOR</a> <ul> <li><a href="#luminance">Luminance, Chrominance (YcbCr)</a> <li><a href="#berlinkay">Berlin-Kay Color</a> </ul> - <LI><A HREF="#colorname">COLOR NAMES</A> + <li><a href="#colorname">COLOR NAMES</a> <ul> <li><a href="#dictionary">System Color Dictionary</a> <li><a href="#ppm_parsecolor">ppm_parsecolor</a> @@ -792,11 +792,11 @@ Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer. <li><a href="#ppm_colorname">ppm_colorname</a> <li><a href="#ppm_readcolornamefile">ppm_readcolornamefile</a> </ul> - <LI><A HREF="#colorindex">COLOR INDEXING</A> - <LI><A HREF="#histogram">COLOR HISTOGRAMS</A> - </UL> - <LI><A HREF="#seealso">SEE ALSO</A> - <LI><A HREF="#author">AUTHOR</A> - </UL> -</BODY> -</HTML> + <li><a href="#colorindex">COLOR INDEXING</a> + <li><a href="#histogram">COLOR HISTOGRAMS</a> + </ul> + <li><a href="#seealso">SEE ALSO</a> + <li><a href="#author">AUTHOR</a> + </ul> +</body> +</html> |