A bunch of utility functions. More...

#include <libCZI_Utilities.h>

Public Types
using	CompressionOption = std::pair< libCZI::CompressionMode, std::shared_ptr< libCZI::ICompressParameters > >

Static Public Member Functions
static char	DimensionToChar (libCZI::DimensionIndex dim)

static libCZI::DimensionIndex	CharToDimension (char c)

static int	CalcMd5SumHash (libCZI::IBitmapData bm, std::uint8_t ptrHash, int hashSize)

static int	CalcMd5SumHash (const void ptrData, size_t sizeData, std::uint8_t ptrHash, int hashSize)

static std::vector< std::uint8_t >	Create8BitLookUpTableFromSplines (int tableElementCnt, float blackPoint, float whitePoint, const std::vector< libCZI::IDisplaySettings::SplineData > &splineData)

static std::vector< std::uint8_t >	Create8BitLookUpTableFromGamma (int tableElementCnt, float blackPoint, float whitePoint, float gamma)

static std::vector< std::uint16_t >	Create16BitLookUpTableFromGamma (int tableElementCnt, float blackPoint, float whitePoint, float gamma)

static std::vector< libCZI::IDisplaySettings::SplineData >	CalcSplineDataFromPoints (int pointCnt, std::function< std::tuple< double, double >(int idx)> getPoint)

static std::shared_ptr< libCZI::IBitmapData >	NearestNeighborResize (libCZI::IBitmapData *bmSrc, int dstWidth, int dstHeight)

static std::shared_ptr< libCZI::IBitmapData >	NearestNeighborResize (libCZI::IBitmapData *bmSrc, int dstWidth, int dstHeight, const DblRect &roiSrc, const DblRect &roiDest)

static float	CalcZoom (const libCZI::IntRect &logicalRect, const libCZI::IntSize &physicalSize)

static float	CalcZoom (const libCZI::IntSize &logicalSize, const libCZI::IntSize &physicalSize)

static const char *	PixelTypeToInformalString (libCZI::PixelType pixeltype)

static std::uint8_t	GetBytesPerPixel (libCZI::PixelType pixelType)

static const char *	CompressionModeToInformalString (libCZI::CompressionMode compressionMode)

static std::string	DimCoordinateToString (const libCZI::IDimCoordinate *coord)

static bool	StringToDimCoordinate (const char sz, libCZI::CDimCoordinate coord)

static std::string	DimBoundsToString (const libCZI::IDimBounds *bounds)

static std::shared_ptr< libCZI::IIndexSet >	IndexSetFromString (const std::wstring &s)

static libCZI::PixelType	TryDeterminePixelTypeForChannel (libCZI::ISubBlockRepository *repository, int channelIdx)

static int	Compare (const IDimCoordinate a, const IDimCoordinate b)

static bool	HasSameDimensions (const IDimCoordinate a, const IDimCoordinate b)

static std::shared_ptr< ICziMetadataBuilder >	CreateSubBlockMetadata (const std::function< bool(int, std::tuple< std::string, std::string > &)> &tagsEnum=nullptr)

static bool	EnumAllCoordinates (const libCZI::CDimBounds &bounds, const std::function< bool(std::uint64_t, const libCZI::CDimCoordinate &coord)> &func)

static void	FillBitmap (libCZI::IBitmapData *bm, const libCZI::RgbFloatColor &floatColor)

static libCZI::CompressionMode	CompressionModeFromRawCompressionIdentifier (std::int32_t m)

static std::int32_t	CompressionModeToCompressionIdentifier (libCZI::CompressionMode mode)

static bool	IsValidMindex (int mIndex)

static CompressionOption	ParseCompressionOptions (const std::string &options)

Static Public Attributes
static const char *const	KEY_COMPRESS_EXPLICIT_LEVEL

static const char *const	KEY_COMPRESS_PRE_PROCESS

static const char *const	VALUE_COMPRESS_HILO_BYTE_UNPACK

Detailed Description

A bunch of utility functions.

Member Typedef Documentation

◆ CompressionOption

using libCZI::Utils::CompressionOption = std::pair<libCZI::CompressionMode, std::shared_ptr<libCZI::ICompressParameters> >

Define a type for compression options. It is a pair where one parameter is compression mode and the others are compression parameters.

Member Function Documentation

◆ CalcMd5SumHash() [1/2]

static int libCZI::Utils::CalcMd5SumHash	(	const void *	ptrData,
		size_t	sizeData,
		std::uint8_t *	ptrHash,
		int	hashSize
	)

static

Calculates the MD5SUM hash for the specified data.

