Standards, Environments, and Macros                        pbm(5)

NAME
     pbm - portable bitmap file format

DESCRIPTION
     The portable bitmap format is a  lowest  common  denominator
     monochrome file format.  It serves as the common language of
     a large family of bitmap conversion  filters.   Because  the
     format  pays no heed to efficiency, it is simple and general
     enough that one can easily develop programs  to  convert  to
     and from just about any other graphics format, or to manipu-
     late the image.

     This is not a format that one would normally use to store  a
     file  or to transmit it to someone -- it's too expensive and
     not expressive enough for that.  It's just  an  intermediary
     format.  In it's purest use, it lives only in a pipe between
     two other programs.

     The format definition is as follows.

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

     Each PBM image consists of the following:

     - A "magic number" for identifying the  file  type.   A  pbm
       file's magic number is the two characters "P4".

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

     - The width in pixels of the image, formatted as ASCII char-
       acters in decimal.

     - Whitespace.

     - The height in pixels of the image, again in ASCII decimal.

     - Newline or other single whitespace character.

     - A raster of Height rows, in  order  from  top  to  bottom.
       Each  row  is  Width  bits, packed 8 to a byte, with don't
       care bits to fill out the last bye in the row.   Each  bit
       represents  a pixel: 1 is black, 0 is white.  The order of
       the pixels is left to right.  The order of  their  storage
       within  each  file  byte  is most significant bit to least
       significant bit.  The order of the file bytes is from  the
       beginning of the file toward the end of the file.

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

SunOS 5.8          Last change: 05 March 2000                   1

Standards, Environments, and Macros                        pbm(5)

     There is actually another version of the  PBM  format,  even
     more  more  simplistic, more lavishly wasteful of space than
     PBM, called Plain PBM.  Plain PBM actually came  first,  but
     even  its inventor couldn't stand its recklessly squanderous
     use of resources after a while and switched to what  we  now
     know  as the regular PBM format.  But Plain PBM is so redun-
     dant -- so overstated -- that it's virtually  impossible  to
     break.  You can send it through the most liberal mail system
     (which was the original purpose of the PBM  format)  and  it
     will  arrive  still  readable.   You can flip a dozen random
     bits and easily piece back together the original image.  And
     we  hardly  need  to define the format here, because you can
     decode it by inspection.

     The difference is:

     - There is exactly one image in a file.

     - The "magic number" is "P1" instead of "P4".

     - Each pixel in the raster is represented by a byte contain-
       ing ASCII '1' or '0', representing black and white respec-
       tively.  There are no fill bits at the end of a row.

     - White space in the raster section is ignored.

     - You can put any junk you want  after  the  raster,  if  it
       starts with a white space character.

     - No line should be longer than 70 characters.

     Here is an example of a small bitmap in the plain  PBM  for-
     mat:
     P1
     # feep.pbm
     24 7
     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 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0
     0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 1 0
     0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 1 0
     0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0
     0 1 0 0 0 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 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

     You can generate the Plain PBM format from the  regular  PBM
     format (first image in the file only) with the pnmtoplainpnm
     program.

     Programs that read this format should be as lenient as  pos-
     sible, accepting anything that looks remotely like a bitmap.

SunOS 5.8          Last change: 05 March 2000                   2

Standards, Environments, and Macros                        pbm(5)

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

SEE ALSO
     libpbm(3),pnm(5),pgm(5),

AUTHOR
     Copyright (C) 1989, 1991 by Jef Poskanzer.

SunOS 5.8          Last change: 05 March 2000                   3