README

   1 **********************************************************************
   2  libaec - Adaptive Entropy Coding library
   3 **********************************************************************
   4
   5 Libaec provides fast lossless compression of 1 up to 32 bit wide
   6 signed or unsigned integers (samples). The library achieves best
   7 results for low entropy data as often encountered in space imaging
   8 instrument data or numerical model output from weather or climate
   9 simulations. While floating point representations are not directly
  10 supported, they can also be efficiently coded by grouping exponents
  11 and mantissa.
  12
  13 Libaec implements Golomb Rice coding as defined in the Space Data
  14 System Standard documents 121.0-B-2 [1] and 120.0-G-2[2].
  15
  16
  17 **********************************************************************
  18  Patents
  19 **********************************************************************
  20
  21 In doc/license.txt a clarification on potentially applying
  22 intellectual property rights is given.
  23
  24
  25 **********************************************************************
  26  Installation
  27 **********************************************************************
  28
  29 See INSTALL for details.
  30
  31
  32 **********************************************************************
  33  Encoding
  34 **********************************************************************
  35
  36 In this context efficiency refers to the size of the encoded
  37 data. Performance refers to the time it takes to encode data.
  38
  39 Suppose you have an array of 32 bit signed integers you want to
  40 compress. The pointer pointing to the data shall be called *source,
  41 output goes into *dest.
  42
  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 block_size can vary from 8 to 64 samples. Smaller blocks allow the
  89 compression to adapt to rapid changes in entropy. Larger blocks create
  90 less overhead but can be less efficient if entropy changes across the
  91 block.
  92
  93 rsi sets the reference sample interval. A large RSI will improve
  94 performance and efficiency. It will also increase memory requirements
  95 since internal buffering is based on RSI size. A smaller RSI may be
  96 desirable in situations where each RSI will be packetized and possible
  97 error propagation has to be minimized.
  98
  99 Flags:
 100
 101 AEC_DATA_SIGNED: input data are signed integers. Specifying this
 102 correctly increases compression efficiency. Default is unsigned.
 103
 104 AEC_DATA_PREPROCESS: preprocessing input will improve compression
 105 efficiency if data samples are correlated. It will only cost
 106 performance for no gain in efficiency if the data is already
 107 uncorrelated.
 108
 109 AEC_DATA_MSB: input data is stored most significant byte first
 110 i.e. big endian. You have to specify AEC_DATA_MSB even if your host
 111 architecture is big endian. Default is little endian on all
 112 architectures.
 113
 114 AEC_DATA_3BYTE: the 24 bit input data is stored in three bytes.
 115
 116 AEC_RESTRICTED: use a restricted set of code options. This option is
 117 only valid for bits_per_sample <= 4.
 118
 119 AEC_PAD_RSI: assume that the encoded RSI is padded to the next byte
 120 boundary while decoding. The preprocessor macro ENABLE_RSI_PADDING
 121 needs to be defined while compiling for the encoder to honour this
 122 flag.
 123
 124 Data size:
 125
 126 Except for the AEC_DATA_3BYTE case for 24 bit data, the following
 127 rules apply for deducing storage size from sample size
 128 (bits_per_sample):
 129
 130 sample size   storage size
 131  1 -  8 bits  1 byte
 132  9 - 16 bits  2 bytes
 133 17 - 32 bits  4 bytes (also for 24bit 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 are
 143 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 **********************************************************************
 165  Decoding
 166 **********************************************************************
 167
 168 Using decoding is very similar to encoding, only the meaning of input
 169 and output is reversed.
 170
 171 #include <libaec.h>
 172
 173 ...
 174     struct aec_stream strm;
 175     /* this is now the compressed data */
 176     unsigned char *source;
 177     /* here goes the uncompressed result */
 178     int32_t *dest;
 179
 180     strm.bits_per_sample = 32;
 181     strm.block_size = 16;
 182     strm.rsi = 128;
 183     strm.flags = AEC_DATA_SIGNED | AEC_DATA_PREPROCESS;
 184     strm.next_in = source;
 185     strm.avail_in = source_length;
 186     strm.next_out = (unsigned char *)dest;
 187     strm.avail_out = dest_lenth * sizeof(int32_t);
 188     if (aec_decode_init(&strm) != AEC_OK)
 189         return 1;
 190     if (aec_decode(&strm, AEC_FLUSH) != AEC_OK)
 191         return 1;
 192     aec_decode_end(&strm);
 193 ...
 194
 195 It is essential for decoding that parameters like bits_per_sample,
 196 block_size, rsi, and flags are exactly the same as they were for
 197 encoding. Libaec does not store these parameters in the coded stream
 198 so it is up to the calling program to keep the correct parameters
 199 between encoding and decoding.
 200
 201 The actual values of coding parameters are in fact only relevant for
 202 efficiency and performance. Data integrity only depends on consistency
 203 of the parameters.
 204
 205
 206 **********************************************************************
 207  References
 208 **********************************************************************
 209
 210 [1] Consultative Committee for Space Data Systems. Lossless Data
 211 Compression. Recommendation for Space Data System Standards, CCSDS
 212 121.0-B-2. Blue Book. Issue 2. Washington, D.C.: CCSDS, May 2012.
 213 http://public.ccsds.org/publications/archive/121x0b2.pdf
 214
 215 [2] Consultative Committee for Space Data Systems. Lossless Data
 216 Compression.  Recommendation for Space Data System Standards, CCSDS
 217 120.0-G-3. Green Book. Issue 3. Washington, D.C.: CCSDS, April
 218 2013.
 219 http://public.ccsds.org/publications/archive/120x0g3.pdf