jbig.txt

Using the JBIG-KIT library

                delivered bytes. The pointer file is transparently
                delivered to data_out, as specified in jbg_enc_init().
                Typically, data_out will write the BIE portion to a
                file, send it to a network connection, or append it to
                some memory buffer.

  file          A pointer parameter that is passed on to data_out()
                and can be used, for instance, to allow data_out() to
                distinguish by which compression task it has been
                called in multi-threaded applications.

In the simplest case, the compression is then started by calling the
function

  void jbg_enc_out(struct jbg_enc_state *s);

which will deliver the complete BIE to data_out() in several calls.
After jbg_enc_out has returned, a call to the destructor function

  void jbg_enc_free(struct jbg_enc_state *s);

will release any heap memory allocated by the previous functions.


A minimal example application which sends the BIE of the above
bitmap to stdout looks like this:

---------------------------------------------------------------------------
/* A sample JBIG encoding application */

#include <stdio.h>
#include "jbig.h"

void output_bie(unsigned char *start, size_t len, void *file)
{
  fwrite(start, 1, len, (FILE *) file);
  
  return;
}

int main()
{
  unsigned char bitmap[15] = {
    /* 23 x 5 pixels, "JBIG" */
    0x7c, 0xe2, 0x38, 0x04, 0x92, 0x40, 0x04, 0xe2,
    0x5c, 0x44, 0x92, 0x44, 0x38, 0xe2, 0x38
  };
  unsigned char *bitmaps[1] = { bitmap };
  struct jbg_enc_state se;
  
  jbg_enc_init(&se, 23, 5, 1, bitmaps, 
	       output_bie, stdout);              /* initialize encoder */
  jbg_enc_out(&se);                                    /* encode image */
  jbg_enc_free(&se);                    /* release allocated resources */
  
  return 0;
}
---------------------------------------------------------------------------

This software produces a 42 byte long BIE. (JBIG is not very good at
compressing extremely small images like in this example, because the
arithmetic encoder requires some startup data in order to generate
reasonable statistics which influence the compression process and
because there is some header overhead.)


2.3  More about compression

If jbg_enc_out() is called directly after jbg_enc_init(), the
following default values are used for various compression parameters:

  - Only one single resolution layer is used, i.e. no progressive
    mode.

  - The number of lines per stripe is selected so that approximately
    35 stripes per image are used (as recommended in annex C of the
    standard together with the suggested adaptive template change
    algorithm). However, not less than 2 and not more than 128 lines
    are used in order to stay within the suggested minimum parameter
    support range specified in annex A of the standard).

  - All optional parts of the JBIG algorithm are activated (TPBON,
    TPDON and DPON).

  - The default resolution reduction table and the default deterministic
    prediction table are used

  - The maximal vertical offset of the adaptive template pixel is 0
    and the maximal horizontal offset is 8 (mx = 8, my = 0).

In order to change any of these default parameters, additional
functions have to be called between jbg_enc_init() and jbg_enc_out().

In order to activate progressive encoding, it is possible to specify
with 

  void jbg_enc_layers(struct jbg_enc_state *s, int d);

the number d of differential resolution layers which shall be encoded
in addition to the lowest resolution layer 0. For example, if a
document with 60-micrometer pixels has to be stored, and the lowest
resolution layer shall have 240-micrometer pixels, so that a screen
previewer can directly decompress only the required resolution, then a
call

  jbg_enc_layers(&se, 2);

will cause three layers with 240, 120 and 60 micrometers resolution to
be generated.

If the application does not know what typical resolutions are used and
simply wants to ensure that the lowest resolution layer will fit into
a given maximal window size, then as an alternative, a call to

  int jbg_enc_lrlmax(struct jbg_enc_state *s, unsigned long mwidth,
                     unsigned long mheight);

will cause the library to automatically determine the suitable number
of resolutions so that the lowest resolution layer 0 will not be
larger than mwidth x mheight pixels. E.g. if one wants to ensure that
systems with a 640 x 480 pixel large screen can decode the required
resolution directly, then call

  jbg_enc_lrlmax(&se, 640, 480);

The return value is the number of differential layers selected.

After the number of resolution layers has been specified by calls to
jbg_enc_layers() or jbg_enc_lrlmax(), by default, all these layers
will be written into the BIE. This can be changed with a call to

  int  jbg_enc_lrange(struct jbg_enc_state *s, int dl, int dh);

Parameter dl specifies the lowest resolution layer and dh the highest
resolution layer that will appear in the BIE. For instance, if layer 0
shall be written to the first BIE and layer 1 and 2 shall be written
to a second one, then before writing the first BIE, call

  jbg_enc_lrange(&se, 0, 0);

