CPC Rapid Deployment API
VERSION 5.2

The Cartesian Perceptual Compression (CPC) method and its implementation are designed to be inter-operable across a wide spectrum of application environments, ranging from standalone office equipment to Internet Browser add-on modules. For most applications, however, the core API provides more freedom than is necessary, thereby requiring greater complexity in the application. To facilitate rapid application development, an alternative API, known as the Rapid Deployment API, is provided. Although the Rapid Deployment API does not have the flexibility of the core API, it is sufficient for the overwhelming majority of applications, providing a fast path to incorporating CPC compression into existing applications. This document describes the Rapid Deployment Application Programming Interface to the CPC programming library.

The portion of the API described in this document requires the use of files for the underlying storage of the raw CPC data. The document, Rapid Deployment Data Streams, describes an extension of the API, which allows an application to utilize arbitray storage mechanisms for the raw CPC data.

1. Architecture

The Rapid Deployment API provides two objects for interacting with documents:

• The CpcEncoder, which takes as input a sequence of image pages, and writes the compressed CPC document representation to a file.
• The CpcDecoder, which reads a compressed CPC document representation from a file, and provides random-access to the pages described by the document.

2. Pattern Geometry

2.1. Coordinates

2.2. Dimensions

typedef struct ImDim { 
  ImRow num_rows; ImCol num_cols;
} ImDim;

2.3. Resolution

typedef struct ImResolution { 
  float xDpi, yDpi; 
} ImResolution;

3. Image Bitmaps

Multiple pixels are packed together, as densely as possible, into a single word of memory. Within a long-word, bitmap data is stored in most-significant to least-significant (big-endian) order. That is, column 0 is the most significant bit of the long-word; column 1 is the next most significant bit, etc.

Bit-maps are organized into rows of pixels. For efficiency reasons, it is useful to insure that each row of the map begins on a long-word boundary. Hence, the width of a row is rounded up to a multiple of the number of bits in a long-word (i.e., 32). A bit-map, therefore, has two dimensions:

• the first, known as the image dimensions, describes the actual dimensions of the pattern bounding box (e.g., for a page image, this would be the actual page dimensions);
• the second, known as the memory dimensions, describes the dimensions of the memory buffer for the pattern. (The memory dimension has the same height as the image dimension, and the width is the width of the image dimension rounded up to the next multiple of 32.)

Type Definition: ImBitMap

Describes the bit-map representation of a pattern. The image dimensions of the pattern are stored in img_dim, and the memory dimensions of the pattern are stored in mem_dim. pixels points to the memory buffer that stores the pattern bit-map.

The memory width is always a multiple of the number of bits in a long-word, and hence, each image row in pixels starts on a long-word boundary.

typedef struct ImBitMap { ImDim img_dim, mem_dim; unsigned long *pixels; } ImBitMap;

3.1. Creating a Bit-Map

3.2. Accessing the rows of a Bit-Map

Function Definition: ibm_getRow

Returns a pointer to the pixel longword that contains column 0 of the row, rowNum, within the bit-map, ibm. Rows are numbered from zero.

If rowNum is greater than or equal to the height of the bit-map, the returned pointer is not valid.

unsigned long *ibm_getRow(ImBitMap *ibm, unsigned rowNum);

3.3. Destroying a Bit-Map

Function Definition: ibm_destroy

Destroy the bitmap, ibm, de-allocating its memory.

On return from this function, ibm is no longer valid, and the application should not use it on any subsequent interaction with the CPC library.

void ibm_destroy(ImBitMap *ibm);

4. The CPC Encoder

• Create an encoder using cpcEnc_createFromFile.
• Add each of the document pages to the encoder using cpcEnc_addPage. The order in which the pages are added determines the order of the pages in the document.
• Destroy the encoder using cpcEnc_destroy.

4.1. Creating an Encoder

When the application is done with the encoder, it should call cpcEnc_destroy to deallocate it.

Function Definition: cpcEnc_createFromFile

Create a CPC encoder that sends its compressed CPC data to the file, sink, starting at the file's current seek position. If progressive is non-zero, the document is encoded using the CPC-Progressive format. Otherwise, it is encoded using the CPC-Normal format.

Returns a pointer to the encoder, or 0 if the encoder could not be created. The only reason for failure is that memory could not be allocated.

sink must be a seekable file (i.e., it must not be a pipe), and it must be opened in binary mode.

CpcEncoder *cpcEnc_createFromFile(FILE *sink, unsigned progressive);

4.2. Adding Pages to the Document

4.3. Destroying the Encoder

Function Definition: cpcEnc_destroy

Flush all document data to the output file and destroy the encoder, cpc. If closeOutput is non-zero, the output file is also closed. Otherwise, the encoder is detached from the output file, and on return, the output file's seek pointer is positioned immediately after the compressed document data. (On an error, the position of the output file's seek pointer is undefined.)

If an application is using Rapid Deployment Data Streams, the closeOutput parameter determines whether or not the output Data Stream is also closed.

Returns 0 if the encoder successfully compressed the document. Otherwise, returns a pointer to a zero-terminated ASCII string describing the nature of the error.

On return from this function, cpc is no longer valid, and the application should not use it on any subsequent interaction with the CPC library.

The returned string is owned by the CPC library. It should not be modified or deallocated by the application.

char const *cpcEnc_destroy(CpcEncoder *cpc, unsigned closeOutput);

