Libpolycomp  1.0
A compression/decompression library that implements the polynomial compression and other simple compression schemes
Functions
Floating-point quantization

Functions

pcomp_quant_params_t * pcomp_init_quant_params (size_t element_size, size_t bits_per_sample)
 Initialize a pcomp_quant_params_t structure. More...
 
void pcomp_free_quant_params (pcomp_quant_params_t *params)
 Free a pcomp_quant_params_t structure. More...
 
size_t pcomp_quant_element_size (const pcomp_quant_params_t *params)
 Return the size (in bytes) of the elements to be quantized. More...
 
size_t pcomp_quant_bits_per_sample (const pcomp_quant_params_t *params)
 Return the number of bits that must be used for each quantized sample.
 
double pcomp_quant_normalization (const pcomp_quant_params_t *params)
 Return the normalization constant used for converting floating-point numbers into quantized integers. More...
 
double pcomp_quant_offset (const pcomp_quant_params_t *params)
 Return the additive constant used for converting floating-point numbers into quantized integers. More...
 
void pcomp_quant_set_normalization (pcomp_quant_params_t *params, double normalization, double offset)
 Set the normalization constants (multiplicative and additive) used to quantize floating-point numbers. More...
 
size_t pcomp_quant_bufsize (size_t input_size, const pcomp_quant_params_t *params)
 Return the size (in bytes) of the buffer that will contain a quantized stream of input_size floating point values. More...
 
int pcomp_compress_quant_double (void *output_buf, size_t *output_size, const double *input_buf, size_t input_size, pcomp_quant_params_t *params)
 Quantize a stream of 64-bit floating point numbers. More...
 
int pcomp_compress_quant_float (void *output_buf, size_t *output_size, const float *input_buf, size_t input_size, pcomp_quant_params_t *params)
 Quantize a stream of 32-bit floating point numbers. More...
 

Detailed Description

The algorithm and its applicability

The quantization compression is applicable only to series of floating-point numbers. It works by converting the series into a sequence of integer numbers, whose bit size is less than the number of bits required for the input numbers.

This compression scheme works well for data acquired by means of some digital process. Typically, the bitsize of such samples is smaller than 32 or 64 bits: in such cases, this encoding allows to achieve good compression ratios with negligible loss of information.

This kind of compression is lossy, because the decompressed stream is not identical to the stream before the compression. It is possible to prove that, under quite general assumptions, the difference between the two is a stream of zero-average random numbers. This stream of residuals follows a symmetric, non-Gaussian distribution whose RMS is $q^2/12$, where $q$ is the quantization step (i.e., $q = 2^{-N}$, where $N$ is the number of bits used in the quantization).

Implementation details

Before compressing the data, the caller must initialize an opaque structure, pcomp_quant_params_t, that contains information about the quantization process. Such structure is created via a call to pcomp_init_quant_params and freed by pcomp_free_quant_params. Access to the fields of the structure is only possible through the following functions:

The caller must pre-allocate the buffer that will hold the quantized stream.

Function Documentation

int pcomp_compress_quant_double ( void *  output_buf,
size_t *  output_size,
const double *  input_buf,
size_t  input_size,
pcomp_quant_params_t *  params 
)

Quantize a stream of 64-bit floating point numbers.

This function applies a quantization formula to all the numbers in the array input_buf. It saves the result as a stream of raw bytes in output_buf.

An usage example of the function is the following, which uses 5 bits per every 64-bit input value:

double input_buf[] = { 3.06, 5.31, 2.25, 7.92, 4.86 };
size_t input_size = sizeof(input_buf) / sizeof(input_buf[0]);
pcomp_quant_params_t* params;
size_t output_size;
const size_t bits_per_element = 5;
params = pcomp_init_quant_params(sizeof(input_buf[0]),
bits_per_element);
output_size = pcomp_quant_bufsize(input_size, params);
pcomp_compress_quant_double(output_buf, &output_size, input_buf,
input_size, params);
Parameters
[out]output_bufPointer to the buffer that will contain the quantized values
[in,out]output_sizePointer to a variable containing the number of bytes allocated for output_buf. This number must be at least equal to the return value of the function pcomp_quant_bufsize. On exit, this will contain the actual number of bytes written to output_buf.
[in]input_bufPointer to the array of 64-bit floating points to quantize
[in]input_sizeNumber of 64-bit floating point elements (not bytes) in the array input_buf that must be quantized.
[in]paramsStructure defining the details of the quantization. It should be created via a call to pcomp_init_quant_params.
Returns
PCOMP_STAT_SUCCESS if the encoding completed successfully. Otherwise, the error code specifies the kind of error occurred during the call.
int pcomp_compress_quant_float ( void *  output_buf,
size_t *  output_size,
const float *  input_buf,
size_t  input_size,
pcomp_quant_params_t *  params 
)

