jbig.txt

Using the JBIG-KIT library

                 the first line of the next stripe. This option is by
                 default deactivated and is 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. JBIG-KIT now supports the full range of possible mx values up
to 127 in the encoder and decoder, but my is at the moment ignored and
always set to 0. As the standard requires of all decoder
implementations only to support maximum values mx = 16 and my = 0,
higher values should normally be avoided in order to guarantee
interoperability. The ITU-T T.85 profile for JBIG in fax machines
requires support for mx = 127 and my = 0. Default is mx = 8 and my =
0. If any of the parameters order, options, mx or my is negative, or
l0 is zero, then the corresponding current value remains 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 bit planes. The dest array of pointers to
these bit planes 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 bit planes 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 bit planes 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 vertical offset MY of the adaptive template pixel
    must be zero.

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

  - Not more than JBG_ATMOVES_MAX (currently set to 64) ATMOVE
    marker segments can be handled per stripe.

  - the number D of differential layers must be less than 32

None of the above limitations can be exceeded by a JBIG data stream
that conforms to the ITU-T T.85 application profile for the use of
JBIG1 in fax machines.

There are two more limitations of the current implementation of the
JBIG-KIT decoder that might cause problems with processing JBIG data
stream that conform to ITU-T T.85:

  - The JBIG-KIT decoder was designed to operate incrementally.
    Each received byte is processed immediately as soon as it arrives.
    As a result, it does not look beyond the SDRST/SDNORM at the end
    of all stripes for any immediately following NEWLEN marker that
    might reduce the number of lines encoded by the current stripe.
    However section 6.2.6.2 of ITU-T T.82 says that a NEWLEN marker
    segment "could refer to a line in the immediately preceding stripe
    due to an unexpected termination of the image or the use of only
    such stripe", and ITU-T.85 explicitly suggests the use of this
    for fax machines that start transmission before having encountered
    the end of the page.

  - The image size initially indicated in the BIE header is used to
    allocate memory for a bitmap of this size. This means that BIEs
    that set initially Y_D = 0xffffffff (as suggested in ITU-T T.85
    for fax machines that do not know the height of the page at the
    start of the transmission) cannot be decoded directly by this
    version.

For both issues, there is a very simple workaround:

If you encounter a BIE that has in the header the VLENGTH=1 option bit
set, then first wait until you have received the entire BIE and stored
it in memory. Then call the function

  int jbg_newlen(unsigned char *bie, size_t len);

where bie is a pointer to the first byte of the BIE and len its length
in bytes. This function will scan the entire BIE for the first NEWLEN
marker segment. It will then take the updated image-height value YD
from it and use it to overwrite the YD value in the BIE header. The
jbg_newlen() can return some of the same error codes as jbg_dec_in(),
namely JBG_EOK if everything went fine, JBG_EAGAIN is the data
provided is too short to be a valid BIE, JBG_EINVAL if a format error
was encountered, and JBG_EABORT if an ABORT marker segment was found.
After having patched the image-height value in the BIE using
jbg_newlen(), simply hand over the BIE as usual to jbg_dec_in().


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ür Betriebssysteme, IMMD IV, Universit?t Erlangen-Nürnberg,
  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]