Class which represents an image, which manages properties of an image and image data which is located in pages. More...

#include <mlPagedImage.h>

Inheritance diagram for ml::PagedImage:

Public Types
enum	ThreadSupport { NO_THREAD_SUPPORT = 0 , MULTITHREADED = 1 , IO_THREAD = 4 , USE_MODULE_THREAD_SUPPORT = -1 }
	Defines the multi-threading support of the paged image. More...

Public Member Functions
	ML_FRIEND_TEST (PagedImageDeprecationTest, NewAPI)

	ML_FRIEND_TEST (PagedImageDeprecationTest, DeprecatedAPI)

	ML_FRIEND_TEST (TypedHandlersTest, SetupAndVerifyProperties)

CalculateOutputImageHandler *	getCalculateOutputImageHandler () const
	Returns the pointer to the output image calculation interface.

MLEXPORT void	setExternalCalculateOutputImageHandler (CalculateOutputImageHandler *handler)
	Sets the pointer to the output image calculation interface `handler`, the ownership is NOT passed to the PagedImage and it is not overwritten by Host::updateImageProperties().

bool	hasExternalCalculateOutputImageHandler () const
	Returns if the CalculateOutputImageHandler is an external handler and should not be overwritten.

MLEXPORT void	setCalculateOutputImageHandler (CalculateOutputImageHandler *handler)
	Sets the pointer to the output image calculation interface `handler`, the ownership is passed to the PagedImage.

MLEXPORT void	setCalculateOutputImagePropertiesCB (CalculateOutputImagePropertiesCB callback, void userData)
	Sets the `callback` and `userdata` for the calculation of the properties of this PagedImage if they need to be updated.

MLuint32	getID ()
	Returns the current image id (which changes whenever the image changes and which is unique accross all images)

void	updateID ()
	Sets that the image has changed.

MLEXPORT void	setThreadSupport (ThreadSupport support)
	Sets the thread support of the paged image to the given value.

MLEXPORT ThreadSupport	getThreadSupport () const
	Returns the current thread support of the paged image.

MLEXPORT MLMemoryBlockHandle	getPage (MLint pageID) const
	Returns the pointer to the CachedBuffer containing the data of the page with the id `pageID`.

MLEXPORT MLMemoryBlockHandle	getPageOrCreatePageRequestOrAddToPendingRequest (MLint &pageID, TileRequest tileRequest, PageRequest *newPageRequest)
	Returns the valid page handle if it exists.

MLEXPORT void	clearPendingPageRequest (MLint pageID)
	Clears a pending page request for the given page id.

MLEXPORT PagedImage &	getBypassSourceImage ()
	Returns the reference to the source image of a bypass chain.

MLEXPORT SubImageBox	getPageBox (MLint pageID) const
	Returns the rectangular region in the entire image covered by the page with the id `pageID`.

MLEXPORT void	getPageIDs (std::vector< MLint > &pageIDs, const SubImageBox &subImageBox) const
	Clears `pageIDs` and inserts the ids of all pages which need to be calculated to cover `subImageBox` completely.

MLEXPORT std::size_t	getCachedPagesSizeInBytes () const
	Returns currently used cache size for pages in bytes.

MLEXPORT MLint	getNumPages () const
	Returns the total number of pages in this output image (regardless if they are allocated or not).

MLEXPORT MLMetaProfilePtr &	getMetaProfile () const
	Returns the MLMetaProfile for this paged image. Creates it if necessary.

Construction / Destruction.
MLEXPORT	PagedImage (Module *module=nullptr, MLint outputIndex=-1)
	Constructor.

MLEXPORT	~PagedImage () override
	Destructor.

Set/Get/Update validity of image properties.
bool	isValid () const
	Returns whether image properties are valid and up-to-date.

void	setValid (bool flag=true)
	Sets image properties to valid/up-to-date, i.e., isValid() returns `true` afterwards.

void	setInvalid ()
	Sets image properties invalid, i.e., isValid() returns `false` afterwards.

MLEXPORT void	setUpdateOfImagePropertiesNeeded (bool flag)
	Sets if the update of the image properties is needed, because the ML graph has changed since the last update.

MLEXPORT bool	updateOfImagePropertiesNeeded () const
	Gets if the update of the image properties is needed, because the ML graph has changed since the last update.

MLEXPORT MLErrorCode	updateImageProperties ()
	Updates the image properties of the PagedImage using the Host::updateImageProperties method.

Setting Image and Page Properties
virtual MLEXPORT void	setImageExtent (const ImageVector &extent)
	Sets the extents of the image to `extent`. The list of valid pages and its content are cleared.

void	setImageExtent (MLint x, MLint y, MLint z=1, MLint c=1, MLint t=1, MLint u=1)
	Sets the extents of the image to the extent (x,y,z,c,t,u) and clears the list of valid pages and its content.

void	setImageExtent (const SubImageBox &box)
	Sets the extents of the image to `box.getExtent()` and updates all PagedImage settings.

virtual MLEXPORT void	setImageProperties (const PagedImage &imageProperties)
	Function to copy all associated characteristics from `imageProperties`.

MLEXPORT void	setPageExtent (const ImageVector &pageExtent)
	Sets the extents of the pages to `pageExtent`.

void	setClampPagesToImageExtent (bool flag=true)
	If enabled, the pages are clamped to the image extent, so that pages on the border of the image will not reach outside of the image.

bool	getClampPagesToImageExtent () const
	see setClampPagesToImageExtent().

void	setPageExtent (MLint x, MLint y, MLint z=1, MLint c=1, MLint t=1, MLint u=1)
	Sets the extents of the pages to the extent (x,y,z,c,t,u).

MLEXPORT void	setDataType (MLDataType dataType) override
	Sets type of data to `dataType`. Overriden to perform access check.

MLEXPORT void	setMinVoxelValue (MLdouble minval)
	Sets assumed minimum value to minval. Overriden to perform access check.

MLEXPORT void	setMaxVoxelValue (MLdouble maxval)
	Sets assumed maximum value to maxval. Overriden to perform access check.

