jbig.doc

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

                 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 which does 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 only might perhaps want
                 to deactivate it if the default resolution reduction
                 algorithm is replaced by a new 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
                 the first line of the next stripe. This option is by
                 default deactivated and only required for passing a
                 special compatibility test suite.

In addition, parameter l0 in jbg_enc_options() allows you to specify
the number of lines per stripe in resolution layer 0. The parameters
mx and my change the maximal offset allowed for the adaptive template
pixel. The JBIG-KIT implementation allows currently a maximal mx value
of 23 in the encoder and 32 in the decoder. Parameter my is at the
moment ignored and always set to 0. As the standard requires of all
decoder implementations only a maximum supported mx = 16 and my = 0,
higher values should normally be avoided in order to guarantee
interoperability. Default is mx = 8 and my = 0. If any of the
parameters order, options, l0, mx or my is negative, then this value
is ignored and the current value stays unmodified.

The resolution reduction and deterministic prediction tables can also
be replaced. However as these options are anyway only for experts,
please have a look at the source code of jbg_enc_out() and the struct
members dppriv and res_tab of struct jbg_enc_state for the details of
how to do this in case you really need it. The functions
jbg_int2dppriv and jbg_dppriv2int are provided in order to convert the
DPTABLE data from the format used in the standard into the more
efficient format used internally by JBIG-KIT.

If you want to encode a greyscale image, you can use the library
function

  void jbg_split_planes(unsigned long x, unsigned long y, int has_planes,
                        int encode_planes,
                        const unsigned char *src, unsigned char **dest,
                        int use_graycode);

It separates an image in which each pixel is represented by one or
more bytes into separate bitplanes. The dest array of pointers to
these bitplanes can then be handed over to jbg_enc_init(). The
variables x and y specify the width and height of the image in pixels,
and has_planes specifies how many bits per pixel are used. As each
pixel is represented by an integral number of consecutive bytes, of
which each contains up to eight bits, the total length of the input
image array src[] will therefore be x * y * ((has_planes + 7) / 8)
bytes. The pixels are stored as usually in English reading order, and
for each pixel the integer value is stored with the most significant
byte coming first (Bigendian). This is exactly the format used in raw
PGM files. In encode_planes, the number of bitplanes that shall be
extracted can be specified. This allows for instance to extract only
the most significant 8 bits of a 12-bit image, where each pixel is
represented by two bytes, by specifying has_planes = 12 and
encode_planes = 8. If use_graycode is zero, then the binary code of
the pixel integer values will be used instead of the Gray code. Plane
0 contains always the most significant bit.


3  Decompressing an image

Like with the compression functions, if you want to use the JBIG-KIT
library, you have to put the line

  #include "jbig.h"

into your source code and link your executable with libjbig.a.

The state of a JBIG decoder is stored completely in a struct and you
will have to define a variable like

  struct jbg_dec_state sd;

which is initialized by a call to

  void jbg_dec_init(struct jbg_dec_state *s);

After this, you can directly start to pass data from the BIE to the decoder
by calling the function

  int jbg_dec_in(struct jbg_dec_state *s, unsigned char *data, size_t len,
                 size_t *cnt);

The pointer data points to the first byte of a data block with length
len, which contains bytes from a BIE. It is not necessary to pass a
whole BIE at once to jbg_dec_in(), it can arrive fragmented in any way
by calling jbg_dec_in() several times. It is also possible to send
several BIEs concatenated to jbg_dec_in(), however these then have to
fit together. If you send several BIEs to the decoder, the lowest
resolution layer in each following BIE has to be the highest
resolution layer in the previous BIE plus one and the image sizes and
number of planes also have to fit together, otherwise jbg_dec_in()
will return the error JBG_ENOCONT after the header of the new BIE has
been received completely.

If pointer cnt is not NULL, then the number of bytes actually read
from the data block is stored there. In case the data block did not
contain the end of the BIE, then the value JBG_EAGAIN will be returned
and *cnt equals len.

Once the end of a BIE has been reached, the return value of
jbg_dec_in() will be JBG_EOK. After this has happened, the functions
and macros

  long jbg_dec_getwidth(struct jbg_dec_state *s);
  long jbg_dec_getheight(struct jbg_dec_state *s);
  int jbg_dec_getplanes(struct jbg_dec_state *s);
  unsigned char *jbg_dec_getimage(struct jbg_dec_state *s, int plane);
  long jbg_dec_getsize(struct jbg_dec_state *s);

can be used to query the dimensions of the now completely decoded
image and to get a pointer to all bitmap planes. The bitmaps are
stored as described in section 2.1. The function jbg_dec_getsize()
calculates the number of bytes which one bitmap requires.

The function

  void jbg_dec_merge_planes(const struct jbg_dec_state *s, int use_graycode,
                            void (*data_out)(unsigned char *start, size_t len,
                                             void *file), void *file);

allows you to merge the bitplanes that can be accessed individually
with jbg_dec_getimage() into an array with one or more bytes per pixel
(i.e., the format provided to jbg_split_planes()). If use_graycode is
zero, then a binary encoding will be used. The output array will be
delivered via the callback function data_out, exactly in the same way
in which the encoder provides the BIE. The function

  long jbg_dec_getsize_merged(const struct jbg_dec_state *s);

determines how long the data array delivered by jbg_dec_merge_planes()
is going to be.

Before calling jbg_dec_in() the first time, it is possible to specify with
a call to

  void jbg_dec_maxsize(struct jbg_dec_state *s, unsigned long xmax,
                       unsigned long ymax);

an abort criterion for progressively encoded images. For instance if an
application will display a whole document on a screen which is 1024 x
768 pixels large, then this application should call

  jbg_dec_maxsize(&sd, 1024, 768);

before the decoding process starts. If the image has been encoded in
progressive mode (i.e. with several resolution layers), then the
decoder will stop with a return value JBG_EOK_INTR after the largest
resolution layer that is still smaller than 1024 x 768. However this
is no guarantee that the image which can then be read out using
jbg_dec_getimage(), etc. is really not larger than the specified
maximal size. The application will have to check the size of the
image, because the decoder does not automatically apply a resolution
reduction if no suitable resolution layer is available in the BIE.

If jbg_dec_in() returned JBG_EOK_INTR or JBG_EOK, then it is possible
to continue calling jbg_dec_in() with the remaining data in order to
either decode the remaining resolution layers of the current BIE or in
order to add another BIE with additional resolution layers. In both
cases, after jbg_dec_in() returned JBG_EOK_INTR or JBG_EOK, *cnt is
probably not equal to len and the remainder of the data block which
has not yet been processed by the decoder has to be delivered to
jbg_dec_in() again.

If any other return value than JBG_EOK, JBG_EOK_INTR or JBG_EAGAIN
has been returned by jbg_dec_in(), then an error has occurred and

  void jbg_dec_free(struct jbg_dec_state *s);

should be called in order to release any allocated memory. The
destructor jbg_dec_free() should of course also be called, once the
decoded bitmap returned by jbg_dec_getimage() is no longer required
and the memory can be released.

The function

  const char *jbg_strerror(int errnum, int language);

returns a pointer to a short single line test message which explains
the return value of jbg_dec_in(). This message can be used in order to
provide the user a brief informative message about what when wrong
while decompressing the JBIG image. The error messages are available
in several languages and in several character sets. Currently
supported are the following values for the language parameter:

  JBG_EN              English messages in ASCII
  JBG_DE_8859_1       German messages in ISO 8859-1 Latin 1 character set
  JBG_DE_UTF_8        German messages in ISO 10646/Unicode UTF-8 encoding


The current implementation of the JBIG-KIT decoder has the following
limitations:

  - The maximal horizontal offset mx of the adaptive template pixel
    must not be larger than 32 and the maximal vertical offset must
    be zero.

  - HITOLO and SEQ bits must not be set in the order value.

A more detailed description of the JBIG-KIT implementation is

  Markus Kuhn: Effiziente Kompression von bi-level Bilddaten durch
  kontextsensitive arithmetische Codierung. Studienarbeit, Lehrstuhl
  f黵 Betriebssysteme, IMMD IV, Universit鋞 Erlangen-N黵nberg,
  Erlangen, July 1995. (German, 62 pages)
  <http://www.cl.cam.ac.uk/~mgk25/kuhn-sta.pdf>

Please quote the above if you use JBIG-KIT in your research project.

*** Happy compressing ***

[end]