jbig.doc

linux下将各类格式图片转换工具

                to initialize.

  x             The width of your image.

  y             The height of your image.

  pl            the number of bitmap planes you want to encode.

  p             A pointer to an array of pl pointers, where each is again
                pointing to the first byte of a bitmap as described in
                section 2.1.

  data_out      This is a call-back function which will be called during
                the compression process by libjbig in order to deliver
                the BIE data to the application. The parameters of the
                function data_out are a pointer start to the new block of
                data to be delivered as well as the number len of delivered
                bytes. The pointer file is transparently delivered to
                data_out as specified in jbg_enc_init(). Usually, 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 which is transparently passed to
                data_out() and allows 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(). After this, a call
to the destructor function

  void jbg_enc_free(struct jbg_enc_state *s);

will release any memory allocated by the previous functions.


A minimal example application which sends the BIE of the above example
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 tables 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 300
dpi document has to be stored and the lowest resolution layer shall
have 75 dpi so that a screen previewer can directly decompress only
the required resolution, then a call

  jbg_enc_layers(&se, 2);

will cause three resolution layers with 75, 150 and 300 dots per inch.

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. If e.g. only 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, one calls

  jbg_enc_lrange(&se, 0, 0);

and before writing the second BIE with jbg_enc_out(), one calls

  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 which will represent
the input image. This way, jbg_enc_lrange(&se, -1, -1) can be used to
query the layer of the full image.

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 does currently 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 3 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 might be somewhat confusing, but the following
table (see also Table 11 in ITU-T T.82) makes clear 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