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