ml::SubImage Class Reference
[Reentrant Classes, Image Processing]

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

#include <mlSubImage.h>

Inheritance diagram for ml::SubImage:

List of all members.

Public Member Functions

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.

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.

Constructors and assignments.

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=NULL)

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.

virtual ~SubImage ()

Virtual destructor to suppress compiler warnings.

SubImage & operator= (const SubImage &si)

Assignment operator to get identical copy.

Origin, extents, region of image, offsets and strides.

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.

Deprecated

SubImageBox getBoxFromImageExtent () const

ImageVector getImageExtent () const

void setImageExtent (const ImageVector &newExtent)

Calculation of memory addresses of image voxels

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.

Copy image data from one subimage to another.

MLEXPORT void copySubImage (const SubImage &fromImage, const ScaleShiftData &scaleShiftData=ScaleShiftData())

Copies image data from the subimage fromImage into the overlapping region of this subimage.

Test for validity of coordinates.

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.

Allocation and freeing of buffered data.

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

Special properties

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 (MLldouble &minValue, MLldouble &maxValue, const SubImageBox *const validBox=NULL) 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.

SUBIMAGE FILLING

MLEXPORT void fill (MLldouble 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 fillBordersWithLDoubleValue (const SubImageBox &box, MLldouble 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 fillInvalidRegionWithLDoubleValue (MLldouble 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.

Deprecated

SubImageBox getBoxFromImgExt () const

ImageVector getImgExt () const

void setImgExt (const ImageVector &newExtent)

MLint getSize () const

MLint getByteSize () const

void * getVoidSubImgPos (const ImageVector &p) const

void * getVoidSubImgPos (MLint x, MLint y, MLint z) const

void * getVoidImgPos (const ImageVector &p) const

void * getVoidImgPos (MLint x, MLint y, MLint z) const

MLint isValidSubImgPos (const ImageVector &p) const

MLint isValidSubImgPos (MLint x, MLint y, MLint z) const

MLint isValidImgPos (const ImageVector &p) const

MLint isValidImgPos (MLint x, MLint y, MLint z) const

MLint calcMinMax (MLldouble &minVal, MLldouble &maxVal, const SubImageBox *const validBox=NULL) const

void fillSubImg (MLldouble val)

void fillSubImgWithTypeData (const MLTypeData *val)

void fillBordersWithClampedInputValues (const SubImageBox &box)

Protected Attributes

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.

Properties of subimage

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

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.

Detailed Description

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

Thread-safety: This class is reentrant.

This class owns

Methods to set/access image properties which are inherited from the class ImageProperties.

A pointer to the memory data containing the image data as void pointer.

IMPORTANT NOTES:

This subimage class does NOT allocate/deallocate the memory chunk itself. It usually must be allocated elsewhere and assigned to this class.

The class itself is not exported to avoid that inline usage is inhibited. Only stuff implemented in the .cpp file is exported explicitly.

Other notes:

With this class the Host manages and encapsulates rectangular image regions (e.g., for pages, tiles, cached image results) and passes them to the image processing algorithms.

The typical image processing methods in the ML are located in overloaded methods of Module::calculateOutputSubImage. In these methods usually the untyped memory chunks given as SubImage are wrapped again to typed subimages (see TSubImage). See TSubImage for more information about that.

The type of the image data in memory is handled via a void pointer, however the type is managed as enum type to support typed accesses in derived classes (see TSubImage). Thus the access to certain image voxels is not supported. The Host does not need the knowledge about the data itself. The typed access to voxels is implemented on top of this class as the template class TSubImage.

Definition at line 72 of file mlSubImage.h.

Constructor & Destructor Documentation

ml::SubImage::SubImage ( ) [inline]

Constructor: Creates a subimage with no data.

Definition at line 82 of file mlSubImage.h.

References ML_TRACE_IN_TIME_CRITICAL.

ml::SubImage::SubImage ( const SubImage & si ) [inline]

Copy constructor to get identical copy.

Note that the pointer to the data is copied, and NOT the data itself.

Definition at line 96 of file mlSubImage.h.

References ML_TRACE_IN_TIME_CRITICAL.

ml::SubImage::SubImage	(	const SubImageBox &	box,
		MLDataType	datatype,
		void *	data = `NULL`
	)			`[inline]`

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.

Definition at line 111 of file mlSubImage.h.

References ML_TRACE_IN_TIME_CRITICAL.

virtual ml::SubImage::~SubImage ( ) [inline, virtual]

Virtual destructor to suppress compiler warnings.

Definition at line 123 of file mlSubImage.h.

References ML_TRACE_IN_TIME_CRITICAL.

Member Function Documentation

MLEXPORT void ml::SubImage::allocate ( MLMemoryErrorHandling handleFailure )

Allocate data with MLAlloc().

If the allocation fails it is handled as described by handleFailure (see MLMemoryErrorHandling for description of modes). The internal pointer to the data buffer is simply overwritten; the application is responsible for freeing it before, for example with SubImage::free(). The number of allocated bytes results from the size of the subimage box and the data type. An empty box will result in the allocation of zero bytes on the heap which also need to be freed correctly.

IMPORTANT: By definition the allocated data is not owned by the subimage and will NOT be freed on destruction of the SubImage instance. The calling application is responsible for that. Use SubImage::free() for that.

MLEXPORT void ml::SubImage::allocateAsMemoryBlockHandle ( MLMemoryErrorHandling handleFailure = ML_RETURN_NULL )

Allocate data using the ML memory manager. For failure handing, see SubImage::allocate().

MLint ml::SubImage::calcMinMax	(	MLldouble &	minVal,
		MLldouble &	maxVal,
		const SubImageBox *const	validBox = `NULL`
	)			const `[inline]`

Deprecated:: Use calculateMinMax() instead.

Definition at line 767 of file mlSubImage.h.

MLEXPORT MLint ml::SubImage::calculateMinMax	(	MLldouble &	minValue,
		MLldouble &	maxValue,
		const SubImageBox *const	validBox = `NULL`
	)			const

Scans subimage and determines minimum and maximum values on region which is part of subimage box and of validBox.

If validBox is passed as a NULL pointer (the default), all voxels are checked. The return value is the number of scanned voxels. If the subimage is empty, minValue and maxValue are set to 0 and the return value is 0. Warning: If used in calculateOutputSubImage, take into consideration that pages may also contain invalid data which is not part of the image. Pass 'image box' as validBox to be sure to access only valid regions.

MLEXPORT void ml::SubImage::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.

All pointer parameters may be passed as NULL parameters if not needed and will silently be ignored then.

Parameters:

	subImage2	Second subimage to be compared with.
	regionsMatch	If passed as non-NULL pointer, *regionsMatch is set to `true` if regions are identical.
	dataTypesMatch	If passed as non-NULL pointer, *dataTypesMatch is set to `true` if both data types are identical.
	thisBoxIsPartOfRegion2	If passed as non-NULL pointer, *region1IsPartOfRegion2 is set to `true` if the region of this is a subregion of `subImage2` or is identical.
	region2IsPartOfThisBox	If passed as non-NULL pointer, *region2IsPartOfRegion1 is set to `true` if the region of `subImage2` is a subregion of this or is identical.
	overlapHasSameValues	If passed as non-NULL pointer, *overlapHasSameValues is set to `true` if subimages have the same and valid types, data pointers are both non-NULL and all voxels in the overlapping region of this and `subImage2` contain equal values.
	firstMismatchPos	If passed as non-NULL pointer, *firstMismatchPos is set to the first value which does not match in overlapping regions. If no overlap exists or something is invalid (data pointers or types) it is set to (-1, ..., -1).

static MLEXPORT MLint ml::SubImage::coordToIndex	(	const ImageVector &	voxelPosition,
		const ImageVector &	size
	)			`[static]`

Converts the coordinate voxelPosition into the image with extents size to an index.

This convenience function is static and can be used also without a class instance.

static MLEXPORT MLint ml::SubImage::coordToIndex	(	MLint	x,
		MLint	y,
		MLint	z,
		MLint	c,
		MLint	t,
		MLint	u,
		const ImageVector &	size
	)			`[static]`

Converts the coordinate (x, y, z, c, t,u) to an index into an image with 6D extents given by size.

This convenience function is static and can be used also without a class instance.

MLEXPORT void ml::SubImage::copySubImage	(	const SubImage &	fromImage,
		const ScaleShiftData &	scaleShiftData = `ScaleShiftData()`
	)

Copies image data from the subimage fromImage into the overlapping region of this subimage.

Grey values are transformed linearly according to the settings in scaleShiftData (see ScaleShiftData). Notes:

The copied data always has the data type of this subimage. If necessary it is cast.
By transforming linearly gray values before copying them it is possible to avoid information loss due to type casting.
The default case of scaleShiftData defines scaleShiftData.getScale()==1 and scaleShiftData.getShift()==0. So voxel value transformation does not change anything and copying is implemented as special case which is therefore faster.

Reimplemented in ml::TSubImage< DATATYPE >, and ml::TSubImage< DATATYPE >.

MLEXPORT void ml::SubImage::fill ( MLldouble value )

Fills the subimage with a value cast to the data type of the subimage.

MLEXPORT void ml::SubImage::fillBordersWithBorderValues ( const SubImageBox & box )

Each voxel of which is not inside box is filled with the nearest voxel which is inside box.

Note that box must be specified in global image coordinates. box must overlap the box of the subImage at least in one voxel to guarantee correct operation since copying can be done only from box area. If no overlap exists then the routine returns without filling anything.

Reimplemented in ml::TSubImage< DATATYPE >, and ml::TSubImage< DATATYPE >.

void ml::SubImage::fillBordersWithClampedInputValues ( const SubImageBox & box ) [inline]

Deprecated:: Use fillBordersWithBorderValues() instead.

Reimplemented in ml::TSubImage< DATATYPE >, and ml::TSubImage< DATATYPE >.

Definition at line 778 of file mlSubImage.h.

MLEXPORT void ml::SubImage::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.

Not available regions from the input are ignored and may lead to unchanged regions outside box if inputSubImage does not cover all regions outside box. Note that box must be specified in global image coordinates. So two subimages with different origins and same sizes are filled differently, dependent on their overlap with the box in global image coordinates. This method should be called only if this and inputSubImage differ.

MLEXPORT void ml::SubImage::fillBordersWithLDoubleValue	(	const SubImageBox &	box,
		MLldouble	fillValue
	)

Fill all regions with the fill value fillValue which are not covered by box.

Note that box must be specified in global image coordinates. So two subimages with different origins and same sizes are filled differently, dependent on their overlap with the box in global image coordinates.

MLEXPORT void ml::SubImage::fillBordersWithTypeData	(	const SubImageBox &	box,
		const MLTypeData *	fillValue
	)

Fills all regions with the fill value fillValue which are not covered by box.

Note that box must be specified in global image coordinates. So two subimages with different origins and same sizes are filled differently, dependent on their overlap with the box in global image coordinates. fillValue must point to a valid and correctly sized value of the data type of the subimage. If fillValue is NULL, the call is ignored.

void ml::SubImage::fillInvalidRegionWithBorderValues ( ) [inline]

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

This is useful to initialize invalid regions of an output/input sub image.

Reimplemented in ml::TSubImage< DATATYPE >, and ml::TSubImage< DATATYPE >.

Definition at line 643 of file mlSubImage.h.

void ml::SubImage::fillInvalidRegionWithLDoubleValue ( MLldouble value ) [inline]

Fills the invalid region (everything outside of getValidRegion()) with the given value.

This is useful to initialize invalid regions of an output/input sub image.

Definition at line 630 of file mlSubImage.h.

void ml::SubImage::fillInvalidRegionWithTypeData ( const MLTypeData * value ) [inline]

Fills the invalid region (everything outside of getValidRegion()) with the given value.

This is useful to initialize invalid regions of an output/input sub image.

Definition at line 636 of file mlSubImage.h.

void ml::SubImage::fillSubImg ( MLldouble val ) [inline]

Deprecated:: Use fill() instead.

Definition at line 771 of file mlSubImage.h.

void ml::SubImage::fillSubImgWithTypeData ( const MLTypeData * val ) [inline]

Deprecated:: Use fillWithTypeData() instead.

Definition at line 774 of file mlSubImage.h.

MLEXPORT void ml::SubImage::fillWithTypeData ( const MLTypeData * value )

Fills the subimage with a value given as MLTypeData.

value must point to a valid and correctly sized value of the data type of the subimage. If value is NULL, the call is ignored.

MLEXPORT void ml::SubImage::free ( )

Frees data pointed to by getData() with MLFree().

as described by MLFree(). It is legal to call free() if getData() is NULL. In that case the call is ignored. After this call getData() will return NULL. If the memory has been set via setDataFromMemoryBlockHandle(), free() does NOT delete the memory but just clears the internal memory handle.

const SubImageBox& ml::SubImage::getBox ( ) const [inline]

Returns the box describing the origin/extent of the subimage.

Definition at line 225 of file mlSubImage.h.

References ML_TRACE_IN_TIME_CRITICAL.

Referenced by ml::TSubImage< DATATYPE >::copySubImage(), ml::TSubImage< DATATYPE >::copySubImageReorderColorPlanesToInterleaved(), ml::TSubImage< DATATYPE >::fillBordersWithInputValues(), ml::TSubImage< DATATYPE >::TSubImage(), and ml::TSubImageCursorBase< DATATYPE >::TSubImageCursorBase().

SubImageBox ml::SubImage::getBoxFromExtent ( ) const [inline]

Returns size of image as box with origin 0.

Definition at line 207 of file mlSubImage.h.

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

Deprecated:: Use getBoxFromExtent() instead. Returns extent of the image as box with origin 0.

Definition at line 213 of file mlSubImage.h.

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

Deprecated:: Use getBoxFromExtent() instead.

Definition at line 728 of file mlSubImage.h.

MLint ml::SubImage::getByteSize ( ) const [inline]

Deprecated:: Use getSizeInBytes() instead.

Definition at line 740 of file mlSubImage.h.

void* ml::SubImage::getData ( ) const [inline]

Returns the memory address of the memory managed by the subimage.

Reimplemented in ml::TSubImage< DATATYPE >, and ml::TSubImage< DATATYPE >.

Definition at line 377 of file mlSubImage.h.

Referenced by ml::TSubImage< DATATYPE >::TSubImage(), and ml::tsubimage_cast().

MLDataType ml::SubImage::getDataType ( ) const [inline]

Return type of image data.

Definition at line 288 of file mlSubImage.h.

Referenced by ml::TSubImage< DATATYPE >::copySubImage(), ml::TSubImage< DATATYPE >::copySubImageReorderColorPlanesToInterleaved(), ml::TSubImage< DATATYPE >::fillBordersWithInputValues(), ml::TSubImage< DATATYPE >::TSubImage(), and ml::tsubimage_cast().

ImageVector ml::SubImage::getExtent ( ) const [inline]

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

Definition at line 192 of file mlSubImage.h.

ImageVector ml::SubImage::getImageExtent ( ) const [inline]

Deprecated:: Use getExtent() instead. Returns the extent of the image.

Definition at line 217 of file mlSubImage.h.

void* ml::SubImage::getImagePointer	(	MLint	x,
		MLint	y,
		MLint	z
	)			const `[inline]`

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

The subimage is a part of the complete image. I.e., the position p=getBox.v1() is considered the origin of the image region/subimage.

Reimplemented in ml::TSubImage< DATATYPE >, and ml::TSubImage< DATATYPE >.

Definition at line 333 of file mlSubImage.h.

void* ml::SubImage::getImagePointer ( const ImageVector & voxelPosition ) const [inline]

Returns pointer to voxel data of image voxel at 6d position voxelPosition relative to the begin of the complete image region.

The subimage is a part of the complete image. I.e., the position p=getBox.v1() is considered the origin of the image region/subimage.

Reimplemented in ml::TSubImage< DATATYPE >, and ml::TSubImage< DATATYPE >.

Definition at line 325 of file mlSubImage.h.

ImageVector ml::SubImage::getImgExt ( ) const [inline]

Deprecated:: Use getExtent() instead.

Definition at line 731 of file mlSubImage.h.

const MLMemoryBlockHandle& ml::SubImage::getMemoryBlockHandle ( ) const [inline]

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

Returns an empty handle when the data has been set with setData().

Definition at line 393 of file mlSubImage.h.

MLint ml::SubImage::getNumVoxels ( ) const [inline]

Returns number of voxels in (sub)image.

Note that it could become larger than 2^32 even on 32 bit systems. It will never be smaller than 0; the signed return type is used for safer signed arithmetics.

Definition at line 249 of file mlSubImage.h.

MLint ml::SubImage::getOffset ( const ImageVector & voxelPosition ) const [inline]

Returns the array index offset from the origin (0,0,0,0,0,0) to the voxelPosition.

Definition at line 266 of file mlSubImage.h.

References ML_TRACE_IN_TIME_CRITICAL.

const ImageVector& ml::SubImage::getOrigin ( ) const [inline]

Returns the origin of the subimage (which is identical to getBox().v1).

Definition at line 186 of file mlSubImage.h.

MLint ml::SubImage::getSize ( ) const [inline]

Deprecated:: Use getNumVoxels() instead.

Definition at line 737 of file mlSubImage.h.

MLint ml::SubImage::getSizeInBytes ( ) const [inline]

Returns number of potential bytes in (sub)image.

Note that it could become larger than 2^32 even on 32 bit systems. It will never be smaller than 0; the signed return type is used for safer signed arithmetics.

Definition at line 253 of file mlSubImage.h.

ImageVector ml::SubImage::getSourceImageExtent ( ) const [inline]

Returns the image extent of the source image that was used to create this SubImage.

This is used for the intersection calculation of the getValidRegion() call.

Definition at line 238 of file mlSubImage.h.

Referenced by ml::TSubImage< DATATYPE >::TSubImage().

ImageVector ml::SubImage::getStride ( ) const [inline]

Returns a stride vector to address the memory efficiently.

So the memory address of an subimage voxel can easily be calculated from the dot product of strides and voxel position. Usually stride.x=1, stride.y=x, stride.z=x*y, stride.c=x*y*z, ...

Definition at line 258 of file mlSubImage.h.

References ML_TRACE_IN_TIME_CRITICAL.

Referenced by ml::TSubImage< DATATYPE >::copySubImage(), and ml::TSubImageCursorBase< DATATYPE >::TSubImageCursorBase().

void* ml::SubImage::getSubImagePointer	(	MLint	x,
		MLint	y,
		MLint	z
	)			const `[inline]`

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

I.e., the position (0,0,0,0,0,0) is considered the origin of the subimage.

Reimplemented in ml::TSubImage< DATATYPE >, and ml::TSubImage< DATATYPE >.

Definition at line 311 of file mlSubImage.h.

void* ml::SubImage::getSubImagePointer ( const ImageVector & voxelPosition ) const [inline]

Returns pointer to voxel data of image voxel at 6d voxelPosition relative to the begin of the subimage region.

I.e., the position (0,0,0,0,0,0) is considered the origin of the subimage.

Reimplemented in ml::TSubImage< DATATYPE >, and ml::TSubImage< DATATYPE >.

Definition at line 297 of file mlSubImage.h.

SubImageBox ml::SubImage::getValidRegion ( ) const [inline]

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

Definition at line 242 of file mlSubImage.h.

void* ml::SubImage::getVoidImgPos	(	MLint	x,
		MLint	y,
		MLint	z
	)			const `[inline]`

Deprecated:: Use getImagePointer() instead.

Definition at line 752 of file mlSubImage.h.

void* ml::SubImage::getVoidImgPos ( const ImageVector & p ) const [inline]

Deprecated:: Use getImagePointer() instead.

Definition at line 749 of file mlSubImage.h.

void* ml::SubImage::getVoidSubImgPos	(	MLint	x,
		MLint	y,
		MLint	z
	)			const `[inline]`

Deprecated:: Use getSubImagePointer() instead.

Definition at line 746 of file mlSubImage.h.

void* ml::SubImage::getVoidSubImgPos ( const ImageVector & p ) const [inline]

Deprecated:: Use getSubImagePointer() instead.

Definition at line 743 of file mlSubImage.h.

static MLEXPORT ImageVector ml::SubImage::indexToCoord	(	MLint	index,
		const ImageVector &	extent
	)			`[static]`

Converts an index into an array with extents extent to a coordinate.

This convenience function is static and can be used also without a class instance. Note that it is not really fast.

MLEXPORT bool ml::SubImage::isOneValued ( ) const

Returns true if all page voxels have the same value or if the page contains only 1 voxel.

If subimage has no voxels (empty) or more than one value, false is returned.

Reimplemented in ml::TSubImage< DATATYPE >, and ml::TSubImage< DATATYPE >.

bool ml::SubImage::isValid ( ) const [inline]

Returns 1(=true) if image region and data is valid.

Returns 0(=false) if not. This flag does NOT say anything about the validity of the contents of the memory.

Definition at line 366 of file mlSubImage.h.

References ML_CATCH_RETHROW, ML_TRACE_IN_TIME_CRITICAL, and ML_TRY.

bool ml::SubImage::isValidImagePosition	(	MLint	x,
		MLint	y,
		MLint	z
	)			const `[inline]`

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.

If outside, false is returned. So the position p=getBox().v1 addresses the origin of the subimage.

Definition at line 467 of file mlSubImage.h.

References ML_TRACE_IN_TIME_CRITICAL.

bool ml::SubImage::isValidImagePosition ( const ImageVector & voxelPosition ) const [inline]

Returns true if 6d voxelPosition is a valid position within subimage region, i.e., if voxelPosition is within subImgBox.v1 and subImgBox.v2.

If outside, false is returned. So the position p=getBox().v1 addresses the origin of the subimage.

Definition at line 453 of file mlSubImage.h.

References ML_TRACE_IN_TIME_CRITICAL.

MLint ml::SubImage::isValidImgPos	(	MLint	x,
		MLint	y,
		MLint	z
	)			const `[inline]`

Deprecated:: Use isValidImagePosition() instead.

Definition at line 764 of file mlSubImage.h.

MLint ml::SubImage::isValidImgPos ( const ImageVector & p ) const [inline]

Deprecated:: Use isValidImagePosition() instead.

Definition at line 761 of file mlSubImage.h.

bool ml::SubImage::isValidSubImagePosition	(	MLint	x,
		MLint	y,
		MLint	z
	)			const `[inline]`

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.

If outside, false is returned. So the position p=(0,0,0,0,0,0) addresses the origin of the subimage and all higher coordinates for c, t and u are always used as 0.

Definition at line 441 of file mlSubImage.h.

References ml::ImageVector, and ML_TRACE_IN_TIME_CRITICAL.

bool ml::SubImage::isValidSubImagePosition ( const ImageVector & voxelPosition ) const [inline]

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.

If outside, false is returned. So the position p=(0,0,0,0,0,0) addresses the origin of the subimage.

Definition at line 427 of file mlSubImage.h.

References ml::ImageVector, and ML_TRACE_IN_TIME_CRITICAL.

MLint ml::SubImage::isValidSubImgPos	(	MLint	x,
		MLint	y,
		MLint	z
	)			const `[inline]`

Deprecated:: Use isValidSubImagePosition() instead.

Definition at line 758 of file mlSubImage.h.

MLint ml::SubImage::isValidSubImgPos ( const ImageVector & p ) const [inline]

Deprecated:: Use isValidSubImagePosition() instead.

Definition at line 755 of file mlSubImage.h.

SubImage& ml::SubImage::operator= ( const SubImage & si ) [inline]

Assignment operator to get identical copy.

Note that only the pointer to the data is copied, and NOT the data itself.

Definition at line 127 of file mlSubImage.h.

References _box, _data, _dataType, _dataTypeSize, _memoryBlock, _sourceImageExtent, _stride, and ML_TRACE_IN_TIME_CRITICAL.

void ml::SubImage::setBox ( const ImageVector & imageExtent ) [inline]

Sets a rectangular 6d region of the subimage to imageExtent.

So the origin of box will be (0,0,0,0,0,0), the second box edge will result to the extent -1. This overloads the method from base class ImageProperties.

Definition at line 166 of file mlSubImage.h.

References ML_CATCH_RETHROW, ML_TRACE_IN_TIME_CRITICAL, and ML_TRY.

void ml::SubImage::setBox ( const SubImageBox & subImageBox ) [inline]

Sets a rectangular 6d region of the subimage to subImageBox.

Overloads method from base class ImageProperties.

Definition at line 151 of file mlSubImage.h.

References ml::TSubImageBox< intT >::getExtent(), ML_CATCH_RETHROW, ML_TRACE_IN_TIME_CRITICAL, and ML_TRY.

MLEXPORT void ml::SubImage::setData ( void * data ) [inline]

Sets data as a new memory block for the subimage.

The previous block is NOT touched anymore and it is NOT freed or deleted. If the memory was previously set by setDataFromMemoryBlockHandle(), the memory block handle is cleared.

Definition at line 382 of file mlSubImage.h.

MLEXPORT void ml::SubImage::setDataFromMemoryBlockHandle ( const MLMemoryBlockHandle & data ) [inline]

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.

This calls setData() with the data from the memory block handle.

Definition at line 388 of file mlSubImage.h.

References MLMemoryBlockHandle::data().

void ml::SubImage::setDataType ( MLDataType dataType ) [inline]

Overwrite inherited setDataType method to set type of data to dataType.

The validity flag is not changed.

Definition at line 279 of file mlSubImage.h.

References ML_TRACE_IN_TIME_CRITICAL, and MLSizeOf().

void ml::SubImage::setExtent ( const ImageVector & newExtent ) [inline]

Sets the extent of the subimage (which also changes the strides) to newExtent.

Definition at line 201 of file mlSubImage.h.

void ml::SubImage::setExtent	(	MLint	x,
		MLint	y,
		MLint	z = `1`,
		MLint	c = `1`,
		MLint	t = `1`,
		MLint	u = `1`
	)			`[inline]`

Sets the extent of the subimage (which also changes the strides) to newExtent.

The default value for missing dimensions is 1.

Definition at line 196 of file mlSubImage.h.

References ml::ImageVector.

MLEXPORT void ml::SubImage::setFromImageProperties ( const ImageProperties & imageProperties )

Sets the image box and datatype from the imageProperties extent and datatype.

Note that this does not affect the stored data and that the resulting box will have v1 = ImageVector(0) and v2 = imageProperties.getImgExt()-1. This box is adequate for requesting the complete volume defined by imageProperties as a single tile.

void ml::SubImage::setImageExtent ( const ImageVector & newExtent ) [inline]

Deprecated:: Use setExtent() instead. Sets the extent of the image.

Definition at line 221 of file mlSubImage.h.

void ml::SubImage::setImgExt ( const ImageVector & newExtent ) [inline]

Deprecated:: Use setExtent() instead.

Definition at line 734 of file mlSubImage.h.

void ml::SubImage::setOrigin ( const ImageVector & newOrigin ) [inline]

Sets the origin of the subimage (which moves the box of the subimage to newOrigin).

Definition at line 189 of file mlSubImage.h.

void ml::SubImage::setSourceImageExtent ( const ImageVector & extent ) [inline]

Sets the image extent of the source image that was used to create this SubImage to extent.

This is used for the intersection calculation of the getValidRegion() call.

Definition at line 234 of file mlSubImage.h.

MLEXPORT ImageProperties ml::SubImage::toImageProperties ( ) const

Converts the Subimage's datatype and extend to an ImageProperties object.

Notice the the min/max values of the ImageProperties are not set, since a Subimage does not store a min/max value.

void ml::SubImage::translate ( const ImageVector & offset ) [inline]

Translates the box of the subimage by adding the vector offset.

Definition at line 178 of file mlSubImage.h.

References ML_TRACE_IN_TIME_CRITICAL.

Member Data Documentation

SubImageBox ml::SubImage::_box [protected]

The box of the subimage.

Definition at line 667 of file mlSubImage.h.

Referenced by operator=().

void* ml::SubImage::_data [protected]

Memory chunk managed by this subimage.

Definition at line 673 of file mlSubImage.h.

Referenced by operator=().

MLDataType ml::SubImage::_dataType [protected]

Datatype of the image.

Definition at line 684 of file mlSubImage.h.

Referenced by operator=().

MLMemoryBlockHandle ml::SubImage::_memoryBlock [protected]

Memory block used by this subimage.

Definition at line 676 of file mlSubImage.h.

Referenced by operator=().

ImageVector ml::SubImage::_sourceImageExtent [protected]

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

Definition at line 670 of file mlSubImage.h.

Referenced by operator=().

ImageVector ml::SubImage::_stride [protected]

Stride vector to address the memory efficiently.

So the memory address of an subimage voxel can easily be calculated from the dot product of strides and voxel position. Usually stride.x=1, stride.y=x, stride.z=x*y, stride.c=x*y*z,...

Definition at line 681 of file mlSubImage.h.

Referenced by operator=().

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

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


Public Member Functions
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.
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.
Constructors and assignments.
	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=NULL)
	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.
virtual	~SubImage ()
	Virtual destructor to suppress compiler warnings.
SubImage &	operator= (const SubImage &si)
	Assignment operator to get identical copy.
Origin, extents, region of image, offsets and strides.
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.
Deprecated
SubImageBox	getBoxFromImageExtent () const
ImageVector	getImageExtent () const
void	setImageExtent (const ImageVector &newExtent)
Calculation of memory addresses of image voxels
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.
Copy image data from one subimage to another.
MLEXPORT void	copySubImage (const SubImage &fromImage, const ScaleShiftData &scaleShiftData=ScaleShiftData())
	Copies image data from the subimage `fromImage` into the overlapping region of this subimage.
Test for validity of coordinates.
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.
Allocation and freeing of buffered data.
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().
Special properties
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 (MLldouble &minValue, MLldouble &maxValue, const SubImageBox *const validBox=NULL) 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.
SUBIMAGE FILLING
MLEXPORT void	fill (MLldouble 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	fillBordersWithLDoubleValue (const SubImageBox &box, MLldouble 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	fillInvalidRegionWithLDoubleValue (MLldouble 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.
Deprecated
SubImageBox	getBoxFromImgExt () const
ImageVector	getImgExt () const
void	setImgExt (const ImageVector &newExtent)
MLint	getSize () const
MLint	getByteSize () const
void *	getVoidSubImgPos (const ImageVector &p) const
void *	getVoidSubImgPos (MLint x, MLint y, MLint z) const
void *	getVoidImgPos (const ImageVector &p) const
void *	getVoidImgPos (MLint x, MLint y, MLint z) const
MLint	isValidSubImgPos (const ImageVector &p) const
MLint	isValidSubImgPos (MLint x, MLint y, MLint z) const
MLint	isValidImgPos (const ImageVector &p) const
MLint	isValidImgPos (MLint x, MLint y, MLint z) const
MLint	calcMinMax (MLldouble &minVal, MLldouble &maxVal, const SubImageBox *const validBox=NULL) const
void	fillSubImg (MLldouble val)
void	fillSubImgWithTypeData (const MLTypeData *val)
void	fillBordersWithClampedInputValues (const SubImageBox &box)
Protected Attributes
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.
Properties of subimage
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().
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.

ml::SubImage Class Reference [Reentrant Classes, Image Processing]

Public Member Functions

Protected Attributes

Properties of subimage

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

ml::SubImage Class Reference
[Reentrant Classes, Image Processing]