4.4. Encoder Example

This example is for expository purposes only; in a real-world application, it would be inefficient to buffer all of the page bitmaps for a document.

char const *Encode(ImBitMap *pages[], unsigned pageCnt)
{
  unsigned i; CpcEncoder *cpc; FILE *fp;
  fp = fopen("out.cpi", "wb");
  if(!fp) { return "Unable to create output file"; }
 
  cpc = cpcEnc_createFromFile(fp, 0/*CPC-Normal*/);
  if(!cpc) { fclose(fp); return "Unable to create decoder"; }

  for(i=0; i<pageCnt; i++) { cpcEnc_addPage(cpc, pages[i]); }
  return cpcEnc_destroy(cpc, 1/*closeOutput*/);
}

5. The CPC Decoder

• Create a decoder using cpcDec_createFromFile.
• Determine the number of pages in the document using cpcDec_getPageCount.
• Retrieve the document pages from the decoder using cpcDec_getPage.
• Determine the error status of the decoder using cpcDec_getError.
• Destroy the decoder using cpcDec_destroy.

5.1. Creating a Decoder

Function Definition: cpcDec_createFromFile

Create a CPC decoder that reads its compressed CPC data from the file, data, starting at the file's current seek position. If sequential is non-zero, the decoder is configured for sequential access to the pages. Otherwise, the decoder is configured for random access. (Random access uses an additional 750k of memory.)

Returns a pointer to the decoder, or 0 if the decoder could not be created. The only reason for failure is that memory could not be allocated.

data must be a seekable file (i.e., it must not be a pipe), and it must be opened in binary mode.

CpcDecoder *cpcDec_createFromFile(FILE *data, unsigned sequential);

5.2. Determining the Page Count

5.3. Retrieving Page Bit-Maps

5.4. Determining Page Resolution

5.5. Querying the Error State

Function Definition: cpcDec_getError

Returns 0 if the decoder, cpc, has not encountered any errors. Otherwise, returns a pointer to a zero-terminated ASCII string describing the nature of the error.

The returned string is owned by the CPC library. It should not be modified or deallocated by the application.

char const *cpcDec_getError(CpcDecoder *cpc);

5.6. Destroying the Decoder

Function Definition: cpcDec_destroy

Closes the CPC decoder, cpc. If closeInput is non-zero, the underlying input file will also be closed. Otherwise, the decoder is detached from the input file. On return, the position of the input file's seek pointer is undefined.

If an application is using Rapid Deployment Data Streams, the closeInput parameter determines whether or not the input Data Stream is also closed.

Returns 0 if the decoder has not encountered any errors. Otherwise, returns a pointer to a zero-terminated ASCII string describing the nature of the error.

On return from this function, cpc is no longer valid, and the application should not use it on any subsequent interaction with the CPC library.

The returned string is owned by the CPC library. It should not be modified or deallocated by the application.

char const *cpcDec_destroy(CpcDecoder *cpc, unsigned closeInput);

5.7. Decoder Example

char const *Decode(FILE *fp)
{
  unsigned i, pageCnt; CpcDecoder *cpc;
  cpc = cpcDec_createFromFile(fp, 1/*sequential*/);
  if(!cpc) { return "Unable to create decoder"; }

  for(i=0, pageCnt=cpcDec_getPageCount(cpc); i<pageCount; i++) { 
    ImBitMap *ibm = cpcDec_getPage(cpc,i); 
    if(!ibm) { break; }
    ibm_destroy(ibm);   
  }
  return cpcDec_destroy(cpc, 0/*do not close file*/);
}

6. Compilation

extern "C" {
# include "RapidCpc.h"
};

7. Memory Allocation

typedef struct CpcMemAllocator {
  void *(*Allocate)(unsigned long numBytes);
  void *(*Reallocate)(void *mem, unsigned long numBytes);
  void (*Free)(void *ptr);
} CpcMemAllocator;

The following interface is used to set the memory allocator for the calling process.

Function Definition: cpcMem_setAllocator

Set the CPC memory allocator to the allocator, cpcMem. The CPC library copies the CpcMemAllocator, so the application may pass a pointer to temporary memory.

This function, if it is called, must be called prior to calling any other CPC library functions.

void cpcMem_setAllocator(CpcMemAllocator *cpcMem);

8. Multi-Threading

9. Binary Mode

• binary mode
• CPC-Normal
• CPC-Progressive
• cpcDec_createFromFile [Function]
• cpcDec_destroy [Function]
• cpcDec_getError [Function]
• cpcDec_getPage [Function]
• cpcDec_getPageCount [Function]
• cpcDec_getPageRes [Function]
• CpcDecoder [Opaque Type]
• cpcEnc_addPage [Function]
• cpcEnc_createFromFile [Function]
• cpcEnc_destroy [Function]
• CpcEncoder [Opaque Type]
• cpcMem_setAllocator [Function]
• CpcMemAllocator [Data Type]
• document
• ibm_create [Function]
• ibm_destroy [Function]
• ibm_getRow [Function]
• image dimensions
• ImBitMap [Data Type]
• ImCol [Data Type]
• ImDim [Data Type]
• ImResolution [Data Type]
• ImRow [Data Type]
• memory dimensions
• Rapid Deployment API

Cartesian Products, Inc.
cpi@cartesianinc.com