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. The library achieves best results for low
   7 entropy data as often encountered in space imaging instrument data or
   8 numerical model output from weather or climate simulations. While
   9 floating point representations are not directly supported, they can
  10 also be efficiently coded by grouping exponents and mantissa.
  11
  12 libaec implements a Space Data System Standard [1], [2].
  13
  14
  15 **********************************************************************
  16  Patents
  17 **********************************************************************
  18
  19 In doc/license.txt a clarification on potentially applying
  20 intellectual property rights is given.
  21
  22
  23 **********************************************************************
  24  Installation
  25 **********************************************************************
  26
  27  See INSTALL for details.
  28
  29
  30 **********************************************************************
  31  Encoding
  32 **********************************************************************
  33
  34 In this context efficiency refers to the size of the encoded
  35 data. Performance refers to the time it takes to encode data.
  36
  37 Suppose you have an array of 32 bit signed integers you want to
  38 compress. The pointer pointing to the data shall be called *source,
  39 output goes into *dest.
  40
  41 #include <libaec.h>
  42
  43 ...
  44     struct aec_stream strm;
  45     int32_t *source;
  46     unsigned char *dest;
  47
  48     /* input data ist 32 bits wide */
  49     strm.bits_per_sample = 32;
  50
  51     /* define a block size of 16 */
  52     strm.block_size = 16;
  53
  54     /* the reference sample interval is set to 128 blocks */
  55     strm.rsi = 128;
  56
  57     /* input data is signed and needs to be preprocessed */
  58     strm.flags = AEC_DATA_SIGNED | AEC_DATA_PREPROCESS;
  59
  60     /* pointer to input */
  61     strm.next_in = (unsigned char *)source;
  62
  63     /* length of input in bytes */
  64     strm.avail_in = source_length * 4;
  65
  66     /* pointer to output buffer */
  67     strm.avail_out = dest;
  68
  69     /* length of output buffer in bytes */
  70     strm.next_out = dest_lenth;
  71
  72     /* initialize encoding */
  73     if (aec_encode_init(&strm) != AEC_OK)
  74         return 1;
  75
  76     /* Perform encoding in one call and flush output. */
  77     /* In this example you must be sure that the output */
  78     /* buffer is large enough for all compressed output */
  79     if (aec_encode(&strm, AEC_FLUSH) != AEC_OK)
  80         return 1;
  81
  82     /* free all resources used by encoder */
  83     aec_encode_end(&strm);
  84 ...
  85
  86 block_size can vary from 8 to 64. Smaller blocks allow the compression
  87 to adapt to rapid changes in entropy. Larger blocks create less
  88 overhead but can be less efficient.
  89
  90 rsi sets the reference sample interval. A large RSI will improve
  91 performance and efficiency. It will also increase memory requiremens
  92 since internal buffering is based on RSI size. Smaller RSI may be
  93 desirable in situations where each RSI will be packetized and possible
  94 error propagation has to be minimized (e.g. on board a spacecraft[2]).
  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 almost always improve
 102 compression efficiency. It may only cost performance for no gain in
 103 efficiency if the data is already uncorrelated.
 104
 105 AEC_DATA_MSB: input data is stored most significant byte first
 106 i.e. big endian. You have to specify AEC_DATA_MSB even if your host
 107 architecture is big endian. Default is little endian on all
 108 architectures.
 109
 110 AEC_DATA_3BYTE: the 24 bit input data is stored in three bytes.
 111
 112 Data size:
 113
 114 Except for the AEC_DATA_3BYTE case for 24 bit data, the following
 115 rules apply:
 116
 117   data size   storage size
 118  1 -  8 bit   1 byte
 119  9 - 16 bit   2 bytes
 120 17 - 32 bit   4 bytes (also for 24bit if AEC_DATA_3BYTE is not set)
 121
 122 Flushing:
 123
 124 aec_encode can be used in a streaming fashion by chunking input and
 125 output and specifying AEC_NO_FLUSH. The function will return if either
 126 the input runs empty or the output buffer is full. The calling
 127 function can check avail_in and avail_out to see what occcurred. aec.c
 128 is an example of streaming usage of encoding and decoding.
 129
 130
 131 **********************************************************************
 132  Decoding
 133 **********************************************************************
 134
 135 Usage for decoding is very similar to encoding, only the meaning of
 136 input and output is reversed.
 137
 138 #include <libaec.h>
 139
 140 ...
 141     struct aec_stream strm;
 142     /* this is now the compressed data */
 143     unsigned char *source;
 144     /* here goes the uncompressed result */
 145     int32_t *dest;
 146
 147     strm.bits_per_sample = 32;
 148     strm.block_size = 16;
 149     strm.rsi = 128;
 150     strm.flags = AEC_DATA_SIGNED | AEC_DATA_PREPROCESS;
 151     strm.next_in = source;
 152     strm.avail_in = source_length;
 153     strm.next_out = (unsigned char *)dest;
 154     strm.avail_out = dest_lenth * 4;
 155     if (aec_decode_init(&strm) != AEC_OK)
 156         return 1;
 157     if (aec_decode(&strm, AEC_FLUSH) != AEC_OK)
 158         return 1;
 159     aec_decode_end(&strm);
 160 ...
 161
 162 It is essential for decoding that parameters like bits_per_sample,
 163 block_size, rsi, and flags are exactly the same as they were for
 164 encoding. libaec does not store these parameters in the coded stream
 165 so it is up to the calling program to keep the correct parameters
 166 between encoding and decoding.
 167
 168
 169 **********************************************************************
 170  References
 171 **********************************************************************
 172
 173 [1] Consultative Committee for Space Data Systems. Lossless Data
 174 Compression. Recommendation for Space Data System Standards, CCSDS
 175 121.0-B-2. Blue Book. Issue 2. Washington, D.C.: CCSDS, May 2012.
 176 http://public.ccsds.org/publications/archive/121x0b2.pdf
 177
 178 [2] Consultative Committee for Space Data Systems. Lossless Data
 179 Compression.  Recommendation for Space Data System Standards, CCSDS
 180 120.0-G-2. Green Book. Issue 2. Washington, D.C.: CCSDS, December
 181 2006.
 182 http://public.ccsds.org/publications/archive/120x0g2.pdf