Parameters

[in]	ptrData	Pointer to the data (for which to calculate the MD5SUM-hash).
[in]	sizeData	The size of the data (pointed to by ptrData).
[in,out]	ptrHash	Pointer to the hash-code result. The result will be of size 16 bytes.
	hashSize	Size of the hash-code result pointed to by `ptrHash`. We need 16 bytes.

Returns: The count of bytes that were written to in ptrHash as the MD5SUM-hash (always 16).

◆ CalcMd5SumHash() [2/2]

static int libCZI::Utils::CalcMd5SumHash	(	libCZI::IBitmapData *	bm,
		std::uint8_t *	ptrHash,
		int	hashSize
	)

static

Calculates the MD5SUM hash for the pixels in the specified bitmap.

Parameters

[in]	bm	The bitmap.
[in,out]	ptrHash	Pointer to the hash-code result. The result will be of size 16 bytes.
	hashSize	Size of the hash-code result pointed to by `ptrHash`. We need 16 bytes.

Returns: The count of bytes that were written to in ptrHash as the MD5SUM-hash (always 16).

◆ CalcSplineDataFromPoints()

static std::vector<libCZI::IDisplaySettings::SplineData> libCZI::Utils::CalcSplineDataFromPoints	(	int	pointCnt,
		std::function< std::tuple< double, double >(int idx)>	getPoint
	)

static

Calculates the spline coefficients from a list of control points.

Parameters

pointCnt	Number of control points.
getPoint	A functor which will be used to retrieve the control point's coordinates.

Returns: The calculated spline data from the specified control points.

◆ CalcZoom() [1/2]

static float libCZI::Utils::CalcZoom	(	const libCZI::IntRect &	logicalRect,
		const libCZI::IntSize &	physicalSize
	)

inlinestatic

Calculate a zoom-factor from the physical- and logical size.

Remarks: This calculation not really well-defined.

Parameters

logicalRect	The logical rectangle.
physicalSize	Physical size.

Returns: The calculated zoom.

◆ CalcZoom() [2/2]

static float libCZI::Utils::CalcZoom	(	const libCZI::IntSize &	logicalSize,
		const libCZI::IntSize &	physicalSize
	)

inlinestatic

Calculate a zoom-factor from the physical- and logical size.

Remarks: This calculation not really well-defined.

Parameters

logicalSize	The logical size.
physicalSize	The physical size.

Returns: The calculated zoom.

◆ CharToDimension()

static libCZI::DimensionIndex libCZI::Utils::CharToDimension ( char c )

static

Convert the specified single character to the corresponding dimension enum. The single character may be given uppercase or lowercase. In case that no corresponding dimension enum exists, DimensionIndex::invalid is returned.

Parameters

c	The "single char representation" of a dimension.

Returns: A enum value representing the specified dimension if it exists, DimensionIndex::invalid otherwise.

◆ Compare()

static int libCZI::Utils::Compare	(	const IDimCoordinate *	a,
		const IDimCoordinate *	b
	)

static

Compares two coordinate-objects to determine their relative ordering. The algorithm employed is: we check for all coordinates which are marked valid in a or b (in the order of the numerical value or the enum)...

coordinateA(dim) is valid and coordinateB(dim) is invalid -> a > b
coordinateA(dim) is invalid and coordinateB(dim) is valid -> a < b
if both are valid, then the coordinate-values are determined and compared

Parameters

a	First coordinate to be compared.
b	Second coordinate to be compared.

Returns: Negative if 'a' is less than 'b', 0 if they are equal, or positive if it is greater.

◆ CompressionModeFromRawCompressionIdentifier()

static libCZI::CompressionMode libCZI::Utils::CompressionModeFromRawCompressionIdentifier ( std::int32_t m )

static

Convert the "raw compression identifier" to an enumeration. Note that all unknown values (unknown to libCZI) are mapped to CompressionMode::Invalid. Compression mode from raw compression identifier

Parameters

m	The raw compression identifier to convert.

Returns: The corresponding compression enumeration.

◆ CompressionModeToCompressionIdentifier()

static std::int32_t libCZI::Utils::CompressionModeToCompressionIdentifier ( libCZI::CompressionMode mode )

static

Convert the specified compression enumeration to the corresponding raw compression identifier.

Parameters

mode	The compression enumeration mode.

Returns: The corresponding raw compression identifier.

◆ CompressionModeToInformalString()

static const char* libCZI::Utils::CompressionModeToInformalString ( libCZI::CompressionMode compressionMode )

static

