ml::BitImage Class Reference

Class to manage a binary image. More...

#include <mlBitImage.h>

Inheritance diagram for ml::BitImage:

List of all members.

Public Types

Operation modes to write bit images into normal subimages.

enum OperationModes {
SET_MODE = 0, OR_MODE, AND_MODE, XOR_MODE,
CLEAR_MODE, NUM_MODES
}

Public Member Functions

Construction, Destruction, Assignment

BitImage (bool useExceptions=false)

Constructor.

BitImage (const ImageVector &ext, bool useExceptions=false)

Convenience constructor.

MLTOOLS_EXPORT BitImage (const BitImage &bitImg)

Copy constructor, copies bitImg to this instance.

virtual MLTOOLS_EXPORT ~BitImage ()

Destructor. Never throws controlled diagnostic exceptions.

void reset ()

Make image empty and restore default construction state with disabled exceptions.

bool useExceptionHandling () const

Return true if exception handling is on, otherwise return false.

MLTOOLS_EXPORT void useExceptionHandling (bool useExceptions)

Pass true to enable exception handling, false to disable it.

MLTOOLS_EXPORT const BitImage & operator= (const BitImage &bitImg)

Assignment operator.

Extents

bool setExtent (const ImageVector &ext)

Resize image.

const ImageVector & getExtent () const

Return image size. Never throws controlled diagnostic exceptions.

const SubImageBox getBoxFromImageExtent () const

Return a SubImageBox representing the image extent of the BitImage.

const SubImageBox & getSourceBox () const

Returns the original placement of the bit image corresponding to a potential image the bit image is created from.

void setSourceBox (const SubImageBox &box)

Sets the original placement of the bit image corresponding to a potential image the bit image is created from.

Miscellaneous

const ImageVector & getStrides () const

Return strides for binary pixels.

MLint getCursorBitIndex () const

Return strides for words. Never throws controlled diagnostic exceptions.

bool isEmpty () const

Returns true if image is empty. Never throws controlled diagnostic exceptions.

void clear (bool val)

Clears/sets all bits in the image. Never throws controlled diagnostic exceptions.

Direct access to image content

bool operator[] (const ImageVector &pos) const

Constant vector index read access to voxel value at position pos.

void setValue (const ImageVector &pos, const bool v)

Set bit at position pos to value v.

void set (const ImageVector &pos)

Set bit at position pos optimized for all extents of a bit image.

void clear (const ImageVector &pos)

Clear bit at position pos optimized for all extents of a bit image.

void toggle (const ImageVector &pos)

Toggle bit at position pos.

bool isSet (const ImageVector &pos) const

Return true if bit at position pos is set, otherwise false.

bool isInRange (const ImageVector &p) const

Test for ImageVector coordinates in valid range.

bool isInRange (const Vector6 &p) const

Test for Vector6 coordinates in valid range.

General cursor management.

void setCursorPosition (const ImageVector &pos)

Set cursor position to position pos.

const ImageVector & getCursorPosition () const

Return current cursor position. Never throws controlled diagnostic exceptions.

bool getCursorValue () const

Return true if bit under cursor is true, otherwise false. Never throws controlled diagnostic exceptions.

void setCursorValue (const bool val)

Sets the bit under the cursor to 1 if true is passed as val, otherwise 0 is set. Never throws controlled diagnostic exceptions.

void setCursorValue ()

Sets the bit under the cursor to 1. Never throws controlled diagnostic exceptions.

void toggleCursorValue ()

Toggles the bit under the cursor. Never throws controlled diagnostic exceptions.

void clearCursorValue ()

Clears the bit under the cursor to 0. Never throws controlled diagnostic exceptions.

MLuint32 getCursorWordIndex () const

Return index to word in image to which the cursor points. Never throws controlled diagnostic exceptions.

ML_BIT_IMG_DATA_TYPE getCursorWord () const

Return content of word in image to which the cursor points.

ML_BIT_IMG_DATA_TYPE getCursorBitMask () const

Return the bit mask specifying the bit in the cursor word. Never throws controlled diagnostic exceptions.

Cursor movements forward in X/Y/Z/C/T/U direction. Throws MLErrorCode exceptions when going to invalid position if exception handling is enabled, otherwise state becomes instable.

void moveCursorX ()

void moveCursorY ()

void moveCursorZ ()

void moveCursorC ()

void moveCursorT ()

void moveCursorU ()

Cursor movements backward in X/Y/Z/C/T/U direction. Throws MLErrorCode exceptions when going to invalid position if exception handling is enabled, otherwise state becomes instable.

void reverseMoveCursorX ()

void reverseMoveCursorY ()

void reverseMoveCursorZ ()

void reverseMoveCursorC ()

void reverseMoveCursorT ()

void reverseMoveCursorU ()

Linear image traversal.

MLTOOLS_EXPORT void resetCursor ()

Set cursor and dependent members to default position (0,0,0,0,0,0).

MLTOOLS_EXPORT bool moveCursorXWrapAround ()

Special cursor move: Increment x coordinate of cursor.

Miscellaneous

MLTOOLS_EXPORT void getStatistics (MLuint32 *numBits, MLuint32 *numSetBits, MLuint32 *numClearedBits)

Returns some basic statistical values.

