The ml::ImageProperties class describes the basic image properties

Images are rectangular grids without gaps, and all voxels are of identical extent and types. The six image dimensions in the ML are interpreted as the three spatial dimensions (x, y and z), a color extent (c dimension), a time extent (t dimension) and a user (u) dimension. For example, a dynamic sequence of three dimensional color images that exist in different image acquisitions or reconstructions can be handled by the ML as a single image object.

See mlImageProperties.h in project ML for more information.

The ml::MedicalImageProperties class is derived from ImageProperties (Section 2.3.1, “ ImageProperties ”). It contains additional information specialized for medical data sets:

	Note
	For the c (color) and u dimension, there is a set of constants available describing the image contents, such as ML_RED, ML_BLUE, ML_SATURATION, ML_HUE for the c dimension, or ML_CT, ML_MR, ML_PET for the u dimension (see mlDataTypes.h ). The components of the list for the t dimension are given by the class DateTime (see mlDateTime.h ).

ml::ImagePropertyExtension is used to append additional and user-defined property information to an ML image. This class is independent of the classes ImageProperties and MedicalImageProperties (see Section 2.3.1, “ ImageProperties ” and Section 2.3.2, “ MedicalImageProperties ”). It is an abstract class that serves as a base class from which an application or programmer can derive new properties. These properties are added to the ImagePropertyExtensionContainer that is a member of the class MedicalProperties.

A derived ImagePropertyExtension must meet some requirements:

Most methods to be implemented are pure virtual in the base class ImagePropertyExtension, hence compilation will not work without implementing them

The following programming example demonstrates how to implement a newly derived ImagePropertyExtension:

#include "mlModuleIncludes.h"

ML_START_NAMESPACE

//! Implement a ImagePropertyExtension object which can be passed to the ML.
class MODULE_TESTS_EXPORT OwnImagePropertyExtension : public ImagePropertyExtension
{

public:

  //! Constructor.
  OwnImagePropertyExtension() : ImagePropertyExtension()
  {
    _extInfoString = "NewImageInfosString";
  }

  //! Destructor.
  virtual ~OwnImagePropertyExtension() { }

  //! Implement correct copy construction.
  OwnImagePropertyExtension(const OwnImagePropertyExtension &origObj) :
    ImagePropertyExtension(origObj)
  {
    _extInfoString = origObj._extInfoString;
  }

  //! Implement correct assignment.
  OwnImagePropertyExtension &operator=(const OwnImagePropertyExtension &origObj)
  {
    if (&origObj != this) { _extInfoString = origObj._extInfoString; }
    return *this;
  }

  //! Implement pure virtual equality operation to work even on base class pointers.
  virtual bool equals(const ImagePropertyExtension &extImageProps) const
  {
    if (extImageProps.getTypeId() == getClassTypeId()) {

      // Types are equal, compare contents.
      return _extInfoString == ((OwnImagePropertyExtension&)(extImageProps))._extInfoString;

    } else {
      return false; // Types differ, thus objects also differ.
    }
  }

  //! Creates a copy of the correct derived object (for comparisons / runtime type determination).
  virtual ImagePropertyExtension *createClone() const
  {
    return new OwnImagePropertyExtension(*this);
  }

  //! Returns value of property as string.
  virtual std::string getValueAsString() const
  {
    return _extInfoString;
  }

  //! Set value of property from string value.
  virtual MLErrorCode setValueFromString(const std::string &str)
  {
    _extInfoString = str;
    return ML_RESULT_OK;
  }


private:

  //! The string values used as additional image property.
  std::string _extInfoString;

  //! Implements interface for the runtime type system of the ML.
  ML_CLASS_HEADER(OwnImagePropertyExtension)
};

ML_END_NAMESPACE

Implement the C++ part of the class interface to the runtime type system:

ML_START_NAMESPACE

  //! Implements code for the runtime type system of the ML.
  ML_CLASS_SOURCE(OwnImagePropertyExtension, ImagePropertyExtension);

ML_END_NAMESPACE

Register the class to the runtime type system of the ML when the .dll/.so file is loaded. This is typically done in the InitDll file of the project:

ML_START_NAMESPACE

  int MyProjectInit()
  {
    OwnImagePropertyExtension::initClass();
  }

ML_END_NAMESPACE

In the method calculateOutputImageProperties of your ML module, you can add a copy of your own image property to the output image:

ML_START_NAMESPACE

  MyModule::calculateOutputImageProperties(int outIndex, PagedImage* outImage)
  {
    OwnImagePropertyExtension myNewImgProp;
    outImage->getImagePropertyContainer().appendEntry(&myNewImgProp, true);
  }

ML_END_NAMESPACE

See mlImagePropertyExtension.h and mlImagePropertyExtensionContainer.h in project ML for more information.

The class ml::PagedImage is dedicated to managing paged images in the ML and to representing image outputs of ML modules. See mlPagedImage.h in project ML.

The ML mainly works with pages and tiles. Since ML does usually not process entire images, it is necessary to break them down into smaller fractions of identical extent, the so-called pages. Pages can easily be buffered, cached and processed in parallel without spending too much memory or time. Caching in the ML works exclusively with pages. Moreover, only the pages that overlap with the actually requested image region must be processed. All other pages are not processed. Common page extents are, for example, 128x128x1x1x1x1 voxels. However, they may also have a real six-dimensional extent as do all images in the ML. Often, other image fractions (also called tiles) which do not have standard page extents are needed. Tiles are usually composed from pages and are used by the application or as input for image processing algorithms. In the ML, tiles are usually only temporary, i.e., the ML does not cache tiles.

For algorithms where a page-based implementation is difficult, classes such as VirtualVolume, BitImage or MemoryImage provide special interfaces to simplify efficient implementations. See Section 2.3.7, “ VirtualVolume ”, Section 2.3.6, “ BitImage ” and Section 2.3.8, “ MemoryImage ” for more information.

ml::SubImage is an important class representing image and subimage buffers. It is used to manage, copy, etc. chunks of voxel data. It contains fast data access methods. See mlSubImage.h .

ml::TSubImage is the typed version of SubImage which permits typed data accesses. See mlTSubImage.h in project ML.

ml::TSubImageCursor and ml::ConstTSubImageCursor are cursor classes that allow access to a given TSubImage using cursor positioning and movement.

The SubImage class represents a rectangular 6D image region with linearly organized memory. It offers:

SubImage subImgBuf(SubImageBox(ImageVector(0,0,0,0,0,0),
                           ImageVector(15,31,7,0,0,0)),
                 MLdoubleType,
                 dataPtr);

subImgBuf.fill(7.7);
subImgBuf.fillBordersWithLDoubleValue(SubImageBox(ImageVector(3,3,3,0,0,0),
                                                ImageVector(5,5,5,0,0,0)),
                                      19.3);

subImgBuf.copySubImage(srcSubImg, ScaleShiftData(0.5, 0) );

void *voxPtr = subImgBuf.getImagePointer( ImageVector(1,2,3,0,0,0,0) );

TSubImage<MLdouble> subImgBufT(SubImageBox(ImageVector(0,0,0,0,0,0),
                                       ImageVector(15,31,7,0,0,0)),
                             MLdoubleType,
                             dataPtr);

MLdouble *voxPtrT = subImgBufT.getImagePointer( ImageVector(1,2,3,0,0,0,0) );
*voxPtrT = 29.2;

In the page-based image processing concept of the ML, Boolean data types are not available (nor are they planned).

The BitImage class can be used as an alternative.

The following set of operations is available for this class type:

The ml::VirtualVolume and the ml::TVirtualVolume classes manage efficient voxel access to the output image of an input module or to a 'standalone' image.

So it is possible to implement random access to a paged input image or to a pure virtual image without mapping more than a limited number of bytes. Pages of the input volume are mapped temporarily into memory when needed. If no input volume is specified, the pages are created and filled with a fill value. When the permitted memory size is exceeded, older mapped pages are removed. When pages are written, they are mapped until the virtual volume instance is removed or until they are explicitly cleared by the application. Virtual volumes can easily be accessed by using setValue and getValue. These kinds of access are well-optimized code that might need 9 (1D), 18 (3D) and 36 (6D) instructions per voxel if the page at the position is already mapped.

A cursor manager for moving the cursor with moveCursor* (forward) and reverseMoveCursor* (backward) is also available. setCursorValue and getCursorValue provide voxel access. Good compilers and already mapped pages might require about 5-7 instructions. So the cursor approach will probably be faster for data volumes with more than 2 dimensions.

All the virtual volume access calls can be executed with or without error handling (see last and default constructor parameters). If areExceptionsOn is true, every access to the virtual volume is tested and if necessary, exceptions are thrown that can be caught by the code calling the virtual volume methods. Otherwise, most functions do not perform error handling.

	Note
	Exception handling versions are slower than versions with disabled exceptions. However, this is the only way to handle accesses safely.

	Tip
	This class is the recommended alternative to global image processing algorithms.

2.3.7.1. Code Examples

The following code gives an example of how to use the VirtualVolume class:

Example 2.6. How to Use the VirtualVolume Class

Header:

VirtualVolume *_virtVol;

Constructor:

_virtVol = NULL;

Create/Update the virtual volume in calculateOutputImageProperties() and invalidate the output image on errors, so that calculateOutputSubImage() is not called on bad virtual volume later.

if (_virtVolume != NULL) { delete _virtVolume; }

_virtVolume = new VirtualVolume(this, 0, getInputImage(0)->getDataType());

if (!_virtVolume || (_virtVolume && !_virtVolume->isValid())){
  outImage->setInvalid(); return;

When you do not want to use a 'standalone' virtual volume:

_virtVolume = new VirtualVolume(ImageVector(1024,1024,1,1,1,1), 0, MLuint8Type));

if ((_virtVolume == NULL) || (_virtVolume && !_virtVolume->isValid())){
  outImage->setInvalid(); return;
}

Example of how to access image data directly: calculateOutputSubImage()

// Create wrapper for typed voxel access.
TVirtualVolume<DATATYPE> vVol(*_virtVolume);

ImageVector pos(7,3,0,0,0,0);
DATATYPE value;

vVol.setValue(pos, value);             // Simple setting of an arbitrary voxel.
value = vVol.getValue(pos);            // Reading of an arbitrary voxel.
vVol.fill(outSubImg->getBox(), value); // Fill region with value.

// Now copy valid region of virtVolume to outSubimg.
vVol.copySubImage(*outSubImg);

Example of how to access image data via a cursor: calculateOutputSubImage():

// Create wrapper for typed voxel access.
TVirtualVolume<DATATYPE> vVol(*_virtVolume);

ImageVector pos(7,3,0,0,0,0);
DATATYPE value;

vVol.setCursorPosition(pos);                // Set cursor to any position in volume.
vVol.moveCursorX();                         // Move cursor >F<orward
vVol.moveCursorY();                         // in (positive) X, C and U direction.
vVol.moveCursorZ();
vVol.reverseMoveCursorT();                         // Move cursor >B<ackwards in (negative) T
vVol.reverseMoveCursorZ();                         // and Z direction.

val = vVol.getCursorValue();           // Reading voxel below cursor.
vVol.setCursorValue(10);               // Set voxel value below cursor to 10.

Additionally, the following helper routines are available:

// Fill region of virtual volume with a certain value.

void fill(const SubImageBox &box, DATATYPE value);


// Copy region from the virtual volume into a typed subimg.

void copyToSubImage(TSubImage<DATATYPE> &outSubImg);


// Copy a region from a typed subimg into the virtual volume.

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

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

Note

The class VirtualVolume contains data structures for data management and table caching; its creation is expensive in comparison to the TVirtualVolume class which is only a "lightweight" access interface that can rapidly be created and destroyed on top of a VirtualVolume object. In the case of algorithms which implement template support for arbitrary data types it is recommended to create an untyped VirtualVolume as class member and a TVirtualVolume class in calculateOutputSubImage for maximum performance. However, there are also convenience constructors of the TVirtualVolume class which internally create the VirtualVolume instance automatically ; these constructors are more expensive and should not be used on each calculateOutputSubImage call. Nevertheless they can be useful when a class works only with a fixed data type or without templates.

Using virtual Volume instances that create untyped virtual volume instances automatically.

Creating a TVirtualVolume with a convenience constructor. It creates a VirtualVolume internally. It provides float data access to the input image 0, even if the input image is of another type. Note that the connected input image must be valid:

// Create a typed VirtualVolume from input connector 0 of
// this Module with voxels of type float directly without
// creating the untyped VirtualVolume manually.

TVirtualVolume<float> vVol(this, 0);

MemoryImage can be used for algorithms that need fast random access to entire images, especially if they work “against“ paging e.g., OrthoReformat, MPR, MemCache.

	Important
	A MemoryImage object is always buffered at the output of the connected input module. Try to avoid this approach! It only supports limited image sizes that depend on the available memory! See Section 4.3.3, “VirtualVolume Concept” for information on how to avoid this concept.

Properties:

There are two ways of how to use the memory image at a module output:

Advantages:

Disadvantages: