MeVisLabToolboxReference
|
Abstract base class for ML data compression algorithms. More...
#include <mlDataCompressor.h>
Public Types | |
Constants. | |
enum | { MaxHints = 10 } |
The maximum number of usable optional parameters for a compressor class derived from DataCompressor, default to 0. More... | |
enum | HintType { Unused = 0, IsDouble = 1, IsInt = 2, IsBool = 3, IsString = 4, IsDataType = 5 } |
Possible values to describe the type of a compression parameter. More... | |
Public Member Functions | |
Construction, deconstruction. | |
DataCompressor () | |
Constructor. | |
virtual | ~DataCompressor () |
Destructor. | |
Basic compressor description. | |
virtual std::string | getTypeName () const =0 |
Returns the name of the compression scheme, used for example in user interfaces to select a compression scheme, something of the kind "ZLIB", "TIFF", or "PNG". | |
virtual std::string | getVersion () const =0 |
Returns the version string; the compression class itself must provide checks for compatibility with version handling methods, something of the kind "1.1.4" or "1.1". | |
virtual bool | isSupportedVersion (const std::string &ver) const =0 |
Returns true if the passed version ver is supported by the implemented compressor class and false otherwise. | |
virtual std::string | getVendor () const |
Return the name of the vendor providing the compressor code or algorithm, something of the kind "MeVis", the author or the company selling the algorithm. | |
virtual std::string | getSuffix () const |
Returns the suffix describing the compression scheme, for example "lzw", "tiff" or so. | |
virtual bool | isLossy () const |
Returns true if compression is lossy, false if not; default is false. | |
Optional parameters which may be used by the derived compressor classes. | |
virtual MLDataType | getDataType () const |
Returns the data type of the compressed data or -1 if not known (the default). | |
virtual void | setDataType (MLDataType dt) |
Set the data type of the compressed data or -1 if not known (the default). | |
virtual size_t | getVoxelSize () const |
Returns the size of one voxel or 1 if not known (the default). | |
virtual void | setVoxelSize (size_t vSize) |
Set the size of one voxel or 1 if not known (the default). | |
virtual void | getImageExtent (MLint ext[6]) const |
Returns the extent of the compressed data chunk in voxels or [0,0,0] if not known (the default). | |
virtual void | setImageExtent (const MLint ext[6]) |
Set the size of one voxel or 1 if not known (the default). | |
virtual MLuint8 | numUsedHints () const |
Number of hints used by the derived compressor class, it defaults to 0. | |
virtual void | getHint (MLuint8 hintIdx, HintType &hintType, std::string &strVal, std::string &hintName, double &rangeMin, double &rangeMax) const |
Get the optional parameters settings for different purposes. | |
virtual MLErrorCode | setHint (MLuint8 hintIdx, const std::string value) |
Set the hint value strVal of hint number hintIdx. | |
virtual MLErrorCode | setHint (const std::string &hintName, const std::string &value) |
Set the hint value strVal of hint given by the name hintName. | |
virtual int | findHint (const std::string &hintName) |
Returns the index of the hint with name hintName or -1 if not found. | |
Static Protected Member Functions | |
Data reorganization for better compression ratios. | |
static int | reorderBytePlanes (void *data, size_t dataSize, size_t voxSize) |
Prepares the data for optimal compression, returns 0 on success, and a non 0 value otherwise. | |
static int | unReorderBytePlanes (void *data, size_t dataSize, size_t voxSize) |
Make data preparation undone, returns 0 on success, and a non 0 value otherwise. | |
static void | diffCodeData (void *data, size_t dataSize, size_t voxSize=1) |
This tool recodes a data array by calculating a coded difference between each voxel and its next one and replacing the next one by its coded difference. | |
static void | undiffCodeData (void *data, size_t dataSize, size_t voxSize=1) |
See diffCodeData for the inverse operation and documentation. | |
static int | reorderDataTraversal (void *data, size_t dataSize, size_t voxSize, const MLint64 imgExt[6]) |
Reorders the traversal of the data so that local data coherence is used to reduce changes between neighbour voxels which often improves compression; returns >= 0 on success and no operation, and values < 0 on errors. | |
static int | unReorderDataTraversal (void *data, size_t dataSize, size_t voxSize, const MLint64 imgExt[6]) |
Undoes the operation applied by reorderDataTraversal, for further information see reorderDataTraversal. | |
static void | packMLints (const MLint vec[6], unsigned char packedBuffer[55]) |
Packs six MLint values if possible to a smaller memory. | |
static void | unpackMLints (const unsigned char packedBuffer[55], MLint vec[6]) |
Inverse operation to packMLints. | |
Protected Attributes | |
Arrays of optional compressor parameters which may be changed by derived classes. | |
HintType | _hintType [MaxHints] |
Type of the optional parameter, default is Unused. | |
std::string | _strHints [MaxHints] |
Array for optional string hints, default is "". | |
std::string | _hintName [MaxHints] |
Array for optional string hints, default is "". | |
double | _rangeMin [MaxHints] |
Minimum interval range for numeric parameter, default is 0. | |
double | _rangeMax [MaxHints] |
Maximum interval range for numeric parameter, default is 0. | |
Compression and decompression | |
MLDataType | _dataType |
Data type which can be specified by some applications, default is -1 for not known. | |
size_t | _voxelSize |
Data type which can be specified by some applications, default is 1 for not known. | |
MLint | _ext [6] |
Extent of the compressed data chunk in voxels, default is [0,0,0,0,0,0] for not known. | |
virtual ML_RETURN_VALUE_SHOULD_BE_USED MLErrorCode | compress (const void *srcMem, size_t srcSize, void *&dstMem, MLint &dstNum) const =0 |
Compresses a chunk of memory. | |
virtual ML_RETURN_VALUE_SHOULD_BE_USED MLErrorCode | decompress (const void *srcMem, size_t srcSize, void *&dstMem, MLint64 &resSize) const =0 |
Decompresses a chunk of memory. |
Abstract base class for ML data compression algorithms.
See MLDataCompressorDoc.h for further information.
Definition at line 41 of file mlDataCompressor.h.
anonymous enum |
The maximum number of usable optional parameters for a compressor class derived from DataCompressor, default to 0.
Definition at line 52 of file mlDataCompressor.h.
Possible values to describe the type of a compression parameter.
Definition at line 55 of file mlDataCompressor.h.
ml::DataCompressor::DataCompressor | ( | ) |
Constructor.
virtual ml::DataCompressor::~DataCompressor | ( | ) | [virtual] |
Destructor.
virtual ML_RETURN_VALUE_SHOULD_BE_USED MLErrorCode ml::DataCompressor::compress | ( | const void * | srcMem, |
size_t | srcSize, | ||
void *& | dstMem, | ||
MLint & | dstNum | ||
) | const [pure virtual] |
Compresses a chunk of memory.
srcMem | is the pointer of data to be compressed. |
srcSize | is the size of the data pointed to by srcMem in bytes. |
dstMem | the pointer to the compressed data. The compressor will allocate the required memory and overwrite the dstMem pointer which then must be freed by the caller with MLFree() or Memory::freeMemory(). |
dstNum | will be set to size of the compressed data chunk in bytes or to 0 on error. |
virtual ML_RETURN_VALUE_SHOULD_BE_USED MLErrorCode ml::DataCompressor::decompress | ( | const void * | srcMem, |
size_t | srcSize, | ||
void *& | dstMem, | ||
MLint64 & | resSize | ||
) | const [pure virtual] |
Decompresses a chunk of memory.
srcMem | is the pointer to the compressed data to be decompressed. |
srcSize | is the size of the data pointed to by srcMem in bytes. |
dstMem | returns the pointer to the decompressed data. The dstMem pointer is overwritten with the pointer to the allocated uncompressed data. which must be freed by the caller with MLFree() or Memory::freeMemory(). |
resSize | returns the size of the decompressed data memory in bytes or -1 on error. |
static void ml::DataCompressor::diffCodeData | ( | void * | data, |
size_t | dataSize, | ||
size_t | voxSize = 1 |
||
) | [static, protected] |
This tool recodes a data array by calculating a coded difference between each voxel and its next one and replacing the next one by its coded difference.
The coded difference is the absolute integer difference between both values where the sign bit is stored in the first bit. Image data coded in this way can be compressed better by many types of compressors and therefore is often a good way to improve compression ratios. See also undiffCodeData for restoring the original data.
data | The pointer to the data chunk to be recoded. The call is ignored if data is NULL. |
dataSize | The number of bytes of in data. The call is ignored if dataSize is <2. |
voxSize | The word size of data (for example 2 for short data or 4 for integer data). Giving correct data type sizes as voxSizes usually improves compressibility. For values < 1 or values other than 1,2, 4, or 8 the call is ignored. If the dataSize is not dividable by voxSize the remaining bytes are not coded but left unchanged. |
virtual int ml::DataCompressor::findHint | ( | const std::string & | hintName | ) | [virtual] |
Returns the index of the hint with name hintName or -1 if not found.
virtual MLDataType ml::DataCompressor::getDataType | ( | ) | const [inline, virtual] |
Returns the data type of the compressed data or -1 if not known (the default).
Definition at line 122 of file mlDataCompressor.h.
virtual void ml::DataCompressor::getHint | ( | MLuint8 | hintIdx, |
HintType & | hintType, | ||
std::string & | strVal, | ||
std::string & | hintName, | ||
double & | rangeMin, | ||
double & | rangeMax | ||
) | const [virtual] |
Get the optional parameters settings for different purposes.
virtual void ml::DataCompressor::getImageExtent | ( | MLint | ext[6] | ) | const [inline, virtual] |
Returns the extent of the compressed data chunk in voxels or [0,0,0] if not known (the default).
Definition at line 136 of file mlDataCompressor.h.
virtual std::string ml::DataCompressor::getSuffix | ( | ) | const [inline, virtual] |
Returns the suffix describing the compression scheme, for example "lzw", "tiff" or so.
Definition at line 105 of file mlDataCompressor.h.
virtual std::string ml::DataCompressor::getTypeName | ( | ) | const [pure virtual] |
Returns the name of the compression scheme, used for example in user interfaces to select a compression scheme, something of the kind "ZLIB", "TIFF", or "PNG".
virtual std::string ml::DataCompressor::getVendor | ( | ) | const [inline, virtual] |
Return the name of the vendor providing the compressor code or algorithm, something of the kind "MeVis", the author or the company selling the algorithm.
Definition at line 101 of file mlDataCompressor.h.
virtual std::string ml::DataCompressor::getVersion | ( | ) | const [pure virtual] |
Returns the version string; the compression class itself must provide checks for compatibility with version handling methods, something of the kind "1.1.4" or "1.1".
virtual size_t ml::DataCompressor::getVoxelSize | ( | ) | const [inline, virtual] |
Returns the size of one voxel or 1 if not known (the default).
Definition at line 129 of file mlDataCompressor.h.
virtual bool ml::DataCompressor::isLossy | ( | ) | const [inline, virtual] |
Returns true if compression is lossy, false if not; default is false.
Return true if the decompress method does not restore the data identically, because otherwise other classes will detect checksum errors on that data. If the data is restored identically it should return false to have those security checks enabled.
Definition at line 112 of file mlDataCompressor.h.
virtual bool ml::DataCompressor::isSupportedVersion | ( | const std::string & | ver | ) | const [pure virtual] |
Returns true if the passed version ver is supported by the implemented compressor class and false otherwise.
virtual MLuint8 ml::DataCompressor::numUsedHints | ( | ) | const [inline, virtual] |
Number of hints used by the derived compressor class, it defaults to 0.
Definition at line 143 of file mlDataCompressor.h.
static void ml::DataCompressor::packMLints | ( | const MLint | vec[6], |
unsigned char | packedBuffer[55] | ||
) | [static, protected] |
Packs six MLint values if possible to a smaller memory.
This is useful if for example an image extent has to be stored in compressed data data, because on small data blocks 6 MLint values need considerable data size (48 bytes). The maximum result size is 55 bytes.
static int ml::DataCompressor::reorderBytePlanes | ( | void * | data, |
size_t | dataSize, | ||
size_t | voxSize | ||
) | [static, protected] |
Prepares the data for optimal compression, returns 0 on success, and a non 0 value otherwise.
Dependent on voxSize the lowest bytes are stored first, then medium,.... up to the highest bytes last. Using this function can especially be useful to prepare data for compression algorithms which have better compression ratios on bytes streams of values for example of type 0 0 0 0 321 554 12 37 than on byte streams of type 0 321 0 554 0 12 0 37, etc. This often holds for some text or stream compressors types (lzw, bzip2, zlib). Of course this also depends on the type of data and is mostly used only optionally, because data reordering also costs additional performance and also degrade compression efficiency in some cases.
static int ml::DataCompressor::reorderDataTraversal | ( | void * | data, |
size_t | dataSize, | ||
size_t | voxSize, | ||
const MLint64 | imgExt[6] | ||
) | [static, protected] |
Reorders the traversal of the data so that local data coherence is used to reduce changes between neighbour voxels which often improves compression; returns >= 0 on success and no operation, and values < 0 on errors.
It reorders the data only if voxSize is from [1,2,4,8]. Voxel sizes > 8 are allowed but ignored with return value 1. Return values: -3 : Out of memory error, nothing done. -2 : Error, bad parameter. -1 : Unspecific error or crash. <0 : Error 0 : Data has been successfully reordered. 1 : Nothing done and no error.
virtual void ml::DataCompressor::setDataType | ( | MLDataType | dt | ) | [inline, virtual] |
Set the data type of the compressed data or -1 if not known (the default).
Definition at line 125 of file mlDataCompressor.h.
virtual MLErrorCode ml::DataCompressor::setHint | ( | const std::string & | hintName, |
const std::string & | value | ||
) | [virtual] |
Set the hint value strVal of hint given by the name hintName.
Returns ML_RESULT_OK on success on failure another code describing the problem.
virtual MLErrorCode ml::DataCompressor::setHint | ( | MLuint8 | hintIdx, |
const std::string | value | ||
) | [virtual] |
Set the hint value strVal of hint number hintIdx.
Returns ML_RESULT_OK on success or on failure another code describing the problem.
virtual void ml::DataCompressor::setImageExtent | ( | const MLint | ext[6] | ) | [inline, virtual] |
Set the size of one voxel or 1 if not known (the default).
Definition at line 139 of file mlDataCompressor.h.
virtual void ml::DataCompressor::setVoxelSize | ( | size_t | vSize | ) | [inline, virtual] |
Set the size of one voxel or 1 if not known (the default).
Definition at line 132 of file mlDataCompressor.h.
static void ml::DataCompressor::undiffCodeData | ( | void * | data, |
size_t | dataSize, | ||
size_t | voxSize = 1 |
||
) | [static, protected] |
See diffCodeData for the inverse operation and documentation.
static void ml::DataCompressor::unpackMLints | ( | const unsigned char | packedBuffer[55], |
MLint | vec[6] | ||
) | [static, protected] |
Inverse operation to packMLints.
static int ml::DataCompressor::unReorderBytePlanes | ( | void * | data, |
size_t | dataSize, | ||
size_t | voxSize | ||
) | [static, protected] |
Make data preparation undone, returns 0 on success, and a non 0 value otherwise.
See reorderBytePlanes for further information.
static int ml::DataCompressor::unReorderDataTraversal | ( | void * | data, |
size_t | dataSize, | ||
size_t | voxSize, | ||
const MLint64 | imgExt[6] | ||
) | [static, protected] |
Undoes the operation applied by reorderDataTraversal, for further information see reorderDataTraversal.
MLDataType ml::DataCompressor::_dataType [protected] |
Data type which can be specified by some applications, default is -1 for not known.
Definition at line 217 of file mlDataCompressor.h.
MLint ml::DataCompressor::_ext[6] [protected] |
Extent of the compressed data chunk in voxels, default is [0,0,0,0,0,0] for not known.
Definition at line 223 of file mlDataCompressor.h.
std::string ml::DataCompressor::_hintName[MaxHints] [protected] |
Array for optional string hints, default is "".
Definition at line 235 of file mlDataCompressor.h.
HintType ml::DataCompressor::_hintType[MaxHints] [protected] |
Type of the optional parameter, default is Unused.
Definition at line 229 of file mlDataCompressor.h.
double ml::DataCompressor::_rangeMax[MaxHints] [protected] |
Maximum interval range for numeric parameter, default is 0.
Definition at line 241 of file mlDataCompressor.h.
double ml::DataCompressor::_rangeMin[MaxHints] [protected] |
Minimum interval range for numeric parameter, default is 0.
Definition at line 238 of file mlDataCompressor.h.
std::string ml::DataCompressor::_strHints[MaxHints] [protected] |
Array for optional string hints, default is "".
Definition at line 232 of file mlDataCompressor.h.
size_t ml::DataCompressor::_voxelSize [protected] |
Data type which can be specified by some applications, default is 1 for not known.
Definition at line 220 of file mlDataCompressor.h.