MLTOOLS_EXPORT BitImage * getDownScaledBitImage (const ImageVector &scales) const

Create a down scaled mlBitImage from this.

MLTOOLS_EXPORT long updateBitImageFromVolume (const void *data, const MLDataType dType, const SubImageBox &origBox, const double minVal, const double maxVal, const unsigned char addBorderPixels=0)

Scan volume given by data and origBox and filter all values through the interval given by [minVal, maxVal).

MLTOOLS_EXPORT SubImageBox calculateBoundingBox (bool val=true)

Calculates the bounding box of all bits of value val (default is true).

MLTOOLS_EXPORT void copyToBitImage (BitImage &dstBitImg, OperationModes mode=SET_MODE, const SubImageBox &box=SubImageBox(), const ImageVector &offset=ImageVector(0))

Copy all bits from the overlapping regions from box and *this to the position box.v1+offset to dstBitImg.

MLTOOLS_EXPORT BitImage * getSubBitImageByMask (bool val)

Calculates the bounding box of all bits of value val and returns a new BitImage containing exactly that area.

Interactions with subimages and subimage boxes

MLTOOLS_EXPORT void fill (const SubImageBox &box, const bool value)

Fill the area given by box in the bit image with value value.

MLTOOLS_EXPORT void invert (const SubImageBox &box)

Toggle the area given by box in the bit image.

MLTOOLS_EXPORT void copyToSubImage (SubImage &outSubImg, const long double bkVal, const long double fgVal, const OperationModes mode=SET_MODE) const

Copy area from the bit image into the subimage given by outSubImg.

MLTOOLS_EXPORT void copyFromSubImage (SubImage &inImg, const SubImageBox &box, const ImageVector &pos, const long double intMin, const long double intMax)

Copy the area given by box from inImg to the position p of the bitImage.

Save/load bit image from file.

MLTOOLS_EXPORT bool writeToFile (const std::string &path, bool overwrite=true)

Writes bit image content into file specified by path path and return true on success and false on failure.

MLTOOLS_EXPORT MLErrorCode save (const std::string &path, bool overwrite=true)

Writes bit image content into file specified by path.

MLTOOLS_EXPORT bool readFromFile (const std::string &path)

Reads a bit image from file specified by path and returns true on success, false on error.

MLTOOLS_EXPORT MLErrorCode load (const std::string &path)

Read bit image from file specified by path and returns ML_RESULT_OK success or another error code in case of failure.

Deprecated methods.

bool setExt (const ImageVector &ext)

const ImageVector & getExt () const

SubImageBox getBoxFromImgExt () const

MLint getCursorBitIdx () const

void copyToSubImg (SubImage &outSubImg, const long double bkVal, const long double fgVal, const OperationModes mode=SET_MODE) const

void copyFromSubImg (SubImage &inImg, const SubImageBox &box, const ImageVector &pos, const long double intMin, const long double intMax)

SubImageBox calcBoundingBox (bool val=true)

void setCursorPos (const ImageVector &pos)

const ImageVector & getCursorPos () const

void moveFX ()

void moveFY ()

void moveFZ ()

void moveFC ()

void moveFT ()

void moveFU ()

void moveBX ()

void moveBY ()

void moveBZ ()

void moveBC ()

void moveBT ()

void moveBU ()

bool moveCursorFXLF ()

Static Public Member Functions

static MLTOOLS_EXPORT MLuint32 selfTest ()

Starts a self test of the mlBitImage class.

Detailed Description

Class to manage a binary image.

Definition at line 59 of file mlBitImage.h.

Member Enumeration Documentation

enum ml::BitImage::OperationModes

Enumerator:

SET_MODE	values are written/replaced into target values.
OR_MODE	values are ored to target values.
AND_MODE	values are anded to/with target values.
XOR_MODE	values are xored to/with target values.
CLEAR_MODE	set bits in values are cleared in target values.
NUM_MODES	number of OperationMode enums.

Definition at line 65 of file mlBitImage.h.

Constructor & Destructor Documentation

ml::BitImage::BitImage ( bool useExceptions = false ) [inline]

Constructor.

Creates an empty bit image (extents (0,0,0,0,0,0)). If useExceptions is passed as true then all errors in bit image usage throw exceptions instead of causing damage. Otherwise no checks are performed which will damage the program usually.

Definition at line 81 of file mlBitImage.h.

References ml::ImageVector.

ml::BitImage::BitImage	(	const ImageVector &	ext,
		bool	useExceptions = `false`
	)			`[inline]`

Convenience constructor.

Create a bit image with extents given by ext. If useExceptions is passed as true then all errors in bit image usage throw exceptions instead of causing damage. Otherwise no checks are performed which will damage the program usually. Image contents image will be undefined after creation.

Definition at line 88 of file mlBitImage.h.

MLTOOLS_EXPORT ml::BitImage::BitImage ( const BitImage & bitImg )

Copy constructor, copies bitImg to this instance.

If copying fails due to lack of memory then *this is left in reset state and ML_NO_MEMORY is thrown; without activated exception handling the program runs in an undefined state.

virtual MLTOOLS_EXPORT ml::BitImage::~BitImage ( ) [inline, virtual]

Destructor. Never throws controlled diagnostic exceptions.