MLEXPORT void	setPage (MLint pageID, const MLMemoryBlockHandle &page)
	Sets the given `page` handle as pagedata at `pageID`.

MLEXPORT void	removePage (MLint pageID)
	This method removes a page with id `pageID` from this instance.

MLEXPORT void	deletePageEntryFromDeletionCallback (ExtendedPageEntry *entry)
	This method removes a page referenced by the page entry.

MLEXPORT void	clearPageList ()
	Remove all pages of the page image and from the ML cache, and all page data chunks are freed, if not referenced by a memory block handle elsewhere.

MLEXPORT void	clearPageListAndMemoryImage ()
	Remove all pages of the page image and from the ML cache, and all page data chunks are freed.

Property state info.
virtual MLEXPORT void	setStateInfo (const std::string &info, MLErrorCode errorCode)
	Sets the state information for this PagedImage to the string `info` and the MLErrorCode `errorCode`.

virtual MLEXPORT void	setStateInfoErrorCode (MLErrorCode errorCode)
	Sets the state information as MLErrorCode `errorCode` for this instance.

virtual MLEXPORT const std::string &	getStateInfoString () const
	Returns the current state information string which might explain something about the state of this instance.

virtual MLEXPORT MLErrorCode	getStateInfoErrorCode () const
	Returns the current state information as MLError code which might explain something about the state of this instance.

Bypass handling.
void	setBypassIndex (MLint index)
	Sets the `index` of the input image whose pages should be used instead of the pages of this image.

MLint	getBypassIndex () const
	Returns the index of the input image whose pages should be used instead of the pages of this image or -1 if bypassing is disabled.

Property query
Module *	getModule () const
	Returns the associated Module instance if passed to the constructor, NULL otherwise.

MLEXPORT const PagedImage *	getInputImage (int inputIndex) const
	Returns the input image at `inputIndex` of the associated Module.

MLint	getOutputIndex () const
	Returns associated output index of Module instance if passed to constructor, -1 otherwise.

ImageVector	getPageSetExtent () const
	Returns the extents of the page set covering the entire image extents.

ImageVector	getPageStride () const
	Returns the stride to get from one page to another.

ImageVector	getPageExtent () const
	Returns the extent of a page.

MLint	getPageID (const ImageVector &voxelPosition) const
	Returns the id of that page which contains the image voxel position `voxelPosition`.

MemoryImage &	getMemoryImage ()
	Permits the access to a memory cached output of the paged image.

const MemoryImage &	getMemoryImage () const

Page inplace handling.
void	setInPlaceIndex (MLint inputIndex)
	Set optimization flag: If calculating a page in calculateOutputSubImage() the output image page shall use the same memory as the input page at `inputIndex`.

MLint	getInPlaceIndex () const
	Return optimization flag: Return index of input image whose input tile is used also as output page in calculateOutputSubImage() (instead of allocating its own memory).

Setting the properties of input subimages/tiles for Module::calculateOutputSubImage
The following methods allow to define the properties of the input subimages that are passed to the Module::calculateOutputSubImage(). The default behavior is to provide all input subimages in the datatype of the output image. Using the methods below, this behavior can be modified, to e.g., use the input iamge datatype for the input subimages.
MLEXPORT void	setInputSubImageDataType (int inputIndex, MLDataType dataType)
	Sets the `dataType` for the given `inputIndex`.

MLEXPORT void	setInputSubImageIsReadOnly (int inputIndex, bool readOnly)
	Sets that the input sub image for the input image at `inputIndex` to `readOnly`.

MLEXPORT void	setInputSubImagesAreReadOnly (bool readOnly=true)
	Sets the read-only flag for all input images (see setInputSubImageIsReadOnly() for details)

MLEXPORT void	setInputSubImageUseMemoryImage (int inputIndex, bool useMemoryImage)
	Sets that the input sub image for the input image at `inputIndex` should use a memory image (this implicitly sets setInSubImageIsReadOnly() to true as well).

MLEXPORT void	setInputSubImageScaleShift (int inputIndex, const ScaleShiftData &scaleShift)
	Sets that the input sub image for the input image at `inputIndex` should be rescaled with the given `scaleShift` data The default is to not shift/scale at all.

MLEXPORT const InputSubImageProperties &	getInputSubImageProperties (int inputIndex) const
	Returns a const reference to the InputSubImageProperties of the given input image at `inputIndex`.

MLEXPORT MLDataType	getInputSubImageDataType (int inputIndex) const
	Returns the input sub image data type for the input image at `inputIndex`.

MLEXPORT bool	getInputSubImageIsReadOnly (int inputIndex) const
	Returns if input sub image at `inputIndex` is set to 'read-only'.

Joining and copying Pages into sequential storage areas
MLEXPORT void	copyPages (const std::vector< MLint > &pageIDs, SubImage *subImage, const ScaleShiftData &scaleShiftData=ScaleShiftData()) const
	Fills the `subImage` with contents of the Pages with the IDs `pagesIDs` The grey values become according to the Pages the parameters `scaleShiftData`.

Requesting data with wrapped functionality from Host
MLEXPORT MLErrorCode	getTile (SubImageBox location, MLDataType dataType, void *data, const ScaleShiftData &scaleShiftData=ScaleShiftData(), MLRequestProgressCB progressCallback=nullptr, void *progressCallbackUserData=nullptr)
	See Host::getTile( module, outputIndex, location, dataType, data, scaleShiftData).

MLEXPORT MLErrorCode	getTile (SubImage &subImage, const ScaleShiftData &scaleShiftData=ScaleShiftData(), MLRequestProgressCB progressCallback=nullptr, void progressCallbackUserData=nullptr)
	See Host::getTile( module, outputIndex, subImg, scaleShiftData).

MLEXPORT void	freeTile (void *data)
	Same as corresponding Host::freeTile(void *data).

MLEXPORT MLdouble	getInterpolatedValue (const Vector3 &pos, MLint c=0, MLint t=0, MLint u=0, MLdouble outsideFillValue=0)
	Get trilinear interpolated image value at given voxel position (center of a voxel is 0.5,0.5,0.5).