and before writing the second BIE with jbg_enc_out(), call

  jbg_enc_lrange(&se, 1, 2);

If any of the parameters is negative, it will be ignored. The return
value is the total number of differential layers that will represent
the input image. This way, jbg_enc_lrange(&se, -1, -1) can be used to
query the layer of the full image resolution.

A number of other more exotic options of the JBIG algorithm can be
modified by calling

  void jbg_enc_options(struct jbg_enc_state *s, int order, int options,
                       long l0, int mx, int my);

before calling jbg_enc_out().

The order parameter can be a combination of the bits JBG_HITOLO,
JBG_SEQ, JBG_ILEAVE and JBG_SMID and it determines in which order
the SDEs are stored in the BIE. The bits have the following meaning:

  JBG_HITOLO   Usually, the lower resolution layers are stored before
               the higher resolution layers, so that a decoder can
               already start to display a low resolution version of
               the full image once a prefix of the BIE has been
               received. When this bit is set, however, the BIE will
               contain the higher layers before the lower layers. This
               avoids additional buffer memory in the encoder and is
               intended for applications where the encoder is connected
               to a database which can easily reorder the SDEs before
               sending them to a decoder. Warning: JBIG decoders are
               not expected to support the HITOLO option (e.g. the
               JBIG-KIT decoder currently does not) so you should
               normally not use it.

  JBG_SEQ      Usually, at first all stripes of one resolution layer
               are written to the BIE and then all stripes of the next
               layer, and so on. When the SEQ bit is set however, then
               all layers of the first stripe will be written,
               followed by all layers of the second stripe, etc. This
               option also should normally never be required and is
               not supported by the current JBIG-KIT decoder.

  JBG_SMID     In case there exist several bit planes, then the order of
               the stripes is determined by three loops over all stripes,
               all planes and all layers. When SMID is set, the loop
               over all stripes is the middle loop.

  JBG_ILEAVE   If this bit is set, then at first all layers of one
               plane are written before the encoder starts with the next
               plane.

The above description may be somewhat confusing, but the following
table (see also Table 11 in ITU-T T.82) clarifies how the three bits
JBG_SEQ, JBIG_ILEAVE and JBG_SMID influence the ordering of the loops
over all stripes, planes and layers:


                                                 Loops:
    JBG_SEQ   JBG_ILEAVE   JBG_SMID   |  Outer   Middle    Inner
  ------------------------------------+---------------------------
       0           0           0      |    p        d        s
       0           1           0      |    d        p        s
       0           1           1      |    d        s        p
       1           0           0      |    s        p        d
       1           0           1      |    p        s        d
       1           1           0      |    s        d        p

                                       p: plane, s: stripe, d: layer


By default, the order combination JBG_ILEAVE | JBG_SMID is used.

The options value can contain the following bits, which activate
some of the optional algorithms defined by JBIG:

  JBG_LRLTWO     Normally, in the lowest resolution layer, pixels
                 from three lines around the next pixel are used
                 in order to determine the context in which the next
                 pixel is encoded. Some people in the JBIG committee
                 seem to have argued that using only 2 lines will
                 make software implementations a little bit faster,
                 however others have argued that using only two lines
                 will decrease compression efficiency by around 5%.
                 As you might expect from a committee, now both
                 alternatives are allowed and if JBG_LRLTWO is set,
                 the slightly faster but 5% less well compressing two
                 line alternative is selected. God bless the committees.
                 Although probably nobody will ever need this option,
                 it has been implemented in JBIG-KIT and is off by
                 default.

  JBG_TPDON      This activates the "typical prediction" algorithm
                 for differential layers which avoids that large
                 areas of equal color have to be encoded at all.
                 This is on by default and there is no good reason to
                 switch it off except for debugging or preparing data
                 for cheap JBIG hardware that might not support this
                 option.

  JBG_TPBON      Like JBG_TPDON this activates the "typical prediction"
                 algorithm in the lowest resolution layer. Also activated
                 by default.

  JBG_DPON       This bit activates for the differential resolution
                 layers the "deterministic prediction" algorithm,
                 which avoids that higher resolution layer pixels are
                 encoded when their value can already be determined
                 with the knowledge of the neighbor pixels, the
                 corresponding lower resolution pixels and the
                 resolution reduction algorithm. This is also
                 activated by default and one reason for deactivating
                 it would be if the default resolution reduction
                 algorithm were replaced by another one.

  JBG_DELAY_AT   Use a slightly less efficient algorithm to determine
                 when an adaptive template change is necessary. With
                 this bit set, the encoder output is compatible to the
                 conformance test examples in cause 7.2 of ITU-T T.82.
                 Then all adaptive template changes are delayed until