Abstract base class for ML data compression algorithms. More...

#include <mlDataCompressor.h>

Inheritance diagram for ml::DataCompressor:

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 Types inherited from ml::Base
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; 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.

Public Member Functions inherited from ml::Base
	Base ()
	Constructor.

virtual	~Base ()
	Destructor.

virtual Base *	deepCopy () const
	Set addStateToTree version number that can be accessed via getAddStateVersion()

bool	isOfAllowedType (const std::vector< const RuntimeType * > &types) const
	Check if this object's type is equal to or derived from one of the types given in the argument.

virtual bool	isRefCountedBase () const
	Returns if the instance is derived from RefCountedBase.

virtual std::string	detailString () const
	Return 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
	Write the objects state to the data stream object.

virtual void	readFrom (AbstractPersistenceInputStream *, int)
	Read 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 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 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.

Detailed Description

Abstract base class for ML data compression algorithms.

See MLDataCompressorDoc.h for further information.

Definition at line 36 of file mlDataCompressor.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

The maximum number of usable optional parameters for a compressor class derived from DataCompressor, default to 0.

Enumerator
MaxHints

Definition at line 47 of file mlDataCompressor.h.

◆ HintType

enum ml::DataCompressor::HintType

Possible values to describe the type of a compression parameter.

Enumerator
Unused	Default value: The parameters is not used.
IsDouble	The parameter is a double parameter.
IsInt	The parameter is an integer parameter.
IsBool	The integer is false if 0, true otherwise.
IsString	The parameter is a string parameter.
IsDataType	The integer represents an MLDataType or -1 if not valid.

Definition at line 50 of file mlDataCompressor.h.

Constructor & Destructor Documentation

◆ DataCompressor()

ml::DataCompressor::DataCompressor ( )

Constructor.

◆ ~DataCompressor()

ml::DataCompressor::~DataCompressor ( )

override

Destructor.

Member Function Documentation

◆ compress()

virtual MLErrorCode ml::DataCompressor::compress	(	const void *	srcMem,
		size_t	srcSize,
		void *&	dstMem,
		MLint &	dstNum ) const

pure virtual

Compresses a chunk of memory.

Assumes the data to be aligned on voxel size borders.

Parameters

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.

Returns: ML_RESULT_OK on successful compression or an error code describing the error.

◆ decompress()

virtual MLErrorCode ml::DataCompressor::decompress	(	const void *	srcMem,
		size_t	srcSize,
		void *&	dstMem,
		MLint64 &	resSize ) const

pure virtual

Uncompresses a chunk of memory.

Assumes the data to be aligned on voxel size borders.

Parameters

srcMem	is the pointer to the compressed data to be uncompressed.
srcSize	is 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.

Returns: ML_RESULT_OK on successful decompression or an error code describing the error.

◆ diffCodeData()

static void ml::DataCompressor::diffCodeData	(	void *	data,
		size_t	dataSize,
		size_t	voxSize = 1 )

staticprotected

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.

Parameters

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 divisible by voxSize the remaining bytes are not coded but left unchanged. Assumes the data to be aligned on voxel size borders.

◆ findHint()

virtual int ml::DataCompressor::findHint ( const std::string & hintName )

virtual

Returns the index of the hint with name hintName or -1 if not found.

◆ getDataType()

virtual MLDataType ml::DataCompressor::getDataType ( ) const

inlinevirtual

Returns the data type of the compressed data or -1 if not known (the default).

Definition at line 117 of file mlDataCompressor.h.

◆ getHint()

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.

◆ getImageExtent()

virtual void ml::DataCompressor::getImageExtent ( MLint ext[6] ) const

inlinevirtual

Returns the extent of the compressed data chunk in voxels or [0,0,0] if not known (the default).

Definition at line 131 of file mlDataCompressor.h.

References mlrange_cast().

◆ getSuffix()

virtual std::string ml::DataCompressor::getSuffix ( ) const

inlinevirtual

Returns the suffix describing the compression scheme, for example "lzw", "tiff" or so.

Definition at line 100 of file mlDataCompressor.h.

◆ getTypeName()

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".

◆ getVendor()

virtual std::string ml::DataCompressor::getVendor ( ) const

inlinevirtual

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 96 of file mlDataCompressor.h.

◆ getVersion()

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".

◆ getVoxelSize()

virtual size_t ml::DataCompressor::getVoxelSize ( ) const

inlinevirtual

Returns the size of one voxel or 1 if not known (the default).

Definition at line 124 of file mlDataCompressor.h.

◆ isLossy()

virtual bool ml::DataCompressor::isLossy ( ) const

inlinevirtual

Returns true if compression is lossy, false if not; default is false.

Return true if the uncompress 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 107 of file mlDataCompressor.h.

◆ isSupportedVersion()

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.

◆ numUsedHints()

virtual MLuint8 ml::DataCompressor::numUsedHints ( ) const

inlinevirtual

Number of hints used by the derived compressor class, it defaults to 0.

Definition at line 138 of file mlDataCompressor.h.

◆ packMLints()

static void ml::DataCompressor::packMLints	(	const MLint	vec[6],
		unsigned char	packedBuffer[55] )

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, because on small data blocks 6 MLint values need considerable data size (48 bytes). The maximum result size is 55 bytes.

◆ reorderBytePlanes()