Public Member Functions inherited from ml::MedicalImageProperties
	MedicalImageProperties ()
	Constructor.

	~MedicalImageProperties () override
	Destructor. Cleans up dynamically allocated memory.

	MedicalImageProperties (const MedicalImageProperties &medicalImageProperties)
	Copy constructor from an existing `medicalImageProperties` object to get a copy.

MedicalImageProperties &	operator= (const MedicalImageProperties &medicalImageProperties)
	Assignment operator from an existing `edicalImageProperties` object to get a copy.

void	setImageProperties (const MedicalImageProperties &medicalImageProperties)
	Sets a copy of the passed image properties `medicalImageProperties`.

bool	operator== (const MedicalImageProperties &medicalImageProperties) const
	Returns true if *this and `medicalImageProperties` are identical, otherwise false.

bool	operator!= (const MedicalImageProperties &medicalImageProperties) const
	Returns true if *this and `medicalImageProperties` differ, otherwise false.

void	setVoxelSize (MLdouble dx, MLdouble dy, MLdouble dz)
	Sets the voxel size to `dx`, `dy` and `dz`. This changes the voxelToWorld matrix.

void	setVoxelSize (const Vector3 &voxelSize)
	Sets the voxel size to `voxelSize`. The transformation matrix is adapted adequately.

Vector3	getVoxelSize () const
	Returns the voxel size.

double	getVoxelVolumeInCubicMillimeters () const
	Returns the volume of a single voxel in cubic millimeters (mm3).

double	getVoxelVolumeInMilliliters () const
	Returns the volume of a single voxel in milliliters (ml).

bool	isVoxelToWorldMatrixValid () const
	Shows the validity state of the VoxelToWorldMatrix (default=true=valid).

void	setVoxelToWorldMatrixValid (bool valid)
	Validates/Invalidates the VoxelToWorld matrix by passing true/false as `valid`.

const Matrix4 &	getVoxelToWorldMatrix () const
	Returns the voxelToWorld matrix.

void	setVoxelToWorldMatrix (const Matrix4 &matrix)
	Sets the matrix which transforms voxel to world coordinates to `matrix`.

const Matrix4 &	getWorldToVoxelMatrix () const
	Returns the worlToVoxel matrix.

Vector3	mapVoxelToWorld (const Vector3 &voxelPosition) const
	Maps the `voxelPosition` vector to world coordinates and returns it.

Vector3	mapWorldToVoxel (const Vector3 &worldPosition) const
	Maps the `worldPosition` vector to voxel coordinates and returns it.

void	scaleVoxelToWorldMatrix (const Vector3 &scaleFactors)
	Scales the voxelToWorld matrix by the vector `scaleFactors` and updates the image's voxel size.

void	translateVoxelToWorldMatrix (const Vector3 &offsetVector)
	Translates the voxelToWorld matrix by the `offsetVector`.

std::vector< std::string > &	getCDimensionInfos ()
	Permits access to the additional information for subimages on the c-, t- and u-dimensions.

std::vector< DateTime > &	getTDimensionInfos ()

std::vector< std::string > &	getUDimensionInfos ()

const std::vector< std::string > &	getCDimensionInfos () const

const std::vector< DateTime > &	getTDimensionInfos () const

const std::vector< std::string > &	getUDimensionInfos () const

ImagePropertyExtensionContainer &	getImagePropertyContainer ()
	Permits access to the container for user image properties.

const ImagePropertyExtensionContainer &	getConstImagePropertyContainer () const

Public Member Functions inherited from ml::ImageProperties
MLEXPORT	ImageProperties ()
	Constructor.

virtual MLEXPORT	~ImageProperties ()
	Virtual destructor to suppress compiler warnings.

MLEXPORT	ImageProperties (ImageVector extent, MLDataType dataType, MLdouble minValue, MLdouble maxValue)
	Constructor to set extent to `extent`, data type to `dataType`, minimum value to `minValue` and maximum value to `maxValue`.

MLEXPORT	ImageProperties (const ImageProperties &imageProperties)
	Copy constructor from an existing `imageProperties` object to get an identical copy.

MLEXPORT ImageProperties &	operator= (const ImageProperties &imageProperties)
	Assignment operator from an existing `imageProperties` object to get an identical copy.

MLEXPORT void	setImageProperties (const ImageProperties &imageProperties)
	Copy property parameters from another image property instance `imageProperties`.

MLEXPORT bool	operator== (const ImageProperties &imageProperties) const
	Returns true if *this and `imageProperties` are identical, otherwise false.

MLEXPORT bool	operator!= (const ImageProperties &imageProperties) const
	Returns true if *this and `imageProperties` differ, otherwise false.

MLEXPORT void	setImageExtent (const ImageVector &extent)
	Sets the `extent` of the (sub)image.

ImageVector	getImageExtent () const
	Returns the extent of the (sub)image.

SubImageBox	getBoxFromImageExtent () const
	Returns size of image as box with origin 0.

bool	hasValidExtent () const
	Returns if the image has a valid extent (which means that all components are greater than 0).

MLint	getNumVoxels () const
	Returns number of voxels in (sub)image.

MLint	getSizeInBytes () const
	Returns number of potential bytes in (sub)image.

MLDataType	getDataType () const
	Returns the data type of the image.

void	setMinVoxelValue (MLdouble minval)
	Sets assumed minimum value to minval.

MLdouble	getMinVoxelValue () const
	Returns the assumed minimum value in data.

void	setMaxVoxelValue (MLdouble maxval)
	Sets assumed maximum value to maxval.

MLdouble	getMaxVoxelValue () const
	Returns the assumed maximum value in data.

Static Public Member Functions
static MLEXPORT void	getPageIDs (std::vector< MLint > &pageIDs, const SubImageBox &subImageBox, const ImageVector &imageExtent, const ImageVector &pageExtent)
	Clears `pageIDs` and inserts the ids of all pages which need to be calculated to cover `subImageBox` completely.

