README.md

   1 # libaec - Adaptive Entropy Coding library
   2
   3 Libaec provides fast lossless compression of 1 up to 32 bit wide
   4 signed or unsigned integers (samples). The library achieves best
   5 results for low entropy data as often encountered in space imaging
   6 instrument data or numerical model output from weather or climate
   7 simulations. While floating point representations are not directly
   8 supported, they can also be efficiently coded by grouping exponents
   9 and mantissa.
  10
  11 Libaec implements
  12 [Golomb-Rice](http://en.wikipedia.org/wiki/Golomb_coding) coding as
  13 defined in the Space Data System Standard documents [121.0-B-2][1] and
  14 [120.0-G-2][2].
  15
  16 ## Patents
  17
  18 In [license.txt](doc/license.txt) a clarification on potentially
  19 applying intellectual property rights is given.
  20
  21 ## Installation
  22
  23 See [INSTALL](INSTALL) for details.
  24
  25 ## SZIP Compatibility
  26
  27 [Libaec can replace SZIP](README.SZIP).
  28
  29 ## Encoding
  30
  31 In this context efficiency refers to the size of the encoded
  32 data. Performance refers to the time it takes to encode data.
  33
  34 Suppose you have an array of 32 bit signed integers you want to
  35 compress. The pointer pointing to the data shall be called `*source`,
  36 output goes into `*dest`.
  37
  38 ```c
  39 #include <libaec.h>
  40
  41 ...
  42     struct aec_stream strm;
  43     int32_t *source;
  44     unsigned char *dest;
  45
  46     /* input data is 32 bits wide */
  47     strm.bits_per_sample = 32;
  48
  49     /* define a block size of 16 */
  50     strm.block_size = 16;
  51
  52     /* the reference sample interval is set to 128 blocks */
  53     strm.rsi = 128;
  54
  55     /* input data is signed and needs to be preprocessed */
  56     strm.flags = AEC_DATA_SIGNED | AEC_DATA_PREPROCESS;
  57
  58     /* pointer to input */
  59     strm.next_in = (unsigned char *)source;
  60
  61     /* length of input in bytes */
  62     strm.avail_in = source_length * sizeof(int32_t);
  63
  64     /* pointer to output buffer */
  65     strm.next_out = dest;
  66
  67     /* length of output buffer in bytes */
  68     strm.avail_out = dest_length;
  69
  70     /* initialize encoding */
  71     if (aec_encode_init(&strm) != AEC_OK)
  72         return 1;
  73
  74     /* Perform encoding in one call and flush output. */
  75     /* In this example you must be sure that the output */
  76     /* buffer is large enough for all compressed output */
  77     if (aec_encode(&strm, AEC_FLUSH) != AEC_OK)
  78         return 1;
  79
  80     /* free all resources used by encoder */
  81     aec_encode_end(&strm);
  82 ...
  83 ```
  84
  85 `block_size` can vary from 8 to 64 samples. Smaller blocks allow the
  86 compression to adapt more rapidly to changing source
  87 statistics. Larger blocks create less overhead but can be less
  88 efficient if source statistics change across the block.
  89
  90 `rsi` sets the reference sample interval. A large RSI will improve
  91 performance and efficiency. It will also increase memory requirements
  92 since internal buffering is based on RSI size. A smaller RSI may be
  93 desirable in situations where each RSI will be packetized and possible
  94 error propagation has to be minimized.
  95
  96 ### Flags:
  97
  98 * `AEC_DATA_SIGNED`: input data are signed integers. Specifying this
  99   correctly increases compression efficiency. Default is unsigned.
 100
 101 * `AEC_DATA_PREPROCESS`: preprocessing input will improve compression
 102   efficiency if data samples are correlated. It will only cost
 103   performance for no gain in efficiency if the data is already
 104   uncorrelated.
 105
 106 * `AEC_DATA_MSB`: input data is stored most significant byte first
 107   i.e. big endian. You have to specify `AEC_DATA_MSB` even if your host
 108   architecture is big endian. Default is little endian on all
 109   architectures.
 110
 111 * `AEC_DATA_3BYTE`: the 17 to 24 bit input data is stored in three
 112   bytes. This flag has no effect for other sample sizes.
 113
 114 * `AEC_RESTRICTED`: use a restricted set of code options. This option is
 115   only valid for `bits_per_sample` <= 4.
 116
 117 * `AEC_PAD_RSI`: assume that the encoded RSI is padded to the next byte
 118   boundary while decoding. The preprocessor macro `ENABLE_RSI_PADDING`
 119   needs to be defined while compiling for the encoder to honour this
 120   flag.
 121
 122 ### Data size:
 123
 124 The following rules apply for deducing storage size from sample size
 125 (`bits_per_sample`):
 126
 127  **sample size**  | **storage size**
 128 --- | ---
 129  1 -  8 bits  | 1 byte
 130  9 - 16 bits  | 2 bytes
 131 17 - 24 bits  | 3 bytes (only if `AEC_DATA_3BYTE` is set)
 132 25 - 32 bits  | 4 bytes (if `AEC_DATA_3BYTE` is set)
 133 17 - 32 bits  | 4 bytes (if `AEC_DATA_3BYTE` is not set)
 134
 135 If a sample requires less bits than the storage size provides, then
 136 you have to make sure that unused bits are not set. Libaec does not
 137 check this for performance reasons and will produce undefined output
 138 if unused bits are set. All input data must be a multiple of the
 139 storage size in bytes. Remaining bytes which do not form a complete
 140 sample will be ignored.
 141
 142 Libaec accesses `next_in` and `next_out` buffers only bytewise. There
 143 are no alignment requirements for these buffers.
 144
 145 ### Flushing:
 146
 147 `aec_encode` can be used in a streaming fashion by chunking input and
 148 output and specifying `AEC_NO_FLUSH`. The function will return if either
 149 the input runs empty or the output buffer is full. The calling
 150 function can check `avail_in` and `avail_out` to see what occurred. The
 151 last call to `aec_encode()` must set `AEC_FLUSH` to drain all
 152 output. aec.c is an example of streaming usage of encoding and
 153 decoding.
 154
 155 ### Output:
 156
 157 Encoded data will be written to the buffer submitted with
 158 `next_out`. The length of the compressed data is `total_out`.
 159
 160 See libaec.h for a detailed description of all relevant structure
 161 members and constants.
 162
 163
 164 ## Decoding
 165
 166 Using decoding is very similar to encoding, only the meaning of input
 167 and output is reversed.
 168
 169 ```c
 170 #include <libaec.h>
 171
 172 ...
 173     struct aec_stream strm;
 174     /* this is now the compressed data */
 175     unsigned char *source;
 176     /* here goes the uncompressed result */
 177     int32_t *dest;
 178
 179     strm.bits_per_sample = 32;
 180     strm.block_size = 16;
 181     strm.rsi = 128;
 182     strm.flags = AEC_DATA_SIGNED | AEC_DATA_PREPROCESS;
 183     strm.next_in = source;
 184     strm.avail_in = source_length;
 185     strm.next_out = (unsigned char *)dest;
 186     strm.avail_out = dest_lenth * sizeof(int32_t);
 187     if (aec_decode_init(&strm) != AEC_OK)
 188         return 1;
 189     if (aec_decode(&strm, AEC_FLUSH) != AEC_OK)
 190         return 1;
 191     aec_decode_end(&strm);
 192 ...
 193 ```
 194
 195 It is strongly recommended that the size of the output buffer
 196 (`next_out`) is a multiple of the storage size in bytes. If the buffer
 197 is not a multiple of the storage size and the buffer gets filled to
 198 the last sample, the error code `AEC_MEM_ERROR` is returned.
 199
 200 It is essential for decoding that parameters like `bits_per_sample`,
 201 `block_size`, `rsi`, and `flags` are exactly the same as they were for
 202 encoding. Libaec does not store these parameters in the coded stream
 203 so it is up to the calling program to keep the correct parameters
 204 between encoding and decoding.
 205
 206 The actual values of coding parameters are in fact only relevant for
 207 efficiency and performance. Data integrity only depends on consistency
 208 of the parameters.
 209
 210
 211 ## References
 212
 213 [Consultative Committee for Space Data Systems. Lossless Data
 214 Compression. Recommendation for Space Data System Standards, CCSDS
 215 121.0-B-2. Blue Book. Issue 2. Washington, D.C.: CCSDS, May 2012.][1]
 216 [1]: http://public.ccsds.org/publications/archive/121x0b2.pdf
 217
 218 [Consultative Committee for Space Data Systems. Lossless Data
 219 Compression.  Recommendation for Space Data System Standards, CCSDS
 220 120.0-G-3. Green Book. Issue 3. Washington, D.C.: CCSDS, April 2013.][2]
 221 [2]: http://public.ccsds.org/publications/archive/120x0g3.pdf