Provided by: netpbm_10.0-15_amd64 bug

NAME

       pgm - portable graymap file format

DESCRIPTION

       The PGM format is a lowest common denominator grayscale file format.  It is designed to be
       extremely easy to learn and write programs for.  (It's so simple  that  most  people  will
       simply reverse engineer it because it's easier than reading this specification).

       A  PGM  image represents a grayscale graphic image.  There are many psueudo-PGM formats in
       use where everything is as specified herein except for the  meaning  of  individual  pixel
       values.   For  most  purposes,  a  PGM  image can just be thought of an array of arbitrary
       integers, and all the programs in the world that  think  they're  processing  a  grayscale
       image can easily be tricked into processing something else.

       One  official  variant  of PGM is the transparency mask.  A transparency mask in Netpbm is
       represented by a PGM  image,  except  that  in  place  of  pixel  intensities,  there  are
       opaqueness values.  See below.

       The format definition is as follows.

       A  PGM  file  consists  of  a  sequence  of  one  or  more  PGM images. There are no data,
       delimiters, or padding before, after, or between images.

       Each PGM image consists of the following:

       - A "magic number" for identifying the file type.  A pgm image's magic number is  the  two
         characters "P5".

       - Whitespace (blanks, TABs, CRs, LFs).

       - A width, formatted as ASCII characters in decimal.

       - Whitespace.

       - A height, again in ASCII decimal.

       - Whitespace.

       - The maximum gray value (Maxval), again in ASCII decimal.  Must be less than 65536.

       - Newline or other single whitespace character.

       - A  raster  of Width * Height gray values, proceeding through the image in normal English
         reading order.  Each gray value is a number from 0 through Maxval, with  0  being  black
         and  Maxval being white.  Each gray value is represented in pure binary by either 1 or 2
         bytes.  If the Maxval is less than 256, it is 1 byte.  Otherwise, it is  2  bytes.   The
         most significant byte is first.

       - Each  gray value is a number proportional to the intensity of the pixel, adjusted by the
         CIE Rec. 709 gamma transfer function.  (That transfer function specifies a gamma  number
         of  2.2  and  has a linear section for small intensities).  A value of zero is therefore
         black.  A value of Maxval represents CIE D65 white and the most  intense  value  in  the
         image and any other image to which the image might be compared.

       - Note  that  a  common variation on the PGM format is to have the gray value be "linear,"
         i.e. as specified above except without the gamma adjustment.  pnmgamma takes such a  PGM
         variant as input and produces a true PGM as output.

       - In  the  transparency  mask  variation  on  PGM, the value represents opaqueness.  It is
         proportional to the fraction of intensity of a pixel that would  show  in  place  of  an
         underlying  pixel,  with  the  same gamma transfer function mentioned above applied.  So
         what normally means white represents total opaqueness  and  what  normally  means  black
         represents  total  transparency.   In  between,  you  would  compute  the intensity of a
         composite pixel of an "under" and "over" pixel as  under  *  (1-(alpha/alpha_maxval))  +
         over * (alpha/alpha_maxval).<

       - Characters  from a "#" to the next end-of-line, before the maxval line, are comments and
         are ignored.

       Note that you can use pnmdepth To convert between a the format with 1 byte per gray  value
       and the one with 2 bytes per gray value.

       There  is  actually  another  version  of  the PGM format that is fairly rare: "plain" PGM
       format.  The format above, which generally considered the normal  one,  is  known  as  the
       "raw"  PGM  format.  See pbm(5) for some commentary on how plain and raw formats relate to
       one another.

       The difference in the plain format is:

       - There is exactly one image in a file.

       - The magic number is P2 instead of P5.

       - Each pixel in the raster is represented as an ASCII decimal number (of arbitrary size).

       - Each pixel in the raster has white space before and after it.  There must  be  at  least
         one character of white space between any two pixels, but there is no maximum.

       - No line should be longer than 70 characters.

       Here is an example of a small graymap in this format:
       P2
       # feep.pgm
       24 7
       15
       0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
       0  3  3  3  3  0  0  7  7  7  7  0  0 11 11 11 11  0  0 15 15 15 15  0
       0  3  0  0  0  0  0  7  0  0  0  0  0 11  0  0  0  0  0 15  0  0 15  0
       0  3  3  3  0  0  0  7  7  7  0  0  0 11 11 11  0  0  0 15 15 15 15  0
       0  3  0  0  0  0  0  7  0  0  0  0  0 11  0  0  0  0  0 15  0  0  0  0
       0  3  0  0  0  0  0  7  7  7  7  0  0 11 11 11 11  0  0 15  0  0  0  0
       0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0

       Programs  that  read this format should be as lenient as possible, accepting anything that
       looks remotely like a graymap.

COMPATIBILITY

       Before April 2000, a raw format PGM file could not have a maxval greater than 255.  Hence,
       it could not have more than one byte per sample.  Old programs may depend on this.

       Before July 2000, there could be at most one image in a PGM file.  As a result, most tools
       to process PGM files ignore (and don't read) any data after the first image.

SEE ALSO

       fitstopgm(1),  fstopgm(1),   hipstopgm(1),   lispmtopgm(1),   psidtopgm(1),   rawtopgm(1),
       pgmbentley(1), pgmcrater(1), pgmedge(1), pgmenhance(1), pgmhist(1), pgmnorm(1), pgmoil(1),
       pgmramp(1), pgmtexture(1), pgmtofits(1), pgmtofs(1), pgmtolispm(1),  pgmtopbm(1),  pnm(5),
       pbm(5), ppm(5)

AUTHOR

       Copyright (C) 1989, 1991 by Jef Poskanzer.

                                         12 November 1991                                  pgm(5)