static MLEXPORT void	setPageCountLimitToUsePageEntryMap (MLuint32 limit)
	Sets the `limit` of number of pages for using the page entry map instead of the page list.

static MLEXPORT MLuint32	getPageCountLimitToUsePageEntryMap ()
	Returns the limit of number of pages for using the page entry map instead of the page list.

Protected Member Functions
MLEXPORT void	calculateImageProperties ()
	Updates the image properties via the Module::calculateOutputImageProperties or via CalculateOutputImagePropertiesCB if it is set.

MLEXPORT void	initializeInputSubImageProperties (MLint numInputs)
	Initializes the InSubImageProps for a given number of inputs, should only be called by the Host!

MLEXPORT void	validateInputSubImagePropertiesAfterCalculateOutputImageProperties ()
	Validates the properties and set datatype where it was not set, should only be called by the Host!

Friends
class	Host
	the host may access some methods that are otherwise not available

Detailed Description

Class which represents an image, which manages properties of an image and image data which is located in pages.

Definition at line 65 of file mlPagedImage.h.

Member Enumeration Documentation

◆ ThreadSupport

enum ml::PagedImage::ThreadSupport

Defines the multi-threading support of the paged image.

Enumerator
NO_THREAD_SUPPORT	< The image can only be calculated from the main thread
MULTITHREADED	< The calculation of the image data can be called from multiple threads
IO_THREAD	< The calculation of the image data can be called from a designated IO thread
USE_MODULE_THREAD_SUPPORT	< Use the overall thread support flag of the module.

Definition at line 78 of file mlPagedImage.h.

Constructor & Destructor Documentation

◆ PagedImage()

MLEXPORT ml::PagedImage::PagedImage	(	Module *	module = nullptr,
		MLint	outputIndex = -1 )

Constructor.

Parameters

module	is the Module instance which uses this paged image inside of one of its output connectors, default is NULL.
outputIndex	is the index of the output connector of `module` which contains *this; default is -1. Note: `module` and `outputIndex` are only used by getTile/freeTile methods. If they are not used, the default parameters can be used.

◆ ~PagedImage()

MLEXPORT ml::PagedImage::~PagedImage ( )

override

Destructor.

Remove all pages and reset corresponding memory image if it is controlled by the ML.

Member Function Documentation

◆ calculateImageProperties()

MLEXPORT void ml::PagedImage::calculateImageProperties ( )

protected

Updates the image properties via the Module::calculateOutputImageProperties or via CalculateOutputImagePropertiesCB if it is set.

◆ clearPageList()

MLEXPORT void ml::PagedImage::clearPageList ( )

Remove all pages of the page image and from the ML cache, and all page data chunks are freed, if not referenced by a memory block handle elsewhere.

After this call holds getPage(ID)=0 for all pages of the image.

◆ clearPageListAndMemoryImage()

MLEXPORT void ml::PagedImage::clearPageListAndMemoryImage ( )

Remove all pages of the page image and from the ML cache, and all page data chunks are freed.

Pages are also removed if they are locked pages. After this call holds getPage(ID)=0 for all pages of the image. It also clears the memoryImg if the memoryImg mode is adequate.

◆ clearPendingPageRequest()

MLEXPORT void ml::PagedImage::clearPendingPageRequest ( MLint pageID )

Clears a pending page request for the given page id.

◆ copyPages()

MLEXPORT void ml::PagedImage::copyPages	(	const std::vector< MLint > &	pageIDs,
		SubImage *	subImage,
		const ScaleShiftData &	scaleShiftData = ScaleShiftData() ) const

Fills the subImage with contents of the Pages with the IDs pagesIDs The grey values become according to the Pages the parameters scaleShiftData.

(class ScaleShiftData) linear transformation. Remark:

by the linear transformation of the grey values before copying, one can avoid the overflows by type Casting.
for the default value of scaleShiftData applies for scaleShiftData.getScale()==1 and scaleShiftData.getShift()==0. Thus the grey value transformation does not cause anything and a copying with a special routine is more efficiently implemented.

◆ deletePageEntryFromDeletionCallback()

MLEXPORT void ml::PagedImage::deletePageEntryFromDeletionCallback ( ExtendedPageEntry * entry )

This method removes a page referenced by the page entry.

It removes the page entry of entry->pageId only if the stored pointer in the page entry map is the same as entry. It finally deletes the page entry.

◆ freeTile()

MLEXPORT void ml::PagedImage::freeTile ( void * data )

Same as corresponding Host::freeTile(void *data).

◆ getBypassIndex()

MLint ml::PagedImage::getBypassIndex ( ) const

inline

Returns the index of the input image whose pages should be used instead of the pages of this image or -1 if bypassing is disabled.

Definition at line 295 of file mlPagedImage.h.

◆ getBypassSourceImage()

MLEXPORT PagedImage & ml::PagedImage::getBypassSourceImage ( )

Returns the reference to the source image of a bypass chain.

◆ getCachedPagesSizeInBytes()

MLEXPORT std::size_t ml::PagedImage::getCachedPagesSizeInBytes ( ) const

Returns currently used cache size for pages in bytes.

◆ getCalculateOutputImageHandler()

CalculateOutputImageHandler * ml::PagedImage::getCalculateOutputImageHandler ( ) const

inline

Returns the pointer to the output image calculation interface.

Definition at line 113 of file mlPagedImage.h.

◆ getClampPagesToImageExtent()

bool ml::PagedImage::getClampPagesToImageExtent ( ) const

inline

see setClampPagesToImageExtent().

Definition at line 209 of file mlPagedImage.h.

◆ getID()

MLuint32 ml::PagedImage::getID ( )

inline

Returns the current image id (which changes whenever the image changes and which is unique accross all images)

Definition at line 129 of file mlPagedImage.h.

◆ getInPlaceIndex()

MLint ml::PagedImage::getInPlaceIndex ( ) const

inline

Return optimization flag: Return index of input image whose input tile is used also as output page in calculateOutputSubImage() (instead of allocating its own memory).

