|
Packit |
fbaace |
|
|
Packit |
fbaace |
Getting started with JBIG-KIT
|
|
Packit |
fbaace |
-----------------------------
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
Markus Kuhn -- 2014-03-27
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
JBIG-KIT is a portable C library that should work on any platform with
|
|
Packit |
fbaace |
an ANSI/ISO C compiler, such as GNU gcc.
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
To get started, compile the demonstration software in pbmtools/ and
|
|
Packit |
fbaace |
test it with some of the provided example files.
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
On a Unix system, check Makefile to suit your compiler, then start
|
|
Packit |
fbaace |
"make". If libjbig.a and/or libjbig85.a have been produced correctly,
|
|
Packit |
fbaace |
then activate the automatic library test suite with "make test", or
|
|
Packit |
fbaace |
just start libjbig/tstcodec and libjbig/tstcodec85. If these tests
|
|
Packit |
fbaace |
fail, please do let me know.
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
On other operating systems, just link libjbig/jbig.c and
|
|
Packit |
fbaace |
libjbig/jbig_ar.c together with any application in which you want to
|
|
Packit |
fbaace |
use the full JBIG-KIT library. Likewise, just link libjbig/jbig85.c
|
|
Packit |
fbaace |
and libjbig/jbig_ar.c together with any application in which you want
|
|
Packit |
fbaace |
to use the simpler variant optimized for fax applications.
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
In subdirectory pbmtools/, you will find the programs pbmtojbg and
|
|
Packit |
fbaace |
jbgtopbm. These are two file converters, serving as examples for
|
|
Packit |
fbaace |
applications that use the full JBIG-KIT library (jbig.c). After
|
|
Packit |
fbaace |
testing them on some of the example JBIG files, you can move these
|
|
Packit |
fbaace |
executable files together with their respective man pages (in a UNIX
|
|
Packit |
fbaace |
style environment) to the appropriate directories. Options -h and
|
|
Packit |
fbaace |
--help will give you short command-line usage summaries. The programs
|
|
Packit |
fbaace |
pbmtojbg85 and jbgtopbm85 are very similar, but demonstrate use of the
|
|
Packit |
fbaace |
simpler jbig85.c library instead.
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
The subdirectory examples/ contains a few files as raw JBIG data
|
|
Packit |
fbaace |
streams (called bi-level image entities (BIE) in the standard).
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
Try
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
jbgtopbm ccitt1.jbg ccitt1.pbm
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
to decompress CCITT test letter #1 into a portable bitmap file, which
|
|
Packit |
fbaace |
you can then further convert using Jef Poskanzer's PBM tools
|
|
Packit |
fbaace |
<http://www.acme.com/software/pbmplus/>, or view with many popular
|
|
Packit |
fbaace |
image file viewers, such as the "display" command from ImageMagick.
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
The ccitt1.jbg image is 1728 x 2376 pixels large and may not fit onto
|
|
Packit |
fbaace |
your display screen. However, fortunately, I have stored it in JBIG's
|
|
Packit |
fbaace |
"progressive mode" with the following resolution layers:
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
layer 0: 216 x 297 pixel
|
|
Packit |
fbaace |
layer 1: 432 x 594 pixel
|
|
Packit |
fbaace |
layer 2: 864 x 1188 pixel
|
|
Packit |
fbaace |
layer 3: 1728 x 2376 pixel
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
In progressive mode, each layer has twice the resolution of the
|
|
Packit |
fbaace |
previous one. Resolution layer 0 encodes all its pixels independent
|
|
Packit |
fbaace |
from any other data; all other resolution layers encode only the
|
|
Packit |
fbaace |
difference between the previous and the new resolution layer, which
|
|
Packit |
fbaace |
requires much less space than encoding resolution layers without
|
|
Packit |
fbaace |
referring to the lower layer. By default, the BIE files produced by
|
|
Packit |
fbaace |
pbmtojbg will all start with a lowest resolution layer 0 that fits
|
|
Packit |
fbaace |
onto a 640 x 480 screen.
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
In order to tell jbgtopbm that you do not want to decode higher
|
|
Packit |
fbaace |
resolution layers if they will not fit onto your (say) 1024 x 768
|
|
Packit |
fbaace |
pixel display, simply use
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
jbgtopbm -x 1024 -y 768 ccitt1.jbg ccitt1.pbm
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
You will get a 4 times smaller image, the highest resolution layer
|
|
Packit |
fbaace |
that still fits onto your screen. You can also directly pipe the image
|
|
Packit |
fbaace |
to another application using standard output, by removing the second
|
|
Packit |
fbaace |
file name, e.g.
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
jbgtopbm -x 1024 -y 768 ccitt1.jbg | display
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
In fact, the data in the first quarter of the input file is sufficient
|
|
Packit |
fbaace |
to decode the requested resolution:
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
head --bytes=4000 ccitt1.jbg | ../pbmtools/jbgtopbm -x 1024 -y 768 | display
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
Now let's do some compression. With
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
jbgtopbm ccitt1.jbg ccitt1.pbm
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
followed by
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
pbmtojbg ccitt1.pbm test.jbg
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
you produce again the same data stream as ccitt1.jbg. However if you
|
|
Packit |
fbaace |
want that the lowest resolution layer is not larger than 70 x 100
|
|
Packit |
fbaace |
pixels ("thumb nail" image), then use
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
pbmtojbg -v -x 100 -y 150 ccitt1.pbm test.jbg
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
Option -v will output some technical data, and will tell you that five
|
|
Packit |
fbaace |
incremental resolution layers have been created, in addition to the
|
|
Packit |
fbaace |
lowest 54 x 75 pixel large layer 0. Look at the lowest resolution
|
|
Packit |
fbaace |
layer in test.jbg with
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
jbgtopbm -x 100 test.jbg | display
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
and you will still be able to clearly recognize the layout and line
|
|
Packit |
fbaace |
structure of the page, which the implemented bi-level
|
|
Packit |
fbaace |
resolution-reduction algorithm tried to preserve. With
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
pbmtojbg -q ccitt1.pbm test.jbg
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
you can enforce a single resolution layer, which usually requires a
|
|
Packit |
fbaace |
slightly less space than progressive encoding.
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
OK, another small exercise. Assume you want to build a document
|
|
Packit |
fbaace |
database in which you want to store scanned images in two resolution
|
|
Packit |
fbaace |
layers, one for screen previewing and one for laser-printer output.
|
|
Packit |
fbaace |
However, you do not want your decision to store images in two
|
|
Packit |
fbaace |
resolutions to cause too much additional storage requirement. You
|
|
Packit |
fbaace |
decide that 3 resolution layers in JBIG fit your requirement and you
|
|
Packit |
fbaace |
want to store
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
layer 0: 432 x 594 pixels
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
in the first file test-low.jbg and the two layers
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
layer 1: 864 x 1188 pixels
|
|
Packit |
fbaace |
layer 2: 1728 x 2376 pixels
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
in the second file test-high.jbg. No problem, just call
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
pbmtojbg -d 2 -l 0 -h 0 ccitt1.pbm test-low.jbg
|
|
Packit |
fbaace |
pbmtojbg -d 2 -l 1 -h 2 ccitt1.pbm test-high.jbg
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
where option -d specifies the total number of layers and -l/-h select
|
|
Packit |
fbaace |
the range of layers written to the output file. You will see that the
|
|
Packit |
fbaace |
low and high resolution file together are only 1.6 kB larger than if
|
|
Packit |
fbaace |
you had stored only the high-res version directly without progressive
|
|
Packit |
fbaace |
mode (option -q). Progressive mode has reduced the additional storage
|
|
Packit |
fbaace |
requirement by 50% compared to storing the 3.2 kB low-resolution
|
|
Packit |
fbaace |
version independently of the high resolution image.
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
In order to view only the screen version, use
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
jbgtopbm test-low.jbg | display
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
and in order to send the full version to the printer, just concatenate
|
|
Packit |
fbaace |
both BIE files like in
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
cat test-low.jbg test-high.jbg | jbgtopbm -m | ....
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
All this functionality, and more, are available as functions in the
|
|
Packit |
fbaace |
libjbig C library, which you can link into your application. Just copy
|
|
Packit |
fbaace |
the relevant files from libjbig/ into your own source-code directory
|
|
Packit |
fbaace |
and adapt your Makefile. In libjbig/jbig.txt, you will find
|
|
Packit |
fbaace |
documentation about how to use the full library, while
|
|
Packit |
fbaace |
libjbig/jbig85.txt documents the fax variant of the library. The
|
|
Packit |
fbaace |
latter lacks progressive encoding, but can instead deal better with
|
|
Packit |
fbaace |
images where the height is not yet known at the start of a
|
|
Packit |
fbaace |
transmission.
|
|
Packit |
fbaace |
|
|
Packit |
fbaace |
Markus
|