
Installing and Using the JBIG-KIT Package
-----------------------------------------

Markus Kuhn -- 1995-05-28


This text will help you to compile the software and to get started by
giving you a guided tour in playing around with the demo examples.

The portable JBIG library is located in subdirectory libjbig/. On a
Unix system, just edit the Makefile there so that an ANSI C compiler
with a good optimization level is used and start "make". On other
operating systems, just link jbig.c and jbig_tables.c together with
any application in which you want to use the JBIG-KIT library. If you
get any compiler warnings or error messages, please check whether your
compiler, C library and include files really conform to the ANSI C
standard (there are still a few ancient K&R compilers around and on
some Unix systems with ANSI C compilers, broken include files might
cause a few warnings which you can ignore savely). In case you don't
already have an ANSI compatible C compiler, you should seriously
consider to install GNU gcc which is available with anonymous ftp from
prep.ai.mit.edu.

If libjbig.a has been produced correctly, then activate the automatic
library test suite with "make test" or just start test_codec. If this
test fails, please let me know.

Then you should go to directory ../pbmtools, edit Makefile there and
start "make" in order to build the programs pbmtojbig and jbigtopbm.
After testing them on some of the example JBIG files, you can move
these executable files together with the manpages (if you are in a
UNIX style environment) to the appropriate directories on your system.
Options -h and --help will give you short command line usage summaries
of both programs.

The subdirectory examples/ contains a few files as raw JBIG data
streams (these are called bi-level image entities (BIE) in the
standard, hence the suggested filename suffix ".bie").

A few examples which you might want to try:

  jbigtopbm ccitt1.bie ccitt1.pbm

decompresses the CCITT test letter number one into a portable bitmap
file which you can further convert using Jef Poskanzer's PBM tools
(available on anonymous ftp server wuarchive.wustl.edu) or view with
many popular image processing systems like xv (available for Unix/X11
systems on anonymous ftp server ftp.cis.upenn.edu).

The ccitt1.bie image is 1728 x 2376 pixels large and can not be easily
displayed on your screen. However fortunately, I have stored it in
progressive mode with the following resolution layers:

  layer 0:  216 x  297 pixel
  layer 1:  432 x  594 pixel
  layer 2:  864 x 1188 pixel
  layer 3: 1728 x 2376 pixel

In progressive mode, each layer has twice the resolution of the
previous one. Resolution layer 0 encodes all is pixels independent
from any other data, all other resolution layers encode only the
difference between the previous and the new resolution layer which
requires much less space than encoding resolution layers without
refering to the lower layer. By default, the BIE files produced by
pbmtojbig start all with a lowest resolution layer 0 which will fit on
a 640 x 480 screen.

In order to tell jbigtopbm that you do not want to decode higher
resolution layers if they will not fit on your e.g. 1024 x 768 pixel
display, then simply use

  jbigtopbm -x 1024 -y 768 ccitt1.bie ccitt1.pbm

and you will get much faster a 4 times smaller image, the highest
resolution layer that still fits on your screen. You can also directly
pipe the image to another application using standard output by
removing the second file name, e.g.

  jbigtopbm -x 1024 -y 768 ccitt1.bie | xv -

Now let's do some compression. With

  jbigtopbm ccitt1.bie ccitt1.pbm

followed by

  pbmtojbig ccitt1.pbm test.bie

you produce again the same data stream as ccitt1.bie. However if you
want that the lowest resolution layer is not larger than 70 x 100
pixel (thumb nail image), then use

  pbmtojbig -v -x 100 -y 150 ccitt1.pbm test.bie

Option -v will tell you that this has caused 5 additional resolution
layers to the lowest 54 x 75 pixel large layer 0. If you have a look at
the lowest resolution layer in test.bie with

  jbigtopbm -x 100 test.bie | xv -

you will still be able to clearly recognize the layout and line
structure of the page, which is not the case if less sophisticated
resolution reduction techniques would have been utilized (e.g. as in
xv). With

  pbmtojbig -q ccitt1.pbm test.bie

you can enforce a single resolution layer which is usually a little
bit more efficient and requires a little bit less space than
progressive encoding.


Ok, another small exercise: Assume you want to build a document
database in which you want to store scanned images in two resolution
layers, one for screen previewing and one for laser printer output.
However you do not want that your decision to store images in two
resolutions causes too much additional storage requirement. You decide
that 3 resolution layers in JBIG fit your requirement and you want to
store

  layer 0:  432 x  594 pixels

in the first file test-low.bie and the two layers

  layer 1:  864 x 1188 pixels
  layer 2: 1728 x 2376 pixels

in the second file test-high.bie. No problem, just call

  pbmtojbig -d 2 -l 0 -h 0 ccitt1.pbm test-low.bie
  pbmtojbig -d 2 -l 1 -h 2 ccitt1.pbm test-high.bie

were -d specifies the total number of layers and -l/-h select the
range of layers written to the output file. You will see that the low
and high resolution file together are only 1.6 kb larger than if you
would have stored only the highres version directly without
progressive mode (option -q). Progressive mode has here reduced the
additional storage requirement by 50 % compared to storing the 3.2 kb
long low resolution version completely separately from the high
resolution image.

In order to view only the screen version, use

  jbigtopbm test-low.bie | xv -

and in order to send the full version to the printer, just concatenate
both BIE files like in

  cat test-low.bie test-high.bie | jbigtopbm | ....


All this functionality and a few tricky things more are available as
functions in the libjbig C library which you can link into your
application. Just copy the relevant files from libjbig/ into your own
source code directory and adapt your Makefile. In libjbig/jbig.doc,
you will find documentation about how to use the library.

Markus