If inplace calculation is off then -1 is returned. Using inplace require that page extent and voxel data type remain unchanged or errors will occur or that the ML will disable inplace calculations automatically in some cases.

Definition at line 410 of file mlPagedImage.h.

◆ getInputImage()

MLEXPORT const PagedImage * ml::PagedImage::getInputImage ( int inputIndex ) const

Returns the input image at inputIndex of the associated Module.

◆ getInputSubImageDataType()

MLEXPORT MLDataType ml::PagedImage::getInputSubImageDataType ( int inputIndex ) const

Returns the input sub image data type for the input image at inputIndex.

◆ getInputSubImageIsReadOnly()

MLEXPORT bool ml::PagedImage::getInputSubImageIsReadOnly ( int inputIndex ) const

Returns if input sub image at inputIndex is set to 'read-only'.

◆ getInputSubImageProperties()

MLEXPORT const InputSubImageProperties & ml::PagedImage::getInputSubImageProperties ( int inputIndex ) const

Returns a const reference to the InputSubImageProperties of the given input image at inputIndex.

Indexes outside the bounds of 0-Module::getNumInputs()-1 will be handled fatally.

◆ getInterpolatedValue()

MLEXPORT MLdouble ml::PagedImage::getInterpolatedValue	(	const Vector3 &	pos,
		MLint	c = 0,
		MLint	t = 0,
		MLint	u = 0,
		MLdouble	outsideFillValue = 0 )

Get trilinear interpolated image value at given voxel position (center of a voxel is 0.5,0.5,0.5).

This method can be used for random access, but should not be used to e.g. resample a full dataset, since it has a much larger overhead compared to modules that do the resampling on pages. Values on the image border are filled with the nearest image values and values completely outside of the image are filled with outsideFillValue.

◆ getMemoryImage() [1/2]

MemoryImage & ml::PagedImage::getMemoryImage ( )

inline

Permits the access to a memory cached output of the paged image.

It can be used by the module and by the host for caching the paged image. Who controls this image is defined by _memoryImage.

Definition at line 330 of file mlPagedImage.h.

◆ getMemoryImage() [2/2]

const MemoryImage & ml::PagedImage::getMemoryImage ( ) const

inline

Definition at line 331 of file mlPagedImage.h.

◆ getMetaProfile()

MLEXPORT MLMetaProfilePtr & ml::PagedImage::getMetaProfile ( ) const

Returns the MLMetaProfile for this paged image. Creates it if necessary.

◆ getModule()

Module * ml::PagedImage::getModule ( ) const

inline

Returns the associated Module instance if passed to the constructor, NULL otherwise.

Definition at line 305 of file mlPagedImage.h.

◆ getNumPages()

MLEXPORT MLint ml::PagedImage::getNumPages ( ) const

inline

Returns the total number of pages in this output image (regardless if they are allocated or not).

Definition at line 383 of file mlPagedImage.h.

◆ getOutputIndex()

MLint ml::PagedImage::getOutputIndex ( ) const

inline

Returns associated output index of Module instance if passed to constructor, -1 otherwise.

Definition at line 311 of file mlPagedImage.h.

◆ getPage()

MLEXPORT MLMemoryBlockHandle ml::PagedImage::getPage ( MLint pageID ) const

Returns the pointer to the CachedBuffer containing the data of the page with the id pageID.

◆ getPageBox()

MLEXPORT SubImageBox ml::PagedImage::getPageBox ( MLint pageID ) const

Returns the rectangular region in the entire image covered by the page with the id pageID.

◆ getPageCountLimitToUsePageEntryMap()

static MLEXPORT MLuint32 ml::PagedImage::getPageCountLimitToUsePageEntryMap ( )

inlinestatic

Returns the limit of number of pages for using the page entry map instead of the page list.

Definition at line 545 of file mlPagedImage.h.

◆ getPageExtent()

ImageVector ml::PagedImage::getPageExtent ( ) const

inline

Returns the extent of a page.

Definition at line 320 of file mlPagedImage.h.

◆ getPageID()

MLint ml::PagedImage::getPageID ( const ImageVector & voxelPosition ) const

inline

Returns the id of that page which contains the image voxel position voxelPosition.

Definition at line 323 of file mlPagedImage.h.

◆ getPageIDs() [1/2]

MLEXPORT void ml::PagedImage::getPageIDs	(	std::vector< MLint > &	pageIDs,
		const SubImageBox &	subImageBox ) const

Clears pageIDs and inserts the ids of all pages which need to be calculated to cover subImageBox completely.

◆ getPageIDs() [2/2]

static MLEXPORT void ml::PagedImage::getPageIDs	(	std::vector< MLint > &	pageIDs,
		const SubImageBox &	subImageBox,
		const ImageVector &	imageExtent,
		const ImageVector &	pageExtent )

static

Clears pageIDs and inserts the ids of all pages which need to be calculated to cover subImageBox completely.

Static version of the upper method which also requires the extent of the image given by imageExtent and the extent of the pages pageExtent.

◆ getPageOrCreatePageRequestOrAddToPendingRequest()

MLEXPORT MLMemoryBlockHandle ml::PagedImage::getPageOrCreatePageRequestOrAddToPendingRequest	(	MLint &	pageID,
		TileRequest *	tileRequest,
		PageRequest **	newPageRequest )

Returns the valid page handle if it exists.

If no page data exists and there is a pending page request, the tileRequest is added to the pending request. If no page data and no page request is pending, a new PageRequest is allocated and returned via newPageRequest. The pageID is passed by reference because in an error situation has to be reset and used outside of the method itself.

◆ getPageSetExtent()

ImageVector ml::PagedImage::getPageSetExtent ( ) const

inline

Returns the extents of the page set covering the entire image extents.

Definition at line 314 of file mlPagedImage.h.

◆ getPageStride()

ImageVector ml::PagedImage::getPageStride ( ) const

inline

Returns the stride to get from one page to another.

Definition at line 317 of file mlPagedImage.h.

◆ getStateInfoErrorCode()

virtual MLEXPORT MLErrorCode ml::PagedImage::getStateInfoErrorCode ( ) const