Definition at line 98 of file mlBitImage.h.

Member Function Documentation

SubImageBox ml::BitImage::calcBoundingBox ( bool val = true ) [inline]

Deprecated:: Use calculateBoundingBox() instead.

Definition at line 472 of file mlBitImage.h.

MLTOOLS_EXPORT SubImageBox ml::BitImage::calculateBoundingBox ( bool val = true )

Calculates the bounding box of all bits of value val (default is true).

An empty SubImageBox is returned if no bits of value val are found.

void ml::BitImage::clear ( const ImageVector & pos ) [inline]

Clear bit at position pos optimized for all extents of a bit image.

If exceptions are on and pos is out of range then the error code ML_OUT_OF_RANGE is thrown. Otherwise program state becomes undefined.

Definition at line 193 of file mlBitImage.h.

References ML_BIT_IMG_ALL_BITS, ML_BIT_IMG_INDEX_BITS, ML_BIT_IMG_LOW_BIT, and ML_BIT_IMG_SHIFT.

void ml::BitImage::clear ( bool val ) [inline]

Clears/sets all bits in the image. Never throws controlled diagnostic exceptions.

Definition at line 168 of file mlBitImage.h.

void ml::BitImage::clearCursorValue ( ) [inline]

Clears the bit under the cursor to 0. Never throws controlled diagnostic exceptions.

Definition at line 238 of file mlBitImage.h.

References ML_BIT_IMG_ALL_BITS, ML_BIT_IMG_INDEX_BITS, ML_BIT_IMG_LOW_BIT, and ML_BIT_IMG_SHIFT.

MLTOOLS_EXPORT void ml::BitImage::copyFromSubImage	(	SubImage &	inImg,
		const SubImageBox &	box,
		const ImageVector &	pos,
		const long double	intMin,
		const long double	intMax
	)

Copy the area given by box from inImg to the position p of the bitImage.

The box position (0,0,0,0,0,0) is considered the first valid voxel in inImg. Before copying the region to copy is limited to valid areas. All values >= intMin and < intMax are set to true all other values are set to false.

void ml::BitImage::copyFromSubImg	(	SubImage &	inImg,
		const SubImageBox &	box,
		const ImageVector &	pos,
		const long double	intMin,
		const long double	intMax
	)			`[inline]`

Deprecated:: Use copyFromSubImage() instead.

Definition at line 464 of file mlBitImage.h.

MLTOOLS_EXPORT void ml::BitImage::copyToBitImage	(	BitImage &	dstBitImg,
		OperationModes	mode = `SET_MODE`,
		const SubImageBox &	box = `SubImageBox()`,
		const ImageVector &	offset = `ImageVector(0)`
	)

Copy all bits from the overlapping regions from box and *this to the position box.v1+offset to dstBitImg.

Only valid regions in this are read and copied to dstBitImg. offset defaults to the 0 vector. If box is empty (the default) then the full *this image is copied to position offset as far as target pixels are inside dstBitImg. mode (which defaults to SET_MODE) determines the way how bits in the target image are modified by the copy operation.

MLTOOLS_EXPORT void ml::BitImage::copyToSubImage	(	SubImage &	outSubImg,
		const long double	bkVal,
		const long double	fgVal,
		const OperationModes	mode = `SET_MODE`
	)			const

Copy area from the bit image into the subimage given by outSubImg.

Note that only valid regions of the bit image are read - if outSubImg reaches outside the bit image the corresponding areas are not read, i.e. these regions are left undefined in outSubImg. bkVal is written for false bits, fgVal for true bits. mode describes how the values are written into the voxel values of outSubImage; default is BitImage::SET_MODE. On non integer data types all modes not equal to BitImage::SET_MODE cast the values to MLint64, apply the operations and cast back the results to the data type of outSubImg. Note: bkVal and fgVal are always cast to the data type of outSubImg.

void ml::BitImage::copyToSubImg	(	SubImage &	outSubImg,
		const long double	bkVal,
		const long double	fgVal,
		const OperationModes	mode = `SET_MODE`
	)			const `[inline]`

Deprecated:: Use copyToSubImage() instead.

Definition at line 457 of file mlBitImage.h.

MLTOOLS_EXPORT void ml::BitImage::fill	(	const SubImageBox &	box,
		const bool	value
	)

Fill the area given by box in the bit image with value value.

If area reaches outside the image then it's automatically clamped to a valid region.

const SubImageBox ml::BitImage::getBoxFromImageExtent ( ) const [inline]

Return a SubImageBox representing the image extent of the BitImage.

Definition at line 138 of file mlBitImage.h.

SubImageBox ml::BitImage::getBoxFromImgExt ( ) const [inline]

Deprecated:: Use getBoxFromImageExtent() instead.

Definition at line 449 of file mlBitImage.h.

MLint ml::BitImage::getCursorBitIdx ( ) const [inline]

Deprecated:: Use getCursorBitIndex() instead.

Definition at line 453 of file mlBitImage.h.

MLint ml::BitImage::getCursorBitIndex ( ) const [inline]

Return strides for words. Never throws controlled diagnostic exceptions.

Definition at line 162 of file mlBitImage.h.

ML_BIT_IMG_DATA_TYPE ml::BitImage::getCursorBitMask ( ) const [inline]

Return the bit mask specifying the bit in the cursor word. Never throws controlled diagnostic exceptions.

Definition at line 248 of file mlBitImage.h.

References ML_BIT_IMG_INDEX_BITS, and ML_BIT_IMG_LOW_BIT.

const ImageVector& ml::BitImage::getCursorPos ( ) const [inline]

Deprecated:: Use getCursorPosition() instead.

Definition at line 480 of file mlBitImage.h.

const ImageVector& ml::BitImage::getCursorPosition ( ) const [inline]

Return current cursor position. Never throws controlled diagnostic exceptions.

Definition at line 223 of file mlBitImage.h.

Referenced by ml::TVirtualVolume< DATATYPE >::copyMaskToSubImage().

bool ml::BitImage::getCursorValue ( ) const [inline]

Return true if bit under cursor is true, otherwise false. Never throws controlled diagnostic exceptions.

Definition at line 226 of file mlBitImage.h.

References ML_BIT_IMG_INDEX_BITS, ML_BIT_IMG_LOW_BIT, and ML_BIT_IMG_SHIFT.

Referenced by ml::TVirtualVolume< DATATYPE >::copyMaskToSubImage().

ML_BIT_IMG_DATA_TYPE ml::BitImage::getCursorWord ( ) const [inline]

Return content of word in image to which the cursor points.

Bits of positions outside the image contain undefined values. Never throws controlled diagnostic exceptions.

Definition at line 245 of file mlBitImage.h.

References ML_BIT_IMG_SHIFT.

MLuint32 ml::BitImage::getCursorWordIndex ( ) const [inline]

Return index to word in image to which the cursor points. Never throws controlled diagnostic exceptions.

Definition at line 241 of file mlBitImage.h.

References ML_BIT_IMG_SHIFT.

MLTOOLS_EXPORT BitImage* ml::BitImage::getDownScaledBitImage ( const ImageVector & scales ) const

Create a down scaled mlBitImage from this.

Each extent in all dimensions is scaled down by the corresponding component in scales and increased by 1. A component wise multiplication of a coordinate of the pixel of the result with scales is the original coordinate in the bit image. E.g. (3,1,2,0,0) in the down scaled image comes from position (6,4,2,0,0,0) if scales is (2,4,1,1,1,1). NULL is returned if the original image is empty or the allocation of the result image fails. The user must delete the result after usage.

const ImageVector& ml::BitImage::getExt ( ) const [inline]

Deprecated:: Use getExtent() instead.

Definition at line 445 of file mlBitImage.h.

const ImageVector& ml::BitImage::getExtent ( ) const [inline]

Return image size. Never throws controlled diagnostic exceptions.

Definition at line 135 of file mlBitImage.h.

Referenced by ml::TVirtualVolume< DATATYPE >::copyMaskToSubImage().

const SubImageBox& ml::BitImage::getSourceBox ( ) const [inline]

Returns the original placement of the bit image corresponding to a potential image the bit image is created from.

Default is always empty if not set by setSourceBox() or updateBitImageFromVolume() or by instance assignment/loading. Never throws controlled diagnostic exceptions.

Definition at line 144 of file mlBitImage.h.

MLTOOLS_EXPORT void ml::BitImage::getStatistics	(	MLuint32 *	numBits,
		MLuint32 *	numSetBits,
		MLuint32 *	numClearedBits
	)

Returns some basic statistical values.

Passed NULL pointers are not set. Not const but it doesn't modify the instance really.

const ImageVector& ml::BitImage::getStrides ( ) const [inline]

Return strides for binary pixels.

Must be divided by 32 (>> ML_BIT_IMG_SHIFT) to get word index of bit. Never throws controlled diagnostic exceptions.

Definition at line 159 of file mlBitImage.h.

MLTOOLS_EXPORT BitImage* ml::BitImage::getSubBitImageByMask ( bool val )

Calculates the bounding box of all bits of value val and returns a new BitImage containing exactly that area.

A NULL pointer is returned on failure or if no bits of value val are found.

MLTOOLS_EXPORT void ml::BitImage::invert ( const SubImageBox & box )

Toggle the area given by box in the bit image.

If area reaches outside the image then it's automatically clamped to a valid region.

bool ml::BitImage::isEmpty ( ) const [inline]

Returns true if image is empty. Never throws controlled diagnostic exceptions.

Definition at line 165 of file mlBitImage.h.

bool ml::BitImage::isInRange ( const Vector6 & p ) const [inline]

Test for Vector6 coordinates in valid range.

Only the image dimensions are tested. Never throws controlled diagnostic exceptions.

Definition at line 211 of file mlBitImage.h.

bool ml::BitImage::isInRange ( const ImageVector & p ) const [inline]

Test for ImageVector coordinates in valid range.

Only the image dimensions are tested. Never throws controlled diagnostic exceptions.

Definition at line 207 of file mlBitImage.h.

bool ml::BitImage::isSet ( const ImageVector & pos ) const [inline]

Return true if bit at position pos is set, otherwise false.

If exceptions are on and pos is out of range then the error code ML_OUT_OF_RANGE is thrown. Otherwise program state becomes undefined.

Definition at line 203 of file mlBitImage.h.

References ML_BIT_IMG_INDEX_BITS, ML_BIT_IMG_LOW_BIT, and ML_BIT_IMG_SHIFT.

MLTOOLS_EXPORT MLErrorCode ml::BitImage::load ( const std::string & path )

Read bit image from file specified by path and returns ML_RESULT_OK success or another error code in case of failure.

Content of *this will be undefined in case of non ML_RESULT_OK return value .

void ml::BitImage::moveBC ( ) [inline]

Deprecated:: Use reverseMoveCursorC() instead.

Definition at line 520 of file mlBitImage.h.

void ml::BitImage::moveBT ( ) [inline]

Deprecated:: Use reverseMoveCursorT() instead.

Definition at line 524 of file mlBitImage.h.

void ml::BitImage::moveBU ( ) [inline]

Deprecated:: Use reverseMoveCursorU() instead.

Definition at line 528 of file mlBitImage.h.

void ml::BitImage::moveBX ( ) [inline]

Deprecated:: Use reverseMoveCursorX() instead.

Definition at line 508 of file mlBitImage.h.

void ml::BitImage::moveBY ( ) [inline]

Deprecated:: Use reverseMoveCursorY() instead.

Definition at line 512 of file mlBitImage.h.

void ml::BitImage::moveBZ ( ) [inline]

Deprecated:: Use reverseMoveCursorZ() instead.

Definition at line 516 of file mlBitImage.h.

void ml::BitImage::moveCursorC ( ) [inline]

Definition at line 256 of file mlBitImage.h.

bool ml::BitImage::moveCursorFXLF ( ) [inline]

Deprecated:: Use moveCursorXWrapAround() instead.

Definition at line 532 of file mlBitImage.h.

void ml::BitImage::moveCursorT ( ) [inline]

Definition at line 257 of file mlBitImage.h.

void ml::BitImage::moveCursorU ( ) [inline]

Definition at line 258 of file mlBitImage.h.

void ml::BitImage::moveCursorX ( ) [inline]

Definition at line 253 of file mlBitImage.h.

Referenced by ml::TVirtualVolume< DATATYPE >::copyMaskToSubImage().

MLTOOLS_EXPORT bool ml::BitImage::moveCursorXWrapAround ( )

Special cursor move: Increment x coordinate of cursor.

When going out of image set x to zero and increase y. If y overflows then increment z etc. So an image can easily scanned as a one dimensional sequence. If the cursor is on the last voxel it won't be moved outside the image; it remains there without throwing exceptions or causing errors. It just returns false instead of true. So the sequence resetCursor(); do {} while (moveCursorXWrapAround()); permits easy bit image scanning. Throws no controlled diagnostic exceptions even if exception handling is on.

void ml::BitImage::moveCursorY ( ) [inline]

Definition at line 254 of file mlBitImage.h.

void ml::BitImage::moveCursorZ ( ) [inline]

Definition at line 255 of file mlBitImage.h.

void ml::BitImage::moveFC ( ) [inline]

Deprecated:: Use moveCursorC() instead.

Definition at line 496 of file mlBitImage.h.

void ml::BitImage::moveFT ( ) [inline]

Deprecated:: Use moveCursorT() instead.

Definition at line 500 of file mlBitImage.h.

void ml::BitImage::moveFU ( ) [inline]

Deprecated:: Use moveCursorU() instead.

Definition at line 504 of file mlBitImage.h.

void ml::BitImage::moveFX ( ) [inline]

Deprecated:: Use moveCursorX() instead.

Definition at line 484 of file mlBitImage.h.

void ml::BitImage::moveFY ( ) [inline]

Deprecated:: Use moveCursorY() instead.

Definition at line 488 of file mlBitImage.h.

void ml::BitImage::moveFZ ( ) [inline]

Deprecated:: Use moveCursorZ() instead.

Definition at line 492 of file mlBitImage.h.

MLTOOLS_EXPORT const BitImage& ml::BitImage::operator= ( const BitImage & bitImg )

Assignment operator.

Assigns bitImg to this instance. Throws ML_NO_MEMORY as diagnostic exceptions if exception handling is on and assignment fails due to lack of memory. In such a case *this is left unchanged.

bool ml::BitImage::operator[] ( const ImageVector & pos ) const [inline]

Constant vector index read access to voxel value at position pos.

If exceptions are on and pos is out of range then the error code ML_OUT_OF_RANGE is thrown. Otherwise program state becomes undefined.

Definition at line 178 of file mlBitImage.h.

MLTOOLS_EXPORT bool ml::BitImage::readFromFile ( const std::string & path )

Reads a bit image from file specified by path and returns true on success, false on error.

Only for backward compatibility, use load() instead.

void ml::BitImage::reset ( void ) [inline]

Make image empty and restore default construction state with disabled exceptions.

Never throws controlled diagnostic exceptions.

Definition at line 102 of file mlBitImage.h.

MLTOOLS_EXPORT void ml::BitImage::resetCursor ( )

Set cursor and dependent members to default position (0,0,0,0,0,0).

Throws no controlled diagnostic exceptions even if exception handling is on.

void ml::BitImage::reverseMoveCursorC ( ) [inline]

Definition at line 266 of file mlBitImage.h.

void ml::BitImage::reverseMoveCursorT ( ) [inline]

Definition at line 267 of file mlBitImage.h.

void ml::BitImage::reverseMoveCursorU ( ) [inline]

Definition at line 268 of file mlBitImage.h.

void ml::BitImage::reverseMoveCursorX ( ) [inline]

Definition at line 263 of file mlBitImage.h.

void ml::BitImage::reverseMoveCursorY ( ) [inline]

Definition at line 264 of file mlBitImage.h.

void ml::BitImage::reverseMoveCursorZ ( ) [inline]

Definition at line 265 of file mlBitImage.h.

MLTOOLS_EXPORT MLErrorCode ml::BitImage::save	(	const std::string &	path,
		bool	overwrite = `true`
	)

Writes bit image content into file specified by path.

Return ML_RESULT_OK on success or another error code on failure. If overwrite is true (default) then existing files are overwritten, otherwise they won't be harmed and ML_OBJECT_OR_FILE_EXISTS is returned.

static MLTOOLS_EXPORT MLuint32 ml::BitImage::selfTest ( ) [static]

Starts a self test of the mlBitImage class.

Returns a nonzero value if test failed. Return value is 0 if everything is okay.

void ml::BitImage::set ( const ImageVector & pos ) [inline]

Set bit at position pos optimized for all extents of a bit image.

If exceptions are on and pos is out of range then the error code ML_OUT_OF_RANGE is thrown. Otherwise program state becomes undefined.

Definition at line 188 of file mlBitImage.h.

References ML_BIT_IMG_INDEX_BITS, ML_BIT_IMG_LOW_BIT, and ML_BIT_IMG_SHIFT.

void ml::BitImage::setCursorPos ( const ImageVector & pos ) [inline]

Deprecated:: Use setCursorPosition() instead.

Definition at line 476 of file mlBitImage.h.

void ml::BitImage::setCursorPosition ( const ImageVector & pos ) [inline]

Set cursor position to position pos.

If exceptions are on and pos is out of range then the error code ML_OUT_OF_RANGE is thrown. Otherwise program state becomes undefined.

Definition at line 220 of file mlBitImage.h.

Referenced by ml::TVirtualVolume< DATATYPE >::copyMaskToSubImage().

void ml::BitImage::setCursorValue ( ) [inline]

Sets the bit under the cursor to 1. Never throws controlled diagnostic exceptions.

Definition at line 232 of file mlBitImage.h.

References ML_BIT_IMG_INDEX_BITS, ML_BIT_IMG_LOW_BIT, and ML_BIT_IMG_SHIFT.

void ml::BitImage::setCursorValue ( const bool val ) [inline]

Sets the bit under the cursor to 1 if true is passed as val, otherwise 0 is set. Never throws controlled diagnostic exceptions.

Definition at line 229 of file mlBitImage.h.

References setCursorValue().

Referenced by setCursorValue().

bool ml::BitImage::setExt ( const ImageVector & ext ) [inline]

Deprecated:: Use setExtent() instead.

Definition at line 441 of file mlBitImage.h.

bool ml::BitImage::setExtent ( const ImageVector & ext ) [inline]

Resize image.

Contents are destroyed and are left undefined. On memory allocation failure or too large extents (> 4 giga bit) false is returned, and image is left in reset state without allocated memory. Otherwise true is returned. On extent changes the cursor is reset to position 0. Negative extents are handled as ImageVector(0,0,0,0,0,0) extent and no memory is allocated, and true is returned. Throws no controlled diagnostic exceptions even if exception handling is on.

Definition at line 132 of file mlBitImage.h.

void ml::BitImage::setSourceBox ( const SubImageBox & box ) [inline]

Sets the original placement of the bit image corresponding to a potential image the bit image is created from.

Default is always empty if not set by this method, updateBitImageFromVolume() or by instance assignment/loading. Never throws controlled diagnostic exceptions.

Definition at line 150 of file mlBitImage.h.

void ml::BitImage::setValue	(	const ImageVector &	pos,
		const bool	v
	)			`[inline]`

Set bit at position pos to value v.

If exceptions are on and pos is out of range then the error code ML_OUT_OF_RANGE is thrown. Otherwise program state becomes undefined.

Definition at line 183 of file mlBitImage.h.

void ml::BitImage::toggle ( const ImageVector & pos ) [inline]

Toggle bit at position pos.

If exceptions are on and pos is out of range then the error code ML_OUT_OF_RANGE is thrown. Otherwise program state becomes undefined.

Definition at line 198 of file mlBitImage.h.

References ML_BIT_IMG_INDEX_BITS, ML_BIT_IMG_LOW_BIT, and ML_BIT_IMG_SHIFT.

void ml::BitImage::toggleCursorValue ( ) [inline]

Toggles the bit under the cursor. Never throws controlled diagnostic exceptions.

Definition at line 235 of file mlBitImage.h.

References ML_BIT_IMG_INDEX_BITS, ML_BIT_IMG_LOW_BIT, and ML_BIT_IMG_SHIFT.

MLTOOLS_EXPORT long ml::BitImage::updateBitImageFromVolume	(	const void *	data,
		const MLDataType	dType,
		const SubImageBox &	origBox,
		const double	minVal,
		const double	maxVal,
		const unsigned char	addBorderPixels = `0`
	)

Scan volume given by data and origBox and filter all values through the interval given by [minVal, maxVal).

Find a bounding box so that all values within this interval are within that box and set the bitImage to this size. All voxels within the interval result in a set bit in the bitImage all others result to false. The method returns the number of set bits in bitImage and the resulting bounding box is stored in _sourceBox. If addBorderPixels has bits set of its first six bits then the corresponding dimensions get a surrounding border pixel filled with false bits. E.g. if addBorderPixels is 6 the bits 1 and 2 are set, so dimension y and z get border pixels. Note that border pixels are created only if borders still fit in origBox. So the BitImage never becomes bigger than origBox. If no valid input volume (origBox empty or data is NULL) exists then -1 is returned. If no result volume could be created (e.g. memory allocation error) then -2 is returned.

MLTOOLS_EXPORT void ml::BitImage::useExceptionHandling ( bool useExceptions )

Pass true to enable exception handling, false to disable it.

Never throws controlled diagnostic exceptions.

bool ml::BitImage::useExceptionHandling ( ) const [inline]

Return true if exception handling is on, otherwise return false.

Never throws controlled diagnostic exceptions.

Definition at line 106 of file mlBitImage.h.

MLTOOLS_EXPORT bool ml::BitImage::writeToFile	(	const std::string &	path,
		bool	overwrite = `true`
	)

Writes bit image content into file specified by path path and return true on success and false on failure.

If overwrite is true (default) then existing files are overwritten, otherwise they won't be harmed and false is returned. Only for backward compatibility, use save() instead.

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

MeVisLab/Standard/Sources/ML/MLTools/include/mlBitImage.h


Public Types
Operation modes to write bit images into normal subimages.
enum	OperationModes { SET_MODE = 0, OR_MODE, AND_MODE, XOR_MODE, CLEAR_MODE, NUM_MODES }
Public Member Functions
Construction, Destruction, Assignment
	BitImage (bool useExceptions=false)
	Constructor.
	BitImage (const ImageVector &ext, bool useExceptions=false)
	Convenience constructor.
MLTOOLS_EXPORT	BitImage (const BitImage &bitImg)
	Copy constructor, copies bitImg to this instance.
virtual MLTOOLS_EXPORT	~BitImage ()
	Destructor. Never throws controlled diagnostic exceptions.
void	reset ()
	Make image empty and restore default construction state with disabled exceptions.
bool	useExceptionHandling () const
	Return true if exception handling is on, otherwise return false.
MLTOOLS_EXPORT void	useExceptionHandling (bool useExceptions)
	Pass true to enable exception handling, false to disable it.
MLTOOLS_EXPORT const BitImage &	operator= (const BitImage &bitImg)
	Assignment operator.
Extents
bool	setExtent (const ImageVector &ext)
	Resize image.
const ImageVector &	getExtent () const
	Return image size. Never throws controlled diagnostic exceptions.
const SubImageBox	getBoxFromImageExtent () const
	Return a SubImageBox representing the image extent of the BitImage.
const SubImageBox &	getSourceBox () const
	Returns the original placement of the bit image corresponding to a potential image the bit image is created from.
void	setSourceBox (const SubImageBox &box)
	Sets the original placement of the bit image corresponding to a potential image the bit image is created from.
Miscellaneous
const ImageVector &	getStrides () const
	Return strides for binary pixels.
MLint	getCursorBitIndex () const
	Return strides for words. Never throws controlled diagnostic exceptions.
bool	isEmpty () const
	Returns true if image is empty. Never throws controlled diagnostic exceptions.
void	clear (bool val)
	Clears/sets all bits in the image. Never throws controlled diagnostic exceptions.
Direct access to image content
bool	operator[] (const ImageVector &pos) const
	Constant vector index read access to voxel value at position pos.
void	setValue (const ImageVector &pos, const bool v)
	Set bit at position pos to value v.
void	set (const ImageVector &pos)
	Set bit at position pos optimized for all extents of a bit image.
void	clear (const ImageVector &pos)
	Clear bit at position pos optimized for all extents of a bit image.
void	toggle (const ImageVector &pos)
	Toggle bit at position pos.
bool	isSet (const ImageVector &pos) const
	Return true if bit at position pos is set, otherwise false.
bool	isInRange (const ImageVector &p) const
	Test for ImageVector coordinates in valid range.
bool	isInRange (const Vector6 &p) const
	Test for Vector6 coordinates in valid range.
General cursor management.
void	setCursorPosition (const ImageVector &pos)
	Set cursor position to position pos.
const ImageVector &	getCursorPosition () const
	Return current cursor position. Never throws controlled diagnostic exceptions.
bool	getCursorValue () const
	Return true if bit under cursor is true, otherwise false. Never throws controlled diagnostic exceptions.
void	setCursorValue (const bool val)
	Sets the bit under the cursor to 1 if true is passed as val, otherwise 0 is set. Never throws controlled diagnostic exceptions.
void	setCursorValue ()
	Sets the bit under the cursor to 1. Never throws controlled diagnostic exceptions.
void	toggleCursorValue ()
	Toggles the bit under the cursor. Never throws controlled diagnostic exceptions.
void	clearCursorValue ()
	Clears the bit under the cursor to 0. Never throws controlled diagnostic exceptions.
MLuint32	getCursorWordIndex () const
	Return index to word in image to which the cursor points. Never throws controlled diagnostic exceptions.
ML_BIT_IMG_DATA_TYPE	getCursorWord () const
	Return content of word in image to which the cursor points.
ML_BIT_IMG_DATA_TYPE	getCursorBitMask () const
	Return the bit mask specifying the bit in the cursor word. Never throws controlled diagnostic exceptions.
Cursor movements forward in X/Y/Z/C/T/U direction. Throws MLErrorCode exceptions when going to invalid position if exception handling is enabled, otherwise state becomes instable.
void	moveCursorX ()
void	moveCursorY ()
void	moveCursorZ ()
void	moveCursorC ()
void	moveCursorT ()
void	moveCursorU ()
Cursor movements backward in X/Y/Z/C/T/U direction. Throws MLErrorCode exceptions when going to invalid position if exception handling is enabled, otherwise state becomes instable.
void	reverseMoveCursorX ()
void	reverseMoveCursorY ()
void	reverseMoveCursorZ ()
void	reverseMoveCursorC ()
void	reverseMoveCursorT ()
void	reverseMoveCursorU ()
Linear image traversal.
MLTOOLS_EXPORT void	resetCursor ()
	Set cursor and dependent members to default position (0,0,0,0,0,0).
MLTOOLS_EXPORT bool	moveCursorXWrapAround ()
	Special cursor move: Increment x coordinate of cursor.
Miscellaneous
MLTOOLS_EXPORT void	getStatistics (MLuint32 numBits, MLuint32 numSetBits, MLuint32 *numClearedBits)
	Returns some basic statistical values.
MLTOOLS_EXPORT BitImage *	getDownScaledBitImage (const ImageVector &scales) const
	Create a down scaled mlBitImage from this.
MLTOOLS_EXPORT long	updateBitImageFromVolume (const void *data, const MLDataType dType, const SubImageBox &origBox, const double minVal, const double maxVal, const unsigned char addBorderPixels=0)
	Scan volume given by data and origBox and filter all values through the interval given by [minVal, maxVal).
MLTOOLS_EXPORT SubImageBox	calculateBoundingBox (bool val=true)
	Calculates the bounding box of all bits of value val (default is true).
MLTOOLS_EXPORT void	copyToBitImage (BitImage &dstBitImg, OperationModes mode=SET_MODE, const SubImageBox &box=SubImageBox(), const ImageVector &offset=ImageVector(0))
	Copy all bits from the overlapping regions from box and *this to the position box.v1+offset to dstBitImg.
MLTOOLS_EXPORT BitImage *	getSubBitImageByMask (bool val)
	Calculates the bounding box of all bits of value val and returns a new BitImage containing exactly that area.
Interactions with subimages and subimage boxes
MLTOOLS_EXPORT void	fill (const SubImageBox &box, const bool value)
	Fill the area given by box in the bit image with value value.
MLTOOLS_EXPORT void	invert (const SubImageBox &box)
	Toggle the area given by box in the bit image.
MLTOOLS_EXPORT void	copyToSubImage (SubImage &outSubImg, const long double bkVal, const long double fgVal, const OperationModes mode=SET_MODE) const
	Copy area from the bit image into the subimage given by outSubImg.
MLTOOLS_EXPORT void	copyFromSubImage (SubImage &inImg, const SubImageBox &box, const ImageVector &pos, const long double intMin, const long double intMax)
	Copy the area given by box from inImg to the position p of the bitImage.
Save/load bit image from file.
MLTOOLS_EXPORT bool	writeToFile (const std::string &path, bool overwrite=true)
	Writes bit image content into file specified by path path and return true on success and false on failure.
MLTOOLS_EXPORT MLErrorCode	save (const std::string &path, bool overwrite=true)
	Writes bit image content into file specified by path.
MLTOOLS_EXPORT bool	readFromFile (const std::string &path)
	Reads a bit image from file specified by path and returns true on success, false on error.
MLTOOLS_EXPORT MLErrorCode	load (const std::string &path)
	Read bit image from file specified by path and returns ML_RESULT_OK success or another error code in case of failure.
Deprecated methods.
bool	setExt (const ImageVector &ext)
const ImageVector &	getExt () const
SubImageBox	getBoxFromImgExt () const
MLint	getCursorBitIdx () const
void	copyToSubImg (SubImage &outSubImg, const long double bkVal, const long double fgVal, const OperationModes mode=SET_MODE) const
void	copyFromSubImg (SubImage &inImg, const SubImageBox &box, const ImageVector &pos, const long double intMin, const long double intMax)
SubImageBox	calcBoundingBox (bool val=true)
void	setCursorPos (const ImageVector &pos)
const ImageVector &	getCursorPos () const
void	moveFX ()
void	moveFY ()
void	moveFZ ()
void	moveFC ()
void	moveFT ()
void	moveFU ()
void	moveBX ()
void	moveBY ()
void	moveBZ ()
void	moveBC ()
void	moveBT ()
void	moveBU ()
bool	moveCursorFXLF ()
Static Public Member Functions
static MLTOOLS_EXPORT MLuint32	selfTest ()
	Starts a self test of the mlBitImage class.