PBMTOJBG(1)                                                        PBMTOJBG(1)



NAME
       pbmtojbg - portable bitmap to JBIG1 file converter

SYNOPSIS
       pbmtojbg [ options ] [ input-file | -  [ output-file ]]

DESCRIPTION
       Reads  in  a  portable bitmap (PBM) from a file or standard input, com-
       presses it, and outputs the image as  a  JBIG1  bi-level  image  entity
       (BIE) file.

       JBIG1 is a highly effective lossless compression algorithm for bi-level
       images (one bit per pixel), which is particularly suitable for  scanned
       document pages.

       A JBIG1 encoded image can be stored in several resolutions (progressive
       mode).  These resolution layers can be stored all in one single BIE  or
       they  can be stored in several separate BIE files.  All resolution lay-
       ers except the lowest one are stored merely as differences to the  next
       lower  resolution layer, because this requires less space than encoding
       the full image completely every time. Each resolution layer  has  twice
       the number of horizontal and vertical pixels than the next lower layer.
       JBIG1 files can also store several bits per pixel  as  separate  bitmap
       planes, and pbmtojbg can read a PGM file and transform it into a multi-
       bitplane BIE.


OPTIONS
       -             A single hyphen instead of an input file name will  cause
                     pbmtojbg  to  read  the  data from standard input instead
                     from a file.

       -q            Encode the image in one single resolution layer  (sequen-
                     tial  mode).  This is usually the most efficient compres-
                     sion method. By default, the number of resolution  layers
                     is  chosen automatically such that the lowest layer image
                     is not larger than 640 x 480 pixels. This is  a  shortcut
                     for -d 0.

       -x number     Specify the maximal horizontal size of the lowest resolu-
                     tion layer.  The default is 640 pixels.

       -y number     Specify the maximal vertical size of the  lowest  resolu-
                     tion layer.  The default is 480 pixels.

       -l number     Select  the  lowest resolution layer that will be written
                     to the BIE. It is possible to store the  various  resolu-
                     tion  layers  of  a  JBIG1 image in progressive mode into
                     different BIEs. Options -l and -h  allow  to  select  the
                     resolution-layer interval that will appear in the created
                     BIE. The lowest resolution layer has number 0 and this is
                     also  the  default  value.  By default all layers will be
                     written.

       -h number     Select the highest resolution layer that will be  written
                     to  the  BIE.  By default all layers will be written. See
                     also option -l.

       -b            Use binary values instead of Gray code words in order  to
                     encode  pixel  values  in multiple bitplanes. This option
                     has only an effect if the input is a PGM file and if more
                     than  one bitplane is produced. Note that the decoder has
                     to make the same selection but cannot determine from  the
                     BIE,  whether  Gray or binary code words were used by the
                     encoder.

       -d number     Specify the total number of differential resolution  lay-
                     ers  into which the input image will be split in addition
                     to the lowest layer. Each additional  layer  reduces  the
                     size of layer 0 by 50 %. This option overrides options -x
                     and -y which  are  usually  a  more  comfortable  way  of
                     selecting the number of resolution layers.

       -s number     The  JBIG1  algorithm  splits each image into a number of
                     horizontal  stripes.  This  option  specifies  that  each
                     stripe  shall  have  number lines in layer 0. The default
                     value is selected so that approximately 35  stripes  will
                     be used for the whole image.

       -m number     Select the maximum horizontal offset of the adaptive tem-
                     plate pixel.  The JBIG1 encoder uses ten neighbour pixels
                     to estimate the probability of the next pixel being black
                     or white. It can move one out of these ten  pixels.  This
                     is  especially useful for dithered images, as long as the
                     distance of this adaptive pixel can be  adjusted  to  the
                     period  of  the  dither pattern. By default, the adaptive
                     template pixel is allowed to move up  to  8  pixels  away
                     horizontally.  This  encoder supports distances up to 127
                     pixels. Annex A of the standard  suggests  that  decoders
                     should  support at least a horizontal distance of 16 pix-
                     els, so using values not higher than 16 for number  might
                     increase the chances of interoperability with other JBIG1
                     implementations. On the other hand, the T.85 fax applica-
                     tion profile requires decoders to support horizontal off-
                     sets up to 127 pixels, which the maximum value  permitted
                     by  the  standard.  (The  maximal  vertical offset of the
                     adaptive template pixel is always zero for this encoder.)

       -t number     Encode only the specified number of most significant  bit
                     planes.  This  option  allows  to  reduce the depth of an
                     input PGM file if not all bits per pixel  are  needed  in
                     the output.

       -o number     JBIG1 separates an image into several horizontal stripes,
                     resolution layers and planes, were  each  plane  contains
                     one  bit  per  pixel.  One single stripe in one plane and
                     layer is encoded as a data unit called stripe data entity
                     (SDE)  inside  the  BIE.  There are 12 different possible
                     orders in which the SDEs can be stored inside the BIE and
                     number  selects which one shall be used. The order of the
                     SDEs is only  relevant  for  applications  that  want  to
                     decode  a JBIG1 file which has not yet completely arrived
                     from e.g. a slow network connection.  For  instance  some
                     applications prefer that the outermost of the three loops
                     (stripes, layers, planes) is over all layers so that  all
                     data of the lowest resolution layer is transmitted first.
                     The   following  values  for  number  select  these  loop
                     arrangements for writing the SDEs (outermost loop first):

                        0      planes, layers, stripes
                        2      layers, planes, stripes
                        3      layers, stripes, planes
                        4      stripes, planes, layers
                        5      planes, stripes, layers
                        6      stripes, layers, planes

                     All loops count starting with zero, however by  adding  8
                     to  the  above order code, the layer loop can be reversed
                     so that it counts down to zero and then higher resolution
                     layers will be stored before lower layers.  Default order
                     is 3 which writes at first all planes of the first stripe
                     and  then  completes  layer  0 before continuing with the
                     next layer and so on.

       -p number     This option allows  to  activate  or  deactivate  various
                     optional  algorithms  defined in the JBIG1 standard. Just
                     add the numbers of the following options which  you  want
                     to activate in order to get the number value:

                        4      deterministic prediction (DPON)
                        8      layer 0 typical prediction (TPBON)
                       16      diff. layer typ. pred. (TPDON)
                       64      layer 0 two-line template (LRLTWO)

                     Except  for special applications (like communication with
                     JBIG1 subset implementations) and for debugging  purposes
                     you  will  normally not want to change anything here. The
                     default  is  28,  which  provides  the  best  compression
                     result.

       -C string     Add  the  string  in a comment marker segment to the pro-
                     duced data stream. (There is no support  at  present  for
                     adding comments that contain the zero byte.)

       -c            Determine  the  adaptive  template pixel movement as sug-
                     gested in annex C of the standard. By  default  the  tem-
                     plate change takes place directly in the next line, which
                     is most effective. However, a few conformance test  exam-
                     ples in the standard require the adaptive template change
                     to be delayed until the first line of  the  next  stripe.
                     This  option selects this special behavior, which is nor-
                     mally not required except in order to pass  some  confor-
                     mance tests.

       -r            Use the SDRST marker instead of the normal SDNORM marker.
                     The probably only useful application of this option is to
                     generate  test  data for checking whether a JBIG1 decoder
                     has implemented SDRST correctly. In a normal  JBIG1  data
                     stream, each stripe data entity (SDE) is terminated by an
                     SDNORM marker, which preserves the state  of  the  arith-
                     metic  encoder (and more) for the next stripe in the same
                     layer. The alternative SDRST marker resets this state  at
                     the end of the stripe.

       -Y number     A  long  time  ago, there were fax machines that couldn't
                     even hold a single page in  memory.  They  had  to  start
                     transmitting  data  before  the  page was scanned in com-
                     pletely and the length  of  the  image  was  known.   The
                     authors  of  the standard added a rather ugly hack to the
                     otherwise beautiful JBIG1 format  to  support  this.  The
                     NEWLEN  marker  segment  can  override  the  image height
                     stated in the BIE  header  anywhere  later  in  the  data
                     stream.  Normally  pbmtojbg never generates NEWLEN marker
                     segments, as it knows the correct image  height  when  it
                     outputs  the  header.  This option is solely intended for
                     the purpose of generating test files with  NEWLEN  marker
                     segments.  It  can  be  used  to specify a higher initial
                     image height for use in the BIE header, and pbmtojbg will
                     then  add  a NEWLEN marker segment at the latest possible
                     opportunity to the data  stream  to  signal  the  correct
                     final height.

       -f            This  option makes the output file comply to the "facsim-
                     ile application profile" defined in ITU-T  Recommendation
                     T.85.  It  is  a shortcut for -q -o 0 -p 8 -s 128 -t 1 -m
                     127.

       -v            After the BIE has been created, a few  technical  details
                     of the created file will be listed (verbose mode).

BUGS
       Using  standard input and standard output for binary data works only on
       systems where there is no difference between binary  and  text  streams
       (e.g.,  Unix). On other systems (e.g., MS-DOS), using standard input or
       standard output may cause control  characters  like  CR  or  LF  to  be
       inserted or deleted and this will damage the binary data.

STANDARDS
       This  program  implements the JBIG1 image coding algorithm as specified
       in ISO/IEC 11544:1993 and ITU-T T.82(1993).

AUTHOR
       The pbmtojbg program is part of the JBIG-KIT package,  which  has  been
       developed  by  Markus  Kuhn.   The most recent version of this portable
       JBIG1    library    and     tools     set     is     available     from
       <http://www.cl.cam.ac.uk/~mgk25/jbigkit/>.

SEE ALSO
       pbm(5), pgm(5), jbgtopbm(1)



                                  2003-06-04                       PBMTOJBG(1)