virtual

Returns the current state information as MLError code which might explain something about the state of this instance.

◆ getStateInfoString()

virtual MLEXPORT const std::string & ml::PagedImage::getStateInfoString ( ) const

virtual

Returns the current state information string which might explain something about the state of this instance.

◆ getThreadSupport()

MLEXPORT ThreadSupport ml::PagedImage::getThreadSupport ( ) const

Returns the current thread support of the paged image.

If the thread support is set to USE_MODULE_THREAD_SUPPORT, this method returns the thread support of the owning module.

◆ getTile() [1/2]

MLEXPORT MLErrorCode ml::PagedImage::getTile	(	SubImage &	subImage,
		const ScaleShiftData &	scaleShiftData = ScaleShiftData(),
		MLRequestProgressCB *	progressCallback = nullptr,
		void *	progressCallbackUserData = nullptr )

See Host::getTile( module, outputIndex, subImg, scaleShiftData).

The call of this method requires that valid module and outputIndex parameters have been passed to the constructor. This is true if this instance is part of an output connector of a Module.

◆ getTile() [2/2]

MLEXPORT MLErrorCode ml::PagedImage::getTile	(	SubImageBox	location,
		MLDataType	dataType,
		void **	data,
		const ScaleShiftData &	scaleShiftData = ScaleShiftData(),
		MLRequestProgressCB *	progressCallback = nullptr,
		void *	progressCallbackUserData = nullptr )

See Host::getTile( module, outputIndex, location, dataType, data, scaleShiftData).

The call of this method requires that valid module and outputIndex parameters have been passed to the constructor. This is true if this instance is part of an output connector of a Module.

◆ hasExternalCalculateOutputImageHandler()

bool ml::PagedImage::hasExternalCalculateOutputImageHandler ( ) const

inline

Returns if the CalculateOutputImageHandler is an external handler and should not be overwritten.

Definition at line 120 of file mlPagedImage.h.

◆ initializeInputSubImageProperties()

MLEXPORT void ml::PagedImage::initializeInputSubImageProperties ( MLint numInputs )

protected

Initializes the InSubImageProps for a given number of inputs, should only be called by the Host!

◆ isValid()

bool ml::PagedImage::isValid ( ) const

inline

Returns whether image properties are valid and up-to-date.

The default of a new instance is false. The validity is changed only by the methods setValid() and setInvalid(), all other functions/ methods do not change the valid state of the instance.

Definition at line 143 of file mlPagedImage.h.

◆ ML_FRIEND_TEST() [1/3]

ml::PagedImage::ML_FRIEND_TEST	(	PagedImageDeprecationTest	,
		DeprecatedAPI	)

◆ ML_FRIEND_TEST() [2/3]

ml::PagedImage::ML_FRIEND_TEST	(	PagedImageDeprecationTest	,
		NewAPI	)

◆ ML_FRIEND_TEST() [3/3]

ml::PagedImage::ML_FRIEND_TEST	(	TypedHandlersTest	,
		SetupAndVerifyProperties	)

◆ removePage()

MLEXPORT void ml::PagedImage::removePage ( MLint pageID )

This method removes a page with id pageID from this instance.

If it is no more referenced by another memory block handle, it is freed immediately.

◆ setBypassIndex()

void ml::PagedImage::setBypassIndex ( MLint index )

inline

Sets the index of the input image whose pages should be used instead of the pages of this image.

The index = -1 disables the option to find pages also in an input image. Bypassing requires that image (data) content, image extent, page extent and voxel data type remain unchanged or errors will occur.

Definition at line 291 of file mlPagedImage.h.

◆ setCalculateOutputImageHandler()

MLEXPORT void ml::PagedImage::setCalculateOutputImageHandler ( CalculateOutputImageHandler * handler )

Sets the pointer to the output image calculation interface handler, the ownership is passed to the PagedImage.

◆ setCalculateOutputImagePropertiesCB()

MLEXPORT void ml::PagedImage::setCalculateOutputImagePropertiesCB	(	CalculateOutputImagePropertiesCB *	callback,
		void *	userData )

Sets the callback and userdata for the calculation of the properties of this PagedImage if they need to be updated.

◆ setClampPagesToImageExtent()

void ml::PagedImage::setClampPagesToImageExtent ( bool flag = true )

inline

If enabled, the pages are clamped to the image extent, so that pages on the border of the image will not reach outside of the image.

This means that Module::calculateOutputSubImage and Module::calculateInputSubImageBox will get called with pages of different sizes. If disabled (which is the default), all pages will have the same size, even if they are partly outside of the image extent. The advantage of enabling the clamping is less memory usage and that the implementation of calculateOutputSubImage() does not need to use the valid region of the SubImage, since the whole page will always be in the valid region.

Definition at line 206 of file mlPagedImage.h.

References mlrange_cast().

◆ setDataType()

MLEXPORT void ml::PagedImage::setDataType ( MLDataType dataType )

overridevirtual

Sets type of data to dataType. Overriden to perform access check.

Reimplemented from ml::ImageProperties.

Referenced by ml::ClusterHandler< CLUSTERVOXELTYPE, DerivedAlgorithm >::calculateOutputImageProperties().

◆ setExternalCalculateOutputImageHandler()

MLEXPORT void ml::PagedImage::setExternalCalculateOutputImageHandler ( CalculateOutputImageHandler * handler )

Sets the pointer to the output image calculation interface handler, the ownership is NOT passed to the PagedImage and it is not overwritten by Host::updateImageProperties().

◆ setImageExtent() [1/3]

virtual MLEXPORT void ml::PagedImage::setImageExtent ( const ImageVector & extent )

virtual

Sets the extents of the image to extent. The list of valid pages and its content are cleared.

Referenced by ml::ClusterHandler< CLUSTERVOXELTYPE, DerivedAlgorithm >::calculateOutputImageProperties().

◆ setImageExtent() [2/3]

void ml::PagedImage::setImageExtent ( const SubImageBox & box )

inline

Sets the extents of the image to box.getExtent() and updates all PagedImage settings.

