This template class manages/represents a rectangular 6d image region in memory which is organized linearly. More...

#include <mlTSubImage.h>

Inheritance diagram for ml::TSubImage< DATATYPE >:

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

typedef TSubImageCursor< DATATYPE >	Cursor
	A read/write cursor.

typedef ConstTSubImageCursor< DATATYPE >	ConstCursor
	A read-only cursor.

Public Member Functions
Constructors
	TSubImage (const SubImageBox &box, MLDataType dataType, void *data)
	Constructor for an image region with location/extent `box`, with data type `dataType` (must fit to DATATYPE!) and the memory address `data` which hold the image region.

	TSubImage ()
	Default constructor to build a typed subimage (with an empty box) from scratch.

	TSubImage (const SubImage &subImage)
	Constructor to build a typed subimage from an untyped `subImage`.

	TSubImage (const TSubImage< DATATYPE > &typedSubImage)
	Copy constructor to get an identical copy.

	~TSubImage () override=default
	Virtual destructor to shut up compiler warnings.

TSubImage &	operator= (const TSubImage< DATATYPE > &typedSubImage)
	Assignment operator to get an identical copy.

Properties of TSubImage
const DATATYPE *	getData () const
	Returns memory address of image region (Overloads method from SubImage)

DATATYPE *	getData ()

Calculation of memory addresses of image voxels
const DATATYPE *	getSubImagePointer (const ImageVector &position) const
	Returns a pointer to voxel data of image voxel at the 6d `position` relative to the begin of the subimage region.

DATATYPE *	getSubImagePointer (const ImageVector &position)


const DATATYPE *	getSubImagePointer (MLint x, MLint y, MLint z) const
	Returns a pointer to voxel data of image voxel at 3d position p=(`x`, `y`, `z`) relative to the begin of the subimage region.

DATATYPE *	getSubImagePointer (MLint x, MLint y, MLint z)


const DATATYPE *	getImagePointer (const ImageVector &position) const
	Returns a pointer to voxel data of image voxel at 6d position `position` relative to the begin of the complete image region.

DATATYPE *	getImagePointer (const ImageVector &position)


const DATATYPE *	getImagePointer (MLint x, MLint y, MLint z) const
	Returns a pointer to voxel data of image voxel at 3d position p=(`x`, `y`, `z`) relative to the begin of the complete image region.

DATATYPE *	getImagePointer (MLint x, MLint y, MLint z)

Calculate coordinates from pointers into image data(from memory positions)
ImageVector	convertPointerToSubImagePosition (DATATYPE *pointer) const
	Returns 6d voxel coordinates corresponding to the memory address `pointer`.

void	convertPointerToSubImagePosition (DATATYPE pointer, MLint x, MLint y, MLint z) const
	Returns 3d voxel coordinates corresponding to the memory address `pointer`.

ImageVector	convertPointerToImagePosition (DATATYPE *pointer) const
	Returns 6d voxel coordinates corresponding to the memory address `pointer`.

void	convertPointerToImagePosition (DATATYPE pointer, MLint x, MLint y, MLint z) const
	Returns 3d voxel coordinates corresponding to the memory address `pointer`.

Set/Get voxel data
const DATATYPE &	operator[] (const ImageVector &position) const
	Constant reference access to voxel value at the given `position`.

DATATYPE &	operator[] (const ImageVector &position)
	Reference access to voxel value at the given `position`.

void	setSubImageValue (const ImageVector &position, DATATYPE value)
	Sets the voxel value at the given `position` to the given `value` where `position` is relative to the origin of the subimage region.

DATATYPE	getSubImageValue (const ImageVector &position) const
	Returns voxel value at the given `position` where `position` is relative to the origin of the subimage region.

void	setSubImageValue (MLint x, MLint y, DATATYPE value)
	Sets the voxel value at the given position(`x`, `y`) to the given `value` where the position is relative to the origin of the subimage region.

DATATYPE	getSubImageValue (MLint x, MLint y) const
	Returns the voxel value at position (`x`, `y`) where the position is relative to the origin of the subimage region.

void	setSubImageValue (MLint x, MLint y, MLint z, DATATYPE value)
	Sets the voxel value at the given position (`x`, `y`, `z`) to the given `value` where the positionis relative to the origin of the subimage region.

DATATYPE	getSubImageValue (MLint x, MLint y, MLint z) const
	Returns the voxel value at the given position (`x`, `y`, `z`) where the position is relative to the origin of the subimage region.

void	setImageValue (const ImageVector &position, DATATYPE value)
	Sets the 6d voxel at the given `position` to the given `value`.

DATATYPE	getImageValue (const ImageVector &position) const
	Returns the 6d voxel value from the given `position`.

void	setImageValue (MLint x, MLint y, DATATYPE value)
	Sets the 2d voxel at the given position (`x`, `y`) to the the given `value`.

DATATYPE	getImageValue (MLint x, MLint y) const
	Returns the 2d voxel value from the given position (`x`, `y`).

void	setImageValue (MLint x, MLint y, MLint z, DATATYPE value)
	Sets the 3d voxel at the given position (`x`, `y`, `z`) to the given `value`.

DATATYPE	getImageValue (MLint x, MLint y, MLint z) const
	Returns the 3d voxel value from given position (`x`, `y`, `z`).

Return min/max values of subimage
MLint	calculateMinMax (DATATYPE &minValue, DATATYPE &maxValue, const SubImageBox *const validBox=nullptr) const
	Scans subimage and determines minimum and maximum values of the region which is part of subimage box and of `validBox`.

Copying voxel from one subimage to another
template<typename FROM_DATATYPE >
void	copySubImageReorderColorPlanesToInterleaved (const TSubImage< FROM_DATATYPE > &typedFromImage, const ScaleShiftData &scaleShiftData)
	Implements special case for void copySubImageTyped(const TSubImage<FROM_DATATYPE> &typedFromImg, const ScaleShiftData& scaleShiftData) where color planes shall be interleaved instead of in planes.

template<typename FROM_DATATYPE >
void	copySubImageTyped (const TSubImage< FROM_DATATYPE > &typedFromImg, const ScaleShiftData &scaleShiftData)
	Copies image data from the subimage fromImg into the overlapping region of this subimage.

SUBIMAGE FILLING
void	fill (DATATYPE value)
	Sets all voxel values in subimage to `value`.

void	fillBordersWithValue (const SubImageBox &box, DATATYPE fillValue)
	Fills all regions with `fillValue` which are not covered by `box`.

void	fillInvalidRegionWithValue (DATATYPE value)
	Fills the invalid region (everything outside of getValidRegion()) with the given `value`.

void	fillInvalidRegionWithBorderValues ()
	Fills the invalid region (everything outside of getValidRegion()) with the values on the borders of the valid region.

Public Member Functions inherited from ml::SubImage
const SubImageBox &	getBox () const
	Returns the box describing the origin/extent of the subimage.

void	setSourceImageExtent (const ImageVector &extent)
	Sets the image extent of the source image that was used to create this SubImage to `extent`.

ImageVector	getSourceImageExtent () const
	Returns the image extent of the source image that was used to create this SubImage.

SubImageBox	getValidRegion () const
	Returns the valid region of the SubImage, which is defined by the intersection of the SubImage::getBox() and the SubImageBox(ImageVector(0), SubImage::getSourceImageExtent()-1).

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

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

ImageVector	getStride () const
	Returns a stride vector to address the memory efficiently.

MLint	getOffset (const ImageVector &voxelPosition) const
	Returns the array index offset from the origin (0,0,0,0,0,0) to the `voxelPosition`.

void	setDataType (MLDataType dataType)
	Overwrite inherited setDataType method to set type of data to `dataType`.

MLDataType	getDataType () const
	Return type of image data.

const MLTypeInfos *	getDataTypeInfos () const
	Get MLTypeInfos for image data type.

MLEXPORT ImageProperties	toImageProperties () const
	Converts the Subimage's datatype and extend to an ImageProperties object.

MLEXPORT void	setFromImageProperties (const ImageProperties &imageProperties)
	Sets the image box and datatype from the `imageProperties` extent and datatype.

void	toStream (std::ostream &ostr) const

	SubImage ()
	Constructor: Creates a subimage with no data.

	SubImage (const SubImage &si)
	Copy constructor to get identical copy.

	SubImage (const SubImageBox &box, MLDataType datatype, void *data=nullptr)
	Constructor for a rectangular 6d image region with position and extent given by box, with data type datatype and memory given by the pointer data.

	SubImage (const SubImage &si, const ImageVector &offset)
	Copy constructor to get identical copy.

virtual	~SubImage ()=default
	Virtual destructor to suppress compiler warnings.

SubImage &	operator= (const SubImage &si)
	Assignment operator to get identical copy.

void	setBox (const SubImageBox &subImageBox)
	Sets a rectangular 6d region of the subimage to `subImageBox`.

void	setBox (const ImageVector &imageExtent)
	Sets a rectangular 6d region of the subimage to `imageExtent`.

void	translate (const ImageVector &offset)
	Translates the box of the subimage by adding the vector `offset`.

const ImageVector &	getOrigin () const
	Returns the origin of the subimage (which is identical to getBox().v1).

void	setOrigin (const ImageVector &newOrigin)
	Sets the origin of the subimage (which moves the box of the subimage to `newOrigin`).

ImageVector	getExtent () const
	Returns the extent of the subimage (which is identical to getBox().getExtent()).

void	setExtent (MLint x, MLint y, MLint z=1, MLint c=1, MLint t=1, MLint u=1)
	Sets the extent of the subimage (which also changes the strides) to `newExtent`.

void	setExtent (const ImageVector &newExtent)
	Sets the extent of the subimage (which also changes the strides) to `newExtent`.

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

SubImageBox	getBoxFromImageExtent () const

ImageVector	getImageExtent () const

void	setImageExtent (const ImageVector &newExtent)

void *	getSubImagePointer (const ImageVector &voxelPosition) const
	Returns pointer to voxel data of image voxel at 6d `voxelPosition` relative to the begin of the subimage region.

void *	getSubImagePointer (MLint x, MLint y, MLint z) const
	Returns pointer to voxel data of image voxel at 3d position p=(`x`,`y`,`z`) relative to the begin of the subimage region.

void *	getImagePointer (const ImageVector &voxelPosition) const
	Returns pointer to voxel data of image voxel at 6d position `voxelPosition` relative to the begin of the complete image region.

void *	getImagePointer (MLint x, MLint y, MLint z) const
	Returns pointer to voxel data of image voxel at 3d position p=(`x`, `y`, `z`) relative to the begin of the complete image region.

MLEXPORT void	copySubImage (const SubImage &fromImage, const ScaleShiftData &scaleShiftData)
	Copies image data from the subimage `fromImage` into the overlapping region of this subimage.

MLEXPORT void	copySubImage (const SubImage &fromImage)
	Implements special case for void copySubImage(const TSubImage<FROM_DATATYPE> &typedFromImg, const ScaleShiftData& scaleShiftData) where scaleShiftData is default.

bool	isValidSubImagePosition (const ImageVector &voxelPosition) const
	Returns `true` if 6d `voxelPosition` is a valid position within subimage region, i.e., if `voxelPosition` is within (0,0,0,0,0,0) and subimage extents.

bool	isValidSubImagePosition (MLint x, MLint y, MLint z) const
	Returns `true` if 3d position p=(`x`, `y`, `z`) is a valid position within subimage region, i.e., if the position is within (0,0,0) and subimage extents.

bool	isValidImagePosition (const ImageVector &voxelPosition) const
	Returns `true` if 6d `voxelPosition` is a valid position within subimage region, i.e., if `voxelPosition` is within subImgBox.v1 and subImgBox.v2.

bool	isValidImagePosition (MLint x, MLint y, MLint z) const
	Returns `true` if 3d position p=(`x`, `y`, `z`) is a valid position within subimage region, i.e., if the position is within subImgBox.v1 and subImgBox.v2.

MLEXPORT void	allocate (MLMemoryErrorHandling handleFailure)
	Allocate data with MLAlloc().

MLEXPORT void	allocateAsMemoryBlockHandle (MLMemoryErrorHandling handleFailure=ML_RETURN_NULL)
	Allocate data using the ML memory manager. For failure handing, see SubImage::allocate().

MLEXPORT void	free ()
	Frees data pointed to by getData() with MLFree().

MLEXPORT bool	isOneValued () const
	Returns `true` if all page voxels have the same value or if the page contains only 1 voxel.

MLEXPORT MLint	calculateMinMax (MLdouble &minValue, MLdouble &maxValue, const SubImageBox *const validBox=nullptr) const
	Scans subimage and determines minimum and maximum values on region which is part of subimage box and of validBox.

MLEXPORT void	compare (const SubImage &subImage2, bool regionsMatch, bool dataTypesMatch, bool thisBoxIsPartOfRegion2, bool region2IsPartOfThisBox, bool overlapHasSameValues, ImageVector firstMismatchPos) const
	Compare two subimages with respect to their regions and their contents.

MLEXPORT void	fill (MLdouble value)
	Fills the subimage with a `value` cast to the data type of the subimage.

MLEXPORT void	fillWithTypeData (const MLTypeData *value)
	Fills the subimage with a `value` given as MLTypeData.

MLEXPORT void	fillBordersWithScalarValue (const SubImageBox &box, MLdouble fillValue)
	Fill all regions with the fill value fillValue which are not covered by box.

MLEXPORT void	fillBordersWithTypeData (const SubImageBox &box, const MLTypeData *fillValue)
	Fills all regions with the fill value `fillValue` which are not covered by `box`.

MLEXPORT void	fillBordersWithInputValues (const SubImageBox &box, const SubImage &inputSubImage)
	Fills all regions with values from `inputSubImage` which are not covered by `box`, however, only valid regions of `inputSubImage` are read.

MLEXPORT void	fillBordersWithBorderValues (const SubImageBox &box)
	Each voxel of which is not inside `box` is filled with the nearest voxel which is inside `box`.

void	fillInvalidRegionWithScalarValue (MLdouble value)
	Fills the invalid region (everything outside of getValidRegion()) with the given `value`.

void	fillInvalidRegionWithTypeData (const MLTypeData *value)
	Fills the invalid region (everything outside of getValidRegion()) with the given `value`.

void	fillInvalidRegionWithBorderValues ()
	Fills the invalid region (everything outside of getValidRegion()) with the values on the borders of the valid region.

MLEXPORT bool	isValid () const
	Returns 1(=true) if image region and data is valid.

void *	getData () const
	Returns the memory address of the memory managed by the subimage.

MLEXPORT void	setData (void *data)
	Sets `data` as a new memory block for the subimage.

MLEXPORT void	setDataFromMemoryBlockHandle (const MLMemoryBlockHandle &data)
	Sets the managed `data` from a given MLMemoryBlockHandle, the sub image will store this handle and thus reference count the memory managed by the handle as long as the SubImage stays alive.

const MLMemoryBlockHandle &	getMemoryBlockHandle () const
	Returns the memory block handle that manages the data of this SubImage if it has been set via setDataFromMemoryBlockHandle().

Additional Inherited Members
Static Public Member Functions inherited from ml::SubImage
static MLEXPORT MLint	coordToIndex (MLint x, MLint y, MLint z, MLint c, MLint t, MLint u, const ImageVector &size)
	Converts the coordinate (`x`, `y`, `z`, `c`, `t`,`u`) to an index into an image with 6D extents given by `size`.

static MLEXPORT MLint	coordToIndex (const ImageVector &voxelPosition, const ImageVector &size)
	Converts the coordinate `voxelPosition` into the image with extents `size` to an index.

static MLEXPORT ImageVector	indexToCoord (MLint index, const ImageVector &extent)
	Converts an `index` into an array with extents `extent` to a coordinate.

Protected Member Functions inherited from ml::SubImage
void	_calcFillAreaParams (const SubImageBox &box, const SubImageBox &maxValidInputRegion, ImageVector &boxV1, ImageVector &boxV2, ImageVector &outputTSubImageV1, ImageVector &outputTSubImageV2, MLint &fullLineLenX, MLint &fullLineLenXB, MLint &leftLineStartX, MLint &leftLineLenX, MLint &leftLineLenXB, MLint &rightLineStartX, MLint &rightLineLenX, MLint &rightLineLenXB)
	Helper method to calculate important parameters for page based border filling.

void	_copySubImageGeneric (const SubImage &fromImage, const ScaleShiftData &scaleShiftData)
	Generic, non-optimized version of copySubImage.

const MLTypeInfos *	_getDataTypeInfos (MLDataType dt) const
	Get MLTypeInfos for used data types, indicates error if type is not registered.

Protected Attributes inherited from ml::SubImage
SubImageBox	_box
	The box of the subimage.

ImageVector	_sourceImageExtent
	The extent of the source image, which is used for getValidRegion()

void *	_data
	Memory chunk managed by this subimage.

MLMemoryBlockHandle	_memoryBlock
	Memory block used by this subimage.

ImageVector	_stride
	Stride vector to address the memory efficiently.

MLDataType	_dataType
	Datatype of the image.

Detailed Description

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

This template class manages/represents a rectangular 6d image region in memory which is organized linearly.

It inherits the functionality of SubImage and adds data type specific access functions to that class. Apart from the direct data access methods, there are the TSubImage::Cursor and TSubImage::ConstCursor classes, which allow to work on the typed data with cursor positioning/movements.

A const TSubImage can be used to only allow const access to the underlying image data.

Thread-safety: This class is reentrant.

This template class owns

all functionality from SubImage
methods query and set of (sub)image properties, which are inherited from the class ImageProperties (via SubImage).
a typed pointer to the memory chunk. The data type is given by the template parameter DATATYPE.
Access functions/methods for image data. Examples are
DATATYPE value;

ImageVector p(......); // Define coordinate

value = getImgVal(p); // Get voxel value from image

setImgVal(p,value); // Set value of voxel p in image

ml::TImageVector< MLint >

mlrange_cast
Target mlrange_cast(Source arg)
Generic version of checked ML casts.
Definition mlRangeCasts.h:332

Notes: In the overloaded Module::calculateOutputSubImage, the Host passes untyped subimages (see SubImage). The image processing module usually needs to build typed wrappers around these untyped SubImages to have easy access to them. Then this class represents typed input tiles and output pages for image processing algorithms. Algorithms which have different typed input images can build easily template code to access the image data correctly. The methods to access image voxels are designed for image manipulation to be used by algorithm developers.

Definition at line 109 of file mlTSubImage.h.

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ComponentType

◆ ConstCursor

◆ Cursor

Constructor & Destructor Documentation

◆ TSubImage() [1/4]

◆ TSubImage() [2/4]

◆ TSubImage() [3/4]

◆ TSubImage() [4/4]

◆ ~TSubImage()

Member Function Documentation

◆ calculateMinMax()

◆ convertPointerToImagePosition() [1/2]

◆ convertPointerToImagePosition() [2/2]

◆ convertPointerToSubImagePosition() [1/2]

◆ convertPointerToSubImagePosition() [2/2]

◆ copySubImageReorderColorPlanesToInterleaved()

◆ copySubImageTyped()

◆ fill()

◆ fillBordersWithValue()

◆ fillInvalidRegionWithBorderValues()

◆ fillInvalidRegionWithValue()

◆ getData() [1/2]

◆ getData() [2/2]

◆ getImagePointer() [1/4]

◆ getImagePointer() [2/4]

◆ getImagePointer() [3/4]

◆ getImagePointer() [4/4]

◆ getImageValue() [1/3]

◆ getImageValue() [2/3]

◆ getImageValue() [3/3]

◆ getSubImagePointer() [1/4]

◆ getSubImagePointer() [2/4]

◆ getSubImagePointer() [3/4]

◆ getSubImagePointer() [4/4]

◆ getSubImageValue() [1/3]

◆ getSubImageValue() [2/3]

◆ getSubImageValue() [3/3]

◆ operator=()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ setImageValue() [1/3]

◆ setImageValue() [2/3]

◆ setImageValue() [3/3]

◆ setSubImageValue() [1/3]

◆ setSubImageValue() [2/3]

◆ setSubImageValue() [3/3]