ML Reference
|
Base class for an image processing module of the ML. More...
#include <mlModule.h>
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. | |
MLErrorCode | processMissingPages (int outputIndex=0, SubImageBox region=SubImageBox()) ML_RETURN_VALUE_SHOULD_BE_USED |
Processes all missing pages on the given output image. | |
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 |
class | ClassicHost |
Image processing and general properties of the module. | |
enum | THREAD_SUPPORT { NO_THREAD_SUPPORT = PagedImage::NO_THREAD_SUPPORT, MULTITHREADED = PagedImage::MULTITHREADED, IO_THREAD = PagedImage::IO_THREAD, ML_CALCULATEOUTPUTSUBIMAGE_ON_STD_TYPES = PagedImage::MULTITHREADED, ML_CALCULATEOUTPUTSUBIMAGE_ON_ALL_TYPES = PagedImage::MULTITHREADED, CALC_OUTSUBIMAGE_ON_STD_TYPES = PagedImage::MULTITHREADED, CALC_OUTSUBIMAGE_ON_ALL_TYPES = PagedImage::MULTITHREADED } |
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 () |
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:
Connected modules derived from Module define an image processing graph.
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 166 of file mlModule.h.
See documentation of handleInput.
Definition at line 363 of file mlModule.h.
See documentation of handleInput.
DISCONNECTED | |
CONNECTED_BUT_INVALID | |
CONNECTED_AND_VALID | |
CONNECTED_BUT_NEEDS_UPDATE | |
OPEN | |
UNDEFINED_CLOSED |
Definition at line 351 of file mlModule.h.
See documentation of setVoxelDataTypeSupport.
ONLY_SCALAR_TYPES | |
ONLY_DEFAULT_TYPES | |
ALL_REGISTERED_TYPES | |
ONLY_STANDARD_TYPES |
|
FULLY_OPERATIONAL |
|
MINIMUM_OPERATIONAL |
|
Definition at line 293 of file mlModule.h.
Enumerator deciding whether and which type of multithreading is supported by this module.
NO_THREAD_SUPPORT |
The module is not thread safe at all. |
MULTITHREADED |
The calculation of the image data can be called from multiple threads. |
IO_THREAD |
The calculation of the image data can be called from a designated IO thread. |
ML_CALCULATEOUTPUTSUBIMAGE_ON_STD_TYPES |
|
ML_CALCULATEOUTPUTSUBIMAGE_ON_ALL_TYPES |
|
CALC_OUTSUBIMAGE_ON_STD_TYPES |
|
CALC_OUTSUBIMAGE_ON_ALL_TYPES |
|
Definition at line 247 of file mlModule.h.
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.
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] |
Definition at line 1010 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:
virtual InputConnectorField* ml::Module::addInputConnector | ( | const char * | name, |
Module * | module, | ||
MLint | i | ||
) | [virtual] |
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] |
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 798 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
.
Definition at line 628 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 616 of file mlModule.h.
References calculateOutputImageProperties().
Referenced by calculateOutputImageProperties().
virtual void ml::Module::calculateOutputImageProperties | ( | int | ) | [inline, protected, virtual] |
Definition at line 620 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.
void ml::Module::clearOutImg | ( | MLint | i = 0 | ) | [inline] |
Definition at line 1022 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:
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.
static void ml::Module::destroyBaseOp | ( | ) | [inline, static] |
Definition at line 1043 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 803 of file mlModule.h.
Definition at line 1040 of file mlModule.h.
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] |
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] |
Definition at line 1031 of file mlModule.h.
FieldContainer* ml::Module::getFieldContainer | ( | ) | [inline] |
Returns a pointer to the container of all the module's fields.
Definition at line 772 of file mlModule.h.
const FieldContainer* ml::Module::getFieldContainer | ( | ) | const [inline] |
Returns a constant pointer to the container of all the module's fields.
Definition at line 777 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] |
Definition at line 1025 of file mlModule.h.
PagedImage* ml::Module::getInImg | ( | MLint | i, |
bool | getReal = false |
||
) | const [inline] |
Definition at line 992 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] |
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] |
Definition at line 983 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 |
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.
static size_t ml::Module::getNumBaseOps | ( | ) | [inline, static] |
Definition at line 1034 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] |
Definition at line 1028 of file mlModule.h.
PagedImage* ml::Module::getOutImg | ( | MLint | i = 0 | ) | const [inline] |
Definition at line 989 of file mlModule.h.
Definition at line 969 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.
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] |
Definition at line 986 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] |
static MLErrorCode ml::Module::getTile | ( | Module * | op, |
MLint | outIndex, | ||
SubImage & | subimg, | ||
const ScaleShiftData & | scaleShiftData = ScaleShiftData() |
||
) | [static] |
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 | ( | 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] |
Definition at line 995 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.
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 | ( | Module & | op, |
MLint | outIdx, | ||
const ImageVector & | pos, | ||
MLErrorCode * | errCode = NULL , |
||
const std::string & | errResult = "" |
||
) | [inline, static] |
Definition at line 933 of file mlModule.h.
References getOutputImage().
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.
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 398 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:
Definition at line 793 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 | ( | 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.
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 from the this module.
The normal page-based image processing takes place with the following changes:
region
.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.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.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::getOutputImage(-1) will not work, but you can use calculateOutputImageProperties(MLint outputIndex, PagedImage* outputImage) to change the temporary output images properties, e.g., the page extent.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. MLErrorCode ml::Module::processMissingPages | ( | int | outputIndex = 0 , |
SubImageBox | region = SubImageBox() |
||
) |
Processes all missing pages on the given output image.
If the pages are already available, they are not recomputed. Apart from this, it behaves like processAllPages(outputIndex), except that the outputIndex may not be -1.
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.
Definition at line 665 of file mlModule.h.
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] |
Definition at line 1050 of file mlModule.h.
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] |
Definition at line 1053 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] |
static MLErrorCode ml::Module::updateImageProps | ( | Module * | op, |
MLint | outIndex | ||
) | [static] |
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".
friend class ClassicHost [friend] |
Definition at line 178 of file mlModule.h.
friend class Host [friend] |
Permit other classes access to protected methods.
Definition at line 172 of file mlModule.h.
friend class ModuleCalculateOutputImageHandler [friend] |
Definition at line 176 of file mlModule.h.
friend class PagedImage [friend] |
Definition at line 173 of file mlModule.h.
friend class PageRequest [friend] |
Definition at line 174 of file mlModule.h.
friend class State [friend] |
Definition at line 177 of file mlModule.h.
friend class TileRequest [friend] |
Definition at line 175 of file mlModule.h.