The list of valid pages and its content are cleared.

Definition at line 185 of file mlPagedImage.h.

References ml::TSubImageBox< intT >::getExtent(), and setImageExtent().

Referenced by setImageExtent().

◆ setImageExtent() [3/3]

void ml::PagedImage::setImageExtent	(	MLint	x,
		MLint	y,
		MLint	z = 1,
		MLint	c = 1,
		MLint	t = 1,
		MLint	u = 1 )

inline

Sets the extents of the image to the extent (x,y,z,c,t,u) and clears the list of valid pages and its content.

The default value for missing dimensions is 1.

Definition at line 178 of file mlPagedImage.h.

References ml::ImageProperties::setImageExtent().

◆ setImageProperties()

virtual MLEXPORT void ml::PagedImage::setImageProperties ( const PagedImage & imageProperties )

virtual

Function to copy all associated characteristics from imageProperties.

Inherited image characteristics as well as all MedicalImageProperties. Note that it usually does only properties and not page or image contents. The list of valid pages and its content are cleared and virgin.

◆ setInPlaceIndex()

void ml::PagedImage::setInPlaceIndex ( MLint inputIndex )

inline

Set optimization flag: If calculating a page in calculateOutputSubImage() the output image page shall use the same memory as the input page at inputIndex.

So less allocations occur and the read and written buffer are identical. Usually only useful for pixel operations or algorithms which do not modify the image data. Using inplace require that page extent and voxel data type remain unchanged or errors will occur or that the ML will disable inplace calculations automatically in some cases.

Definition at line 401 of file mlPagedImage.h.

References mlrange_cast().

◆ setInputSubImageDataType()

MLEXPORT void ml::PagedImage::setInputSubImageDataType	(	int	inputIndex,
		MLDataType	dataType )

Sets the dataType for the given inputIndex.

If this method is not called, the default is the output data type (getDataType()) after the Module::calculateOutputImageProperties() call. Note that your algorithm in Module::calculateOutputSubImage has to support different data types for in- and output subimages if you change the data type. NOTE: This should only be called from within Module::calculateOutputImageProperties().

Referenced by ml::ClusterHandler< CLUSTERVOXELTYPE, DerivedAlgorithm >::calculateOutputImageProperties().

◆ setInputSubImageIsReadOnly()

MLEXPORT void ml::PagedImage::setInputSubImageIsReadOnly	(	int	inputIndex,
		bool	readOnly )

Sets that the input sub image for the input image at inputIndex to readOnly.

This means it is not allowed to write to this input sub image in Module::calculateOutputSubImage(). To ensure that your module supports this, you should use a "const TSubImage" to ensure that the data is only accessed via const pointers. For the Host to make usage of this, the SubImageBox of the input subimage needs to match that of an input page, otherwise the input data needs to be copied anyways. NOTE: This should only be called from within Module::calculateOutputImageProperties().

◆ setInputSubImagesAreReadOnly()

MLEXPORT void ml::PagedImage::setInputSubImagesAreReadOnly ( bool readOnly = true )

Sets the read-only flag for all input images (see setInputSubImageIsReadOnly() for details)

Referenced by ml::ClusterHandler< CLUSTERVOXELTYPE, DerivedAlgorithm >::calculateOutputImageProperties().

◆ setInputSubImageScaleShift()

MLEXPORT void ml::PagedImage::setInputSubImageScaleShift	(	int	inputIndex,
		const ScaleShiftData &	scaleShift )

Sets that the input sub image for the input image at inputIndex should be rescaled with the given scaleShift data The default is to not shift/scale at all.

NOTE: This should only be called from within Module::calculateOutputImageProperties().

◆ setInputSubImageUseMemoryImage()

MLEXPORT void ml::PagedImage::setInputSubImageUseMemoryImage	(	int	inputIndex,
		bool	useMemoryImage )

Sets that the input sub image for the input image at inputIndex should use a memory image (this implicitly sets setInSubImageIsReadOnly() to true as well).

This is turned off on default. When requesting this, make sure that you return the complete input image box in Module::calculateInputSubImageBox(). If this is set to true and the input module does not control its memory image itself then the host saves the input volume in the memory output of the input image. So the input tile does not have to be calculated many times if many modules request it. So a significant memory and performance gain may result if many connected modules request the same output page and at least one of them enables this flag. NOTE: Use the flag useMemoryImage only if really necessary, because it usually assumes that the entire input image is cached at the output of the input module. This breaks the page based image processing and may require a lot of memory. Also it requests the entire input image through predecessor modules which may use a lot of processing time. NOTE: This should only be called from within Module::calculateOutputImageProperties().

◆ setInvalid()

void ml::PagedImage::setInvalid ( )

inline

Sets image properties invalid, i.e., isValid() returns false afterwards.

Definition at line 151 of file mlPagedImage.h.

◆ setMaxVoxelValue()

MLEXPORT void ml::PagedImage::setMaxVoxelValue ( MLdouble maxval )

Sets assumed maximum value to maxval. Overriden to perform access check.

◆ setMinVoxelValue()

MLEXPORT void ml::PagedImage::setMinVoxelValue ( MLdouble minval )

Sets assumed minimum value to minval. Overriden to perform access check.

◆ setPage()

MLEXPORT void ml::PagedImage::setPage	(	MLint	pageID,
		const MLMemoryBlockHandle &	page )

Sets the given page handle as pagedata at pageID.

◆ setPageCountLimitToUsePageEntryMap()

static MLEXPORT void ml::PagedImage::setPageCountLimitToUsePageEntryMap ( MLuint32 limit )

inlinestatic

Sets the limit of number of pages for using the page entry map instead of the page list.

Definition at line 542 of file mlPagedImage.h.

References mlrange_cast().

◆ setPageExtent() [1/2]

MLEXPORT void ml::PagedImage::setPageExtent ( const ImageVector & pageExtent )

Sets the extents of the pages to pageExtent.

Referenced by ml::ClusterHandler< CLUSTERVOXELTYPE, DerivedAlgorithm >::calculateOutputImageProperties().

◆ setPageExtent() [2/2]

void ml::PagedImage::setPageExtent	(	MLint	x,
		MLint	y,
		MLint	z = 1,
		MLint	c = 1,
		MLint	t = 1,
		MLint	u = 1 )

inline

Sets the extents of the pages to the extent (x,y,z,c,t,u).

The default value for missing dimensions is 1.

Definition at line 213 of file mlPagedImage.h.

◆ setStateInfo()

virtual MLEXPORT void ml::PagedImage::setStateInfo	(	const std::string &	info,
		MLErrorCode	errorCode )

virtual

Sets the state information for this PagedImage to the string info and the MLErrorCode errorCode.

Calling this method only changes the state information, but no data or validity of the instance itself. This method can be called by module programmers in calculateOutputImageProperties() to describe why they invalidated the module output.

◆ setStateInfoErrorCode()

virtual MLEXPORT void ml::PagedImage::setStateInfoErrorCode ( MLErrorCode errorCode )

virtual

Sets the state information as MLErrorCode errorCode for this instance.

It also sets the stateInfoString to the corresponding MLErrorCode. Calling this method only changes the state information, but no data or validity of the instance itself. This method can be called by module programmers in calculateOutputImageProperties() to describe why they invalidated the module output.

◆ setThreadSupport()

MLEXPORT void ml::PagedImage::setThreadSupport ( ThreadSupport support )

inline

Sets the thread support of the paged image to the given value.

This should only be called/changed from within calculateOutputImageProperties(). If it is set to USE_MODULE_THREAD_SUPPORT (which is the default), the thread support of the owning module is used.

Definition at line 338 of file mlPagedImage.h.

References mlrange_cast().

◆ setUpdateOfImagePropertiesNeeded()

MLEXPORT void ml::PagedImage::setUpdateOfImagePropertiesNeeded ( bool flag )

Sets if the update of the image properties is needed, because the ML graph has changed since the last update.

This sets the isOutOfDate() flag as well if set to true.

◆ setValid()

void ml::PagedImage::setValid ( bool flag = true )

inline

Sets image properties to valid/up-to-date, i.e., isValid() returns true afterwards.

Definition at line 147 of file mlPagedImage.h.

References mlrange_cast().

◆ updateID()

void ml::PagedImage::updateID ( )

inline

Sets that the image has changed.

Definition at line 132 of file mlPagedImage.h.

◆ updateImageProperties()

MLEXPORT MLErrorCode ml::PagedImage::updateImageProperties ( )

Updates the image properties of the PagedImage using the Host::updateImageProperties method.

◆ updateOfImagePropertiesNeeded()

MLEXPORT bool ml::PagedImage::updateOfImagePropertiesNeeded ( ) const

inline

Gets if the update of the image properties is needed, because the ML graph has changed since the last update.

Definition at line 159 of file mlPagedImage.h.

◆ validateInputSubImagePropertiesAfterCalculateOutputImageProperties()

MLEXPORT void ml::PagedImage::validateInputSubImagePropertiesAfterCalculateOutputImageProperties ( )

protected

Validates the properties and set datatype where it was not set, should only be called by the Host!

Friends And Related Symbol Documentation

◆ Host

friend class Host

friend

the host may access some methods that are otherwise not available

Definition at line 86 of file mlPagedImage.h.

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

MeVis/Foundation/Sources/ML/include/mlPagedImage.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ ThreadSupport

Constructor & Destructor Documentation

◆ PagedImage()

◆ ~PagedImage()

Member Function Documentation

◆ calculateImageProperties()

◆ clearPageList()

◆ clearPageListAndMemoryImage()

◆ clearPendingPageRequest()

◆ copyPages()

◆ deletePageEntryFromDeletionCallback()

◆ freeTile()

◆ getBypassIndex()

◆ getBypassSourceImage()

◆ getCachedPagesSizeInBytes()

◆ getCalculateOutputImageHandler()

◆ getClampPagesToImageExtent()

◆ getID()

◆ getInPlaceIndex()

◆ getInputImage()

◆ getInputSubImageDataType()

◆ getInputSubImageIsReadOnly()

◆ getInputSubImageProperties()

◆ getInterpolatedValue()

◆ getMemoryImage() [1/2]

◆ getMemoryImage() [2/2]

◆ getMetaProfile()

◆ getModule()

◆ getNumPages()

◆ getOutputIndex()

◆ getPage()

◆ getPageBox()

◆ getPageCountLimitToUsePageEntryMap()

◆ getPageExtent()

◆ getPageID()

◆ getPageIDs() [1/2]

◆ getPageIDs() [2/2]

◆ getPageOrCreatePageRequestOrAddToPendingRequest()

◆ getPageSetExtent()

◆ getPageStride()

◆ getStateInfoErrorCode()

◆ getStateInfoString()

◆ getThreadSupport()

◆ getTile() [1/2]

◆ getTile() [2/2]

◆ hasExternalCalculateOutputImageHandler()

◆ initializeInputSubImageProperties()

◆ isValid()

◆ ML_FRIEND_TEST() [1/3]

◆ ML_FRIEND_TEST() [2/3]

◆ ML_FRIEND_TEST() [3/3]

◆ removePage()

◆ setBypassIndex()

◆ setCalculateOutputImageHandler()

◆ setCalculateOutputImagePropertiesCB()

◆ setClampPagesToImageExtent()

◆ setDataType()

◆ setExternalCalculateOutputImageHandler()

◆ setImageExtent() [1/3]

◆ setImageExtent() [2/3]

◆ setImageExtent() [3/3]

◆ setImageProperties()

◆ setInPlaceIndex()

◆ setInputSubImageDataType()

◆ setInputSubImageIsReadOnly()

◆ setInputSubImagesAreReadOnly()

◆ setInputSubImageScaleShift()

◆ setInputSubImageUseMemoryImage()

◆ setInvalid()

◆ setMaxVoxelValue()

◆ setMinVoxelValue()

◆ setPage()

◆ setPageCountLimitToUsePageEntryMap()