Quantize a stream of 32-bit floating point numbers.

Parameters
[out]output_bufPointer to the buffer that will contain the quantized values
[in,out]output_sizePointer to a variable containing the number of bytes allocated for output_buf. This number must be at least equal to the return value of the function pcomp_quant_bufsize. On exit, this will contain the actual number of bytes written to output_buf.
[in]input_bufPointer to the array of 32-bit floating points to quantize
[in]input_sizeNumber of 32-bit floating point elements (not bytes) in the array input_buf that must be quantized.
[in]paramsStructure defining the details of the quantization. It should be created via a call to pcomp_init_quant_params.
Returns
PCOMP_STAT_SUCCESS if the encoding completed successfully. Otherwise, the error code specifies the kind of error occurred during the call.
void pcomp_free_quant_params ( pcomp_quant_params_t *  params)

Free a pcomp_quant_params_t structure.

Free the memory associated with the structured pointed by params. Such structure must have been allocated via a call to pcomp_init_quant_params.

If params is NULL, the function does nothing.

[in] params Pointer to the structure to free.

Definition at line 128 of file quant.c.

pcomp_quant_params_t* pcomp_init_quant_params ( size_t  element_size,
size_t  bits_per_sample 
)

Initialize a pcomp_quant_params_t structure.

The function returns a pointer to a heap-allocated structure. It must be freed by the caller once is no longer used via a call to pcomp_free_quant_params.

Parameters
[in]element_sizeWidth (in bytes) of the values to be quantized. It can either be 4 (32-bit floating points) or 8 (64-bit floating points), but the function does not enforce this.
[in]bits_per_sampleNumber of bits to be used for each sample after quantization. This value should be less than the number of bits used in the input floating-point numbers, in order to achieve a compression ratio greater than 1.
Returns
A pointer to the newly created pcomp_quant_params_t structure.

Definition at line 104 of file quant.c.

size_t pcomp_quant_bufsize ( size_t  input_size,
const pcomp_quant_params_t *  params 
)

Return the size (in bytes) of the buffer that will contain a quantized stream of input_size floating point values.

Unlike functions like pcomp_rle_bufsize, the value returned by this function is exact, not an upper bound. It represents the number of bytes needed to store all the compressed floating point values.

Parameters
[in]input_sizeNumber of elements to compress
[in]paramsParameters describing the quantization process (created by pcomp_init_quant_params)
Returns
The size in bytes of the buffer needed to hold all the input_size compressed values.

Definition at line 244 of file quant.c.

size_t pcomp_quant_element_size ( const pcomp_quant_params_t *  params)

Return the size (in bytes) of the elements to be quantized.

Returns
Either 4 (32-bit floating points) or 8 (64-bit floating points).

Definition at line 142 of file quant.c.

double pcomp_quant_normalization ( const pcomp_quant_params_t *  params)

Return the normalization constant used for converting floating-point numbers into quantized integers.

See pcomp_quant_set_normalization for further information.

Definition at line 170 of file quant.c.

double pcomp_quant_offset ( const pcomp_quant_params_t *  params)

Return the additive constant used for converting floating-point numbers into quantized integers.

See pcomp_quant_set_normalization for further information.

Definition at line 185 of file quant.c.

void pcomp_quant_set_normalization ( pcomp_quant_params_t *  params,
double  normalization,
double  offset 
)

Set the normalization constants (multiplicative and additive) used to quantize floating-point numbers.

This function allows to change the quantization transform described by params via the two additive values $S$ (normalization) and $\Delta$ (offset) used in the formula

\[x_\mathrm{out} = [S \times x_\mathrm{in} + \Delta]\]

, where square brackets denote a rounding operation.

Parameters
[in]paramsPointer to the pcomp_quant_params_t structure to modify
[in]normalizationNew value for the multiplicative constant $S$
[in]offsetNew value for the additive constant $\Delta$

Definition at line 212 of file quant.c.