xrif
A fast, high performance, lossless compression system.
Code documentation is here: https://jaredmales.github.io/xrif-docs/modules.html
Building
Dependencies
The only dependencies are the check unit testing framework and subunit streaming system.
On CentOS:
$ sudo yum install check-devel
$ sudo yum install subunit-devel
On Ubuntu:
$ sudo apt-get install check
Configure, Make, and Install
For a standard posix system, you should only need to do these steps:
$ mkdir build
$ cd build
$ cmake ..
$ make
$ make test
$ sudo make install
$ sudo ldconfig
Basic Usage
The below code shows the steps needed to initialize an xrif handle and use it to compress a cube of images.
int16_t * source_data;
// ... allocate and populate source_data with `planes` images of size `rows X cols`
xrif_t xrif;
xrif_error_t rv;
rv = xrif_new(&xrif);
rv = xrif_set_size(xrif, rows, cols, 1, planes, XRIF_TYPECODE_INT16); // For a cube with `planes` images of size `rows X cols` of type `int16_t`
rv = xrif_allocate(xrif);
memcpy( xrif->raw, source_data, rows*cols*planes*sizeof(int16_t));
rv = xrif_encode(xrif);
rv = xrif_decode(xrif);
memcpy(source_data, xrif->raw, rows*cols*planes*sizeof(int16_t));
The library provides ways to use source_data directly (avoiding the memcpy), and control over which algorithms are used at each step of the compression.
Note that only int16 monochrome images are fully supported at this time.
Header Format
| Field | Bytes | value |
|---|---|---|
| 0 | 0-3 | 'x' 'r' 'i' 'f' [magic number] |
| 1 | 4-7 | uint32_t version number of xrif protocol |
| 2 | 8-11 | uint32_t total size of header [offset to beginning of data, minimum is 48] |
| 3 | 12-15 | uint32_t width of a frame |
| 4 | 16-19 | uint32_t height of a frame |
| 5 | 20-23 | uint32_t depth of a frame [allows cubes, IFU spectra, etc] |
| 6 | 24-27 | uint32_t number of frames |
| 7 | 28-29 | uint16_t typecode [is uint8_t in struct, but alignment] |
| 7 | 30-31 | uint16_t difference method |
| 8 | 32-33 | uint16_t reorder method |
| 9 | 34-35 | uint16_t compression method |
| 10 | 36-39 | uint32_t size of compressed data |
| 10 | 40-47 | Reserved, used for method specific parameters. |
The current version is 0
The size of the data is specified by width X height X depth X xrif_typesize(typecode) X frames
Difference method can be:
| Val. | Meaning |
|---|---|
| 0 | none |
| 100 | w.r.t. previous frame |
| 200 | w.r.t. first frame |
Reorder method can be:
| Val. | Meaning |
|---|---|
| 0 | none |
| 100 | bytepack |
| 200 | bytepack-renibble |
| 300 | bitpack [warning: bitpack is broken, do not use] |
Compression method can be:
| Val. | Meaning |
|---|---|
| 0 | none |
| 100 | LZ4 |
If Compression method is LZ4 then bytes 40-41 are uint16_t containing the lz4_acceleration parameter.
Code Documentation
The code documentation is here: https://jaredmales.github.io/xrif/