Skip to content

macro module #116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
May 21, 2025
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 100 additions & 12 deletions mevislab.github.io/content/tutorials/basicmechanisms/macromodules.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Example 2: Macro modules and Module Interaction"
date: 2022-06-15T08:58:44+02:00
date: 19-05-2025
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

adapt format

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

draft: false
weight: 370
status: "OK"
Expand All @@ -15,16 +15,104 @@ menu:

# Example 2: Macro modules {#TutorialChapter6}

## Macro modules and Module Interactions via User Interface and Python Scripting
## Macro Module
A macro module can be used to develop your own functionality in MeVisLab. You have two main options for how to use it:

MeVisLab provides different types of modules, which can be distinguished by their color. The brown modules are called Macro modules. Macro modules condense a whole network into one module. You can open the internal network by pressing the middle mouse button {{< mousebutton "middle" >}} or via right mouse click {{< mousebutton "right" >}} and select {{< menuitem "Help" "Show Internal Network" >}}. Macro modules provide the possibility to create customized user interfaces and Python interactions.
* **With Internal Networks**: Use a macro module to reuse a network of modules. For example, if you build a network that applies a specific image filter and you want to use this setup in multiple projects, you can wrap the entire network into a single macro module. This way, you don’t need to manually reconnect all the individual modules each time — you just use your macro module.You can see in the left side of the image is the Internal network. You can see an example in [Basic Mechanics of MeVisLab (Example: Building a Contour Filter)](/tutorials/basicmechanisms#TutorialMacroModules).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.You can see in the left side of the image is the Internal network. ->
. You can see the internal network at the left side of the image.

  • which image this refers to?


In [Chapter I - Basic Mechanics](./tutorials/basicmechanisms) we built a
contour filter and condensed all the modules into one local Macro module.
Until now, the local Macro module containing the contour filter can only
be used in the current network. In the following chapters, we like to make
the Macro module commonly available throughout projects and equip this
Macro module with panels and help pages. Commonly available macro
modules are called global macros and can be found in MeVisLab {{< menuitem "Module Search" >}}. Global macros and projects are stored
in packages. A package structure makes it easy to exchange projects and
different functionalities between people.
* **Without Internal Networks**: Use a macro module to add your own Python code. If MeVisLab is missing a specific functionality, you can write your own Python script and include it in a macro module.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can see the right side of the image the python code. ->
You can see the Python code at the right side of the image.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

This allows you to extend the software with custom behavior that integrates smoothly into your project. You can see the right side of the image the python code.

The figure below is a Macro Module with Internal Processing and Python Interaction:

![Internal Processing and Python Interaction](/images/tutorials/basicmechanics/with.png "Internal Processing and Python Interaction")

### Benefits:

* **Encapsulation:**
It takes an existing network of modules or Python code. To the user, interacting with the macro module, it appears as a single entity with its own defined inputs, outputs, and parameters. You don't need to know or interact with the internal functionality unless you specifically open the macro module for editing.
* **Reusability:**
Once you've created a macro module, you can easily add it to any other MeVisLab network, just like any built-in module. This promotes modularity and avoids the need to rebuild common processing pipelines repeatedly. For example, if you have a standard preprocessing pipeline for medical images, you can encapsulate it into a macro module and reuse it across different projects.
* **Simplified Interface:**
Often, a macro module will expose a simplified and more focused interface compared to the combined interfaces of all the modules within it. You can choose which inputs, outputs, and parameters of the internal network are exposed at the macro module's level. This makes it easier to use for specific tasks without being overwhelmed by too many options.

### Key characteristics:
* **Implementation:**
Macro modules are primarily defined using the MeVisLab Definition Language (MDL) and often incorporate Python scripting for more dynamic behavior. You don't need to write C++ code to create a macro module.
* **User Interface:**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

...using MDL.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

You can define your own User Interface for macro modules.
* **Scope:**
Macro modules can be either global (available in all your MeVisLab projects) or local (specific to the current network you are working on).

### Types of Macro modules:
#### Local Macro module:
A Local Macro in MeVisLab is a macro module that exists only within the context of the current network document - i.e. it’s defined *locally* rather than being installed into the global module database. It does not require a package, it lives only inside the current network file (.mlab) you’re working on.

* A local macro is visible and editable only in the current network.
* A local macro is not listed in the Modules panel and module search.
* A local macro can only be reused elsewhere by copying it into another folder with your network file.

#### Global Macro module:
A global macro module is stored in a central location within your MeVisLab installation's module directories (or a custom path) called Package. Once created, it appears in the module browser and can be used in any MeVisLab network you open. See [Package creation](/tutorials/basicmechanisms/macromodules/package/) for details about Packages.

* A global macro can be used in any MeVisLab network.
* A global macro is listed in the Modules panel and module search.

{{<alert class="info" caption="Info">}}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: zour

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Packages are the way MeVisLab organizes different development projects. You can organize zour own modules, test cases or C++ modules in a package.
{{</alert>}}

### Inputs, Outputs, and Fields:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: addd

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

You can addd inputs and outputs to your macro module to connect it with the other modules:
* **Inputs:** These are connection points through which the module receives data from other modules. You define inputs in the *\*.script* file using the Input keyword. You can also define the type for each input.
* **Outputs:** These are connection points through which the module sends processed data to other modules. You define outputs in the *\*.script* file using the Output keyword. You can also define the type for each output.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove an "also"

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

You can also add fields to your macro module. Fields allow you to change parameters for your module or to see the values of results. Fields can also be added to the panel of the macro module so that the user can change them.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

modules panel -> module's panel

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

* **Fields:** These are parameters that control the module's behavior, typically visible in the modules panel or in the Module Inspector. You define fields in the *\*.script* file using the Field keyword, specifying the data type, default value, and other properties.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typos

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

The below figure shows the input , outoutand feilds :
![Inputs, Outputs, and Fields](/images/tutorials/basicmechanics/fields.png "Inputs, Outputs, and Fields")

### Files Associated with a Macro Module:
Macro modules typically contain the following files:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: Defintion

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

* **Definition file (*\*.def*):** The module definition file contains the definition and information about the module like name, author, package, etc. **Defintion files are only available for global macro modules**.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for multiple situations -> on field changes and user interactions

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

* **Script file (*\*.script*):** The script file defines inputs, outputs, fields and the user interface of the macro module. In case you want to add Python code, it includes the reference to the Python script file. The *\*.script* file allows you to define Python functions to be called for multiple situations.

* **Module Initialization**: You can add the *initCommand* to the *Commands* section and the given Python function is called whenever the module is added to the workspace or reloaded.
* **Window creation**: You can add the *initCommand* to the *Window* section and the given Python function is called whenever the panel of the module is opened.
* **User interaction**: You can add commands to any user interface element like *Buttons* to call Python functions on user interactions with this element. The image below shows you the user interface and the internal interface:
![user interface and the internal interface](/images/tutorials/basicmechanics/mycountourFilter.png "user interface and the internal interface")

* **Field changes**: You can also react on any changes of fields in your module and create Field Listeners. See below for details.
* **Python file (*\*.py*):** *(Optional)*: The Python file contains the Python code that is used by the module. You can add Python functions to fields or UI elements to react on user interactions in the *\*.script* file.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also add section about .mlab and .mhelp files here.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


### Field Listeners:
Field listeners are mechanisms to execute Python code automatically when the value of a field changes. This allows you to create dynamic responses to user interactions in the module's parameter panel.

You create field listeners within the *Commands* sections of the *\*.script* file. You get a reference to the field object and then use a method to add a callback function that will be executed when the field's value is modified.

For an example see [Example 2.5.2: Module interactions via Python scripting](/tutorials/basicmechanisms/macromodules/scriptingexample2/).

## Summary
* Macro Module: a custom block in MeVisLab used to group a network of modules or custom Python code into a single reusable unit.

* Benefits:
* Organized structure.
* Easy to reuse across projects.
* Simplified user interface.

* Types:
* Local: Only available in the current network, not shown in the module browser.
* Global: Available in all projects, must be part of a package.

* Files
* (*\*.script*): Defines inputs, outputs, fields, and user interface.
* (*\*.py*): Optional, contains Python code.
* (*\*.def*): Definition file (only for global macros).

* Components
* Inputs/Outputs: For connecting the module with other modules.
* Fields: Parameters for user control
* Field Listeners: Run Python code when a field value changes

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Packages

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

* Package: are the way MeVisLab organizes different development projects. Required for global macros.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading