The TVirtualVolume class implements random access to a paged input image or a pure virtual image without mapping more than a limited number of bytes. Pages of the input volume are mapped temporarily into memory when needed. If no input volume is specified the pages are created and filled with a fill value. When the permitted amount of memory is exceeded then older mapped pages are removed. When pages are written they are mapped until the virtual volume instance is removed or if they are explicitly cleared by the application. More...

#include <mlTVirtualVolume.h>

Public Types
typedef DATATYPE	ComponentType
	A typedef to "export" the type of voxels components.

Public Member Functions
	TVirtualVolume (VirtualVolume &vVol)
	Constructor 1.

	TVirtualVolume (PagedImage *image, MLint maxNumKB=-1, bool areExceptionsOn=false)
	Convenience constructor (2) creating an untyped virtual volume inside the typed one to avoid additional management of the untyped instance.

	TVirtualVolume (const ImageVector &ext, MLdouble fillVal=0, MLint maxNumKB=-1, bool areExceptionsOn=false)
	Convenience constructor (3) creating an untyped virtual volume inside the typed one to avoid additional management of the untyped instance.

virtual	~TVirtualVolume ()
	Destructor.

VirtualVolume &	getVirtualVolume ()
	Returns the pointer to the wrapped untyped virtual volume.

void	getValues (const ImageVector pos, DATATYPE results, MLuint num)
	Get a set of voxels from the virtual volume.

DATATYPE	getValue (const ImageVector &pos)
	Get a voxel value from the virtual volume.

void	setValue (const ImageVector &pos, DATATYPE data)
	Write a voxel into the virtual volume.

void	setCursorPosition (const ImageVector &pos)
	Set the cursor to a certain position.

const ImageVector &	getCursorPosition () const
	Return the current cursor coordinates.

void	setCursorValue (DATATYPE val)
	Set value under cursor and lock page.

DATATYPE	getCursorValue ()
	Return value under cursor.

bool	isMapped (const ImageVector &pos) const
	Returns true if voxel is mapped into memory, otherwise it returns false.

void	moveCursorByOffset (const ImageVector &off)
	Shift cursor to current position + offset.

void	fill (const SubImageBox &box, DATATYPE value)
	Fill the area box in the virtual image with voxel value value.

void	copyToSubImage (TSubImage< DATATYPE > &outSubImg)
	Copy area from the virtual volume into the subimage given by outSubImg.

void	copyFromSubImage (const TSubImage< DATATYPE > &inImg, const SubImageBox &box, const ImageVector &pos)
	Copy the area given by box from inImg to the position p of the virtual volume.

template<typename OUTDTYPE >
void	copyMaskToSubImage (TSubImage< OUTDTYPE > &outSubImg, BitImage &maskBits, bool maskValue=true, bool writeBK=false, OUTDTYPE bkVal=ml_cast_from_scalar< OUTDTYPE >(0))
	Takes overlapping region from this, outSubImg and maskBits and copies all voxels from this to outSubImg if the corresponding bit in maskBits has the value maskValue.

DATATYPE *	getWrittenPageData (MLuint32 wp) const
	Returns typed pointer to data of written page with page id wp.

Move cursor to next higher/lower position.
void	moveCursorX ()

void	moveCursorY ()

void	moveCursorZ ()

void	moveCursorC ()

void	moveCursorT ()

void	moveCursorU ()

void	reverseMoveCursorX ()

void	reverseMoveCursorY ()

void	reverseMoveCursorZ ()

void	reverseMoveCursorC ()

void	reverseMoveCursorT ()

void	reverseMoveCursorU ()

Linear image traversal.
Set cursor to default position (0,0,0,0,0,0).
void	resetCursor ()
	Set cursor to default position (0,0,0,0,0,0).

bool	moveCursorXWrapAround ()
	Special cursor move: Increment x coordinate of cursor.

Static Public Member Functions

static MLint	getIntValueWrapped (void *vv, const ImageVector &pos)
	Wrapper functions for non template application interfaces.

static MLint64	getInt64ValueWrapped (void *vv, const ImageVector &pos)

static MLdouble	getDoubleValueWrapped (void *vv, const ImageVector &pos)

static MLldouble	getLDoubleValueWrapped (void *vv, const ImageVector &pos)

static MLint	getIntCursorValueWrapped (void *vv)

static MLint64	getInt64CursorValueWrapped (void *vv)

static MLdouble	getDoubleCursorValueWrapped (void *vv)

static MLldouble	getLDoubleCursorValueWrapped (void *vv)

static const ImageVector &	getCursorPositionWrapped (void *vv)

static bool	isMappedWrapped (void *vv, const ImageVector &pos)

static void	setCursorPositionWrapped (void *vv, const ImageVector &pos)

static void	setIntValueWrapped (void *vv, const ImageVector &pos, MLint v)

static void	setInt64ValueWrapped (void *vv, const ImageVector &pos, MLint64 v)

static void	setDoubleValueWrapped (void *vv, const ImageVector &pos, MLdouble v)

static void	setLDoubleValueWrapped (void *vv, const ImageVector &pos, MLldouble v)

static void	setIntCursorValueWrapped (void *vv, MLint v)

static void	setInt64CursorValueWrapped (void *vv, MLint64 v)

static void	setDoubleCursorValueWrapped (void *vv, MLdouble v)

static void	setLDoubleCursorValueWrapped (void *vv, MLldouble v)

static void	fillIntWrapped (void *vv, const ImageVector &v1, const ImageVector &v2, MLint v)

static void	fillInt64Wrapped (void *vv, const ImageVector &v1, const ImageVector &v2, MLint64 v)

static void	fillDoubleWrapped (void *vv, const ImageVector &v1, const ImageVector &v2, MLdouble v)

static void	fillLDoubleWrapped (void *vv, const ImageVector &v1, const ImageVector &v2, MLldouble v)

static void	moveCursorXWrapped (void *vv)

static void	moveCursorYWrapped (void *vv)

static void	moveCursorZWrapped (void *vv)

static void	moveCursorCWrapped (void *vv)

static void	moveCursorTWrapped (void *vv)

static void	moveCursorUWrapped (void *vv)

static void	reverseMoveCursorXWrapped (void *vv)

static void	reverseMoveCursorYWrapped (void *vv)

static void	reverseMoveCursorZWrapped (void *vv)

static void	reverseMoveCursorCWrapped (void *vv)

static void	reverseMoveCursorTWrapped (void *vv)

static void	reverseMoveCursorUWrapped (void *vv)

static void	moveCursorByOffsetWrapped (void *vv, const ImageVector &off)

static void	resetCursorWrapped (void *vv)

static bool	moveCursorXWrapAroundWrapped (void *vv)

Protected Member Functions
	TVirtualVolume ()
	Hide the default constructor to avoid incorrect usage due to missing initializations.

TVirtualVolume &	operator= (const TVirtualVolume &)
	Hide the default assignment operator to avoid incorrect usage due to missing initializations.

void	_init (VirtualVolume &vVol)
	Initialize the typed virtual volume. A valid virtual volume should be passed.

void	_cleanUp ()
	Clean up all settings. Implements the destruction sequence.

Both with and without tests and exceptions is implemented.
DATATYPE	_getVoxel1D (const ImageVector &pos)
	Get voxel method for a certain dimension. (1d)

DATATYPE	_getVoxel2D (const ImageVector &pos)
	Get voxel method for a certain dimension. (2d)

DATATYPE	_getVoxel3D (const ImageVector &pos)
	Get voxel method for a certain dimension. (3d)

DATATYPE	_getVoxel4D (const ImageVector &pos)
	Get voxel method for a certain dimension. (4d)

DATATYPE	_getVoxel5D (const ImageVector &pos)
	Get voxel method for a certain dimension. (5d)

DATATYPE	_getVoxel6D (const ImageVector &pos)
	Get voxel method for a certain dimension. (6d)

DATATYPE	_getVoxel1DE (const ImageVector &pos)
	Get voxel at a position for a certain dimension with testing and exception throw if necessary. (1D)

DATATYPE	_getVoxel2DE (const ImageVector &pos)
	Get voxel at a position for a certain dimension with testing and exception throw if necessary. (2d)

DATATYPE	_getVoxel3DE (const ImageVector &pos)
	Get voxel at a position for a certain dimension with testing and exception throw if necessary. (3d)

DATATYPE	_getVoxel4DE (const ImageVector &pos)
	Get voxel at a position for a certain dimension with testing and exception throw if necessary. (4d)

DATATYPE	_getVoxel5DE (const ImageVector &pos)
	Get voxel at a position for a certain dimension with testing and exception throw if necessary. (5d)

DATATYPE	_getVoxel6DE (const ImageVector &pos)
	Get voxel at a position for a certain dimension with testing and exception throw if necessary. (6d)

Implementation of 6 setValue versions, optimized to the image dimensions.
In all functions first calculate the page index by dividing the coordinate components by their page extents and by multiplying them with _strides. Then call the page data access function by calling the function pointer in the page. That function maps the page if necessary. Then compute the index into that page by multiplying the coordinate components with _pStrides. Both with and without tests and exceptions is implemented.
void	_setVoxel1D (const ImageVector &pos, DATATYPE voxVal)
	Set voxel method for a certain dimension. (1d)

void	_setVoxel2D (const ImageVector &pos, DATATYPE voxVal)
	Set voxel method for a certain dimension. (2d)

void	_setVoxel3D (const ImageVector &pos, DATATYPE voxVal)
	Set voxel method for a certain dimension. (3d)

void	_setVoxel4D (const ImageVector &pos, DATATYPE voxVal)
	Set voxel method for a certain dimension. (4d)

void	_setVoxel5D (const ImageVector &pos, DATATYPE voxVal)
	Set voxel method for a certain dimension. (5d)

void	_setVoxel6D (const ImageVector &pos, DATATYPE voxVal)
	Set voxel method for a certain dimension. (6d)

void	_setVoxel1DE (const ImageVector &pos, DATATYPE voxVal)
	Set voxel at a position for a certain dimension with testing and exception throw if necessary. (1d)

void	_setVoxel2DE (const ImageVector &pos, DATATYPE voxVal)
	Set voxel at a position for a certain dimension with testing and exception throw if necessary. (2d)

void	_setVoxel3DE (const ImageVector &pos, DATATYPE voxVal)
	Set voxel at a position for a certain dimension with testing and exception throw if necessary. (3d)

void	_setVoxel4DE (const ImageVector &pos, DATATYPE voxVal)
	Set voxel at a position for a certain dimension with testing and exception throw if necessary. (4d)

void	_setVoxel5DE (const ImageVector &pos, DATATYPE voxVal)
	Set voxel at a position for a certain dimension with testing and exception throw if necessary. (5d)

void	_setVoxel6DE (const ImageVector &pos, DATATYPE voxVal)
	Set voxel at a position for a certain dimension with testing and exception throw if necessary. (6d)

Implementation of 6 isMapped versions, optimized to the image dimensions.
In all functions first calculate the page index by dividing the coordinate components by their page extents and by multiplying them with _strides. Then it looks whether the function to access the page is set or the load page function. Both with and without tests and exceptions is implemented.
bool	_isMapped1D (const ImageVector &pos) const
	Returns true if voxel is mapped in memory for a certain dimension, otherwise false. (1d)

bool	_isMapped2D (const ImageVector &pos) const
	Returns true if voxel is mapped in memory for a certain dimension, otherwise false. (2d)

bool	_isMapped3D (const ImageVector &pos) const
	Returns true if voxel is mapped in memory for a certain dimension, otherwise false. (3d)

bool	_isMapped4D (const ImageVector &pos) const
	Returns true if voxel is mapped in memory for a certain dimension, otherwise false. (4d)

bool	_isMapped5D (const ImageVector &pos) const
	Returns true if voxel is mapped in memory for a certain dimension, otherwise false. (6d)

bool	_isMapped6D (const ImageVector &pos) const
	Returns true if voxel is mapped in memory for a certain dimension, otherwise false. (6d)

bool	_isMapped1DE (const ImageVector &pos) const
	Returns true if voxel is mapped in memory for a certain dimension, otherwise false. (1d) Throws exception if out of range.

bool	_isMapped2DE (const ImageVector &pos) const
	Returns true if voxel is mapped in memory for a certain dimension, otherwise false. (2d) Throws exception if out of range.

bool	_isMapped3DE (const ImageVector &pos) const
	Returns true if voxel is mapped in memory for a certain dimension, otherwise false. (3d) Throws exception if out of range.

bool	_isMapped4DE (const ImageVector &pos) const
	Returns true if voxel is mapped in memory for a certain dimension, otherwise false. (4d) Throws exception if out of range.

bool	_isMapped5DE (const ImageVector &pos) const
	Returns true if voxel is mapped in memory for a certain dimension, otherwise false. (6d) Throws exception if out of range.

bool	_isMapped6DE (const ImageVector &pos) const
	Returns true if voxel is mapped in memory for a certain dimension, otherwise false. (6d) Throws exception if out of range.

Set the cursor to a certain position in 1D-6D, without and with exceptions.
Cursor offsetting implementation.
void	_setCursorPos1D (const ImageVector &p)
	Set cursor position for a certain dimension. (1d)