static int ml::DataCompressor::reorderBytePlanes	(	void *	data,
		size_t	dataSize,
		size_t	voxSize )

staticprotected

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. Assumes the data to be aligned on voxel size borders.

◆ reorderDataTraversal()

static int ml::DataCompressor::reorderDataTraversal	(	void *	data,
		size_t	dataSize,
		size_t	voxSize,
		const MLint64	imgExt[6] )

staticprotected

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. Assumes the data to be aligned on voxel size borders.

◆ setDataType()

virtual void ml::DataCompressor::setDataType ( MLDataType dt )

inlinevirtual

Set the data type of the compressed data or -1 if not known (the default).

Definition at line 120 of file mlDataCompressor.h.

References mlrange_cast().

◆ setHint() [1/2]

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.

◆ setHint() [2/2]

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.

◆ setImageExtent()

virtual void ml::DataCompressor::setImageExtent ( const MLint ext[6] )

inlinevirtual

Set the size of one voxel or 1 if not known (the default).

Definition at line 134 of file mlDataCompressor.h.

References mlrange_cast().

◆ setVoxelSize()

virtual void ml::DataCompressor::setVoxelSize ( size_t vSize )

inlinevirtual

Set the size of one voxel or 1 if not known (the default).

Definition at line 127 of file mlDataCompressor.h.

References mlrange_cast().

◆ undiffCodeData()

static void ml::DataCompressor::undiffCodeData	(	void *	data,
		size_t	dataSize,
		size_t	voxSize = 1 )

staticprotected

See diffCodeData for the inverse operation and documentation.

Assumes the data to be aligned on voxel size borders.

◆ unpackMLints()

static void ml::DataCompressor::unpackMLints	(	const unsigned char	packedBuffer[55],
		MLint	vec[6] )

staticprotected

Inverse operation to packMLints.

◆ unReorderBytePlanes()

static int ml::DataCompressor::unReorderBytePlanes	(	void *	data,
		size_t	dataSize,
		size_t	voxSize )

staticprotected

Make data preparation undone, returns 0 on success, and a non 0 value otherwise.

See reorderBytePlanes for further information. Assumes the data to be aligned on voxel size borders.

◆ unReorderDataTraversal()

static int ml::DataCompressor::unReorderDataTraversal	(	void *	data,
		size_t	dataSize,
		size_t	voxSize,
		const MLint64	imgExt[6] )

staticprotected

Undoes the operation applied by reorderDataTraversal, for further information see reorderDataTraversal.

Assumes the data to be aligned on voxel size borders.

Member Data Documentation

◆ _dataType

MLDataType ml::DataCompressor::_dataType

protected

Data type which can be specified by some applications, default is -1 for not known.

Definition at line 214 of file mlDataCompressor.h.

◆ _ext

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 220 of file mlDataCompressor.h.

◆ _hintName

std::string ml::DataCompressor::_hintName[MaxHints]

protected

Array for optional string hints, default is "".

Definition at line 232 of file mlDataCompressor.h.

◆ _hintType

HintType ml::DataCompressor::_hintType[MaxHints]

protected

Type of the optional parameter, default is Unused.

Definition at line 226 of file mlDataCompressor.h.

◆ _rangeMax

double ml::DataCompressor::_rangeMax[MaxHints]

protected

Maximum interval range for numeric parameter, default is 0.

Definition at line 238 of file mlDataCompressor.h.

◆ _rangeMin

double ml::DataCompressor::_rangeMin[MaxHints]

protected

Minimum interval range for numeric parameter, default is 0.

Definition at line 235 of file mlDataCompressor.h.

◆ _strHints

std::string ml::DataCompressor::_strHints[MaxHints]

protected

Array for optional string hints, default is "".

Definition at line 229 of file mlDataCompressor.h.

◆ _voxelSize

size_t ml::DataCompressor::_voxelSize

protected

Data type which can be specified by some applications, default is 1 for not known.

Definition at line 217 of file mlDataCompressor.h.

The documentation for this class was generated from the following file:

MeVis/Foundation/Sources/MLDataCompressors/MLDataCompressor/mlDataCompressor.h

Public Types

Public Member Functions

Static Protected Member Functions

Protected Attributes

Compression and decompression

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ HintType

Constructor & Destructor Documentation

◆ DataCompressor()

◆ ~DataCompressor()

Member Function Documentation

◆ compress()

◆ decompress()

◆ diffCodeData()

◆ findHint()

◆ getDataType()

◆ getHint()

◆ getImageExtent()

◆ getSuffix()

◆ getTypeName()

◆ getVendor()

◆ getVersion()

◆ getVoxelSize()

◆ isLossy()

◆ isSupportedVersion()

◆ numUsedHints()

◆ packMLints()

◆ reorderBytePlanes()

◆ reorderDataTraversal()

◆ setDataType()

◆ setHint() [1/2]

◆ setHint() [2/2]

◆ setImageExtent()

◆ setVoxelSize()

◆ undiffCodeData()

◆ unpackMLints()

◆ unReorderBytePlanes()

◆ unReorderDataTraversal()

Member Data Documentation

◆ _dataType

◆ _ext

◆ _hintName

◆ _hintType

◆ _rangeMax

◆ _rangeMin

◆ _strHints

◆ _voxelSize