ML Reference
Public Member Functions | Protected Member Functions | Friends
ml::Module Class Reference
Non-thread-safe Classes and Functions | Image Processing

Base class for an image processing module of the ML. More...

#include <mlModule.h>

Inheritance diagram for ml::Module:
ml::FieldContainer ml::Base ml::BaseOp ml::Engine ml::DummyOp

List of all members.

Public Member Functions

MLMetaProfilePtr & getMetaProfile () const
 Returns the meta profile for the base operator.
Construction/Destruction/Initialization
 Module (int numInputImages, int numOutputImages)
 Constructor: Initializes numInputImages input images and numOutputImages output images of the module.
virtual ~Module ()
 Destructor: Destroys this module.
Debugging properties of the module.
std::string whoAmI (bool withInstanceName=true) const
 Returns type and instance name of format "ModuleTypeName(ModuleInstanceName)" if the instance name is not empty and withInstanceName is true.
Input/Output connections and connected modules
InputConnectorField * getInputImageField (MLint i) const
 Returns the field representing input image i. i must be a valid index.
OutputConnectorField * getOutputImageField (MLint i=0) const
 Returns field representing output image i. i must be a valid index.
MLint getNumInputImages () const
 Returns number of input images of this module.
MLint getNumOutputImages () const
 Returns number of output images of this module.
PagedImage * getOutputImage (MLint outputIndex=0) const
 Returns output image outputIndex. The index needs to be in the range [0, getNumOutputImages()-1].
InputConnectorField * addInputImage (const char *name=NULL)
 Adds a new input image with name to the module.
OutputConnectorField * addOutputImage (const char *name=NULL)
 Adds a new output image with name to the module.
PagedImage * getInputImage (MLint inputIndex, bool getReal=false) const
 Returns the output image of the module connected to input inputIndex.
PagedImage * getUpdatedInputImage (MLint inputIndex, bool getReal=false)
 Convenience method for safe access to the input image at index inputIndex.
Sequential image processing.
MLErrorCode processAllPages (int outputIndex=-1, SubImageBox region=SubImageBox()) ML_RETURN_VALUE_SHOULD_BE_USED
 Processes all pages of a module for easy implementation of page-based image processing of complete images.
MLErrorCode processAllPages (ProcessAllPagesHandler &handler, SubImageBox region=SubImageBox()) ML_RETURN_VALUE_SHOULD_BE_USED
 Process input images with a ProcessAllPagesHandler handler on a temporary output image (which allocates no data) For details, see processAllPages(-1) above.
Memory management
void clearOutputImage (MLint i=0)
 Clear cached output image pages of output image i.
Module marker for recursive work on the modules. Should not be used by the module itself.
void setMarker (int val)
 Sets the marker flag to value.
int getMarker ()
 Returns the current marker value. Default is 0.
DeprecatedVirtuals

Macro to declare methods for the ML runtime type system (see mlRuntimeSubClass.h).

It registers the Module class and its string name. In the implementation (.cpp) file there must be a similar macro, too, which registers the parent class name and string. This macro also implements the init function of this module which needs to be called before first module usage in e.g., the dll initialization. These methods can no be inside of ML_DEPRECATED, since they would change binary compatibility.

virtual InputConnectorField * addInputConnector (const char *name, Module *module, MLint i)
virtual OutputConnectorField * addOutputConnector (const char *name, Module *module, MLint i)

Static Public Member Functions

Convenience functions and methods.
static MLErrorCode getTile (PagedImage *image, SubImageBox loc, MLDataType datatype, void **data, const ScaleShiftData &scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED
 For documentation see Host::getTile() function with same signature.
static MLErrorCode getTile (PagedImage *image, SubImage &subimg, const ScaleShiftData &scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED
 For documentation see Host::getTile() function with same signature and Module passed as reference.
static MLErrorCode updateImageProperties (PagedImage *image) ML_RETURN_VALUE_SHOULD_BE_USED
 For documentation see Host::updateImageProperties() function with same signature.
static void freeTile (void *data)
 For documentation see Host::freeTile().
static void updateProgress (const char *info1, const char *info2)
 For documentation see Host::updateProgress().
static bool shouldTerminate ()
 For documentation see Host::shouldTerminate().
static Field * getPressedNotifyField ()
 For documentation see Host::getPressedNotifyField().
static void adaptPageExtent (ImageVector &pageExtent, MLDataType imageType, const ImageVector &newImgExtent, const ImageVector &oldImgExtent, const ImageVector &pageUnit=ImageVector(0), const ImageVector &minPageExtent=ImageVector(0), const ImageVector &maxPageExtent=ImageVector(0))
 Adapt page size.
Convenience functions not wrapped from Host.
static std::string getVoxelValueAsString (PagedImage *image, const ImageVector &position, MLErrorCode *errorCode=NULL, const std::string &errorResult="")
 Returns the voxel value at position position of the image image.
Data base of currently instantiated modules.
static size_t getNumModules ()
 Returns number of instantiated modules.
static Module * getModule (size_t index)
 Returns pointer to instantiated module index.
static MLint findModuleIndex (Module &module)
 Returns index of Module module. If not found -1 is returned.
static void destroyModule ()
 Destroys static allocated tables to avoid memory leaks.

Protected Member Functions

virtual void handleNotificationInternal (Field *field, FieldSensor::Strength strength)
 Called from FieldContainer whenever a field changes.
Virtual methods to implement the image processing algorithm.
virtual
CalculateOutputImageHandler * 		createCalculateOutputImageHandler (PagedImage *outputImage)
 Creates the CalculateOutputImageHandler for the given output image outputImage.
virtual void calculateOutputImageProperties (int outputIndex, PagedImage *)
 Set properties of output image outputImage with output index outputIndex.
virtual void calculateOutputImageProperties (int)
virtual SubImageBox calculateInputSubImageBox (int, const SubImageBox &outputSubImageBox, int)
 Called by the Host to determine which input image region (tile) of input inputIndex is required to calculate a certain output image region (page) of output outputIndex.
virtual void calculateOutputSubImage (SubImage *outputSubImage, int outputIndex, SubImage *inputSubImages)
 Calculate page outputSubImage of output image with index outputIndex given the input image tiles in array inputSubImages.
Custom page allocation.
virtual void provideCustomPage (int, const SubImageBox &, MLMemoryBlockHandle &)
 This method allows a Module to provide its own pages to the Host for the outputIndex output image.
Control of handleNotification calls.
void handleNotificationOff ()
 Decreases lock counter for handleNotification calls.
void handleNotificationOn ()
 Increases lock counter for handleNotification calls.
bool isHandleNotificationOn ()
 Returns true if handleNotification calls are permitted, otherwise false.

Friends

class Host
 Permit other classes access to protected methods.
class PagedImage
class PageRequest
class TileRequest
class ModuleCalculateOutputImageHandler
class State

Image processing and general properties of the module.

enum  THREAD_SUPPORT {
  NO_THREAD_SUPPORT = 0, ML_CALCULATEOUTPUTSUBIMAGE_ON_STD_TYPES = 1, ML_CALCULATEOUTPUTSUBIMAGE_ON_ALL_TYPES = 3, CALC_OUTSUBIMAGE_ON_STD_TYPES = ML_CALCULATEOUTPUTSUBIMAGE_ON_STD_TYPES,
  CALC_OUTSUBIMAGE_ON_ALL_TYPES = ML_CALCULATEOUTPUTSUBIMAGE_ON_ALL_TYPES
}
 Enumerator deciding whether and which type of multithreading is supported by this module. More...
MLint getOutputImageInplace (MLint outputIndex=0) const
 Return optimization flag: Return index of input image whose input tile is used also as output page for output outputIndex in calculateOutputSubImage() (instead of allocating its own memory).
MLint getBypass (MLint outputIndex=0) const
 Returns the currently bypass index or -1 if bypassing is disabled (default).
THREAD_SUPPORT getThreadSupport () const
 Returns the multithreading mode supported by this module, default is NO_THREAD_SUPPORT.
bool areRecursiveHandleNotificationsPermitted () const
 Returns if recursive entries in handleNotification are permitted.
MLint getHandleNotificationEntryCounter () const
 A counter returning the current number of (recursive re)entries in handleNotification.
void setOutputImageInplace (MLint outputIndex=0, MLint inputIndex=0)
 Set optimization flag: If calculating a page in calculateOutputSubImage(), the output image page of output outputIndex shall use the same memory as the input page of input inputIndex.
void unsetOutputImageInplace (MLint outputIndex=0)
 Clear optimization flag: output page of output at outputIndex and input tile shall use different memory buffers in calculateOutputSubImage().
void setBypass (MLint outputIndex=0, MLint inputIndex=0)
 Sets the input image whose pages can also be used instead of output pages for the output image at outputIndex to avoid recalculations.
void setThreadSupport (THREAD_SUPPORT supportMode)
 Pass any THREAD_SUPPORT supportMode to decide whether and what type of multithreading is supported by this module.
void permitRecursiveHandleNotifications (bool enable)
 If this flag is set to enable =true, recursive entries in handleNotification are permitted.

Data type support of this module.

enum  PERMITTED_TYPES {
  ONLY_SCALAR_TYPES, ONLY_DEFAULT_TYPES, ALL_REGISTERED_TYPES, ONLY_STANDARD_TYPES = ONLY_SCALAR_TYPES,
  FULLY_OPERATIONAL = ONLY_DEFAULT_TYPES, MINIMUM_OPERATIONAL = ALL_REGISTERED_TYPES
}
 See documentation of setVoxelDataTypeSupport. More...
PERMITTED_TYPES getVoxelDataTypeSupport () const
 Returns the current state of supported voxel data types.
bool isSupportedVoxelDataType (MLDataType dt) const
 Check if a given data type is supported on the module as configured with setVoxelDataTypeSupport.
void setVoxelDataTypeSupport (PERMITTED_TYPES permTypes)
 Specifies which types this module supports.

Input handling

enum  INPUT_STATE {
  DISCONNECTED = 0, CONNECTED_BUT_INVALID = 1, CONNECTED_AND_VALID = 2, CONNECTED_BUT_NEEDS_UPDATE = 3,
  OPEN = DISCONNECTED, UNDEFINED_CLOSED = CONNECTED_BUT_INVALID
}
 See documentation of handleInput. More...
enum  INPUT_HANDLE { INVALIDATE = 0, ALLOW_INVALID_INPUT = 2, REDIRECT_TO_DUMMY_OP = 1 }
 See documentation of handleInput. More...
virtual INPUT_HANDLE handleInput (int, INPUT_STATE) const
 This method may be reimplemented to enable support for invalid input images on the module.
INPUT_STATE getInputState (MLint index)
 Returns the current state of the input connection.
INPUT_STATE getUpdatedInputState (MLint index)
 Returns the updated state of the input image by calling updateImageProperties(index) and returning getInputState(index) afterwards.

Management of fields

bool isInputImageField (Field *field) const
 Returns if the given field is an input image field. This can be used in handleNotification(), to check if one of the input images has changed.
void touchOutputImageFields () const
 Touch all output image fields to indicate that the images have changed.
FieldContainer * getFieldContainer ()
 Returns a pointer to the container of all the module's fields.
const FieldContainer * getFieldContainer () const
 Returns a constant pointer to the container of all the module's fields.
virtual void beginSaveFields ()
 Called before all fields data contents of this modules are saved.
virtual void endSaveFields ()
 Called after saving all field contents of this module.
virtual void handleNotification (Field *)
 Called when any field data in the field container of this module is modified.

Deprecated methods.

bool getMemoryOutputControl (MLint outputIndex) const
BaseOp * getInOp (MLint i, bool getReal=false) const
MLint getInOpIndex (MLint i, bool getReal=false) const
MLint getOutImgInplace (MLint outIndex=0) const
MLint getInputNum () const
MLint getOutputNum () const
PagedImage * getOutImg (MLint i=0) const
PagedImage * getInImg (MLint i, bool getReal=false) const
PagedImage * getUpdatedInImg (MLint i, bool getReal=false)
PagedImage * getNonDummyUpdatedInImg (int inIndex)
 This convenience routine gets the input image from input at connector inputIndex with the getUpdatedInImg(inputIndex) method and returns NULL if the value is a NULL pointer or if the image pointer is identical with DummyOp::getGlobalOutImg(); otherwise the pointer to the valid PagedImage is returned.
void clearOutImg (MLint i=0)
InputConnectorField * getInField (MLint i) const
OutputConnectorField * getOutField (MLint i=0) const
const FieldContainer * getConstFieldContainer () const
void setMemoryOutputControl (MLint outputIndex, bool manually)
void setOutImgInplace (MLint outIndex=0, MLint inIndex=0)
void unsetOutImgInplace (MLint outIndex=0)
static std::string getVoxelValueAsString (Module &op, MLint outIdx, const ImageVector &pos, MLErrorCode *errCode=NULL, const std::string &errResult="")
static MLErrorCode getTile (Module *op, MLint outIndex, SubImageBox loc, MLDataType datatype, void **data, const ScaleShiftData &scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED
static MLErrorCode getTile (Module *op, MLint outIndex, SubImage &subimg, const ScaleShiftData &scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED
static MLErrorCode updateImageProps (Module *op, MLint outIndex) ML_RETURN_VALUE_SHOULD_BE_USED
static MLErrorCode updateImageProperties (Module *op, MLint outIndex) ML_RETURN_VALUE_SHOULD_BE_USED
static void getInInfos (const BaseOp &op, MLint i, bool getReal, bool *isValidInputRet, BaseOp **inOpRet, PagedImage **inImgRet, MLint *inOpIndexRet)
static void adaptPageExt (ImageVector &pageExt, MLDataType imgType, const ImageVector &newImgExt, const ImageVector &oldImgExt, const ImageVector &pageUnit=ImageVector(0), const ImageVector &minPageExt=ImageVector(0), const ImageVector &maxPageExt=ImageVector(0))
static size_t getNumBaseOps ()
static BaseOp * getBaseOp (size_t idx)
static MLint findBaseOpIndex (Module &op)
static void destroyBaseOp ()

Detailed Description

Base class for an image processing module of the ML.

Thread-safety: This class is not thread-safe and should only be used from the main thread.

This class is the base class for all image processing modules of the ML. Such modules have the following properties:

  • They have
  • input modules, which supply input images
  • output modules, which demand and receive image information

Connected modules derived from Module define an image processing graph.

  • Module modules have methods which permit to establish and remove connections between modules.
  • Image processing parameters are defined as fields (derived from class Field) and are kept in a FieldContainer. Each module has such a field container. The field container can contain an arbitrary number of fields/parameters. Accesses to these parameters are controlled via methods and parameter modifications are notified by calling Module::handleNotifications(). This way, the module can handle parameter changes. Note that other instances also can be attached to fields so that they are notified if any field changes. Note also the field notifications are/can be disabled in some circumstances.
  • Module modules provide some methods which implement the image processing algorithm and its (image) properties. They are called from the ML core when needed. These methods are usually virtual and can and should be replaced by derived classes.

IMPORTANT NOTE: An ML module derived from Module is mostly a reacting class, not an acting one. The module is almost every time activated by a call from the ML core (the so called Host) which controls image and image property calculation in the module graph. The Host controls image/page (de)allocation, image/page calculation etc.

IMPORTANT NOTE: An ML modules usually works with input and output images. These images are calculated by calculating the so called pages by the ML. An image is usually composed of many pages of identical size. To calculate a page, an image processing module derived from Module requests one or more arbitrary regions of an input image, the so called tiles. Pages and tiles are derived from the so called SubImage.

Each creation/deletion of this class sends automatically a notification to the global MLNotify instance. See mlNotify.h for more information.

If you want to derive your own image processing module from a Module then you should consider to overload the following methods:

Constructor - Creates the module, sets some image processing properties (multithreading, inplace calculation, etc.) and creates module fields. Superclass constructor specifies number of inputs/outputs.

Destructor - Destroys the module.

activateAttachments - Enables notification handling for the Module class again; it should be used to reset field values after module (re)load or clone, because handleNotification is not called during module state reload or clone.

handleNotification - Called on field changes so that the image processing algorithms can adapt itself to the new settings.

calculateOutputImageProperties - Called by the host to determine the properties of an (output) image.

calculateInputSubImageBox - Called by the host to determine which input image region (tile) is required to calculate a certain output image region (page).

calculateOutputSubImage - Implements the actual image processing algorithm. It reads one (or more) input image region (tile) and calculates the output image region (page) out of it. Two versions are available - a normal one and an extended one which passes additional data with thread information for multithreading support.

For a more detailed description of these methods have a look at their header documentation.

Definition at line 165 of file mlModule.h.

Member Enumeration Documentation

enum ml::Module::INPUT_HANDLE

See documentation of handleInput.

Enumerator:
INVALIDATE 
ALLOW_INVALID_INPUT 
REDIRECT_TO_DUMMY_OP 

Definition at line 360 of file mlModule.h.

enum ml::Module::INPUT_STATE

See documentation of handleInput.

Enumerator:
DISCONNECTED 
CONNECTED_BUT_INVALID 
CONNECTED_AND_VALID 
CONNECTED_BUT_NEEDS_UPDATE 
OPEN 
UNDEFINED_CLOSED 

Definition at line 348 of file mlModule.h.

enum ml::Module::PERMITTED_TYPES

See documentation of setVoxelDataTypeSupport.

Enumerator:
ONLY_SCALAR_TYPES 
ONLY_DEFAULT_TYPES 
ALL_REGISTERED_TYPES 
ONLY_STANDARD_TYPES 
Deprecated:
use ONLY_SCALAR_TYPES instead
FULLY_OPERATIONAL 
Deprecated:
use ONLY_DEFAULT_TYPES instead
MINIMUM_OPERATIONAL 
Deprecated:
use ALL_REGISTERED_TYPES instead

Definition at line 289 of file mlModule.h.

enum ml::Module::THREAD_SUPPORT

Enumerator deciding whether and which type of multithreading is supported by this module.

Enumerator:
NO_THREAD_SUPPORT 
ML_CALCULATEOUTPUTSUBIMAGE_ON_STD_TYPES 

The module is not thread safe at all.

ML_CALCULATEOUTPUTSUBIMAGE_ON_ALL_TYPES 

calculateOutputSubImage can be called in parallel for scalar voxel types.

CALC_OUTSUBIMAGE_ON_STD_TYPES 
CALC_OUTSUBIMAGE_ON_ALL_TYPES 

Definition at line 245 of file mlModule.h.

Constructor & Destructor Documentation

ml::Module::Module ( int  numInputImages,
int  numOutputImages 
)

Constructor: Initializes numInputImages input images and numOutputImages output images of the module.

(Usually this is called by the implementation of the derived constructor). Moreover, a FieldContainer is initialized, which will contain all image processing parameters (see Field). The touching of these fields will call handleSensorNotification() and handleNotification() when changed. Notifies MLNotify. See mlMLNotify.h for more infos.

virtual ml::Module::~Module ( ) [virtual]

Destructor: Destroys this module.

Should be called only by the application managing the module graph. It automatically cleans up indirectly created stuff like Field objects, field connections, PagedImgs and data managed by PagedImgs. Notifies MLNotify. See mlMLNotify.h for more infos.

Member Function Documentation

static void ml::Module::adaptPageExt ( ImageVector &  pageExt,
MLDataType  imgType,
const ImageVector &  newImgExt,
const ImageVector &  oldImgExt,
const ImageVector &  pageUnit = ImageVector(0),
const ImageVector &  minPageExt = ImageVector(0),
const ImageVector &  maxPageExt = ImageVector(0) 
) [inline, static]
Deprecated:
Use adaptPageExtent() instead.

Definition at line 994 of file mlModule.h.

static void ml::Module::adaptPageExtent ( ImageVector &  pageExtent,
MLDataType  imageType,
const ImageVector &  newImgExtent,
const ImageVector &  oldImgExtent,
const ImageVector &  pageUnit = ImageVector(0),
const ImageVector &  minPageExtent = ImageVector(0),
const ImageVector &  maxPageExtent = ImageVector(0) 
) [static]

Adapt page size.

Call this method when the operator modifies the image size to avoid large memory overhead. Arguments are:

  • pageExtent: Suggested page size (e.g., of input image), overwritten by new page size
  • imageType: Data type of output image
  • newImgExtent: Size of output image
  • oldImgExtent: Size of input image
  • pageUnit: Page size must be a multiple of this, or 0 if do not care
  • minPageExtent: Minimum page size, or 0 if do not care
  • maxPageExtent: Maximum page size, or 0 if do not care
virtual InputConnectorField* ml::Module::addInputConnector ( const char *  name,
Module *  module,
MLint  i 
) [virtual]
Deprecated:
Use Module::addInputImage() instead.

Reimplemented from ml::FieldContainer.

InputConnectorField* ml::Module::addInputImage ( const char *  name = NULL)

Adds a new input image with name to the module.

The new InputConnectorField gets appended to the fields list and to the input images list. It gets getNumInputImages() as its index. If no name is given, the image is named "input" + its index. The returned field is owned by the Module.

virtual OutputConnectorField* ml::Module::addOutputConnector ( const char *  name,
Module *  module,
MLint  i 
) [virtual]
Deprecated:
Use Module::addOutputImage() instead.

Reimplemented from ml::FieldContainer.

OutputConnectorField* ml::Module::addOutputImage ( const char *  name = NULL)

Adds a new output image with name to the module.

The new OutputConnectorField gets appended to the fields list and to the input images list. A new PagedImage is created and owned by the OutputConnectorField. It gets getNumOutputImages() as its index. If no name is given, the image is named "output" + its index. The returned field is owned by the Module.

bool ml::Module::areRecursiveHandleNotificationsPermitted ( ) const

Returns if recursive entries in handleNotification are permitted.

By default this setting is false.

virtual void ml::Module::beginSaveFields ( ) [inline, virtual]

Called before all fields data contents of this modules are saved.

Useful for initializing time consuming field states only for saving module state.

Definition at line 782 of file mlModule.h.

virtual SubImageBox ml::Module::calculateInputSubImageBox ( int  ,
const SubImageBox &  outputSubImageBox,
int   
) [inline, protected, virtual]

Called by the Host to determine which input image region (tile) of input inputIndex is required to calculate a certain output image region (page) of output outputIndex.

Default is that a region with position and location of outputSubImageBox is requested from input image inputIndex.

Note:
This method is a convenience method and will only be called if you do not reimplement createCalculateOutputImageHandler(). In that case, calculateInputSubImageBox() will be called on your handler.

Definition at line 625 of file mlModule.h.

virtual void ml::Module::calculateOutputImageProperties ( int  outputIndex,
PagedImage *   
) [inline, protected, virtual]

Set properties of output image outputImage with output index outputIndex.

With getInputImage(inputIndex) the input images can be accessed to calculate output image properties. By default, the properties of input image are copied to output image and all input sub images are requested with the datatype of the outputImage. If you want to request input sub images of a different type as your output image, you can use the PagedImage::setInSubImageDataType() to specify those types. See PagedImage for details on the properties you can set for input sub images. In case of a processAllPages(-1) call, the outputIndex will be -1 and outImage will be a temporary output image whose properties can be set. To invalidate the output image, do: 

       outImg->setInvalid();
       return;

Definition at line 613 of file mlModule.h.

References calculateOutputImageProperties().

Referenced by calculateOutputImageProperties().

virtual void ml::Module::calculateOutputImageProperties ( int  ) [inline, protected, virtual]
Deprecated:
Change to calculateOutputImageProperties(int outputIndex, PagedImage* outputImage) instead.

Definition at line 617 of file mlModule.h.

virtual void ml::Module::calculateOutputSubImage ( SubImage *  outputSubImage,
int  outputIndex,
SubImage *  inputSubImages 
) [protected, virtual]

Calculate page outputSubImage of output image with index outputIndex given the input image tiles in array inputSubImages.

inputSubImages contains as many images as inputs of the module exists (see getNumInputImages()). If not overloaded, the content of the inputSubImage i is copied to outputSubImage i if possible. If more outputs than input images exist, the last input image is copied to the additional output images. If output images are bigger than the input images, non overlapping regions remain filled with undefined values. If no input exists, the outputs are remain filled with undefined values. If handleInput() is reimplemented and returns ALLOW_INVALID_INPUT for an invalid input image (either not connected or connected and invalid), the input sub image at that index will be empty and contain no data.

Note:
This method is a convenience method and will only be called if you do not reimplement createCalculateOutputImageHandler(). In that case, calculateOutputSubImage() will be called on your handler.
void ml::Module::clearOutImg ( MLint  i = 0) [inline]
Deprecated:
Use clearOutputImage() instead.

Definition at line 1006 of file mlModule.h.

void ml::Module::clearOutputImage ( MLint  i = 0)

Clear cached output image pages of output image i.

virtual CalculateOutputImageHandler* ml::Module::createCalculateOutputImageHandler ( PagedImage *  outputImage) [protected, virtual]

Creates the CalculateOutputImageHandler for the given output image outputImage.

The default implementation returns a CalculateOutputImageHandler that maps the interface back to the Module, callings its calculateOutputSubImage() and calculateInputSubImageBox(). Although this default implementation might feel simpler than implementing your own handler, please note that it is worth the effort and that it makes several issues much simpler:

  • ensuring thread-safety, since the handler has its own state and lifetime
  • clear separation between image calculation and other module state/fields
  • you can have a different handler for each output image
  • you can have different handlers for the same output image depending on the module state
  • typed image processing support is much better with handlers, see TypedCalculateOutputImageHandler for details.

A derived module may reimplement this virtual function to provide a CalculateOutputImageHandler which is used for the calculation of the pages of the given outputImage. Since this is called for each output image individually, it is possible to create different handlers for different output images. This method is be called by the ML Host after calculateOutputImageProperties() was called for one of the output images and the output image is valid after that call. Because of this, it is also possible to return a different handler for the same output image, depending on the module state, e.g. one handler that implements one kind of filter and another one which implements another filter, instead of using a switch statement in a single handler. If you are about thread-safety, please make sure that you copy all needed state in the constructor of your handler and do NOT store any back-references to the module, the output image, field pointers etc.

Warning:
The ownership of the returned object is passed to the ML, so the programmer MAY NOT store a pointer to the returned CalculateOutputImageHandler.
static void ml::Module::destroyBaseOp ( ) [inline, static]
Deprecated:
Use destroyModule() instead.

Definition at line 1027 of file mlModule.h.

static void ml::Module::destroyModule ( ) [static]

Destroys static allocated tables to avoid memory leaks.

Only to be called on ML destruction.

virtual void ml::Module::endSaveFields ( ) [inline, virtual]

Called after saving all field contents of this module.

Useful to clean up field states only generated for saving module state. See beginSaveFields().

Definition at line 787 of file mlModule.h.

static MLint ml::Module::findBaseOpIndex ( Module &  op) [inline, static]
Deprecated:
Use findModuleIndex() instead.

Definition at line 1024 of file mlModule.h.

static MLint ml::Module::findModuleIndex ( Module &  module) [static]

Returns index of Module module. If not found -1 is returned.

static void ml::Module::freeTile ( void *  data) [static]

For documentation see Host::freeTile().

static BaseOp* ml::Module::getBaseOp ( size_t  idx) [static]
Deprecated:
Use getModule() instead.
MLint ml::Module::getBypass ( MLint  outputIndex = 0) const

Returns the currently bypass index or -1 if bypassing is disabled (default).

Bypassing requires that image (data) content, image extent, page extent and voxel data type remain unchanged or errors will occur.

const FieldContainer* ml::Module::getConstFieldContainer ( ) const [inline]
Deprecated:
Use getFieldContainer() instead.

Definition at line 1015 of file mlModule.h.

FieldContainer* ml::Module::getFieldContainer ( ) [inline]

Returns a pointer to the container of all the module's fields.

Deprecated:
This is no longer required, because Module is derived from FieldContainer.

Definition at line 756 of file mlModule.h.

const FieldContainer* ml::Module::getFieldContainer ( ) const [inline]

Returns a constant pointer to the container of all the module's fields.

Deprecated:
This is no longer required, because Module is derived from FieldContainer.

Definition at line 761 of file mlModule.h.

MLint ml::Module::getHandleNotificationEntryCounter ( ) const

A counter returning the current number of (recursive re)entries in handleNotification.

It typically has the value 1 in handleNotification() and 0 outside. It can only return higher values if permitRecursiveHandleNotification() permits recursions in handleNotification().

InputConnectorField* ml::Module::getInField ( MLint  i) const [inline]
Deprecated:
Use getInputImageField() instead.

Definition at line 1009 of file mlModule.h.

PagedImage* ml::Module::getInImg ( MLint  i,
bool  getReal = false 
) const [inline]
Deprecated:
Use getInputImage() instead.

Definition at line 976 of file mlModule.h.

static void ml::Module::getInInfos ( const BaseOp &  op,
MLint  i,
bool  getReal,
bool *  isValidInputRet,
BaseOp **  inOpRet,
PagedImage **  inImgRet,
MLint *  inOpIndexRet 
) [static]
Deprecated:
Do not use it.
BaseOp* ml::Module::getInOp ( MLint  i,
bool  getReal = false 
) const
Deprecated:
Change to getInputImage(i)->getModule() instead (if you are replacing a getTile call, pass getInputImage() directly instead of getInOp() and getInOpIndex() to getTile().
MLint ml::Module::getInOpIndex ( MLint  i,
bool  getReal = false 
) const
Deprecated:
Change to getInputImage(i)->getOutputIndex() instead (if you are replacing a getTile call, pass getInputImage() directly instead of getInOp() and getInOpIndex() to getTile().
PagedImage* ml::Module::getInputImage ( MLint  inputIndex,
bool  getReal = false 
) const

Returns the output image of the module connected to input inputIndex.

The index inputIndex needs to be in the range [0, getNumInputImages()-1]. If getReal==true is passed, handleInput() will not be called and a connected input image will be returned regardless of its state (see getInputState()) for possible input image states) or NULL if there is no connection.

If getReal==false is passed, the return value depends on the reimplementation of handleInput(). It will return either the real input image (not regarding its state) or NULL. DEPRECATED: In the case of the deprecated redirection to the global dummy image, a pointer to the dummy image will be returned.

NOTE: getInputImage() should typically NOT be used outside of the calculate*() methods of Module, please use getUpdatedInputImage() instead to make sure that the input image is correctly updated if its properties have changed.

InputConnectorField* ml::Module::getInputImageField ( MLint  i) const

Returns the field representing input image i. i must be a valid index.

MLint ml::Module::getInputNum ( ) const [inline]
Deprecated:
Use getNumInputImages() instead.

Definition at line 967 of file mlModule.h.

INPUT_STATE ml::Module::getInputState ( MLint  index)

Returns the current state of the input connection.

NOTE: This does not update the input image, so it will return Module::CONNECTED_BUT_NEEDS_UPDATE if the input image state is unknown and could be updated via updateImageProperties(). When this method is called from within calculateOutputImageProperties(), you can be sure that Module::CONNECTED_BUT_NEEDS_UPDATE is never returned, because the ML host calls updateImageProperties() on each input image prior to calling calculateOutputImageProperties().

int ml::Module::getMarker ( )

Returns the current marker value. Default is 0.

bool ml::Module::getMemoryOutputControl ( MLint  outputIndex) const
Deprecated:
Use getOutputImage(outputIndex)->getMemoryImage()->isUserControlled() instead.
MLMetaProfilePtr& ml::Module::getMetaProfile ( ) const

Returns the meta profile for the base operator.

static Module* ml::Module::getModule ( size_t  index) [static]

Returns pointer to instantiated module index.

PagedImage* ml::Module::getNonDummyUpdatedInImg ( int  inIndex)

This convenience routine gets the input image from input at connector inputIndex with the getUpdatedInImg(inputIndex) method and returns NULL if the value is a NULL pointer or if the image pointer is identical with DummyOp::getGlobalOutImg(); otherwise the pointer to the valid PagedImage is returned.

This method is especially useful to get the real input image in case of potentially redirected inputs.

Deprecated:
Do not use it.
static size_t ml::Module::getNumBaseOps ( ) [inline, static]
Deprecated:
Use getNumModules() instead.

Definition at line 1018 of file mlModule.h.

MLint ml::Module::getNumInputImages ( ) const

Returns number of input images of this module.

static size_t ml::Module::getNumModules ( ) [static]

Returns number of instantiated modules.

MLint ml::Module::getNumOutputImages ( ) const

Returns number of output images of this module.

OutputConnectorField* ml::Module::getOutField ( MLint  i = 0) const [inline]
Deprecated:
Use getOutputImageField() instead.

Definition at line 1012 of file mlModule.h.

PagedImage* ml::Module::getOutImg ( MLint  i = 0) const [inline]
Deprecated:
Use getOutputImage() instead.

Definition at line 973 of file mlModule.h.

MLint ml::Module::getOutImgInplace ( MLint  outIndex = 0) const [inline]
Deprecated:
Use getOutputImageInplace() instead.

Definition at line 953 of file mlModule.h.

PagedImage* ml::Module::getOutputImage ( MLint  outputIndex = 0) const

Returns output image outputIndex. The index needs to be in the range [0, getNumOutputImages()-1].

Referenced by getVoxelValueAsString().

OutputConnectorField* ml::Module::getOutputImageField ( MLint  i = 0) const

Returns field representing output image i. i must be a valid index.

MLint ml::Module::getOutputImageInplace ( MLint  outputIndex = 0) const

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

If inplace calculation is off, -1 is returned.

MLint ml::Module::getOutputNum ( ) const [inline]
Deprecated:
Use getNumOutputImages() instead.

Definition at line 970 of file mlModule.h.

static Field* ml::Module::getPressedNotifyField ( ) [static]

For documentation see Host::getPressedNotifyField().

THREAD_SUPPORT ml::Module::getThreadSupport ( ) const

Returns the multithreading mode supported by this module, default is NO_THREAD_SUPPORT.

See THREAD_SUPPORT for possible return values.

static MLErrorCode ml::Module::getTile ( Module *  op,
MLint  outIndex,
SubImageBox  loc,
MLDataType  datatype,
void **  data,
const ScaleShiftData &  scaleShiftData = ScaleShiftData() 
) [static]
Deprecated:
Use getTile(PagedImage*, ...) instead.
static MLErrorCode ml::Module::getTile ( PagedImage *  image,
SubImageBox  loc,
MLDataType  datatype,
void **  data,
const ScaleShiftData &  scaleShiftData = ScaleShiftData() 
) [static]

For documentation see Host::getTile() function with same signature.

On NULL op parameter ML_BAD_OPERATOR_POINTER is returned.

static MLErrorCode ml::Module::getTile ( Module *  op,
MLint  outIndex,
SubImage &  subimg,
const ScaleShiftData &  scaleShiftData = ScaleShiftData() 
) [static]
Deprecated:
Use getTile(PagedImage*, ...) instead.
static MLErrorCode ml::Module::getTile ( PagedImage *  image,
SubImage &  subimg,
const ScaleShiftData &  scaleShiftData = ScaleShiftData() 
) [static]

For documentation see Host::getTile() function with same signature and Module passed as reference.

On NULL op parameter ML_BAD_OPERATOR_POINTER is returned.

PagedImage* ml::Module::getUpdatedInImg ( MLint  i,
bool  getReal = false 
) [inline]
Deprecated:
Use getUpdatedInputImage() instead.

Definition at line 979 of file mlModule.h.

PagedImage* ml::Module::getUpdatedInputImage ( MLint  inputIndex,
bool  getReal = false 
)

Convenience method for safe access to the input image at index inputIndex.

It is forbidden to call this in calculateOutputSubImage, calculateInputSubImageBox or calculateOutputImageProperties, please use getInputImage(i) instead. This method will call updateImageProperties() if needed and will return a pointer to the image if it is valid (isValid()==true).

DEPRECATED: In the case of getReal==false and usage of the deprecated redirection to the DummyOp in handleInput(), the returned image will be a pointer to the global dummy image if there is no real input image or it can not be updated to a valid state. This can be detected by PagedImage::isGlobalDummyImage().

INPUT_STATE ml::Module::getUpdatedInputState ( MLint  index)

Returns the updated state of the input image by calling updateImageProperties(index) and returning getInputState(index) afterwards.

It will never return Module::CONNECTED_BUT_NEEDS_UPDATE.

Warning:
This method may NOT be called from the calculate*() methods, use getInputState() instead.
PERMITTED_TYPES ml::Module::getVoxelDataTypeSupport ( ) const

Returns the current state of supported voxel data types.

See also Module::PERMITTED_TYPES and setVoxelDataTypeSupport. Default is Module::ONLY_SCALAR_TYPES.

static std::string ml::Module::getVoxelValueAsString ( PagedImage *  image,
const ImageVector &  position,
MLErrorCode *  errorCode = NULL,
const std::string &  errorResult = "" 
) [static]

Returns the voxel value at position position of the image image.

On any error errorResult is returned instead of the pixel value as string. errCode can be passed as NULL (the default). Otherwise errors are reported in *errorCode or ML_RESULT_OK is set. If the voxel position is out of image range "" is returned and *result is set to ML_RESULT_OK.

static std::string ml::Module::getVoxelValueAsString ( Module &  op,
MLint  outIdx,
const ImageVector &  pos,
MLErrorCode *  errCode = NULL,
const std::string &  errResult = "" 
) [inline, static]
Deprecated:
Use getVoxelValueAsString(PagedImage*, ...) instead.

Definition at line 917 of file mlModule.h.

References getOutputImage().

virtual INPUT_HANDLE ml::Module::handleInput ( int  ,
INPUT_STATE   
) const [inline, virtual]

This method may be reimplemented to enable support for invalid input images on the module.

If all inputs are connected and valid, this method is not called at all.

The handleInput method is called for each disconnected or invalid input image that is encountered. It allows to consider two cases separately:

The two cases are indicated by the passed state. If you do not care about the difference between a disconnected and an invalid connected image, just return the same handling and ignore the state flag. The default implementation returns Module::INVALIDATE to indicate that all input images need to be connected and valid.

The reimplemented version may return one of the following flags for each of the two cases:

It is strongly advised to not use REDIRECT_TO_DUMMY_OP in new code, please use Module::ALLOW_INVALID_INPUT instead.

If Module::ALLOW_INVALID_INPUT is returned, getInputImage() will return NULL for the invalid input image, so you need to handle this in your code, e.g., when calling getInputImage() in calculateOutputImageProperties() you need to handle a possible NULL return value. The same applies to calculateOutputSubImage(), where the input sub images for invalid inputs will be empty (isEmpty()==true) and and will contain no data (getData()==NULL).

IMPORTANT: For one input configuration handleInput must return a unique value. Input handling cannot change during life time of the Module instance. If it changes image processing may become instable.

Definition at line 395 of file mlModule.h.

virtual void ml::Module::handleNotification ( Field *  ) [inline, protected, virtual]

Called when any field data in the field container of this module is modified.

The pointer to the changed field is passed in field. Notes:

  • This method can/should be overloaded in derived modules to implement reactions of the module algorithm if fields are changed.
  • Field notifications are disabled globally within the Module::calculate*-methods. No other fields are notified and handleNotifications() is NOT called.
  • Field changes within handleNotifications() notify all attached fields (i.e., attached user interfaces are updated) but a reentry into handleNotification in this module is typically blocked. Only if permitRecursiveHandleNotification() is enabled then recursions will take place.

Definition at line 777 of file mlModule.h.

virtual void ml::Module::handleNotificationInternal ( Field *  field,
FieldSensor::Strength  strength 
) [protected, virtual]

Called from FieldContainer whenever a field changes.

This method will call the virtual handleNotification() method if handleNotification is enabled.

Reimplemented from ml::FieldContainer.

void ml::Module::handleNotificationOff ( ) [protected]

Decreases lock counter for handleNotification calls.

Calls can be nested. If < 0 then handleNotification calls are prohibited.

void ml::Module::handleNotificationOn ( ) [protected]

Increases lock counter for handleNotification calls.

Calls can be nested. If >= 0 then handleNotification calls are permitted.

bool ml::Module::isHandleNotificationOn ( ) [protected]

Returns true if handleNotification calls are permitted, otherwise false.

bool ml::Module::isInputImageField ( Field *  field) const

Returns if the given field is an input image field. This can be used in handleNotification(), to check if one of the input images has changed.

bool ml::Module::isSupportedVoxelDataType ( MLDataType  dt) const

Check if a given data type is supported on the module as configured with setVoxelDataTypeSupport.

void ml::Module::permitRecursiveHandleNotifications ( bool  enable) [protected]

If this flag is set to enable =true, recursive entries in handleNotification are permitted.

By default this setting is false and should only be enabled with care.

MLErrorCode ml::Module::processAllPages ( int  outputIndex = -1,
SubImageBox  region = SubImageBox() 
)

Processes all pages of a module for easy implementation of page-based image processing of complete images.

Internally all pages of the output image with index outputIndex are requested like from a connected module. So a normal image processing takes place with the following changes:

  • Before any calculation of pages eventually existing pages or memory image are cleared so that really all pages are processed.
  • If outputIndex is -1, a temporary output image with index -1 is created. The properties for the temporary output image are copied from the input image 0. If outputIndex is positive, it must specify a legal module output index.
  • If outputIndex is -1, in calculateOutputSubImage the output subimages must NOT be written since not data is collected for them to improve performance for pure input scan algorithms.
  • If outputIndex is -1, the calculateOutputImageProperties method is called with outputIndex set to -1 and outImg set to the temporary image. This allows to specify different properties for the temporary output image than the properties of image 0. Note: Module::getOutImg(-1) will not work, but you can use calculateOutputImageProperties(MLint outputIndex, PagedImage* outputImage) to change the temporaty output images properties, e.g., the page extent.
  • The output index outputIndex is passed to calculateOutputSubImage (even if it is negative). By negative value you can see that the output must not be written.
  • region can be passed by the caller to specify a region which covers all pages to be processed instead of all pages of the image. By default it is empty which means that all pages of the images are to be processed. The return value will ML_RESULT_OK on successful operation, otherwise a code describing the error.
    Note:
    Using a ProcessAllPagesHandler instead of calling this method will give you more flexibility, see method below.
MLErrorCode ml::Module::processAllPages ( ProcessAllPagesHandler &  handler,
SubImageBox  region = SubImageBox() 
)

Process input images with a ProcessAllPagesHandler handler on a temporary output image (which allocates no data) For details, see processAllPages(-1) above.

Note:
Using a ProcessAllPagesHandler gives you more flexibility and you do not need to mix the regular calculateOutputSubImage code with process all pages code.
virtual void ml::Module::provideCustomPage ( int  ,
const SubImageBox &  ,
MLMemoryBlockHandle &   
) [inline, protected, virtual]

This method allows a Module to provide its own pages to the Host for the outputIndex output image.

The pageBox specifies the location of the requested page. To return an own page, the page needs to be allocated with the MLMemoryManager and needs to be assigned to the resultPage parameter.

Note:
: Even if this method provides its own page (which may already contain valid data), calculateOutputSubImage() is still called by the Host. The default implementation does nothing and leaves the allocation to the Host.

Definition at line 662 of file mlModule.h.

void ml::Module::setBypass ( MLint  outputIndex = 0,
MLint  inputIndex = 0 
) [protected]

Sets the input image whose pages can also be used instead of output pages for the output image at outputIndex to avoid recalculations.

Setting an inputIndex of -1 disables bypassing (which is the default). Bypassing requires that image (data) content, image extent, page extent and voxel data type remain unchanged or errors will occur.

void ml::Module::setMarker ( int  val)

Sets the marker flag to value.

void ml::Module::setMemoryOutputControl ( MLint  outputIndex,
bool  manually 
) [protected]
Deprecated:
Use getOutputImage(outputIndex)->getMemoryImage()->setUserControlled(manually) instead.
void ml::Module::setOutImgInplace ( MLint  outIndex = 0,
MLint  inIndex = 0 
) [inline, protected]
Deprecated:
Use setOutputImageInplace() instead.

Definition at line 1034 of file mlModule.h.

void ml::Module::setOutputImageInplace ( MLint  outputIndex = 0,
MLint  inputIndex = 0 
) [protected]

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

This way less allocations occur because the read and written buffer are identical. Usually only useful for pixel operations or algorithms which do not modify the image data. Setting inIndex = -1 disables inplace optimization for the given outputIndex.

void ml::Module::setThreadSupport ( THREAD_SUPPORT  supportMode) [protected]

Pass any THREAD_SUPPORT supportMode to decide whether and what type of multithreading is supported by this module.

See THREAD_SUPPORT for possible modes.

void ml::Module::setVoxelDataTypeSupport ( PERMITTED_TYPES  permTypes) [protected]

Specifies which types this module supports.

If Module::ALL_REGISTERED_TYPES is set then the module might work on all registered data types.

If Module::ONLY_DEFAULT_TYPES is set then the module only supports operations on the default scalar and extended types. See the macro ML_INSTANTIATE_DEFAULT_EXTENDED_TYPES for the list of the default extended types.

Default is Module::ONLY_SCALAR_TYPES, i.e., the module can work only with the standard built-in data types. (MLuint8, MLint8,..., MLint64, MLfloat, MLdouble).

The set of allowed types can still be further restricted in calculateOutputSubImageProperties by setting the output image to invalid for not supported combinations of types and modes/parameters.

static bool ml::Module::shouldTerminate ( ) [static]

For documentation see Host::shouldTerminate().

void ml::Module::touchOutputImageFields ( ) const

Touch all output image fields to indicate that the images have changed.

void ml::Module::unsetOutImgInplace ( MLint  outIndex = 0) [inline, protected]
Deprecated:
Use unsetOutputImageInplace() instead.

Definition at line 1037 of file mlModule.h.

void ml::Module::unsetOutputImageInplace ( MLint  outputIndex = 0) [protected]

Clear optimization flag: output page of output at outputIndex and input tile shall use different memory buffers in calculateOutputSubImage().

This is an equivalent to setOutImgInplace(outIndex, -1).

static MLErrorCode ml::Module::updateImageProperties ( PagedImage *  image) [static]

For documentation see Host::updateImageProperties() function with same signature.

On NULL PagedImage parameter ML_BAD_OPERATOR_POINTER is returned.

static MLErrorCode ml::Module::updateImageProperties ( Module *  op,
MLint  outIndex 
) [static]
Deprecated:
Change to updateImageProperties(getOutputImage(outIndex)) instead.
static MLErrorCode ml::Module::updateImageProps ( Module *  op,
MLint  outIndex 
) [static]
Deprecated:
Change to updateImageProperties(getOutputImage(outIndex)) instead.
static void ml::Module::updateProgress ( const char *  info1,
const char *  info2 
) [static]

For documentation see Host::updateProgress().

std::string ml::Module::whoAmI ( bool  withInstanceName = true) const

Returns type and instance name of format "ModuleTypeName(ModuleInstanceName)" if the instance name is not empty and withInstanceName is true.

If withInstanceName is false or no instance name exists, the name is returned in the format "ModuleTypeName".

Friends And Related Function Documentation

friend class Host [friend]

Permit other classes access to protected methods.

Definition at line 171 of file mlModule.h.

friend class ModuleCalculateOutputImageHandler [friend]

Definition at line 175 of file mlModule.h.

friend class PagedImage [friend]

Definition at line 172 of file mlModule.h.

friend class PageRequest [friend]

Definition at line 173 of file mlModule.h.

friend class State [friend]

Definition at line 176 of file mlModule.h.

friend class TileRequest [friend]

Definition at line 174 of file mlModule.h.

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