FFDec
CCITT group IV-2d decompressor

Prototype

Put the following prototype in the prototypes section of the application program header file: 

int  ( __stdcall *pfnFFDec )( HANDLE, int, void*, int, int, int );

Purpose

Decompress a black & white image coded CCITT group 4-2d from a file, and put the decompressed data into a memory area.

Description and use

This function was originally written in 16 bit DOS assembly. Then it has been ported to 32 bit win32asm. The purpose of this routine is to decompress a single black & white image out of a file (usually a bilevel 200 dpi TIFF file, the kind of file commonly used in optical document storage and retrieval systems).

The decompressed data will be put into a normal memory area (a "frame buffer") that you can easily create with a standard Win32 API call to GlobalAlloc (...originally the frame buffer was implemented in the DOS extended memory).

The size in bytes of the frame buffer that the application program should allocate using GlobalAlloc is the product of the image width in pixels by the image length in lines. In fact this decompression routine writes a byte in the frame buffer for each decompressed pixel (0x00 or 0xFF, depending whether the pixel was black or white).

This might appear a waste of memory, but I had to do that because the general purpose display routine FFView that I wrote to render the uncompressed image actually handles 256 colour-palette images and it expects one-byte-per-pixel even if the image is black & white.

Anycase a letter-size image ad 200 dpi does not require more than 0.5 MB of memory, and today it is actually a very small amount of memory.

The experience demonstrates that allocating 0.1% more than the strictly requested amount of memory will avoid many errors that might derive from the decompression of the final bytes of the coded data. Don't forget to allocate this extra bytes before calling FFDec.

Specification

The decompression algorythm is fully compliant with the CCITT blue book, volume VII, fascicle VII.3, recommendation T.6 for group 4 facsimile apparatus. The implementation is robust and does not suffer from errors in the coded data; if an unknown code is detected the routine simply exits. Millions of images have been decompressed by this routine.

The maximum image width is 2352 pixels (297 mm at 200 dpi). To increment the image width I should recompile the DLL with a more large buffer. There is no limit in the image length.

Parameters
  • HANDLE file handle: handle to the file that contains the compressed data; leave the file pointer positioned to the beginning of the compressed data
  • int FillOrder: normally set to 1 (set to 2 for fax data, see note below)
  • void* pointer to the memory area: the memory area should be as large as needed to accomodate the uncompressed data as described above
  • int image width in pixels divided by 8 (max 294)
  • int overscan (see below)
  • int image length in lines (there is no limit)
Note on the overscan: if the image width in pixels is a multiple of 8 the overscan parameter should be 0; if the image width in pixels is *not* a multiple of 8 the image width parameter should be the first available multiple of 8 divided by 8, and the overscan should be the difference between the first available multiple of 8 and the actual image width in pixels. Example: image width is 2350 pixels, then the image width divided by 8 should be 294 and the overscan should be 2.
Note on the FillOrder: for a complete description of FillOrder see the TIFF rev.6 image specification. If FillOrder=1 then the bits in the bytes from the coded stream are decoded in the order from MSB to LSB. If FillOrder=2 every single byte is reversed, and is decoded from LSB to MSB. This second case is necessary to support any image coming from a fax server software.

Return value

If the requested number of lines (6th parameter) has been decompressed the return value is true; if an error in the data has been detected the return value is false.

Application examples

See also
  • FFTiffServices: single image TIFF file management
  • FFView: 256 colours *full screen* bitmap display with pan, zoom, rotation, etc.
  • FFOMR: OMR (Optical Mark Recognition)

Notes

This routine is extremely fast. In an old PC with a 300 MHz clock it would take less than one tenth of a second to decompress a letter size image.