MeVisLab Toolbox Reference
|
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. 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... | |
![]() | |
enum | PersistenceInterface { PersistenceByString , PersistenceByTreeNode , PersistenceByStream } |
This enum describes the different persistence interfaces available. More... | |
Public Member Functions | |
Construction, destruction. | |
DataCompressor () | |
Constructor. | |
~DataCompressor () override | |
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. | |
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 |
Returns 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". | |
virtual bool | isLossy () const |
Returns true if compression is lossy, false if not. | |
Optional parameters that may be used by the derived compressor classes. | |
virtual MLDataType | getDataType () const |
Returns the data type of the compressed data or -1 if unknown. Default is -1. | |
virtual void | setDataType (MLDataType dt) |
Sets the data type of the compressed data or -1 if unknown. Default is -1. | |
virtual size_t | getVoxelSize () const |
Returns the size of one voxel or 1 if unknown. Default is 1. | |
virtual void | setVoxelSize (size_t vSize) |
Sets the size of one voxel or 1 if unknown. Default is 1. | |
virtual void | getImageExtent (MLint ext[6]) const |
Returns the extent of the compressed data chunk in voxels or [0,0,0] if unknown. Default is [0,0,0]. | |
virtual void | setImageExtent (const MLint ext[6]) |
Sets the size of one voxel or 1 if unknown. Default is 1. | |
virtual MLuint8 | numUsedHints () const |
Returns the 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 |
Gets the optional parameters settings for different purposes. | |
virtual MLErrorCode | setHint (MLuint8 hintIdx, const std::string value) |
Sets the hint value of the hint number hintIdx . | |
virtual MLErrorCode | setHint (const std::string &hintName, const std::string &value) |
Sets the hint value of the 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. | |
![]() | |
Base () | |
Constructor. | |
virtual | ~Base () |
Destructor. | |
virtual Base * | deepCopy () const |
Creates a deep copy of the given object. | |
bool | isOfAllowedType (const std::vector< const RuntimeType * > &types) const |
Checks whether this object's type is equal to or derived from one of the types given in the argument. | |
virtual bool | isRefCountedBase () const |
Returns whether the instance is derived from RefCountedBase. | |
virtual std::string | detailString () const |
Returns a string describing this object. | |
virtual bool | implementsPersistence (PersistenceInterface) const |
Override this method to declare which persistence interfaces are implemented by your derived class. | |
virtual std::string | persistentState () const |
Returns a string describing the object's internal state. | |
virtual void | setPersistentState (const std::string &state) |
Restores the object's internal state from a string that had been previously generated using persistentState(). | |
virtual void | addStateToTree (TreeNode *) const |
Attaches the object state as children of the given parent node. | |
virtual void | readStateFromTree (TreeNode *) |
Reads the object state from the children of the given parent node. | |
virtual void | writeTo (AbstractPersistenceOutputStream *) const |
Writes the objects state to the data stream object. | |
virtual void | readFrom (AbstractPersistenceInputStream *, int) |
Reads the objects state from the data stream object. | |
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-zero value otherwise. | |
static int | unReorderBytePlanes (void *data, size_t dataSize, size_t voxSize) |
Makes data preparation undone, returns 0 on success, and a non-zero 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 voxel, replacing the next voxel with 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 to use local data coherence, reducing changes between neighboring voxels, which often improves compression. | |
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 that 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 that can be specified by some applications, default is -1 if unknown. | |
size_t | _voxelSize |
Data type that can be specified by some applications, default is 1 if unknown. | |
MLint | _ext [6] |
Extent of the compressed data chunk in voxels, default is [0,0,0,0,0,0] if unknown. | |
virtual MLErrorCode | compress (const void *srcMem, size_t srcSize, void *&dstMem, MLint &dstNum) const =0 |
Compresses a chunk of memory. | |
virtual MLErrorCode | decompress (const void *srcMem, size_t srcSize, void *&dstMem, MLint64 &resSize) const =0 |
Uncompresses a chunk of memory. | |
Abstract base class for ML data compression algorithms.
See MLDataCompressorDoc.h for further information.
Definition at line 36 of file mlDataCompressor.h.
The maximum number of usable optional parameters for a compressor class derived from DataCompressor.
Default is 0.
Enumerator | |
---|---|
MaxHints |
Definition at line 47 of file mlDataCompressor.h.
Possible values to describe the type of a compression parameter.
Definition at line 50 of file mlDataCompressor.h.
ml::DataCompressor::DataCompressor | ( | ) |
Constructor.
|
override |
Destructor.
|
pure virtual |
Compresses a chunk of memory.
Assumes the data to be aligned on voxel size borders.
srcMem | The pointer of data to be compressed. |
srcSize | The size of the data pointed to by srcMem in bytes. |
dstMem | Returns the pointer to the compressed data. The compressor will allocate the required memory and overwrite the dstMem pointer, which 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. |
|
pure virtual |
Uncompresses a chunk of memory.
Assumes the data to be aligned on voxel size borders.
srcMem | The pointer to the compressed data to be uncompressed. |
srcSize | The size of the data pointed to by srcMem in bytes. |
dstMem | Returns the pointer to the uncompressed 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 uncompressed data memory in bytes or 0 on error. |
|
staticprotected |
This tool recodes a data array by calculating a coded difference between each voxel and its next voxel, replacing the next voxel with its coded difference.
The coded difference is the absolute integer difference between both values, with the sign bit stored in the first bit. Image data coded in this way can be compressed better by many types of compressors, often improving 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, 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 divisible by voxSize, the remaining bytes are not coded but left unchanged. Assumes the data to be aligned on voxel size borders. |
Returns the index of the hint with name hintName
or -1 if not found.
|
inlinevirtual |
Returns the data type of the compressed data or -1 if unknown. Default is -1.
Definition at line 117 of file mlDataCompressor.h.
|
virtual |
Gets the optional parameters settings for different purposes.
Returns the extent of the compressed data chunk in voxels or [0,0,0] if unknown. Default is [0,0,0].
Definition at line 131 of file mlDataCompressor.h.
References mlrange_cast().
|
inlinevirtual |
Returns the suffix describing the compression scheme, for example "lzw", "tiff".
Definition at line 100 of file mlDataCompressor.h.
|
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".
|
inlinevirtual |
Returns 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 96 of file mlDataCompressor.h.
|
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".
Returns the size of one voxel or 1 if unknown. Default is 1.
Definition at line 124 of file mlDataCompressor.h.
Returns true
if compression is lossy, false
if not.
Default is false
. Returns true
if the uncompress method does not restore the data identically, as 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 107 of file mlDataCompressor.h.
Returns true
if the passed version ver
is supported by the implemented compressor class and false
otherwise.
Returns the number of hints used by the derived compressor class, it defaults to 0.
Definition at line 138 of file mlDataCompressor.h.
|
staticprotected |
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, as on small data blocks six MLint values need considerable data size (48 bytes). The maximum result size is 55 bytes.
|
staticprotected |
Prepares the data for optimal compression, returns 0 on success, and a non-zero value otherwise.
Depending 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 that 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. This often holds true 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, as data reordering also costs additional performance and also degrades compression efficiency in some cases. Assumes the data to be aligned on voxel size borders.
|
staticprotected |
Reorders the traversal of the data to use local data coherence, reducing changes between neighboring voxels, which often improves compression.
Returns >= 0 on success or no operation, and values < 0 on errors. It reorders the data only if voxSize is in [1,2,4,8]. Voxel sizes > 8 are allowed but ignored, with a return value of 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. Assumes the data to be aligned on voxel size borders.
|
inlinevirtual |
Sets the data type of the compressed data or -1 if unknown. Default is -1.
Definition at line 120 of file mlDataCompressor.h.
References mlrange_cast().
|
virtual |
Sets the hint value
of the hint given by the name hintName
.
Returns ML_RESULT_OK on success and on failure, returns a code describing the problem.
|
virtual |
Sets the hint value
of the hint number hintIdx
.
Returns ML_RESULT_OK on success and on failure, returns a code describing the problem.
Sets the size of one voxel or 1 if unknown. Default is 1.
Definition at line 134 of file mlDataCompressor.h.
References mlrange_cast().
Sets the size of one voxel or 1 if unknown. Default is 1.
Definition at line 127 of file mlDataCompressor.h.
References mlrange_cast().
|
staticprotected |
See diffCodeData for the inverse operation and documentation.
Assumes the data to be aligned on voxel size borders.
|
staticprotected |
Inverse operation to packMLints.
|
staticprotected |
Makes data preparation undone, returns 0 on success, and a non-zero value otherwise.
See reorderBytePlanes for further information. Assumes the data to be aligned on voxel size borders.
|
staticprotected |
Undoes the operation applied by reorderDataTraversal, for further information see reorderDataTraversal.
Assumes the data to be aligned on voxel size borders.
|
protected |
Data type that can be specified by some applications, default is -1 if unknown.
Definition at line 214 of file mlDataCompressor.h.
|
protected |
Extent of the compressed data chunk in voxels, default is [0,0,0,0,0,0] if unknown.
Definition at line 220 of file mlDataCompressor.h.
|
protected |
Array for optional string hints, default is "".
Definition at line 232 of file mlDataCompressor.h.
Type of the optional parameter, default is Unused.
Definition at line 226 of file mlDataCompressor.h.
Maximum interval range for numeric parameter, default is 0.
Definition at line 238 of file mlDataCompressor.h.
Minimum interval range for numeric parameter, default is 0.
Definition at line 235 of file mlDataCompressor.h.
|
protected |
Array for optional string hints, default is "".
Definition at line 229 of file mlDataCompressor.h.
|
protected |
Data type that can be specified by some applications, default is 1 if unknown.
Definition at line 217 of file mlDataCompressor.h.