Guidelines for Developing a New TTK Module

Thanks for creating a new module for TTK!

Please take the time to review our guidelines below, which will hopefully ease your work.

1. Module structure

As documented in TTK's companion paper, each TTK module is organized in 3 layers:

• Base layer core/base/: This directory contains the implementations of the core algorithms.
• VTK layer core/vtk: This directory provides wrappers for the VTK API.
• ParaView layer paraview/: This directory provides XML specifications for the ParaView support. We provide a set of scripts which will help you create automatically all the necessary files. To create a blank new module, enter the following command from the top of TTK's source tree: scripts/createTTKmodule.sh <Name, first letter in uppercase, no space. for example: HelloWorld>

Assuming your module name is HelloWorldThe above command will create the following directories:

• core/base/helloWorld
• core/vtk/ttkHelloWorld
• core/paraview/HelloWorld
• standalone/HelloWorld The last directory (standalone/HelloWorld) contains 2 standalone programs using your new module (one in command line, the other one with a basic VTK-based GUI). If you do now wish to provide/maintain these standalone programs, simply remove the directory standalone/HelloWorld.

At this point, if you build and install TTK, your new module should be readily available and executable in ParaView.

If you wish to delete a module (for instance the above HelloWorld example), enter the following command: $ scripts/deleteTTKmodule.sh HelloWorld

You can also create a new module by cloning an already-existing module (which is particularly useful to copy a specific configuration of the VTK layer, in terms of inputs and outputs): scripts/cloneTTKmodule.sh

If you created your module with the createTTKmodule.sh script, you can start to adjust the module to your needs by typically updating the input and output specification at the VTK/ParaView layers. For this, follow the TODO comments, in increasing order, from the file core/vtk/ttkHelloWorld/ttkHelloWorld.h. Note that modifications made to the VTK layer will have to be reported to the ParaView and standalone components.

Once you have adjusted the inputs and outputs of your TTK module, you can proceed with the implementation of the core algorithm in the base layer. For this, follow the TODO comments, in increasing order, from the file core/base/helloWorld/HelloWorld.h. Note that this file contains many other comments providing useful recommendations (in particular regarding interactions with TTK's internal triangulation data structure).

Note that by default, new modules will use TTK's internal triangulation data structure for efficient mesh traversals. Please review this class documentation before using it, as it uses a pre-conditioning mechanism.

Now, before diving in the implementation of your module, we invite you to read carefully the following recommendations.

2. Implementation recommendations

• base layer:
  • The core TTK classes (implementing the core of your module) should be implemented as templatized functors.
  • dMsg
• vtk layer:
  • helloworld
• ParaView layer: make sure to assign your module to the right category.
• Third-party dependencies:
• General recommendations:
  • Never use new (or related functions, such as VTK's ::New()).

3. Authorship and references

4. Documentation