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

#include <mlModule.h>

Inheritance diagram for ml::Module:

Public Member Functions
MLMetaProfilePtr &	getMetaProfile () const
	Returns the meta profile for the base operator. More...

const char *	getTypeNameFast () const
	Macro to declare methods for the ML runtime type system (see mlRuntimeSubClass.h). More...

Construction/Destruction/Initialization
	Module (int numInputImages, int numOutputImages)
	Constructor: Initializes `numInputImages` input images and `numOutputImages` output images of the module. More...

	~Module () override
	Destructor: Destroys this module. More...

Input/Output connections and connected modules
InputConnectorField *	getInputImageField (MLint i) const
	Returns the field representing input image `i`. `i` must be a valid index. More...

OutputConnectorField *	getOutputImageField (MLint i=0) const
	Returns field representing output image `i`. `i` must be a valid index. More...

MLint	getNumInputImages () const
	Returns number of input images of this module. More...

MLint	getNumOutputImages () const
	Returns number of output images of this module. More...

PagedImage *	getOutputImage (MLint outputIndex=0) const
	Returns output image `outputIndex`. The index needs to be in the range [0, getNumOutputImages()-1]. More...

InputConnectorField *	addInputImage (const char *name=nullptr)
	Adds a new input image with `name` to the module. More...

OutputConnectorField *	addOutputImage (const char *name=nullptr)
	Adds a new output image with `name` to the module. More...

PagedImage *	getInputImage (MLint inputIndex, bool getReal=false) const
	Returns the output image of the module connected to input `inputIndex`. More...

PagedImage *	getUpdatedInputImage (MLint inputIndex, bool getReal=false) const
	Convenience method for safe access to the input image at index `inputIndex`. More...

Sequential image processing.
MLErrorCode	processAllPages (int outputIndex=-1, SubImageBox region=SubImageBox(), MLRequestProgressCB progressCallback=nullptr, void progressCallbackUserData=nullptr)
	Processes all pages of a module for easy implementation of page-based image processing of complete images. More...

MLErrorCode	processAllPages (ProcessAllPagesHandler &handler, SubImageBox region=SubImageBox(), MLRequestProgressCB progressCallback=nullptr, void progressCallbackUserData=nullptr)
	Process input images with a ProcessAllPagesHandler `handler` on a temporary output image (which allocates no data) For details, see processAllPages(-1) above. More...

MLErrorCode	processMissingPages (int outputIndex=0, SubImageBox region=SubImageBox(), MLRequestProgressCB progressCallback=nullptr, void progressCallbackUserData=nullptr)
	Processes all missing pages on the given output image. More...

Memory management
void	clearOutputImage (MLint i=0)
	Clear cached output image pages of output image `i`. More...

DeprecatedVirtuals
These methods can no be inside of ML_DEPRECATED, since they would change binary compatibility. Deprecated: Use Module::addInputImage() instead.
InputConnectorField *	addInputConnector (const char name, Module module, MLint i) override

OutputConnectorField *	addOutputConnector (const char name, Module module, MLint i) override

Public Member Functions inherited from ml::FieldContainer
	FieldContainer ()
	Constructor. More...

	~FieldContainer () override
	Destructor: Deletes all added fields. More...

std::string	whoAmI (bool withInstanceName=true) const
	Returns type and instance name of format "ClassTypeName(instanceName)" if the instance name is not empty and `withInstanceName` is true. More...

Field *	addField (const char name, const char type, const char *value)
	Adds a new field with name `name`, type `type` and value `value` (coded as string) to the container. More...

Field *	addField (Field *field)
	Adds a `field`, the ownership of the field is passed to the FieldContainer. More...

BoolField *	addBool (const char *name)
	Creates a BoolField with `name` and adds it to the container. Default value is false. More...

BoolField *	addBool (const char *name, bool value)
	Creates a BoolField with `name` and adds it to the container. More...

IntField *	addInt (const char *name)
	Creates an IntField with `name` and adds it to the container. Default value is 0. More...

IntField *	addInt (const char *name, MLint value)
	Creates an IntField with `name` and adds it to the container. More...

EnumField *	addEnum (const char name, const char const *enumerationItemNames, MLint numEnumerationItems)
	Creates an EnumField field with `name` and adds it to the container. More...

EnumField *	addEnum (const char *name, const std::vector< std::string > &enumerationItemNames)
	Creates an EnumField field with `name` and adds it to the container. More...

template<typename EnumType >
TypedEnumField< EnumType > *	addEnum (const char *name, const EnumValues< EnumType > &values, EnumType initialValue)
	Creates a TypedEnumField field with `name` and adds it to the container. More...

FloatField *	addFloat (const char *name)
	Creates a FloatField with `name` and adds it to the container. Default value is 0.f. More...

FloatField *	addFloat (const char *name, float value)
	Creates a FloatField with `name` and adds it to the container. More...

ProgressField *	addProgress (const char *name)
	Creates a float ProgressField with `name` and adds it to the container. Default value is 0.f. More...

ProgressField *	addProgress (const char *name, float value)
	Creates a float ProgressField with `name` and adds it to the container. More...

DoubleField *	addDouble (const char *name)
	Creates a DoubleField with `name` and adds it to the container. Default value is 0. More...

DoubleField *	addDouble (const char *name, double value)
	Creates a DoubleField with `name` and adds it to the container. More...

StringField *	addString (const char *name)
	Creates a StringField with `name` and adds it to the container. Default value is empty string. More...

StringField *	addString (const char *name, const std::string &value)
	Creates a StringField with `name` and adds it to the container. More...

NotifyField *	addNotify (const char *name)
	Creates a NotifyField field with `name` and adds it to the container. More...

TriggerField *	addTrigger (const char *name)
	Creates a TriggerField field with `name` and adds it to the container. More...

BaseField *	addBase (const char *name)
	Creates a Base field with `name` and adds it to the container. Default value is NULL. More...

BaseField *	addBase (const char name, Base value)
	Creates a Base field with `name` and adds it to the container. More...

BaseField *	addBase (const char *name, const RefCountedBasePtr &value)
	Creates a Base field with `name` and adds it to the container. Sets the value from intrusive pointer. More...

template<typename T >
BaseField *	addBaseWithAllowedType (const char name, T value=nullptr)
	As above, but also sets the allowed type of the field. More...

template<typename T >
BaseField *	addBaseWithAllowedType (const char *name, const ::boost::intrusive_ptr< T > &value)
	As above, but also sets the allowed type of the field. More...

template<typename T >
TypedBaseField< T > *	addTypedBase (const char *name)
	Creates a TypedBaseField with `name` and adds it to the container. Default value is NULL. More...

template<typename T >
TypedBaseField< T > *	addTypedBase (const char name, T value)
	Creates a TypedBaseField with `name` and adds it to the container. More...

template<typename T >
TypedBaseField< T > *	addTypedBase (const char *name, const ::boost::intrusive_ptr< T > &value)
	Creates a TypedBaseField with `name` and adds it to the container. Sets the value from intrusive pointer. More...

SoNodeField *	addSoNode (const char *name)
	Creates a SoNodeField with `name` and adds it to the container. Default value is NULL. More...

SoNodeField *	addSoNode (const char name, SoNode value)
	Creates a SoNodeField with `name` and adds it to the container. More...

PointerField *	addPointer (const char *name)
	Creates a PointerField with `name` and adds it to the container. More...

Vector2Field *	addVector2 (const char *name)
	Creates a Vector2Field with `name` and adds it to the container. More...

Vector2Field *	addVector2 (const char *name, const Vector2 &value)
	Creates a Vector2Field with `name` and adds it to the container. More...

Vector2Field *	addVector2 (const char *name, double x, double y)
	Creates a Vector2Field with `name` and adds it to the container. More...

Vector3Field *	addVector3 (const char *name)
	Creates a Vector3Field with `name` and adds it to the container. More...

Vector3Field *	addVector3 (const char *name, const Vector3 &value)
	Creates a Vector3Field with `name` and adds it to the container. More...

Vector3Field *	addVector3 (const char *name, double x, double y, double z)
	Creates a Vector3Field with `name` and adds it to the container. More...

Vector4Field *	addVector4 (const char *name)
	Creates a Vector4Field with `name` and adds it to the container. More...

Vector4Field *	addVector4 (const char *name, const Vector4 &value)
	Creates a Vector4Field with `name` and adds it to the container. More...

Vector4Field *	addVector4 (const char *name, double x, double y, double z, double w)
	Creates a Vector4Field with `name` and adds it to the container. More...

Vector5Field *	addVector5 (const char *name)
	Creates a Vector5Field with `name` and adds it to the container. More...

Vector5Field *	addVector5 (const char *name, const Vector5 &value)
	Creates a Vector5Field with `name` and adds it to the container. More...

Vector6Field *	addVector6 (const char *name)
	Creates a Vector6Field with `name` and adds it to the container. More...

Vector6Field *	addVector6 (const char *name, const Vector6 &value)
	Creates a Vector6Field with `name` and adds it to the container. More...

Vector10Field *	addVector10 (const char *name)
	Creates a Vector10Field with `name` and adds it to the container. More...

Vector10Field *	addVector10 (const char *name, const Vector10 &value)
	Creates a Vector10Field with `name` and adds it to the container. More...

ImageVectorField *	addImageVector (const char *name)
	Creates a ImageVectorField with `name` and adds it to the container. More...

ImageVectorField *	addImageVector (const char *name, const ImageVector &value)
	Creates a ImageVectorField with `name` and adds it to the container. More...

