Encoder class for optimized encoding of images. More...

#include <ImageCompressor.h>

Inheritance diagram for icl::io::ImageCompressor:

Classes
struct	CompressedData
	most simple dyn-size array with given data and length More...

struct	CompressionSpec
	compression specification More...

struct	Header
	Compressed image header. More...

Public Member Functions
	ImageCompressor (const CompressionSpec &spec=CompressionSpec("none"))
	Creates an image Compressor with given compression mode. More...

	~ImageCompressor ()
	Destructor. More...

virtual void	setCompression (const CompressionSpec &spec)
	string based interface for setting the compression mode More...

virtual CompressionSpec	getCompression () const
	can be implemented for returning the current compression mode More...

utils::Time	pickTimeStamp (const icl8u *compressedData)
	this can help to find out wheter the data is new and must be encoded More...

const CompressedData	compress (const core::ImgBase *image, bool skipMetaData=false)
	encodes a given image into the compressed code More...

const core::ImgBase *	uncompress (const icl8u compressedData, int len, core::ImgBase *dst=0)
	decodes the given byte segment More...

Protected Member Functions
Header	uncompressHeader (const icl8u *compressedData, int len)
	only decodes an image header More...

Header	createHeader (const core::ImgBase *image, bool skipMetaData)
	creates a header for a given image (not data will be null) More...

Protected Member Functions inherited from icl::utils::Uncopyable
	Uncopyable ()
	Empty base constructor. More...

Private Member Functions
int	estimateEncodedBufferSize (const core::ImgBase *image, bool skipMetaData)
	internal utlity function More...

int	estimateRawDataSize (const core::ImgBase *image, bool skipMetaData)
	internal utlity function More...

Private Attributes
Data *	m_data
	pimpl type More...

Detailed Description

Encoder class for optimized encoding of images.

The ImageCompressor class allows for simple and for optimized serialization and desirealization of images

Serialization Modes

Right now, 4 different serialization modes are supported.

"rlen" Run Length Encoding: here, the image is scanned line by line and instead of encoding pixel data [ pix1, pix2, pix3, ...], it is encoded by [value|length] pairs. Which means, that the value was found length+1 times in the image data. This type of compression is very well suited for images with low structure and in particular for low noise binary images. However, it fails completely for natual camera images. The "rlen" plugin supports four different quality settings, where each setting determines the number of bits, that are used for the value and for lenght tokens.
- Quality 1: value: 1Bit, length 7Bit. This core::format is most appropriate for binary images with low noise. Here, a compression to 1% of the original size can easily be reached. Please note, that the binarization threshold is explicitly set to 127 for this quality level. For the other quality levels, only the most significant bits are used.
- Quality 4: value: 4Bit, length 4Bit. Can be used to compress with remaining 4Bit value resolution (usually, this is only needed for very special cases) The compression is usually also worse since the maximum reachable compression ration is 1/(2^4).
- Quality 6: value 6Bit, length 2Bit. Bad compression ratio, but an visibly almost lossless compression.
- Quality 8: value 8Bit, length 8Bit. Best for non-binary images with lots of homogeneous regions. Lossless, but not neccessarily better than uncompressed serialization. Best case: 1/(2^8) compression, Worst case: 2/1.
"dith" Works as rlen, but before sending, the image is dithered
"jpeg" uses jpeg compression. Comparable to motion jpeg and only available if ICL has been build with LIBJPEG support. The compression quality can be varied from 0 to 100. Which is the default JPEG compression quality value. Usually values around 70 provide sufficient results with a very good compression ration (about 2%). However, please note that even a quality setting of 100 does not lead to lossless compression.
- "1611" compresses unsigned 16-bit images to 11-bit packed continuous data. The result is a pointer to an unsigned 16-bit-array
  - Quality 0: Cuts the upper 5 bits (only values up to 2^11 are supported)
  - Quality 1: Compresses 16-bit arrays to 11-bit packed arrays as follows: D = (a/Z)+b and uncompresses Z = a/(D-b) (See Kinect11BitCompressor for details)
"none" Uncompressed image serialization. This is the only compression mode, that can be used for non-core::Img8u images.

Depth Support

Only core::Img8u-images can be compressed. For all other formats, the compression mode "none" (with quality setting "none") has to be chosen.

Serialization Structure

The serialized image consists of 3 parts: The Header information, which is exactly the binarized version of ImageCompressor::Header::Params. Optionally meta data, whose length can also be 0. And the actual compressed image data. The lengths of the meta data and the image data segements are defined by the header.

Image Meta Data

The ImageCompressor preserves an images meta data, however meta data is always binarized in an uncompressed manner.

ROI-Support

The image ROI is also compressed and later uncompressed. So if you compress an image with a non-full ROI, the uncompressed version will also be the whole image with a non-full ROI.

Benchmarks:

There are several factors, that have to be regarded: image size image fragmentation (b/w noise)

Both, the encoding /decoding steps should scale linearily with the image pixel count, while extremely vertical images provide in slower results. Also the image fragmentation is important for the en-/de-coding speed. Benchmarks were take on an Intel (R) Xeon E5530 @2.40GHz CPU, only single channel images were used.

VGA image, high noise: compression to 20%: encoding 3msec, decoding 2msec
VGA image, low noise: compression to 5%: encoding 1msec, decoding 0.8msec
VGA image, very low noise: compression to 1.7%: encoding 0.4msec, decoding 0.37msec
SXVGA (4-times VGA), high noise, compression to 22%: encoding 8.4msec, decoding 7.8msec
SXVGA (4-times VGA), low noise, compression to 4.1%: encoding 2.0msec, decoding 1.8msec
SXVGA (4-times VGA), very low noise, compression to 1.4%: encoding 0.8msec, decoding 0.76mse

Memory Consumption

In order to avoid run-time memory allocation, the run-length coder always ensures that enough bytes are available: I.e. 1 byte per image pixel

header size of 37 + N bytes (N is meta data size)
for JPEG data, 2x the raw image data is allocated

Constructor & Destructor Documentation

◆ ImageCompressor()

icl::io::ImageCompressor::ImageCompressor ( const CompressionSpec & spec = CompressionSpec("none") )

Creates an image Compressor with given compression mode.

◆ ~ImageCompressor()

icl::io::ImageCompressor::~ImageCompressor ( )

Destructor.

Member Function Documentation

◆ compress()

const CompressedData icl::io::ImageCompressor::compress	(	const core::ImgBase *	image,
		bool	skipMetaData = `false`
	)

encodes a given image into the compressed code

JPEG compression does not yet meta data

◆ createHeader()

Header icl::io::ImageCompressor::createHeader	(	const core::ImgBase *	image,
		bool	skipMetaData
	)

protected

creates a header for a given image (not data will be null)

◆ estimateEncodedBufferSize()

int icl::io::ImageCompressor::estimateEncodedBufferSize	(	const core::ImgBase *	image,
		bool	skipMetaData
	)

private

internal utlity function

◆ estimateRawDataSize()

int icl::io::ImageCompressor::estimateRawDataSize	(	const core::ImgBase *	image,
		bool	skipMetaData
	)

private

internal utlity function

◆ getCompression()

virtual CompressionSpec icl::io::ImageCompressor::getCompression ( ) const

virtual

can be implemented for returning the current compression mode

Reimplemented in icl::io::GenericImageOutput.

◆ pickTimeStamp()

utils::Time icl::io::ImageCompressor::pickTimeStamp ( const icl8u * compressedData )

this can help to find out wheter the data is new and must be encoded

not supported for jpeg data

◆ setCompression()

virtual void icl::io::ImageCompressor::setCompression ( const CompressionSpec & spec )

virtual

string based interface for setting the compression mode

Parameters

spec

(e.g. CompressionSpec("mode") with mode = rle, jpg, or none) the compression quality, which might depend on the set type (e.g. 1 Bit for binary rle, or 90 for 90% jpeg compression) Current valid compression modes are

"none" no compression (default, possible for all data types)
"rlen" run lenght encoding (quality can be 1, 4 or 6, it defines the number of bits, that are used for the value domain. Default value is 1, which is used for binary images)
"jpeg" jpeg encoding (quality is default jpeg quality 1% - 100%)

Reimplemented in icl::io::GenericImageOutput.

◆ uncompress()

const core::ImgBase* icl::io::ImageCompressor::uncompress	(	const icl8u *	compressedData,
		int	len,
		core::ImgBase **	dst = `0`
	)

decodes the given byte segment

◆ uncompressHeader()

Header icl::io::ImageCompressor::uncompressHeader	(	const icl8u *	compressedData,
		int	len
	)

protected

only decodes an image header

not supported for jpeg data

Member Data Documentation

◆ m_data

Data* icl::io::ImageCompressor::m_data

private

pimpl type

pimpl pointer

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

/Users/alneuman/vm/icl/ICLIO/src/ICLIO/ImageCompressor.h

Classes

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Serialization Modes

Depth Support

Serialization Structure

Image Meta Data

ROI-Support

Benchmarks:

Memory Consumption

Constructor & Destructor Documentation

◆ ImageCompressor()

◆ ~ImageCompressor()

Member Function Documentation

◆ compress()

◆ createHeader()

◆ estimateEncodedBufferSize()

◆ estimateRawDataSize()

◆ getCompression()

◆ pickTimeStamp()

◆ setCompression()

◆ uncompress()

◆ uncompressHeader()

Member Data Documentation

◆ m_data