Installing and Using the JBIG-KIT Package ----------------------------------------- Markus Kuhn -- 1998-04-10 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. On a Unix system, just edit the Makefile so that an ANSI C compiler with a good optimization level is used and start "make". On other operating systems, just link libjbig/jbig.c and libjbig/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 old Unix systems with ANSI C compilers, broken include files might cause a few warnings which you can ignore safely). In case you don't already have an ANSI compatible C compiler, you should seriously consider to install GNU gcc which is available from . If libjbig.a has been produced correctly, then activate the automatic library test suite with "make test" or just start libjbig/test_codec. If this test fails, please let me know. In subdirectory pbmtools/, you will find the programs pbmtojbig and jbigtopbm. These are two file converters as examples for applications which use the JBIG-KIT library. After testing them on some of the example JBIG files, you can move these executable files together with the man-pages (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 referring 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 where -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 high-res 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