25.2. Modules (C++) Wizard

[Tip]Tip

For details on using the C++ module creation wizard, see the Getting Started, chapter Developing ML Modules.

The Wizards for programmed modules of the type Inventor, ML, and WEM module start rather similar, with a first dialog on which the name, package and other descriptors are added.

The Wizard leads through the creation process. Move between the dialogs with Back and Next. The settings can be saved at any point as .wiz file via Save Setting.

Please refer to the Getting Started document for a complete list of the files that are generated by the wizard.

[Note]Note

After module creation, the module database has to be reloaded before the new module can be used in a network.

25.2.1. First C++ Module Wizard Dialog

Figure 25.3. First C++ Module Wizard Dialog — ML Module Example

First C++ Module Wizard Dialog — ML Module Example

Name

Enter the <ModuleName> here. It has to be a unique name within the MeVisLab module database (including the SDK module database).

Author, Comment, Keywords, See Also, Genre:

Enter descriptors to classify the module within the MeVisLab module database. Author, comment and genre are mandatory entries. See the descriptions of existing modules for inspiration of what to enter here. Errors in the descriptions will be displayed in the Debug Output upon loading the module database.

Add reference to example network

If selected, creates an empty example network <ModuleName>Example.mlab which may be edited later (optional). It is recommended that each module should be completed by an example network to explain its function and usage in an exemplary application.

Select Target Package

Sets the Package for the module project. Select one from the list. For more information on Packages, see Section 25.5, “Packages”.

Project Properties

Directory Structure

  • Classic: the project files are separated into Sources and Modules folders

  • Self-contained: all project files are located in one self-contained folder that makes it easy to move and exchange the whole folder

Figure 25.4. Create an ML Module in a Self-contained Folder

Create an ML Module in a Self-contained Folder

Select

Allows adding the project to an already existing ML project within the selected Target Package. The selected project name is inserted in the field Project.

If working without a license file, the project prefix receives a leading underscore, for example “_ML”.

Include project files

If selected, the following C++ files are also created (in addition to the files listed above): <ModuleName>System.h, <ModuleName>Init.h, <ModuleName>Init.cpp, <ModuleName>.pro, <ModuleName>.bat, <ModuleName>.sh.

Click Next for the next screen, which is specific for each module type available in the Wizard.

25.2.2. Inventor Module

For the first dialog, see Section 25.2.1, “First C++ Module Wizard Dialog”.

Figure 25.5. Inventor Type

Inventor Type

The Open Inventor module has to be assigned a module type. Select a type to see additional comments in the Info area.

  • SoShape: Creates an Inventor shape, representing a geometric object, for example cones, spheres, cubes and alike. Functions for GLRender, handleEvent, etc. are provided.

  • SoGroup: Creates an Inventor group, which offers more than one input.

  • SoSeparator: Creates an Inventor separator. In addition to a SoGroup, the OpenGL state is pushed and popped.

  • SoNode: Creates a basic Inventor node.

  • SoView2DExtension: Creates a View2D extension which renders in Open GL on a 2D viewer and processes user interaction (mouse, keyboard).

  • Add Node Sensor: Adds a SoNodeSensor that will trigger on any field changes and thus allows for user interaction. The necessary code is provided to fill in the gaps.

  • Verbose comments: Adds verbose comments that you might want to add when first trying out this Wizard.

  • Example code: Adds additional example source code.

  • Has group inputs: (not for all Open Inventor module variants): Sets whether the MeVisLab GUI allows multiple SoNode inputs.

Click Next for the next screen, see Section 25.4, “Module Field Interface”,

25.2.3. ML Module

ML modules generate compilable C++ code and platform-dependent project files to implement a new image processing template module in MeVisLab. Define the number of image inputs and outputs of the module as well as module parameters (fields). After compilation and reloading of the module database via ExtrasReload Module Database (Clear Cache), you can create the new module on your network document. If you created the module in an existing Project (DLL) you may have to restart MeVisLab (use FileRestart With Current Networks).

[Note]Note

The properties available in this dialog are also described in the ML Guide, chapter Deriving Your Own Module From Module. The Project Wizard simply makes it easier to implement these methods.

As of MeVisLab version 2.1, two implementation styles of ML modules are available, new and classic. The difference is that in the classic ML style, the standard assumption was that input and output image were of the same data type, and changes of the data type had to be programmed manually. In the code, this was done via Template that had the data type as parameter, and during compilation, the function ML_CalculateOutputSubImage was compiled as routine for all data types.

In contrast to this, the new style ML module does not use the Template mechanism but uses handler classes for the input/output routine. The wizard supports the handling configuration already in the GUI.

For the first dialog, see Section 25.2.1, “First C++ Module Wizard Dialog”.

25.2.3.1. ML Module (New Style)

Figure 25.6. Imaging Module Properties (New Style)

Imaging Module Properties (New Style)

Number of Input/Output Images

Inputs, Outputs: Sets the number of image processing inputs and outputs.

The handling of the datatypes of output and input image is done in via the drop-down lists in the window.

In the following figures, the number of Inputs is set to two so that the extended Handling and Reference options are better visible.

Figure 25.7. New Style ML Module

New Style ML Module

Two options are available for the handling of the output image:

  • uses fixed datatype: Sets the output datatype to a fixed format that has to be entered in the column Type Support, see Figure 25.8, “New Style ML Module — Uses Fixed Datatype ”.

    Figure 25.8. New Style ML Module — Uses Fixed Datatype

    New Style ML Module — Uses Fixed Datatype

  • uses datatype of: Sets the output datatype to the same format as the selected input image. In addition, the supported types can be limited to certain types in the column Type Support.

    Figure 25.9. New Style ML Module — Uses Datatype Of Input Image

    New Style ML Module — Uses Datatype Of Input Image

    Figure 25.10. New Style ML Module — Entering The Supported Types

    New Style ML Module — Entering The Supported Types

Three options are available for the handling of the input image:

Figure 25.11. New Style ML Module — Configuring The Input Handling

New Style ML Module — Configuring The Input Handling

Below the configuration of the input/output types, two image processing options are available:

Image Processing Methods

Add calculateInputSubImageBox(): If enabled, the method calculateInputSubImageBox() is added. It is required if the calculation of an output page requires another (smaller or larger) image region from the input than the one of the output page.

Add voxel loop to calculateOutputSubImage(): If enabled, an example loop is implemented which reads all voxels from input 0 (if available) and copies them to the output page. It simplifies loop-based implementations of calculateOutputSubImage().

Click Next.

25.2.3.2. ML Module (Classic Style)

[Note]Note

For new modules, it is recommended to use the new style. The classic style implementation is offered as legacy option. For an explanation of new style versus classic style, see Section 25.2.3, “ML Module”.

Figure 25.13. Imaging Module Properties (Classic Style)

Imaging Module Properties (Classic Style)

Number of Input/Output Images

Inputs, Outputs: Sets the number of image processing inputs and outputs.

Image Processing Methods

Add calculateInputSubImageBox(): If enabled, the method calculateInputSubImageBox() is added. It is required if the calculation of an output page requires another (smaller or larger) image region from the input than the one of the output page.

Modify input/output data types: If enabled, adds demo code for the modification of input/output image data types in classic style. (For new style ML module, the modification of data types is supported in the methods and the GUI, see Section 25.2.3.1, “ML Module (New Style)”.)

Add calculateOutputSubImage() template: If enabled, a template function is added for the implementation of the virtual method calculateOutputSubImage(). This is the typical way to implement the algorithm independent of the voxel type.

Add voxel loop to calculateOutputSubImage(): If enabled, an example loop is implemented which reads all voxels from input 0 (if available) and copies them to the output page. It simplifies loop based implementations of calculateOutputSubImage().

Use type free loop: (Only active for certain selections) If enabled, an example loop is implemented which reads all voxels from input 0 (if available) and copies them to the output page. It is implemented without using any voxel types, but only copying the image memory voxel by voxel. Useful if the algorithm is type-independent or specific for a known voxel type.

Click Next.

25.2.3.3. Additional ML Module Properties

For both new and classic style ML modules, the same additional options are available:

Figure 25.14. Additional ML Module Properties

Additional ML Module Properties

Parameter Handling

Auto-update output images on field changes: If enabled, code is added to the handleNotification() method that causes a touching of the output image field(s) on changes of any input or parameter field.

Add handleInput(): If enabled, the method handleInput() is added. It is required if the module shall be able to operate with optionally disconnected or invalid image inputs.

Add activateAttachments(): If enabled, the method void activateAttachments() is added. It is called after module clones or reloads and is needed to update the internal module state/members after reload or clone operations if it depends on field values.

Documentation / GUI

Add more detailed comments: If enabled, more comments to the generated code, for example possible parameters, their effect or details about the methods or functions to be implemented are added to the code.

Add configuration hints: If enabled, hints for inplace, bypass, voxel type and multi-threading support are added to the code.

Add MDL window with fields: If enabled, a window section with all fields is added to the MDL definition file of the module.

Click Next for the next screen, if you want to add fields, see Section 25.4, “Module Field Interface”, Otherwise, click Create to create the new ML module.

25.2.3.4. ML Module — Created Files

When creating the new ML module, A number of files are generated, some of which have the same purpose in another surrounding/operating system:

In the path: <Package>/Modules/<ModuleType>/<ModuleName>

  • <ModuleName>.def: MeVisLab definition file

In the path: Modules/<ModuleType>/<ModuleName>/networks

  • testExample.mlab: Example network (template)

In the path: <Package>/Sources/<ModuleName>

  • <ModuleName>.vcxproj: Visual C++ project file

  • <ModuleName>System.h:

  • <ModuleName>Init.h: C++ header file

  • <ModuleName>Init.cpp: C++ file

  • <ModuleName>.bat: Windows batch file for creating the module project for the development environment (for example VC10).

  • <ModuleName>.sh: Shell script for Linux/Mac OS X (equivalent to batch file).

  • <ModuleName>.pro: .MeVisLab profile file, see qmake documentation.