Retrieves an informal string representing the specified compression mode. The string representation returned here is suitable for use with the compression-options parsing function (ParseCompressionOptions).

Parameters

compressionMode The compression mode.

Returns: A pointer to a static string. Will always be non-null (even in case of an invalid value for compressionMode.

◆ Create16BitLookUpTableFromGamma()

static std::vector<std::uint16_t> libCZI::Utils::Create16BitLookUpTableFromGamma	(	int	tableElementCnt,
		float	blackPoint,
		float	whitePoint,
		float	gamma
	)

static

Creates 16-bit look-up table from the specified gamma value. An exponential with the specified gamma is sampled between blackPoint and whitePoint (i. e. points left of blackPoint are set to 0 and right of whitePoint are set to 1).

Parameters

tableElementCnt	Number of points to sample - the result will have as many samples as specified here.
blackPoint	The black point.
whitePoint	The white point.
gamma	The gamma.

Returns: The new 16-bit look up table generated from the gamma value. The number is elements is as specified by tableElementCount.

◆ Create8BitLookUpTableFromGamma()

static std::vector<std::uint8_t> libCZI::Utils::Create8BitLookUpTableFromGamma	(	int	tableElementCnt,
		float	blackPoint,
		float	whitePoint,
		float	gamma
	)

static

Creates 8-bit look-up table from the specified gamma value. An exponential with the specified gamma is sampled between blackPoint and whitePoint (i. e. points left of blackPoint are set to 0 and right of whitePoint are set to 1).

Parameters

tableElementCnt	Number of points to sample - the result will have as many samples as specified here.
blackPoint	The black point.
whitePoint	The white point.
gamma	The gamma.

Returns: The new 8-bit look up table generated from the gamma value. The number is elements is as specified by tableElementCount.

◆ Create8BitLookUpTableFromSplines()

static std::vector<std::uint8_t> libCZI::Utils::Create8BitLookUpTableFromSplines	(	int	tableElementCnt,
		float	blackPoint,
		float	whitePoint,
		const std::vector< libCZI::IDisplaySettings::SplineData > &	splineData
	)

static

Creates an 8-bit look-up table from the specified splines. A spline is sampled between blackPoint and whitePoint (i. e. points left of blackPoint are set to 0 and right of whitePoint are set to 1).

Parameters

tableElementCnt	Number of points to sample - the result will have as many samples as specified here.
blackPoint	The black point.
whitePoint	The white point.
splineData	Information describing the spline.

Returns: The new 8-bit look up table generated from the spline. The number is elements is as specified by tableElementCount.

◆ CreateSubBlockMetadata()

static std::shared_ptr<ICziMetadataBuilder> libCZI::Utils::CreateSubBlockMetadata ( const std::function< bool(int, std::tuple< std::string, std::string > &)> & tagsEnum = nullptr )

static

Creates a metadata-builder object suitable for generating sub-block metadata. It generates XML in the form

<METADATA>
    <Tags>
        <StageXPosition>-8906.346</StageXPosition>
        <StageYPosition>-648.51</StageYPosition>
    </Tags>
</METADATA>

The specified function can be used to give a set of nodename-value-pairs - which are added under the "Tags"-node.

Parameters

[in] tagsEnum Optionally, a function which is called to provide a pair of strings, where the first element gives the node-name and the second the value. The first integer argument counts the number of calls made to this function. The function has to return true, if it provided valid information and it will be called again. If it returns false, it will not be called again.

Returns: The newly created metadata-builder object.

◆ DimBoundsToString()

static std::string libCZI::Utils::DimBoundsToString ( const libCZI::IDimBounds * bounds )

static

Get a string representation of the specified bounds.

Parameters

bounds The bounds.

Returns: A string representation of the specified bounds.

◆ DimCoordinateToString()

static std::string libCZI::Utils::DimCoordinateToString ( const libCZI::IDimCoordinate * coord )

static

Get a string representation of the specified coordinate.

Parameters

coord The coordinate.

Returns: A string representation of the specified coordinate.

◆ DimensionToChar()

static char libCZI::Utils::DimensionToChar ( libCZI::DimensionIndex dim )

static

Convert the specified dimension enum to the corresponding "single char representation". The returned character will be uppercase. If the specified dimension enum cannot be converted, '?' is returned.

Parameters

dim	The dimension enum.

Returns: A character representing the specified dimension.

◆ EnumAllCoordinates()

static bool libCZI::Utils::EnumAllCoordinates	(	const libCZI::CDimBounds &	bounds,
		const std::function< bool(std::uint64_t, const libCZI::CDimCoordinate &coord)> &	func
	)

static

Enumerate all coordinates "contained" in the specified bounds. The specified function is called with all valid coordinates (which lie inside the bounds). The first argument to the function is a counter which increments for each generated coordinate (and starts with 0). If the function returns false, the enumeration is ended, and this function returns immediately with false.

Parameters

bounds	The bounds.
func	The function to be called with the generated coordinates.

Returns: True if the enumeration completed, false if it was cancelled (by returning false from the callback).

◆ FillBitmap()

static void libCZI::Utils::FillBitmap	(	libCZI::IBitmapData *	bm,
		const libCZI::RgbFloatColor &	floatColor
	)

static

Fill the specified bitmap with the specified color.

Parameters

[in,out]	bm	The bitmap.
	floatColor	The color.

◆ GetBytesPerPixel()

static std::uint8_t libCZI::Utils::GetBytesPerPixel ( libCZI::PixelType pixelType )

static

Gets the number of bytes which represent a pixel. In case of an invalid pixelType-argument, and invalid_argument is thrown.

Parameters

pixelType The pixel type.

Returns: The number of bytes which represent a pixel.

◆ HasSameDimensions()

static bool libCZI::Utils::HasSameDimensions	(	const IDimCoordinate *	a,
		const IDimCoordinate *	b
	)

static

Test whether the two specified coordinates have the same set of valid dimensions.

Parameters

a	The first coordinate-object to compare.
b	The second coordinate-object to compare.

Returns: True if the two coordinates have the same set of valid dimensions, false otherwise.

◆ IndexSetFromString()

static std::shared_ptr<libCZI::IIndexSet> libCZI::Utils::IndexSetFromString ( const std::wstring & s )

static

Create an index-set object from a string representation. The string is a list of intervals, separated by comma (','). It can be of the form "5", "17", "3-5", "-3-5". The string "inf" (meaning 'infinity') is recognized in order to express "all numbers up to" or "all numbers after" , e. g. "-inf-4" or "5-inf". In case of an invalid string, an LibCZIStringParseException exception is thrown.

Parameters

s	The string to convert to an index-set object.

Returns: A newly create std::shared_ptr<libCZI::IIndexSet> object.

◆ IsValidMindex()

static bool libCZI::Utils::IsValidMindex ( int mIndex )

inlinestatic

Determine if the specified value is a valid m-index.

Parameters

mIndex The m-index to check.

Returns: True if the value is a valid m-index, false if not.

◆ NearestNeighborResize() [1/2]

static std::shared_ptr<libCZI::IBitmapData > libCZI::Utils::NearestNeighborResize	(	libCZI::IBitmapData *	bmSrc,
		int	dstWidth,
		int	dstHeight
	)

static

Resize the specified bitmap to the specified width and height. This method employs a nearest-neighbor-scaling algorihm.

Parameters

[in]	bmSrc	The source bitmap.
	dstWidth	Width of the destination.
	dstHeight	Height of the destination.

Returns: A std::shared_ptr<libCZI::IBitmapData > containing the scaled bitmap.

◆ NearestNeighborResize() [2/2]

static std::shared_ptr<libCZI::IBitmapData > libCZI::Utils::NearestNeighborResize	(	libCZI::IBitmapData *	bmSrc,
		int	dstWidth,
		int	dstHeight,
		const DblRect &	roiSrc,
		const DblRect &	roiDest
	)

static

Resize a ROI from the specified bitmap to the specified width and height. This method employs a nearest-neighbor-scaling algorihm.

Parameters

[in]	bmSrc	The source bitmap.
	dstWidth	Width of the destination.
	dstHeight	Height of the destination.
	roiSrc	The ROI (in the source bitmap).
	roiDest	The ROI (in the destination bitmap)

Returns: A std::shared_ptr<libCZI::IBitmapData >

◆ ParseCompressionOptions()

static CompressionOption libCZI::Utils::ParseCompressionOptions ( const std::string & options )

static

Parse specified string as a compression option and return the compression option, which is a pair of compression mode and the compression parameters. The format of the string representation is: "<compression_method>: key=value; ...". It starts with the name of the compression-method, followed by a colon, then followed by a list of key-value pairs which are separated by a semicolon. Examples: "zstd0:ExplicitLevel=3", "zstd1:ExplicitLevel=2;PreProcess=HiLoByteUnpack" If parsing fails an excpetion of type "Logic_error" is thrown.

◆ PixelTypeToInformalString()

static const char* libCZI::Utils::PixelTypeToInformalString ( libCZI::PixelType pixeltype )

static

Retrieves an informal string representing the specified pixeltype.

Parameters

pixeltype The pixel-type.

Returns: A pointer to a static string. Will always be non-null (even in case of an invalid value for pixeltype.

◆ StringToDimCoordinate()

static bool libCZI::Utils::StringToDimCoordinate	(	const char *	sz,
		libCZI::CDimCoordinate *	coord
	)

static

Convert the specified string into a dimension-coordinate instance.

Parameters

	sz	The string to convert.
[out]	coord	If non-null and if the parsing was successful, the information will be put here.

Returns: True if the string parsed successfully, false otherwise.

◆ TryDeterminePixelTypeForChannel()

static libCZI::PixelType libCZI::Utils::TryDeterminePixelTypeForChannel	(	libCZI::ISubBlockRepository *	repository,
		int	channelIdx
	)

static

Try to determine the pixel type for channel. This is done by looking at an (arbitrary) subblock within the specified channel. There are cases where this does not yield a result - e. g. if there is no subblock present with the specified channel-index.

Parameters

[in]	repository	The CZI-document.
	channelIdx	The channel index.

Returns: The pixeltype if it can be determined. If it cannot be determined reliably (e.g. there is no subblock with the specified channel-index), then PixelType::Invalid is returned.

Member Data Documentation

◆ KEY_COMPRESS_EXPLICIT_LEVEL

const char* const libCZI::Utils::KEY_COMPRESS_EXPLICIT_LEVEL

static

ZStdX compression level parameter. This parameter is used both with ZStd0 and ZStd1. Example: "zstd0:ExplicitLevel=2" or "zstd1:ExplicitLevel=2"

◆ KEY_COMPRESS_PRE_PROCESS

const char* const libCZI::Utils::KEY_COMPRESS_PRE_PROCESS

static

ZStd1 compression preprocessing parameter. The valid value is "HiLoByteUnpack" The parameter is valid only for ZStd1 compression and ignored in case of ZStd0. Example: "zstd1:ExplicitLevel=2;PreProcess=HiLoByteUnpack" and ignored in case of "zstd0:ExplicitLevel=2;PreProcess=HiLoByteUnpack"

◆ VALUE_COMPRESS_HILO_BYTE_UNPACK

const char* const libCZI::Utils::VALUE_COMPRESS_HILO_BYTE_UNPACK

static

The valid (expected) value in case of Pre-Processing. The flag indicates whether the "HiLoByteUnpack" is enabled or not. The parameter and the value are valid only for 16- and 48-bit pixel images. For all other pixel types the parameter and the value are ignored. Example: - Pixel type Bgr8 : Ignored --> "zstd1:ExplicitLevel=2;PreProcess=HiLoByteUnpack"

Pixel type Bgr24 : Ignored --> "zstd1:ExplicitLevel=2;PreProcess=HiLoByteUnpack"
Pixel type Gray16: Used --> "zstd1:ExplicitLevel=2;PreProcess=HiLoByteUnpack"
Pixel type Gray48: Used --> "zstd1:ExplicitLevel=2;PreProcess=HiLoByteUnpack"

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

libCZI/libCZI_Utilities.h

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ CompressionOption

Member Function Documentation

◆ CalcMd5SumHash() [1/2]

◆ CalcMd5SumHash() [2/2]

◆ CalcSplineDataFromPoints()

◆ CalcZoom() [1/2]

◆ CalcZoom() [2/2]

◆ CharToDimension()

◆ Compare()

◆ CompressionModeFromRawCompressionIdentifier()

◆ CompressionModeToCompressionIdentifier()

◆ CompressionModeToInformalString()

◆ Create16BitLookUpTableFromGamma()

◆ Create8BitLookUpTableFromGamma()

◆ Create8BitLookUpTableFromSplines()

◆ CreateSubBlockMetadata()

◆ DimBoundsToString()

◆ DimCoordinateToString()

◆ DimensionToChar()

◆ EnumAllCoordinates()

◆ FillBitmap()

◆ GetBytesPerPixel()

◆ HasSameDimensions()

◆ IndexSetFromString()

◆ IsValidMindex()

◆ NearestNeighborResize() [1/2]

◆ NearestNeighborResize() [2/2]

◆ ParseCompressionOptions()

◆ PixelTypeToInformalString()

◆ StringToDimCoordinate()

◆ TryDeterminePixelTypeForChannel()

Member Data Documentation

◆ KEY_COMPRESS_EXPLICIT_LEVEL

◆ KEY_COMPRESS_PRE_PROCESS

◆ VALUE_COMPRESS_HILO_BYTE_UNPACK