Class Utils

Class Utils#

Defined in File libCZI_Utilities.h

Class Documentation#

class Utils#

A bunch of utility functions.

Public Types

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

Public Static Functions

static char DimensionToChar(libCZI::DimensionIndex dim)#

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.

static libCZI::DimensionIndex CharToDimension(char c)#

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.

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

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

Parameters:

bm – [in] The bitmap.
ptrHash – [inout] 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).

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

Calculates the MD5SUM hash for the specified data.

Parameters:

ptrData – [in] Pointer to the data (for which to calculate the MD5SUM-hash).
sizeData – [in] The size of the data (pointed to by ptrData).
ptrHash – [inout] 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).

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

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.

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

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.

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

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.

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

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.

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

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

Parameters:

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

Returns:

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

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

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

Parameters:

bmSrc – [in] 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 >

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

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

Remark

This calculation not really well-defined.

Parameters:

logicalRect – The logical rectangle.
physicalSize – Physical size.

Returns:

The calculated zoom.

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

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

Remark

This calculation not really well-defined.

Parameters:

logicalSize – The logical size.
physicalSize – The physical size.

Returns:

The calculated zoom.

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

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.

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

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.

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

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.

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

Get a string representation of the specified coordinate.

Parameters:: coord – The coordinate.
Returns:: A string representation of the specified coordinate.

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

Convert the specified string into a dimension-coordinate instance.

Parameters:

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

Returns:

True if the string parsed successfully, false otherwise.

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

Get a string representation of the specified bounds.

Parameters:: bounds – The bounds.
Returns:: A string representation of the specified bounds.

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

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.

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

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:

repository – [in] 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.

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

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.

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

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.

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

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:: tagsEnum – [in] 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.

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

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

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

Fill the specified bitmap with the specified color.

Parameters:

bm – [inout] The bitmap.
floatColor – The color.

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

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.

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

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

Parameters:: mode – The compression enumeration mode.
Returns:: The corresponding raw compression identifier.

static inline bool IsValidMindex(int mIndex)#

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.

static CompressionOption ParseCompressionOptions(const std::string &options)#: 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.

static std::string ConvertToUtf8(const std::wstring &wide_string)#

Converts the specified wide string into UTF8-encoding.

Parameters:: wide_string – The wide string to be converted.
Returns:: The given data converted to an UTF8-encoding.

Public Static Attributes

static const char *const KEY_COMPRESS_EXPLICIT_LEVEL#: ZStdX compression level parameter. This parameter is used both with ZStd0 and ZStd1. Example: “zstd0:ExplicitLevel=2” or “zstd1:ExplicitLevel=2”

static const char *const KEY_COMPRESS_PRE_PROCESS#: 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”

static const char *const VALUE_COMPRESS_HILO_BYTE_UNPACK#

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”

Class Utils

Contents

Class Utils#

Class Documentation#