void	_setCursorPos2D (const ImageVector &p)
	Set cursor position for a certain dimension. (2d)

void	_setCursorPos3D (const ImageVector &p)
	Set cursor position for a certain dimension. (3d)

void	_setCursorPos4D (const ImageVector &p)
	Set cursor position for a certain dimension. (4d)

void	_setCursorPos5D (const ImageVector &p)
	Set cursor position for a certain dimension. (5d)

void	_setCursorPos6D (const ImageVector &p)
	Set cursor position for a certain dimension. (6d)

void	_setCursorPos1DE (const ImageVector &p)
	Set cursor position for a certain dimension with testing and exception throw if necessary. (1d)

void	_setCursorPos2DE (const ImageVector &p)
	Set cursor position for a certain dimension with testing and exception throw if necessary. (2d)

void	_setCursorPos3DE (const ImageVector &p)
	Set cursor position for a certain dimension with testing and exception throw if necessary. (3d)

void	_setCursorPos4DE (const ImageVector &p)
	Set cursor position for a certain dimension with testing and exception throw if necessary. (4d)

void	_setCursorPos5DE (const ImageVector &p)
	Set cursor position for a certain dimension with testing and exception throw if necessary. (5d)

void	_setCursorPos6DE (const ImageVector &p)
	Set cursor position for a certain dimension with testing and exception throw if necessary. (6d)

void	_moveCursorOffset1D (const ImageVector &p)
	Move cursor by an offset to a new position. (1d)

void	_moveCursorOffset2D (const ImageVector &p)
	Move cursor by an offset to a new position. (2d)

void	_moveCursorOffset3D (const ImageVector &p)
	Move cursor by an offset to a new position. (3d)

void	_moveCursorOffset4D (const ImageVector &p)
	Move cursor by an offset to a new position. (4d)

void	_moveCursorOffset5D (const ImageVector &p)
	Move cursor by an offset to a new position. (5d)

void	_moveCursorOffset6D (const ImageVector &p)
	Move cursor by an offset to a new position. (6d)

void	_moveCursorOffset1DE (const ImageVector &p)
	Move cursor by an offset to a new position with testing and exception throw if necessary. (1d)

void	_moveCursorOffset2DE (const ImageVector &p)
	Move cursor by an offset to a new position with testing and exception throw if necessary. (2d)

void	_moveCursorOffset3DE (const ImageVector &p)
	Move cursor by an offset to a new position with testing and exception throw if necessary. (3d)

void	_moveCursorOffset4DE (const ImageVector &p)
	Move cursor by an offset to a new position with testing and exception throw if necessary. (4d)

void	_moveCursorOffset5DE (const ImageVector &p)
	Move cursor by an offset to a new position with testing and exception throw if necessary. (5d)

void	_moveCursorOffset6DE (const ImageVector &p)
	Move cursor by an offset to a new position with testing and exception throw if necessary. (6d)

Move cursor to next higher position. The *E versions throw ML_OUT_OF_RANGE exceptions when outside the image.
Cursor movement implementation.
void	_moveFX ()

void	_moveFY ()

void	_moveFZ ()

void	_moveFC ()

void	_moveFT ()

void	_moveFU ()

void	_moveFXE ()

void	_moveFYE ()

void	_moveFZE ()

void	_moveFCE ()

void	_moveFTE ()

void	_moveFUE ()

Move cursor to next lower position. The *E versions throw ML_OUT_OF_RANGE exceptions when outside the image.
void	_moveBX ()

void	_moveBY ()

void	_moveBZ ()

void	_moveBC ()

void	_moveBT ()

void	_moveBU ()

void	_moveBXE ()

void	_moveBYE ()

void	_moveBZE ()

void	_moveBCE ()

void	_moveBTE ()

void	_moveBUE ()

Static Protected Member Functions
Static functions to wrap/call the correct function to get/set voxel methods. Only one of these set/get methods is
called via the function pointers _getVoxelFunc and _setVoxelFunc for a certain image dimension. All other functions are usually not used for that dimension. Both with and without tests and exceptions are implemented.
static DATATYPE	_getVoxel1DCB (TVirtualVolume *obj, const ImageVector &pos)

static DATATYPE	_getVoxel2DCB (TVirtualVolume *obj, const ImageVector &pos)

static DATATYPE	_getVoxel3DCB (TVirtualVolume *obj, const ImageVector &pos)

static DATATYPE	_getVoxel4DCB (TVirtualVolume *obj, const ImageVector &pos)

static DATATYPE	_getVoxel5DCB (TVirtualVolume *obj, const ImageVector &pos)

static DATATYPE	_getVoxel6DCB (TVirtualVolume *obj, const ImageVector &pos)

static DATATYPE	_getVoxel1DCBE (TVirtualVolume *obj, const ImageVector &pos)

static DATATYPE	_getVoxel2DCBE (TVirtualVolume *obj, const ImageVector &pos)

static DATATYPE	_getVoxel3DCBE (TVirtualVolume *obj, const ImageVector &pos)

static DATATYPE	_getVoxel4DCBE (TVirtualVolume *obj, const ImageVector &pos)

static DATATYPE	_getVoxel5DCBE (TVirtualVolume *obj, const ImageVector &pos)

static DATATYPE	_getVoxel6DCBE (TVirtualVolume *obj, const ImageVector &pos)

static void	_setVoxel1DCB (TVirtualVolume *obj, const ImageVector &pos, DATATYPE voxVal)

static void	_setVoxel2DCB (TVirtualVolume *obj, const ImageVector &pos, DATATYPE voxVal)

static void	_setVoxel3DCB (TVirtualVolume *obj, const ImageVector &pos, DATATYPE voxVal)

static void	_setVoxel4DCB (TVirtualVolume *obj, const ImageVector &pos, DATATYPE voxVal)

static void	_setVoxel5DCB (TVirtualVolume *obj, const ImageVector &pos, DATATYPE voxVal)

static void	_setVoxel6DCB (TVirtualVolume *obj, const ImageVector &pos, DATATYPE voxVal)

static void	_setVoxel1DCBE (TVirtualVolume *obj, const ImageVector &pos, DATATYPE voxVal)

static void	_setVoxel2DCBE (TVirtualVolume *obj, const ImageVector &pos, DATATYPE voxVal)

static void	_setVoxel3DCBE (TVirtualVolume *obj, const ImageVector &pos, DATATYPE voxVal)

static void	_setVoxel4DCBE (TVirtualVolume *obj, const ImageVector &pos, DATATYPE voxVal)

static void	_setVoxel5DCBE (TVirtualVolume *obj, const ImageVector &pos, DATATYPE voxVal)

static void	_setVoxel6DCBE (TVirtualVolume *obj, const ImageVector &pos, DATATYPE voxVal)

static bool	_isMapped1DCB (const TVirtualVolume *obj, const ImageVector &pos)

static bool	_isMapped2DCB (const TVirtualVolume *obj, const ImageVector &pos)

static bool	_isMapped3DCB (const TVirtualVolume *obj, const ImageVector &pos)

static bool	_isMapped4DCB (const TVirtualVolume *obj, const ImageVector &pos)

static bool	_isMapped5DCB (const TVirtualVolume *obj, const ImageVector &pos)

static bool	_isMapped6DCB (const TVirtualVolume *obj, const ImageVector &pos)

static bool	_isMapped1DCBE (const TVirtualVolume *obj, const ImageVector &pos)

static bool	_isMapped2DCBE (const TVirtualVolume *obj, const ImageVector &pos)

static bool	_isMapped3DCBE (const TVirtualVolume *obj, const ImageVector &pos)

static bool	_isMapped4DCBE (const TVirtualVolume *obj, const ImageVector &pos)

static bool	_isMapped5DCBE (const TVirtualVolume *obj, const ImageVector &pos)

static bool	_isMapped6DCBE (const TVirtualVolume *obj, const ImageVector &pos)

1-6D static functions with and without exceptions to wrap the correct setCursorPosition function for any dimension.
static void	_setCursorPos1DCB (TVirtualVolume *obj, const ImageVector &p)

static void	_setCursorPos2DCB (TVirtualVolume *obj, const ImageVector &p)

static void	_setCursorPos3DCB (TVirtualVolume *obj, const ImageVector &p)

static void	_setCursorPos4DCB (TVirtualVolume *obj, const ImageVector &p)

static void	_setCursorPos5DCB (TVirtualVolume *obj, const ImageVector &p)

static void	_setCursorPos6DCB (TVirtualVolume *obj, const ImageVector &p)

static void	_setCursorPos1DCBE (TVirtualVolume *obj, const ImageVector &p)

static void	_setCursorPos2DCBE (TVirtualVolume *obj, const ImageVector &p)