ImageVectorField *	addImageVector (const char *name, MLint x, MLint y, MLint z, MLint c, MLint t, MLint u)
	Creates a ImageVectorField with `name` and adds it to the container. More...

SubImageBoxField *	addSubImageBox (const char *name)
	Creates a SubImageBoxField with `name` and adds it to the container. More...

SubImageBoxField *	addSubImageBox (const char *name, const SubImageBox &value)
	Creates a SubImageBoxField with `name` and adds it to the container. More...

SubImageBoxdField *	addSubImageBoxd (const char *name)
	Creates a SubImageBoxd field with `name` and adds it to the container. More...

SubImageBoxdField *	addSubImageBoxd (const char *name, const SubImageBoxd &value)
	Creates a SubImageBoxd field with `name` and adds it to the container. More...

ColorField *	addColor (const char *name)
	Creates a ColorField with `name` and adds it to the container. More...

ColorField *	addColor (const char *name, float r, float g, float b)
	Creates a ColorField with `name` and adds it to the container. More...

ColorField *	addColor (const char *name, const Vector3 &value)
	Creates a ColorField with `name` and adds it to the container. More...

PlaneField *	addPlane (const char *name)
	Creates a PlaneField with `name` and adds it to the container. More...

PlaneField *	addPlane (const char *name, double f0, double f1, double f2, double f3)
	Creates a PlaneField with `name` and adds it to the container. More...

PlaneField *	addPlane (const char *name, const Plane &value)
	Creates a PlaneField with `name` and adds it to the container. More...

RotationField *	addRotation (const char *name)
	Creates a RotationField with `name` and adds it to the container. More...

RotationField *	addRotation (const char *name, const Rotation &value)
	Creates a RotationField with `name` and adds it to the container. More...

Matrix2Field *	addMatrix2 (const char *name)
	Creates a Matrix2Field with `name` and adds it to the container. More...

Matrix2Field *	addMatrix2 (const char *name, const Matrix2 &value)
	Creates a Matrix2Field with `name` and adds it to the container. More...

Matrix3Field *	addMatrix3 (const char *name)
	Creates a Matrix3Field with `name` and adds it to the container. More...

Matrix3Field *	addMatrix3 (const char *name, const Matrix3 &value)
	Creates a Matrix3Field with `name` and adds it to the container. More...

Matrix4Field *	addMatrix4 (const char *name)
	Creates a Matrix4Field with `name` and adds it to the container. More...

Matrix4Field *	addMatrix4 (const char *name, const Matrix4 &value)
	Creates a Matrix4Field with `name` and adds it to the container. More...

Matrix5Field *	addMatrix5 (const char *name)
	Creates a Matrix5Field with `name` and adds it to the container. More...

Matrix5Field *	addMatrix5 (const char *name, const Matrix5 &value)
	Creates a Matrix5Field with `name` and adds it to the container. More...

Matrix6Field *	addMatrix6 (const char *name)
	Creates a Matrix6Field with `name` and adds it to the container. More...

Matrix6Field *	addMatrix6 (const char *name, const Matrix6 &value)
	Creates a Matrix6Field with `name` and adds it to the container. More...

MatrixField *	addMatrix (const char *name)
	Creates a MatrixField with `name` and adds it to the container. More...

MatrixField *	addMatrix (const char *name, const Matrix4 &value)
	Creates a MatrixField with `name` and adds it to the container. More...

MLDataTypeField *	addMLDataType (const char *name)
	Creates a MTDataTypeField with `name` and adds it to the container. More...

MLDataTypeField *	addMLDataType (const char *name, MLDataType value)
	Creates a MTDataTypeField with `name` and adds it to the container. More...

UniversalTypeField *	addUniversalType (const char *name)
	Creates an UniversalTypeField field with `name` and adds it to the container. More...

IntListField *	addIntList (const char *name)
	Creates an IntListField field with `name` and empty list value and adds it to the container. More...

IntListField *	addIntList (const char *name, const std::vector< MLint > &value)
	Creates an IntListField field with `name` and given list value and adds it to the container. More...

DoubleListField *	addDoubleList (const char *name)
	Creates an DoubleListField field with `name` and empty list value and adds it to the container. More...

DoubleListField *	addDoubleList (const char *name, const std::vector< double > &value)
	Creates an DoubleListField field with `name` and given list value and adds it to the container. More...

Vector2ListField *	addVector2List (const char *name)
	Creates an Vector2ListField field with `name` and empty list value and adds it to the container. More...

Vector2ListField *	addVector2List (const char *name, const std::vector< Vector2 > &value)
	Creates an Vector2ListField field with `name` and given list value and adds it to the container. More...

Vector3ListField *	addVector3List (const char *name)
	Creates an Vector3ListField field with `name` and empty list value and adds it to the container. More...

Vector3ListField *	addVector3List (const char *name, const std::vector< Vector3 > &value)
	Creates an Vector3ListField field with `name` and given list value and adds it to the container. More...

Vector4ListField *	addVector4List (const char *name)
	Creates an Vector4ListField field with `name` and empty list value and adds it to the container. More...

Vector4ListField *	addVector4List (const char *name, const std::vector< Vector4 > &value)
	Creates an Vector4ListField field with `name` and given list value and adds it to the container. More...

size_t	getNumFields () const
	Returns the number of added fields. More...

bool	hasField (const std::string &name) const
	Returns true if the field with name `name` exists; otherwise false is returned. More...

Field *	getField (const std::string &name) const
	Returns the pointer to the field with name `name`. More...

Field *	getField (MLint index) const
	Returns pointer of field at `index` if it exists. If not, -1 is returned. More...

MLint	getFieldIndex (Field *field) const
	Returns index of `field` if it exists. If not, -1 is returned. More...

void	setFieldStringValue (const std::string &name, const std::string &value)
	Sets the `value` of the field with `name` if it exists. More...

std::string	getFieldStringValue (const std::string &name) const
	Returns the string value of the field with `name` if it is found. More...

virtual void	activateAttachments ()
	Reactivates notification handling, i.e., all fields of this module will send notifications again to attached sensors and fields if their value is set or changed. More...

virtual void	deactivateAttachments ()
	Disables notification handling, i.e., all fields of this module will not send notifications to attached sensors and fields any more if their values are set or changed. More...

Public Member Functions inherited from ml::Base
	Base ()
	Constructor. More...

virtual	~Base ()
	Destructor. More...

virtual Base *	deepCopy () const
	Set addStateToTree version number that can be accessed via getAddStateVersion() More...

bool	isOfAllowedType (const std::vector< const RuntimeType * > &types) const
	Check if this object's type is equal to or derived from one of the types given in the argument. More...

virtual bool	isRefCountedBase () const
	Returns if the instance is derived from RefCountedBase. More...

virtual std::string	detailString () const
	Return a string describing this object. More...

virtual bool	implementsPersistence (PersistenceInterface) const
	Override this method to declare which persistence interfaces are implemented by your derived class. More...

virtual std::string	persistentState () const
	Returns a string describing the object's internal state. More...

virtual void	setPersistentState (const std::string &state)
	Restores the object's internal state from a string that had been previously generated using `persistentState()`. More...

virtual void	addStateToTree (TreeNode *) const
	Attaches the object state as children of the given parent node. More...

virtual void	readStateFromTree (TreeNode *)
	Reads the object state from the children of the given parent node. More...

virtual void	writeTo (AbstractPersistenceOutputStream *) const
	Write the objects state to the data stream object. More...

virtual void	readFrom (AbstractPersistenceInputStream *, int)
	Read the objects state from the data stream object. More...

Static Public Member Functions
Convenience functions and methods.
static MLErrorCode	getTile (PagedImage image, SubImageBox loc, MLDataType datatype, void data, const ScaleShiftData &scaleShiftData=ScaleShiftData(), MLRequestProgressCB progressCallback=nullptr, void *progressCallbackUserData=nullptr)
	For documentation see Host::getTile() function with same signature. More...

static MLErrorCode	getTile (PagedImage image, SubImage &subimg, const ScaleShiftData &scaleShiftData=ScaleShiftData(), MLRequestProgressCB progressCallback=nullptr, void *progressCallbackUserData=nullptr)
	For documentation see Host::getTile() function with same signature and Module passed as reference. More...

static MLErrorCode	updateImageProperties (PagedImage *image)
	For documentation see Host::updateImageProperties() function with same signature. More...

static void	freeTile (void *data)
	For documentation see Host::freeTile(). More...

static void	updateProgress (const char info1, const char info2)
	For documentation see Host::updateProgress(). More...

static bool	shouldTerminate ()
	For documentation see Host::shouldTerminate(). More...

static Field *	getPressedNotifyField ()
	For documentation see Host::getPressedNotifyField(). More...

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

Convenience functions not wrapped from Host.
static std::string	getVoxelValueAsString (PagedImage image, const ImageVector &position, MLErrorCode errorCode=nullptr, const std::string &errorResult="")
	Returns the voxel value at position `position` of the image `image`. More...

Data base of currently instantiated modules.
static size_t	getNumModules ()
	Returns number of instantiated modules. More...

static Module *	getModule (size_t index)
	Returns pointer to instantiated module `index`. More...

static MLint	findModuleIndex (Module &module)
	Returns index of Module `module`. If not found -1 is returned. More...

static void	destroyModule ()
	Destroys static allocated tables to avoid memory leaks. More...

Protected Member Functions
void	handleNotificationInternal (Field *field, FieldSensor::Strength strength) override
	Called from FieldContainer whenever a field changes. More...

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

Control of handleNotification calls.
void	handleNotificationOff ()
	Decreases lock counter for handleNotification calls. More...

void	handleNotificationOn ()
	Increases lock counter for handleNotification calls. More...

bool	isHandleNotificationOn ()
	Returns true if handleNotification calls are permitted, otherwise false. More...

Protected Member Functions inherited from ml::Base
virtual char *	getPersistentState () const
	Returns a C string describing the object's internal state. More...

virtual void	setPersistentState (const char *)
	Restores the object's internal state from a string that had been previously generated using `getPersistentState()`. More...

virtual void	clearPersistentState (char *) const
	Disposes a string previously allocated by `getPersistentState()`. More...

Friends
class	Host
	Permit other classes access to protected methods. More...

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

MLint	getBypass (MLint outputIndex=0) const
	Returns the currently bypass index or -1 if bypassing is disabled (default). More...

THREAD_SUPPORT	getThreadSupport () const
	Returns the multithreading mode supported by this module, default is NO_THREAD_SUPPORT. More...

bool	areRecursiveHandleNotificationsPermitted () const
	Returns if recursive entries in handleNotification are permitted. More...

MLint	getHandleNotificationEntryCounter () const
	A counter returning the current number of (recursive re)entries in handleNotification. More...

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`. More...

void	unsetOutputImageInplace (MLint outputIndex=0)
	Clear optimization flag: output page of output at `outputIndex` and input tile shall use different memory buffers in calculateOutputSubImage(). More...

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

void	setClampPagesToImageExtent (bool flag=true)
	Enables/disables page clamping on all output images. More...

void	setThreadSupport (THREAD_SUPPORT supportMode)
	Pass any THREAD_SUPPORT `supportMode` to decide whether and what type of multithreading is supported by this module. More...

void	permitRecursiveHandleNotifications (bool enable)
	If this flag is set to `enable` =true, recursive entries in handleNotification are permitted. More...

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

bool	isSupportedVoxelDataType (MLDataType dt) const
	Check if a given data type is supported on the module as configured with setVoxelDataTypeSupport. More...

void	setVoxelDataTypeSupport (PERMITTED_TYPES permTypes)
	Specifies which types this module supports. More...

Input handling
enum	INPUT_STATE { DISCONNECTED = 0 , CONNECTED_BUT_INVALID = 1 , CONNECTED_AND_VALID = 2 , CONNECTED_BUT_NEEDS_UPDATE = 3 }
	See documentation of handleInput. More...

enum	INPUT_HANDLE { INVALIDATE = 0 , ALLOW_INVALID_INPUT = 2 }
	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. More...

INPUT_STATE	getInputState (MLint index)
	Returns the current state of the input connection. More...

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

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

void	touchOutputImageFields () const
	Touch all output image fields to indicate that the images have changed. More...

FieldContainer *	getFieldContainer ()
	Returns a pointer to the container of all the module's fields. More...

const FieldContainer *	getFieldContainer () const
	Returns a constant pointer to the container of all the module's fields. More...

virtual void	beginSaveFields ()
	Called before all fields data contents of this modules are saved. More...

virtual void	endSaveFields ()
	Called after saving all field contents of this module. More...

virtual void	handleNotification (Field *)
	Called when any field data in the field container of this module is modified. More...

Virtual methods to implement the image processing algorithm.
virtual CalculateOutputImageHandler *	createCalculateOutputImageHandler (PagedImage *outputImage)
	Creates the CalculateOutputImageHandler for the given output image `outputImage`. More...

virtual void	calculateOutputImageProperties (int outputIndex, PagedImage *)
	Set properties of output image `outputImage` with output index `outputIndex`. More...

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`. More...

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`. More...

Additional Inherited Members
Public Types inherited from ml::Base
enum	PersistenceInterface { PersistenceByString , PersistenceByTreeNode , PersistenceByStream }
	This enum describes the different persistence interfaces available. More...

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 155 of file mlModule.h.

Member Enumeration Documentation

◆ INPUT_HANDLE

enum ml::Module::INPUT_HANDLE

See documentation of handleInput.

Enumerator
INVALIDATE
ALLOW_INVALID_INPUT

Definition at line 342 of file mlModule.h.

◆ INPUT_STATE

enum ml::Module::INPUT_STATE

See documentation of handleInput.

Enumerator
DISCONNECTED
CONNECTED_BUT_INVALID
CONNECTED_AND_VALID
CONNECTED_BUT_NEEDS_UPDATE

Definition at line 330 of file mlModule.h.

◆ PERMITTED_TYPES

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 288 of file mlModule.h.

◆ THREAD_SUPPORT

enum ml::Module::THREAD_SUPPORT

protected

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

Enumerator
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	Deprecated: use MULTITHREADED instead
ML_CALCULATEOUTPUTSUBIMAGE_ON_ALL_TYPES	Deprecated: use MULTITHREADED instead

Definition at line 242 of file mlModule.h.

Constructor & Destructor Documentation

◆ Module()

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.

◆ ~Module()

ml::Module::~Module ( )

override

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

◆ adaptPageExtent()

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

◆ addInputConnector()

InputConnectorField* ml::Module::addInputConnector	(	const char *	name,
		Module *	module,
		MLint	i
	)

overridevirtual

Reimplemented from ml::FieldContainer.

◆ addInputImage()

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

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.

◆ addOutputConnector()

OutputConnectorField* ml::Module::addOutputConnector	(	const char *	name,
		Module *	module,
		MLint	i
	)

overridevirtual

Deprecated:: Use Module::addOutputImage() instead.

Reimplemented from ml::FieldContainer.

◆ addOutputImage()

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

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.

◆ areRecursiveHandleNotificationsPermitted()

bool ml::Module::areRecursiveHandleNotificationsPermitted ( ) const

Returns if recursive entries in handleNotification are permitted.

By default this setting is false.

◆ beginSaveFields()

virtual void ml::Module::beginSaveFields ( )

inlinevirtual

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

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

Reimplemented in ml::ListContainerBase.

Definition at line 803 of file mlModule.h.

◆ calculateInputSubImageBox()

virtual SubImageBox ml::Module::calculateInputSubImageBox	(	int	,
		const SubImageBox &	outputSubImageBox,
		int
	)

inlineprotectedvirtual

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.

Reimplemented in ml::MLImageFormatFileCache, ml::KernelEditor, ml::KernelBaseModule, and ml::ApplyDicomPixelModifiers.

Definition at line 616 of file mlModule.h.

◆ calculateOutputImageProperties()

virtual void ml::Module::calculateOutputImageProperties	(	int	outputIndex,
		PagedImage *
	)

inlineprotectedvirtual

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:

outputImage->setInvalid();

return;

Reimplemented in ml::ZeroCrossingsFilter, ml::SurroundFilter, ml::StdDeviationFilter, ml::Sobel3DFilter, ml::SigmaFilter, ml::RobertsFilter, ml::RankFilter, ml::MorphologyFilter, ml::LoGFilter, ml::LocalMaximaFilter, ml::KernelModule, ml::KernelCurvatureEstimationFilter, ml::KernelBaseModule, ml::ExtConvolutionFilter, ml::ConvolutionFilter, ml::BitMorphologyFilter, ml::MLImageFormatLoad, ml::MLImageFormatFileCache, ml::CSOConvertor, ml::AlgorithmModule, ml::KernelEditor, ml::MultiFileVolumeListSMImageOutput, ml::MultiFileVolumeListImageOutput, ml::DirectDicomImport, ml::DicomModifyTreeAndImage, ml::ApplyDicomPixelModifiers, and ml::PCLVoxelGrid.

Definition at line 600 of file mlModule.h.

References calculateOutputImageProperties().

Referenced by calculateOutputImageProperties().

◆ calculateOutputSubImage()

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

protectedvirtual

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.

Reimplemented in ml::KernelEditor, ml::MLImageFormatLoad, ml::MLImageFormatFileCache, ml::MultiFileVolumeListSMImageOutput, ml::MultiFileVolumeListImageOutput, ml::DirectDicomImport, ml::ApplyDicomPixelModifiers, ml::RTImageToML, ml::RTDoseToML, and ml::PCLVoxelGrid.

◆ clearOutputImage()

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

Clear cached output image pages of output image i.

◆ createCalculateOutputImageHandler()

virtual CalculateOutputImageHandler* ml::Module::createCalculateOutputImageHandler ( PagedImage * outputImage )

protectedvirtual

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.

Reimplemented in ml::AlgorithmModuleExampleWithOutputImage.

◆ destroyModule()

static void ml::Module::destroyModule ( )

static

Destroys static allocated tables to avoid memory leaks.

Only to be called on ML destruction.

◆ endSaveFields()

virtual void ml::Module::endSaveFields ( )

inlinevirtual

Called after saving all field contents of this module.

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

Reimplemented in ml::ListContainerBase.

Definition at line 808 of file mlModule.h.

◆ findModuleIndex()

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

static

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

◆ freeTile()

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

static

For documentation see Host::freeTile().

◆ getBypass()

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.

◆ getFieldContainer() [1/2]

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 777 of file mlModule.h.

Referenced by ml::CopyBase< BASE_DERIVED_CLASS >::CopyBase(), and ml::ListContainerTemplate< T >::ListContainerTemplate().

◆ getFieldContainer() [2/2]

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 782 of file mlModule.h.

◆ getHandleNotificationEntryCounter()

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

◆ getInputImage()

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.

Referenced by ml::determineImageFilterInRegionTN(), and ml::determineImageFilterOutImageRegionTN().

◆ getInputImageField()

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

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

◆ getInputState()

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

◆ getMetaProfile()

MLMetaProfilePtr& ml::Module::getMetaProfile ( ) const

Returns the meta profile for the base operator.

◆ getModule()

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

static

Returns pointer to instantiated module index.

◆ getNumInputImages()

MLint ml::Module::getNumInputImages ( ) const

Returns number of input images of this module.

◆ getNumModules()

static size_t ml::Module::getNumModules ( )

static

Returns number of instantiated modules.

◆ getNumOutputImages()

MLint ml::Module::getNumOutputImages ( ) const

Returns number of output images of this module.

◆ getOutputImage()

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

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

◆ getOutputImageField()

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

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

◆ getOutputImageInplace()

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.

◆ getPressedNotifyField()

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

static

For documentation see Host::getPressedNotifyField().

◆ getThreadSupport()

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.

◆ getTile() [1/2]

static MLErrorCode ml::Module::getTile	(	PagedImage *	image,
		SubImage &	subimg,
		const ScaleShiftData &	scaleShiftData = `ScaleShiftData()`,
		MLRequestProgressCB *	progressCallback = `nullptr`,
		void *	progressCallbackUserData = `nullptr`
	)

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.

◆ getTile() [2/2]

static MLErrorCode ml::Module::getTile	(	PagedImage *	image,
		SubImageBox	loc,
		MLDataType	datatype,
		void **	data,
		const ScaleShiftData &	scaleShiftData = `ScaleShiftData()`,
		MLRequestProgressCB *	progressCallback = `nullptr`,
		void *	progressCallbackUserData = `nullptr`
	)

static

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

On NULL op parameter ML_BAD_OPERATOR_POINTER is returned.

◆ getTypeNameFast()

const char* ml::Module::getTypeNameFast ( ) const

inline

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. Get registered type name of this module, returns "<unregistered_module>" if not registered. Unlike getTypeIdName() this will not print an error message if the type is not registered.

Definition at line 910 of file mlModule.h.

◆ getUpdatedInputImage()

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

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

Referenced by ml::getInputAsItkImportImageAndSubImg().

◆ getUpdatedInputState()

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.

◆ getVoxelDataTypeSupport()

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.

◆ getVoxelValueAsString()

static std::string ml::Module::getVoxelValueAsString	(	PagedImage *	image,
		const ImageVector &	position,
		MLErrorCode *	errorCode = `nullptr`,
		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.

◆ handleInput()

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

inlinevirtual

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:

no image is not connected (state == Module::DISCONNECTED)
image is connected, but not valid after call to updateImageProperties() (state == Module::CONNECTED_BUT_INVALID)

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:

Module::INVALIDATE - Default value, the input needs to be connected and valid.
Module::ALLOW_INVALID_INPUT - Indicates that it is acceptable by the module that the input image is not present/invalid.
Module::REDIRECT_TO_DUMMY_OP - DEPRECATED, indicates that getInputImage() should return a global dummy image instead of the invalid image.

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.

Reimplemented in ml::MLImageFormatFileCache, and ml::DicomModifyTreeAndImage.

Definition at line 377 of file mlModule.h.

◆ handleNotification()

virtual void ml::Module::handleNotification ( Field * )

inlineprotectedvirtual

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 798 of file mlModule.h.

◆ handleNotificationInternal()

void ml::Module::handleNotificationInternal	(	Field *	field,
		FieldSensor::Strength	strength
	)

overrideprotectedvirtual

Called from FieldContainer whenever a field changes.

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

Reimplemented from ml::FieldContainer.

◆ handleNotificationOff()

void ml::Module::handleNotificationOff ( )

protected

Decreases lock counter for handleNotification calls.

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

◆ handleNotificationOn()

void ml::Module::handleNotificationOn ( )

protected

Increases lock counter for handleNotification calls.

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

◆ isHandleNotificationOn()

bool ml::Module::isHandleNotificationOn ( )

protected

Returns true if handleNotification calls are permitted, otherwise false.

◆ isInputImageField()

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.

◆ isSupportedVoxelDataType()

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

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

◆ permitRecursiveHandleNotifications()

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.

◆ processAllPages() [1/2]

MLErrorCode ml::Module::processAllPages	(	int	outputIndex = `-1`,
		SubImageBox	region = `SubImageBox()`,
		MLRequestProgressCB *	progressCallback = `nullptr`,
		void *	progressCallbackUserData = `nullptr`
	)

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.

Note: Using a ProcessAllPagesHandler instead of calling this method will give you more flexibility, see method below.; This method gives no guarantee at all in which order the pages are calculated, especially if a multi-threaded host is used. So if you need an ordering guarantee, you need to implement a loop using getTile() calls instead.

The normal page-based 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. This is done regardless of the size of the requested region.
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::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.
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. For details on progressCallback, see Host::getTile().

◆ processAllPages() [2/2]

MLErrorCode ml::Module::processAllPages	(	ProcessAllPagesHandler &	handler,
		SubImageBox	region = `SubImageBox()`,
		MLRequestProgressCB *	progressCallback = `nullptr`,
		void *	progressCallbackUserData = `nullptr`
	)

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. For details on progressCallback, see Host::getTile().

◆ processMissingPages()

MLErrorCode ml::Module::processMissingPages	(	int	outputIndex = `0`,
		SubImageBox	region = `SubImageBox()`,
		MLRequestProgressCB *	progressCallback = `nullptr`,
		void *	progressCallbackUserData = `nullptr`
	)

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. For details on progressCallback, see Host::getTile().

◆ provideCustomPage()

virtual void ml::Module::provideCustomPage	(	int	,
		const SubImageBox &	,
		MLMemoryBlockHandle &
	)

inlineprotectedvirtual

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 653 of file mlModule.h.

◆ setBypass()

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.

◆ setClampPagesToImageExtent()

void ml::Module::setClampPagesToImageExtent ( bool flag = true )

protected

Enables/disables page clamping on all output images.

(default when not called is false, for backward compatibility) For details, see PagedImage::setClampPagesToImageExtent().

◆ setOutputImageInplace()

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.

◆ setThreadSupport()

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.

◆ setVoxelDataTypeSupport()

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.

◆ shouldTerminate()

static bool ml::Module::shouldTerminate ( )

static

For documentation see Host::shouldTerminate().

◆ touchOutputImageFields()

void ml::Module::touchOutputImageFields ( ) const

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

◆ unsetOutputImageInplace()

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

◆ updateImageProperties()

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.

◆ updateProgress()

static void ml::Module::updateProgress	(	const char *	info1,
		const char *	info2
	)

static

For documentation see Host::updateProgress().

Friends And Related Function Documentation

◆ ClassicHost

friend class ClassicHost

friend

Definition at line 167 of file mlModule.h.

◆ Host

friend class Host

friend

Permit other classes access to protected methods.

Definition at line 161 of file mlModule.h.

◆ ModuleCalculateOutputImageHandler

friend class ModuleCalculateOutputImageHandler

friend

Definition at line 165 of file mlModule.h.

◆ PagedImage

friend class PagedImage

friend

Definition at line 162 of file mlModule.h.

◆ PageRequest

friend class PageRequest

friend

Definition at line 163 of file mlModule.h.

◆ State

friend class State

friend

Definition at line 166 of file mlModule.h.

◆ TileRequest

friend class TileRequest

friend

Definition at line 164 of file mlModule.h.

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

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Image processing and general properties of the module.

Data type support of this module.

Input handling

Management of fields

Virtual methods to implement the image processing algorithm.

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ INPUT_HANDLE

◆ INPUT_STATE

◆ PERMITTED_TYPES

◆ THREAD_SUPPORT

Constructor & Destructor Documentation

◆ Module()

◆ ~Module()

Member Function Documentation

◆ adaptPageExtent()

◆ addInputConnector()

◆ addInputImage()

◆ addOutputConnector()

◆ addOutputImage()

◆ areRecursiveHandleNotificationsPermitted()

◆ beginSaveFields()

◆ calculateInputSubImageBox()

◆ calculateOutputImageProperties()

◆ calculateOutputSubImage()

◆ clearOutputImage()

◆ createCalculateOutputImageHandler()

◆ destroyModule()

◆ endSaveFields()

◆ findModuleIndex()

◆ freeTile()

◆ getBypass()

◆ getFieldContainer() [1/2]

◆ getFieldContainer() [2/2]

◆ getHandleNotificationEntryCounter()

◆ getInputImage()

◆ getInputImageField()

◆ getInputState()

◆ getMetaProfile()

◆ getModule()

◆ getNumInputImages()

◆ getNumModules()

◆ getNumOutputImages()

◆ getOutputImage()

◆ getOutputImageField()

◆ getOutputImageInplace()

◆ getPressedNotifyField()

◆ getThreadSupport()

◆ getTile() [1/2]

◆ getTile() [2/2]

◆ getTypeNameFast()

◆ getUpdatedInputImage()

◆ getUpdatedInputState()

◆ getVoxelDataTypeSupport()

◆ getVoxelValueAsString()

◆ handleInput()

◆ handleNotification()

◆ handleNotificationInternal()

◆ handleNotificationOff()

◆ handleNotificationOn()

◆ isHandleNotificationOn()

◆ isInputImageField()

◆ isSupportedVoxelDataType()

◆ permitRecursiveHandleNotifications()

◆ processAllPages() [1/2]

◆ processAllPages() [2/2]

◆ processMissingPages()

◆ provideCustomPage()

◆ setBypass()

◆ setClampPagesToImageExtent()

◆ setOutputImageInplace()

◆ setThreadSupport()

◆ setVoxelDataTypeSupport()

◆ shouldTerminate()

◆ touchOutputImageFields()