PBMTOJBG(1)

NAME
pbmtojbg - portable bitmap to JBIG1 file converter

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

DESCRIPTION
Reads a file in portable bitmap (PBM) format, compresses it, and outputs the image as a JBIG1 bi-level image entity (BIE). 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 resolution layers (progressive mode). This allows the decoder to recover a lower-resolution version of the encoded image without having to read the complete file. These resolution layers can be stored all in one single BIE or they can be stored in several separate BIE files. All resolution layers, except the lowest one, are stored merely as differences to the next lower resolution layer. 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. For best speed and compression, if you are not interested in efficiently extracting lower-resolution versions from the compressed file, use sequential mode (single resolution layer, option -q). JBIG1 files can also store several bits per pixel, as separate bitmap planes, and pbmtojbg can read a portable graymap format (PGM) file and transform it into a multi-plane BIE.

OPTIONS

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

-v  List technical details of the created file (verbose mode).

-f  This option makes the output file comply with the “facsimile 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.

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

Options affecting the number of resolution layers produced:

-q  Encode the image in one single resolution layer (sequential mode), which is usually the most efficient compression method. By default, the number of resolution layers is instead chosen automatically such that the lowest layer image is not larger than 640 × 480 pixels. This option is just a shortcut for -d 0.

-x number
    Specify the maximal horizontal size of the lowest resolution layer. Default: 640 pixels

-y number
    Specify the maximal vertical size of the lowest resolution layer. Default: 480 pixels

-d number
    Specify the total number of differential resolution layers into which to split the input image (in addition to the lowest layer). Each additional layer reduces both the width and height of layer 0 by 50%. This option overrides options -x and -y, which are usually a more convenient way of selecting the number of resolution layers.

-l number
    Select the lowest resolution layer DL that will appear in the generated BIE. JBIG1 can store the various resolution layers of an image in progressive mode split across several BIEs. Options -l and -h allow you 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. The default is to write all layers.

-h number
    Select the highest resolution layer D that will appear in the generated BIE. The default is to write all layers. See also option -l.

Options for changing other parameters indicated in the BIE header:

-s number
    The JBIG1 algorithm splits each image into horizontal stripes. This option specifies L0, the layer-0 height of each such stripe (except for the last one, which can be shorter). The default is to split the whole image into approximately 35 stripes.

-m number
    Select the maximum horizontal offset MX of the adaptive template pixel. The JBIG1 encoder uses ten neighbour pixels to estimate the probability of the next pixel being black or white. It can adjust the location of one of these ten context 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 pixels, 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 application profile requires decoders to support horizontal offsets up to 127 pixels, which is the maximum value permitted by the standard. (The maximal vertical offset MY of the adaptive template pixel is always zero for this encoder.)

-o number
    Specify the order in which image data appears in the output. 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. For receiving applications, the order of the SDEs mainly matters if they want to start decoding an image before it has been received completely. For instance, some applications may 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. The 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 activates or deactivates 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)
    This option is only for specialist applications (e.g., communication with JBIG1 subset implementations, debugging). The default is 28, which usually provides the best compression result.

Options affecting the processing of PGM files:

-b  Use binary values instead of Gray code words in order to encode pixel values in multiple bit planes. This option has only an effect if the input is a PGM file and if more than one plane is produced. Note that the decoder has to make the same choice, but the BIE does not indicate whether Gray or binary code words were used by the encoder.

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

Options to help generating test files:

-r  Use the SDRST marker instead of the normal SDNORM marker. The probably only useful application for 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 arithmetic 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
    Specify a preliminary image height YD. 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 completely and before even the height of the resulting image was known. The authors of the standard added a rather ugly hack to JBIG1 to support this use case. 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. It will also set the VLENGTH flag in the BIE header.

-c  Determine the adaptive template pixel movement as suggested in Annex C of the standard. By default the template change takes place directly in the next line, which is most effective. However, a few conformance test examples 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 normally not useful other than for conformance testing.

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 international standard ISO/IEC 11544:1993 and ITU-T Recommendation T.82(1993).

AUTHOR
Markus Kuhn wrote JBIG-KIT (http://www.cl.cam.ac.uk/~mgk25/jbigkit/), which includes pbmtojbg.

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