static void	_setCursorPos3DCBE (TVirtualVolume *obj, const ImageVector &p)

static void	_setCursorPos4DCBE (TVirtualVolume *obj, const ImageVector &p)

static void	_setCursorPos5DCBE (TVirtualVolume *obj, const ImageVector &p)

static void	_setCursorPos6DCBE (TVirtualVolume *obj, const ImageVector &p)

1-6D static functions with and without exceptions to wrap the correct moveCursorPos function for any dimension.
static void	_moveCursorOffset1DCB (TVirtualVolume *obj, const ImageVector &p)

static void	_moveCursorOffset2DCB (TVirtualVolume *obj, const ImageVector &p)

static void	_moveCursorOffset3DCB (TVirtualVolume *obj, const ImageVector &p)

static void	_moveCursorOffset4DCB (TVirtualVolume *obj, const ImageVector &p)

static void	_moveCursorOffset5DCB (TVirtualVolume *obj, const ImageVector &p)

static void	_moveCursorOffset6DCB (TVirtualVolume *obj, const ImageVector &p)

static void	_moveCursorOffset1DCBE (TVirtualVolume *obj, const ImageVector &p)

static void	_moveCursorOffset2DCBE (TVirtualVolume *obj, const ImageVector &p)

static void	_moveCursorOffset3DCBE (TVirtualVolume *obj, const ImageVector &p)

static void	_moveCursorOffset4DCBE (TVirtualVolume *obj, const ImageVector &p)

static void	_moveCursorOffset5DCBE (TVirtualVolume *obj, const ImageVector &p)

static void	_moveCursorOffset6DCBE (TVirtualVolume *obj, const ImageVector &p)

Static version:Move cursor to next higher position. The *E versions throw ML_OUT_OF_RANGE exceptions when outside the image.
static void	_moveFXCB (TVirtualVolume *obj)

static void	_moveFYCB (TVirtualVolume *obj)

static void	_moveFZCB (TVirtualVolume *obj)

static void	_moveFCCB (TVirtualVolume *obj)

static void	_moveFTCB (TVirtualVolume *obj)

static void	_moveFUCB (TVirtualVolume *obj)

static void	_moveFXCBE (TVirtualVolume *obj)

static void	_moveFYCBE (TVirtualVolume *obj)

static void	_moveFZCBE (TVirtualVolume *obj)

static void	_moveFCCBE (TVirtualVolume *obj)

static void	_moveFTCBE (TVirtualVolume *obj)

static void	_moveFUCBE (TVirtualVolume *obj)

Static version:Move cursor to next lower position. The *E versions throw ML_OUT_OF_RANGE exceptions when outside the image.
static void	_moveBXCB (TVirtualVolume *obj)

static void	_moveBYCB (TVirtualVolume *obj)

static void	_moveBZCB (TVirtualVolume *obj)

static void	_moveBCCB (TVirtualVolume *obj)

static void	_moveBTCB (TVirtualVolume *obj)

static void	_moveBUCB (TVirtualVolume *obj)

static void	_moveBXCBE (TVirtualVolume *obj)

static void	_moveBYCBE (TVirtualVolume *obj)

static void	_moveBZCBE (TVirtualVolume *obj)

static void	_moveBCCBE (TVirtualVolume *obj)

static void	_moveBTCBE (TVirtualVolume *obj)

static void	_moveBUCBE (TVirtualVolume *obj)

Detailed Description

template<typename DATATYPE>
class ml::TVirtualVolume< DATATYPE >

The TVirtualVolume class implements random access to a paged input image or a pure virtual image without mapping more than a limited number of bytes. Pages of the input volume are mapped temporarily into memory when needed. If no input volume is specified the pages are created and filled with a fill value. When the permitted amount of memory is exceeded then older mapped pages are removed. When pages are written they are mapped until the virtual volume instance is removed or if they are explicitly cleared by the application.

Accesses to the virtual volume can simple be performed with setValue and getValue. The accesses by the setValue and getValue are well optimized code which might be between 9 (1D), 18 (3D) and 36 (6D) instructions per voxel if the page below position is already mapped.

A cursor manager is also available to move a cursor forward with moveF*, backwards with moveB* methods. About 5-9 instructions might be executed for these move methods.

Accesses to voxels below cursor are available with setCursorValue and getCursorValue. On good compilers and already mapped pages they might use about 5-7 instructions.

So the cursor approach will probably be faster on data volumes with more than 2 dimensions.

Notes:

Performance of voxel accesses is best if input pages have powers of 2 as page extents.
Performance of voxel accesses is better for lower dimensional images than for higher dimensional images since less calculations have to be performed for fewer dimensions.
Voxel accesses are not permitted any longer after the input connection or module becomes invalid.
The virtual volume must not be used in parallel in calcOutSubImg calls since the getValue and setValue methods potentially call getTile*() functions which would start multithreading recursively. So be sure that multithreading remains disabled in the module which uses VirtualVolume or TVirtualVolume in calcOutSubImg. Even if no paged image is used as input the write accesses are not multithreading capable due to performance reasons.
If an image has n dimensions (e.g. 3) then higher components in cursor positioning and voxel accesses are simply ignored due to performance reasons and so they do not cause errors if they are set even if they mean that the cursor is outside the image.

All calls of virtual volume accesses can be executed with or without testing of correctness (see areExceptionsOn parameter of constructors). If areExceptionsOn is true then all accesses to the virtual volume are tested and if necessary exceptions are thrown which can be caught by the code calling the virtual volume methods. Otherwise most functions perform no testing. Note that exception handling versions are slower than with disabled exceptions.

Usage:
 
   // Header:
 
        VirtualVolume *_virtVolume;
 
 
   // Constructor:
 
        _virtVolume = NULL;
 
 
   // calcOutSubImgProps: Create/Update the virtual volume. Throw exception on errors.
   //                     So calculateOutputSubImage is not called with bad virtual volume later.
 
        delete _virtVolume;
 
        _virtVolume = nullptr;
 
        // Create new virtual volume and make own checks afterwards for success.
        _virtVolume = new VirtualVolume(this, 0, getInputImage(0)->getDatatype());
        if (!_virtVolume || (_virtVolume && !_virtVolume->isValid())){ getOutputImage(outIndex)->setInvalid(); return; }
 
      or
 
        // Create new virtual volume and make own checks afterwards for success.
        _virtVolume = new VirtualVolume(ImageVector(1024,1024,1,1,1,1), 0, MLuint8Type));
        if (!_virtVolume || (_virtVolume && !_virtVolume->isValid())){ getOutputImage(outIndex)->setInvalid(); return; }
 
 
   // calcOutSubImg: Example to access image data directly:
 
        TVirtualVolume<DATATYPE> vVol(*_virtVolume);  // Create wrapper for typed voxel access.
        const ImageVector pos(7,3,0,0,0,0);
        DATATYPE value=0;
        vVol.setValue(pos, value);             // Simple setting of an arbitrary voxel.
        value = vVol.getValue(pos);            // Reading of an arbitrary voxel.
        vVol.fill(outSubImg->getBox(), value); // Fill region with value.
        vVol.copyToSubImage(*outSubImg);       // Copy valid region of virtVolume to outSubImg.
 
 
   // calcOutSubImg: Example to access image data via a cursor:
 
        TVirtualVolume<DATATYPE> vVol(*_virtVolume);  // Create wrapper for typed voxel access.
        const ImageVector pos(7,3,0,0,0,0);
        vVol.setCursorPosition(pos);           // Set cursor to any position in volume.
        vVol.moveCursorX();                    // Move cursor >F<orward
        vVol.moveCursorC();                    // in (positive) X, C and U direction.
        vVol.moveCursorU();
        vVol.reverseMoveCursorT();             // Move cursor >B<ackwards in (negative) T
        vVol.reverseMoveCursorZ();             // and Z direction.
 
        DATATYPE val = vVol.getCursorValue();  // Reading voxel below cursor.
        vVol.setCursorValue(10);               // Set voxel value below cursor to 10.
 
 
 
   // Additionally the following helper routines are available:
 
       // Fill region of virtual volume with a certain value.
       void fill(const SubImageBox &box, DATATYPE value);
 
       // Copy region from the virtual volume into a typed subimage.
       void copyToSubImage(TSubImage<DATATYPE> &outSubImg);
 
       // Copy a region from a typed subimage into the virtual volume.
       void copyFromSubImage(const TSubImage<DATATYPE> &inImg, const SubImageBox &box, const ImageVector &pos);

There are also some routines to get the boxes of the currently written pages.
It is also possible to read/write the data of the written pages directly.

EXCEPTIONS:

The following exceptions are thrown if areExceptionsOn is passed as true to the constructors and errors occur:

ML_OUT_OF_RANGE - If cursor positioning or voxel accessing try to access invalid image regions. Note that these exceptions leave the virtual volume, the cursor position and voxel content etc. unchanged and the invalid flag of the virtual volume is NOT set. The call is just terminated and ignored. So you can continue to try other voxel accesses.
ML_NO_MEMORY - If any allocation fails because of insufficient memory. The virtual volume is invalidated.
ML_BAD_DIMENSION - If invalid image data extents occurred. This could indicate a programming error or invalid input image data. The virtual volume is invalidated.
ML_BAD_DATA_TYPE - If an invalid image data type occurred. This could indicate a programming error or invalid input image data. The virtual volume is invalidated.

Other exception resulting from failures of page requesting could also be thrown. They usually are returned redirected from getTile-commands.

If areExceptionsOn == false then no exceptions are thrown and many errors are handled by calling the ML_PRINT*() error macros and terminating the function/method. The virtual volume instance will be invalidated then. Invalid voxel accesses or memory failures during voxel accesses will destroy program state or cause unknown exceptions.

Note that areExceptionsOn == true degrades performance of voxel accesses.

Definition at line 210 of file mlTVirtualVolume.h.

void ml::TVirtualVolume< DATATYPE >::copyFromSubImage	(	const TSubImage< DATATYPE > &	inImg,
		const SubImageBox &	box,
		const ImageVector &	pos )

outSubImg	is the target subimage to be filled with masked voxels from this in regions overlapping this and maskBits.
maskBits	specifies voxels mask. If a bit mask value equals maskVal then the voxel from *this is copied to outSubImg if it's within the image extents.
maskValue	is the value which must be the bit value in maskBits to force a copy of a voxel value to outSubImg; default is true.
writeBK	determines whether voxel values in outSubImg are filled with bkVal in the case that voxel is not masked; default is false.
bkVal	is the value written in the case that the corresponding voxel is not masked, that writeBK is true and that voxel is within overlapping range of *this, outSubImg and maskBits; default is 0.

void ml::TVirtualVolume< DATATYPE >::fill	(	const SubImageBox &	box,
		DATATYPE	value )

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ ComponentType

Constructor & Destructor Documentation

◆ TVirtualVolume() [1/4]

◆ TVirtualVolume() [2/4]

◆ TVirtualVolume() [3/4]

◆ TVirtualVolume() [4/4]

◆ ~TVirtualVolume()

Member Function Documentation

◆ _cleanUp()

◆ _getVoxel1D()

◆ _getVoxel1DCB()

◆ _getVoxel1DCBE()

◆ _getVoxel1DE()

◆ _getVoxel2D()

◆ _getVoxel2DCB()

◆ _getVoxel2DCBE()

◆ _getVoxel2DE()

◆ _getVoxel3D()

◆ _getVoxel3DCB()

◆ _getVoxel3DCBE()

◆ _getVoxel3DE()

◆ _getVoxel4D()

◆ _getVoxel4DCB()

◆ _getVoxel4DCBE()

◆ _getVoxel4DE()

◆ _getVoxel5D()

◆ _getVoxel5DCB()

◆ _getVoxel5DCBE()

◆ _getVoxel5DE()

◆ _getVoxel6D()

◆ _getVoxel6DCB()

◆ _getVoxel6DCBE()

◆ _getVoxel6DE()

◆ _init()

◆ _isMapped1D()

◆ _isMapped1DCB()

◆ _isMapped1DCBE()

◆ _isMapped1DE()

◆ _isMapped2D()

◆ _isMapped2DCB()

◆ _isMapped2DCBE()

◆ _isMapped2DE()

◆ _isMapped3D()

◆ _isMapped3DCB()

◆ _isMapped3DCBE()

◆ _isMapped3DE()

◆ _isMapped4D()

◆ _isMapped4DCB()

◆ _isMapped4DCBE()

◆ _isMapped4DE()

◆ _isMapped5D()

◆ _isMapped5DCB()

◆ _isMapped5DCBE()

◆ _isMapped5DE()

◆ _isMapped6D()

◆ _isMapped6DCB()

◆ _isMapped6DCBE()

◆ _isMapped6DE()

◆ _moveBC()

◆ _moveBCCB()

◆ _moveBCCBE()

◆ _moveBCE()

◆ _moveBT()

◆ _moveBTCB()

◆ _moveBTCBE()

◆ _moveBTE()

◆ _moveBU()

◆ _moveBUCB()

◆ _moveBUCBE()

◆ _moveBUE()

◆ _moveBX()

◆ _moveBXCB()

◆ _moveBXCBE()