Added C++ Tutorial (#139)

* Added C++ Tutorial

* Additional code sources

added comment for more code examples in Examples directory to be described later

* Review comments resolved

* additional review comments resolved

* next try

---------

Co-authored-by: Heckmann <sascha.heckmann@mevis.de>

Author: sahehb

mevislab.github.io/content/tutorials/image_processing/cpp_1.md

@@ -0,0 +1,181 @@
+---
+title: "Example 1: Creating a New ML Module for Adding a Value to Each Voxel"
+date: 2026-03-15T08:56:33+02:00
+status: "OK"
+draft: false
+weight: 602
+tags: ["Advanced", "Tutorial", "Image Processing", "C++"]
+menu: 
+  main:
+    identifier: "cpp1"
+    title: "Example 1: Creating a New ML Module for Adding a Value to Each Voxel"
+    weight: 602
+    parent: "cpp"
+---
+
+# Example 1: Creating a New ML Module for Adding a Value to Each Voxel
+
+## Precondition
+Make sure to have [cmake](https://cmake.org/download) installed. This example has been created using CMake Legacy Release (3.31.11).
+
+## Introduction
+In this example, we develop our own C++ ML module, which adds a constant value to each voxel of the given input image.
+
+## Steps to Do
+### Create a New ML Module
+Before creating the module, make sure to have your own user package available. See [Package creation](tutorials/basicmechanisms/macromodules/package/) for details about Packages.
+
+Use the *Project Wizard* via the menu entry {{< menuitem "File" "Run Project Wizard ..." >}} to create a new ML module. Select *ML Module* and click *Run Wizard*.
+
+![ML Module Project Wizard](images/tutorials/image_processing/cpp/cpp1_1.png "ML Module Project Wizard")
+
+Enter properties of your new module and give your module the name `SimpleAdd`. Make sure to select your user package and name your project *SimpleAdd*.
+
+![ML Module Properties](images/tutorials/image_processing/cpp/cpp1_2.png "ML Module Properties")
+
+ Click *Next*. The next screen of the Wizard allows you to define the inputs and outputs of your module. Select *Module Type* as *New style ML Module*, make sure to have one input and one output and leave the rest of the settings unchanged. 
+
+![ML Module Properties](images/tutorials/image_processing/cpp/cpp1_3.png "ML Module Properties")
+
+Click *Next*. On the next screen, we can define some additional properties of our module. Select *Add activateAttachments()*, unselect *Add configuration hints* and select *Add MDL window with fields*.
+
+![ML Module Additional Properties](images/tutorials/image_processing/cpp/cpp1_4.png "ML Module Additional Properties")
+
+Click *Next*. The Module Field Interface allows you to define additional fields for the module. More fields can be added later but this is the easiest way to add fields. Click *New* to create a new field, then enter the following:
+* **Field Name:** constantValue
+* **Field Type:** Double
+* **Field Comment:** This constant value is added to each voxel.
+* **Field Value:** 0.
+
+![ML Module Field Interface](images/tutorials/image_processing/cpp/cpp1_5.png "ML Module Field Interface")
+
+Click *Create*. You see a screen showing the results of the module creation process. In the case the Wizard finished succesfully, you can close the window. Additionally, an explorer window opens showing the created folder containing your sources and the *CMakeLists.txt*.
+
+The foundation of the module has been created with the Wizard. From here on, the programming starts.
+
+After module creation, the module database needs to be reloaded.
+
+### Preparing the Project
+The Project Wizard creates a *CMakeLists.txt* file that describes the typical projects settings and used source files. This file can be translated manually with the CMake tool into a project file for your preferred C++ development tool. But most Integrated Development Environments (IDEs) nowadays can open CMake files directly.
+
+Just make sure that the MLAB_ROOT environment variable is set on your system and points to the packages directory of your MeVisLab installation, because this is used to resolve the reference to the 'MeVisLab' project.
+
+Open a command line and change to your current module directory (the directory containing your *CMakeLists.txt* file). Enter **cmake . -G "Visual Studio 17"**. After execution, a lot of files are generated by CMake. 
+
+For further documentation about our use of CMake, see: [CMake for MeVisLab - Documentation](https://mevislabdownloads.mevis.de/docs/current/MeVisLab/Resources/Documentation/Publish/SDK/CMakeManual/#mainBook).
+
+### Programming the Functions of the ML Module
+Open the file *ALL_BUILD.vcxproj* in your preferred C++ development environment. Select the file *mlSimpleAdd.cpp*.
+
+{{<alert class="info" caption="Note">}}
+In the following code examples, the comment lines already available in the created *.cpp* file are added for better overview.
+{{</alert>}}
+
+#### Implementing *calculateOutputImageProperties*
+As we add a constant value to each voxel, we need to adjust the value range of the output image, which results in:
+
+{{< highlight filename="" >}}
+```c++
+outMin = inMin + constValue
+outMax = inMax + constValue
+```
+{{</highlight>}}
+
+Change the file *mlSimpleAdd.cpp* as shown below.
+
+{{< highlight filename="mlSimpleAdd.cpp" >}}
+```c++
+void SimpleAdd::calculateOutputImageProperties(int /*outputIndex*/, PagedImage* outputImage)
+{
+  // Set up data types and read-only flags of output image and input subimages.
+  SimpleAddOutputImageHandler::setupKnownProperties(outputImage);
+
+  // Change properties of output image outputImage here whose
+  // defaults are inherited from the input image 0 (if there is one).
+  // Get the constant add value.
+  const MLdouble constantValue = _constantValueFld->getDoubleValue();
+
+  // Get the input image's minimum and maximum values.
+  const MLdouble inMinValue = getInputImage(0)->getMinVoxelValue();
+  const MLdouble inMaxValue = getInputImage(0)->getMaxVoxelValue();
+
+  // Set the output image's minimum and maximum values.
+  outputImage->setMinVoxelValue(inMinValue + constantValue);
+  outputImage->setMaxVoxelValue(inMaxValue + constantValue);
+
+  // Verify whether the input/output data types are supported by our handler.
+  // This will invalidate the output image if the type combination is not supported by the handler.
+  SimpleAddOutputImageHandler::verifyProperties(outputImage);
+}
+```
+{{</highlight>}}
+
+{{<alert class="info" caption="Note">}}
+*outputIndex* is the index number of the output connector. It is commented out in this example, because we only defined one output. In the case of more than one outputs, uncomment this parameter.
+{{</alert>}}
+
+#### Implementing *typedCalculateOutputSubImage*
+Next, we are going to finally change the voxel values of the image. Open the file *mlSimpleAddOutputImageHandler.cpp*. A loop over all voxels of the output page is generated automatically and we want to add the constant value to each voxel. Add the following line at the start of the method to obtain the current constant value in the correct data type:
+
+{{< highlight filename="mlSimpleAddOutputImageHandler.cpp" >}}
+```c++
+  // Compute subimage of output image outIndex from input subimages.
+  const OUTTYPE constantValue = static_cast<OUTTYPE>(_parameters.constantValue);
+```
+{{</highlight>}}
+
+Then, change the inner line of the loop so that the constant value is added to the value of the input voxel:
+
+{{< highlight filename="mlSimpleAddOutputImageHandler.cpp" >}}
+```c++
+    // Process all row voxels.
+    for (; p.x <= rowEnd;  ++p.x, ++outVoxel, ++inVoxel0)
+    {
+      *outVoxel = *inVoxel0 + constantValue;
+    }
+```
+{{</highlight>}}
+
+Compile the project in the development environment. Make sure to select a *Release* build.
+
+### Use Your Module in MeVisLab
+Your compiled **.dll* is available in your project directory under *Sources/lib*. In order to use it in MeVisLab, it needs to be copied to the *lib* folder of your user package.
+
+This only works in a post-build step.
+
+If the environment variable *MLAB_AUTOMATIC_POSTBUILD_COPY* is set, the newly compiled DLLs and *.lib* files are copied to the correct location when MeVisLab restarts. Otherwise, they must be copied manually.
+
+For testing purposes, you can use a `LocalImage` module and two `View2D` modules. Connect the `SimpleAdd` module to the second `View2D` and change the <field>Constant Value</field> field.
+
+![Testing Network](images/tutorials/image_processing/cpp/cpp1_6.png "Testing Network")
+
+The output image of the module `SimpleAdd` is automatically recalculated on changing the field <field>Constant Value</field>. This is already implemented in the generated code of the file below:
+
+{{< highlight filename="mlSimpleAdd.cpp" >}}
+```c++
+    void SimpleAdd::handleNotification(Field* field)
+    {
+      // Handle changes of module parameters and input image fields here.
+      bool touchOutputs = false;
+      if (isInputImageField(field))
+      {
+        touchOutputs = true;
+      }
+      else if (field == _constantValueFld)
+      {
+        touchOutputs = true;
+      }
+
+      if (touchOutputs)
+      {
+        // Touch all output image fields to notify connected modules.
+        touchOutputImageFields();
+      }
+    }
+```
+{{</highlight>}}
+
+## Summary
+* MeVisLab allows to develop your own C++ modules.
+* The Project Wizard already generates all necessary *.cpp* and *.h* files and a loop through all voxels of the input image.
+* Changes of user-defined fields automatically lead to a recalculation of the input image.

mevislab.github.io/content/tutorials/image_processing/cpp_development.md

@@ -0,0 +1,65 @@
+---
+title: "Developing Your Own C++ Modules"
+date: 2026-03-15T08:56:33+02:00
+status: "OK"
+draft: false
+weight: 601
+tags: ["Advanced", "Tutorial", "Image Processing", "C++"]
+menu: 
+  main:
+    identifier: "cpp"
+    title: "Developing Your Own C++ Modules"
+    weight: 601
+    parent: "imageprocessing"
+---
+
+# C++ Module Development
+## Introduction
+The development of your own C++ modules can be done by ML modules and by Open Inventor modules.
+
+{{<alert class="info" caption="Important Information">}}
+Make sure to use a compiler that is compatible with your currently installed MeVisLab version.
+{{</alert>}}
+
+### ML Modules on the C++ Level
+* Image processing modules are objects derived from class Module defined in the ML library and therefore are also called ML modules.
+* Image inputs and outputs are connectors to objects of class PagedImage, which are defined in the ML library.
+* Inputs and outputs for abstract data structures are connectors to pointers of objects derived from class Base and are called Base objects.
+
+### Open Inventor Modules on the C++ Level
+* Most Open Inventor modules are objects derived from class SoNode, defined in the Open Inventor library.
+* Open Inventor inputs and outputs are connectors to objects derived from class SoNode, defined in the Open Inventor library. Many Open Inventor modules will return themselves as outputs (“self”). On inputs, they may have connectors to child Open Inventor modules.
+* Some Open Inventor modules are objects derived from class SoEngine. They are used for calculations and return their output not via output connectors but via parameter fields.
+* Open Inventor modules may also have input and output connectors to Base objects and Image objects.
+* All standard Open Inventor nodes defined in the Open Inventor library are available in MeVisLab as Open Inventor modules.
+
+This chapter describes some examples for developing your own ML and Open Inventor modules.
+
+## Some Tips for Module Design
+### Macro Modules or C++ Modules?
+In [Example 2: Macro Modules](tutorials/basicmechanisms/macromodules/), we already described Macro Modules and how to create them yourself.
+
+**Advantages of macros:**
+* Macros are useful for creating a layer of abstraction by hierarchical grouping of existing modules.
+* Scripts can be edited on the fly:
+  * no compilation and reload of the module database necessary
+  * scripting possible on the module or network level
+  * scripting supported by the Scripting Assistant View (basically a recorder for actions performed on the network)
+
+**Conclusion:**
+* For rapid prototyping based on existing image processing algorithms, use macros.
+* For implementing new image processing, write new ML or Open Inventor modules.
+
+### Combining Functionalities
+It is possible to have ML and Open Inventor connectors in the same module. Two cases are possible:
+* Type 1: **ML -> visualization:** Image data or properties are displayed by a visualization module. Usually a <field>SoSFXVImage</field> field gets random access to an ML image by *getTile()*. Examples: `SoView2D`, `GlobalStatistics`.
+* Type 2: **visualization -> ML:** Modules generate an ML image from an Open Inventor scene. Examples: `VoxelizeInventorScene`, `SoExaminerViewer` (hidden functionality).
+
+Generally, however, it is not always a good solution to combine that, as the processes of image processing and image visualization are usually separated.
+
+Therefore, rather separate the ML and Open Inventor functionalities into two modules. This way,
+* functionality is encapsulated and can be reused as module
+* modules for the single steps may already be available in MeVisLab and spare you a new development
+
+## Code Examples
+In addition to the tutorials in this chapter, you can find additional code examples in your MeVisLab installation directory.

mevislab.github.io/static/images/tutorials/image_processing/cpp/cpp1_1.png

@@ -1,7 +1,9 @@
 <div class="card" style="margin-bottom: 2rem">
+    {{ if not (eq (.Get "filename") "") }}
     <div class="card-header d-flex justify-content-between">
         <p class="card-title m-0">{{ with .Get "filename" }}{{.}}{{end}}</p>
     </div>
+    {{ end }}
     <div class="card-body">
         {{ .Inner | markdownify }}
     </div>