pbm

pbm(5)                        File Formats Manual                       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 effi-
       ciency, 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 manipulate 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 image's  magic
         number is the two characters "P4".

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

       - The  width  in  pixels of the image, formatted as ASCII characters 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 byte 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  sig-
         nificant  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.

       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 origi-
       nal purpose of the PBM format) and it will arrive still readable.   You
       can  flip a dozen random bits and easily piece back together the origi-
       nal 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 containing ASCII
         '1' or '0', representing black and white respectively.  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 format:
       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 possible, ac-
       cepting anything that looks remotely like a bitmap.

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),ppm(5)

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

                                 05 March 2000                          pbm(5)