Commit 9438be93 authored by Mathis Rosenhauer's avatar Mathis Rosenhauer Committed by Thomas Jahns
Browse files

clarifications

parent 8ce474cf
...@@ -3,13 +3,15 @@ ...@@ -3,13 +3,15 @@
********************************************************************** **********************************************************************
libaec provides fast lossless compression of 1 up to 32 bit wide libaec provides fast lossless compression of 1 up to 32 bit wide
signed or unsigned integers. The library achieves best results for low signed or unsigned integers (samples). The library achieves best
entropy data as often encountered in space imaging instrument data or results for low entropy data as often encountered in space imaging
numerical model output from weather or climate simulations. While instrument data or numerical model output from weather or climate
floating point representations are not directly supported, they can simulations. While floating point representations are not directly
also be efficiently coded by grouping exponents and mantissa. supported, they can also be efficiently coded by grouping exponents
and mantissa.
libaec implements a Space Data System Standard [1], [2]. libaec implements Golomb Rice coding as defined in the Space Data
System Standard document 121.0-B-2 [1], [2].
********************************************************************** **********************************************************************
...@@ -24,7 +26,7 @@ intellectual property rights is given. ...@@ -24,7 +26,7 @@ intellectual property rights is given.
Installation Installation
********************************************************************** **********************************************************************
See INSTALL for details. See INSTALL for details.
********************************************************************** **********************************************************************
...@@ -45,7 +47,7 @@ output goes into *dest. ...@@ -45,7 +47,7 @@ output goes into *dest.
int32_t *source; int32_t *source;
unsigned char *dest; unsigned char *dest;
/* input data ist 32 bits wide */ /* input data is 32 bits wide */
strm.bits_per_sample = 32; strm.bits_per_sample = 32;
/* define a block size of 16 */ /* define a block size of 16 */
...@@ -83,9 +85,10 @@ output goes into *dest. ...@@ -83,9 +85,10 @@ output goes into *dest.
aec_encode_end(&strm); aec_encode_end(&strm);
... ...
block_size can vary from 8 to 64. Smaller blocks allow the compression block_size can vary from 8 to 64 samples. Smaller blocks allow the
to adapt to rapid changes in entropy. Larger blocks create less compression to adapt to rapid changes in entropy. Larger blocks create
overhead but can be less efficient. less overhead but can be less efficient if entropy changes across the
block.
rsi sets the reference sample interval. A large RSI will improve rsi sets the reference sample interval. A large RSI will improve
performance and efficiency. It will also increase memory requiremens performance and efficiency. It will also increase memory requiremens
...@@ -98,9 +101,10 @@ Flags: ...@@ -98,9 +101,10 @@ Flags:
AEC_DATA_SIGNED: input data are signed integers. Specifying this AEC_DATA_SIGNED: input data are signed integers. Specifying this
correctly increases compression efficiency. Default is unsigned. correctly increases compression efficiency. Default is unsigned.
AEC_DATA_PREPROCESS: preprocessing input will almost always improve AEC_DATA_PREPROCESS: preprocessing input will improve compression
compression efficiency. It may only cost performance for no gain in efficiency if data samples are correlated. It will only cost
efficiency if the data is already uncorrelated. performance for no gain in efficiency if the data is already
uncorrelated.
AEC_DATA_MSB: input data is stored most significant byte first AEC_DATA_MSB: input data is stored most significant byte first
i.e. big endian. You have to specify AEC_DATA_MSB even if your host i.e. big endian. You have to specify AEC_DATA_MSB even if your host
...@@ -112,28 +116,36 @@ AEC_DATA_3BYTE: the 24 bit input data is stored in three bytes. ...@@ -112,28 +116,36 @@ AEC_DATA_3BYTE: the 24 bit input data is stored in three bytes.
Data size: Data size:
Except for the AEC_DATA_3BYTE case for 24 bit data, the following Except for the AEC_DATA_3BYTE case for 24 bit data, the following
rules apply: rules apply for deducing storage size from sample size
(bits_per_sample):
data size storage size sample size storage size
1 - 8 bit 1 byte 1 - 8 bit 1 byte
9 - 16 bit 2 bytes 9 - 16 bit 2 bytes
17 - 32 bit 4 bytes (also for 24bit if AEC_DATA_3BYTE is not set) 17 - 32 bit 4 bytes (also for 24bit if AEC_DATA_3BYTE is not set)
If you use less bits than the storage size provides, then you have to
make sure that unused bits are not set. libaec does not check this for
performance reasons and will produce undefined output if unused bits
are set.
Flushing: Flushing:
aec_encode can be used in a streaming fashion by chunking input and aec_encode can be used in a streaming fashion by chunking input and
output and specifying AEC_NO_FLUSH. The function will return if either output and specifying AEC_NO_FLUSH. The function will return if either
the input runs empty or the output buffer is full. The calling the input runs empty or the output buffer is full. The calling
function can check avail_in and avail_out to see what occcurred. aec.c function can check avail_in and avail_out to see what occcurred. The
is an example of streaming usage of encoding and decoding. last call to aec_encode() must set AEC_FLUSH to drain all
output. aec.c is an example of streaming usage of encoding and
decoding.
********************************************************************** **********************************************************************
Decoding Decoding
********************************************************************** **********************************************************************
Usage for decoding is very similar to encoding, only the meaning of Using decoding is very similar to encoding, only the meaning of input
input and output is reversed. and output is reversed.
#include <libaec.h> #include <libaec.h>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment