This assignment will be a first test at installing the Topology ToolKit (TTK) and building your first program. The goal is to make sure everyone has a working installation of TTK and that everyone is comfortable with which files are edited when you create a new module in TTK.

Simultaneously, we will also work with our first topological property: the Euler characteristic. We’ll use this to compute the genus of simple, triangulated 2-manifolds, in particular testing with the four data sets in data01.zip. You may also want to experiment with other meshes, but you will have to convert them to the VTK .vtp format. You may find A02 from CSC544 useful in this regards, both to understand ParaView, how to use it, and to understand VTK file formats.

Part 1: Download and Install

If you haven’t already, you’ll need to download and install a working copy of the TTK. Please follow the TTK installation instructions and install and compile all dependencies. You will also want to test that the example visualizations work, but they are more complex than what we will be looking at.

After installation, you’ll want to start watching the tutorial videos. Your feedback on these is important to the development of TTK, so please use Piazza to add any thoughts / comments about them. In particular, if you’re having trouble installing you may want to watch Tutorial 1. For the purposes of this assignment, Tutorial 3.d (on “extending TTK with a new module”) is of interest.

You’ll also want to familiarize yourself with the “TTK Developer Documentation” linked on the TTK Documentation page. This has the references for all of the standard classes (in particular the Triangulation class will be used).

Part 2: Your first TTK module

We’re going to use TTK to compute the Euler characteristic of triangulated 2-manifolds. You may assume the manifold is also orientable and that its embedding is intersection and boundary free. It turns out that with these assumptions, the filter requires only a very stripped down instance of a TTK module, where we load a dataset and simply count the number of vertices, edges, and faces. From there, we can extract the Euler characteristic and ultimately the genus of the triangulation.

From the top level, you will execute the scripts/createProject.sh. Create a new project called ComputeGenus. This should create the following files for you:

  • core/baseCode/computeGenus/* <– The class that will do actual computation
  • core/vtkWrappers/ttkComputeGenus/* <– The VTK wrappers for the base code
  • paraview/ComputeGenus/* <– The information for the ParaView plugin (in particular the file ComputeGenus.xml has important specifications)
  • standalone/ComputeGenus/cmd/* <– The code that will call the filter as a command line executable
  • standalone/ComputeGenus/gui/* <– The code that will call the filter as a VTK-based GUI executable

Familiarize yourself with all of the files in this directory before proceeding further.

createProject.sh creates a generic filter that is intended to work with a vtkDataObject that also has input and output vtkDataArray’s (scalar fields) associated with it. This extra machinery is because TTK is primarily designed to work with topological analysis of scalar fields. For computing genus, we will not need any of this power. We also will not need any specific parameters. Note this now, but you will eventually remove most of the logic for the above files that uses these. Part of this assignment is aimed to get comfortable with how values are passed between the various filters, so it is worth while to track which source files are manipulating which variables.

Your main task is to get a working filter that can compute both the Euler characteristic and genus of a mesh. When run correctly, you should see something like this (as an example, this is my output on torus.vtp):

[ComputeGenus] Data-set has an Euler characteristic of
[ComputeGenus] chi = 0 where 
[ComputeGenus] v = 2048
[ComputeGenus] e = 6144
[ComputeGenus] f = 4096
[ComputeGenus] And thus the genus is g = 1

The logic for this should all be inserted in core/baseCode/computeGenus/ComputeGenus.h, where you will have access to both the Triangulation data structure as well as an example of how to display output to the terminal.

Another key piece to the TTK code structure is how the base code files are wrapped by the VTK wrappers. This allows TTK modules to be called as VTK filters (a requirement for ParaView, but also useful as standalone programes). In particular ComputeGenus::execute() (defined in core/baseCode/computeGenus/ComputeGenus.h) will be called by vtkComputeGenus::doIt() (defined in core/vtkWrappers/ttkComputeGenus/ttkComputeGenus.cpp). Note though that execute() is a templated function, and you’ll see it uses a particular macro to set the template parameter (VTK_TT). For now, we won’t need any of this logic, so you can replace this with a call such as computeGenus_.execute<float>();, which hard codes the template type to be float. Note that, in this case a properly coded execute() function will not make use of the dataType anyway.

Finally, since we won’t be editing any of the scalar fields, you can replace the ShallowCopy() in doIt() with a DeepCopy(), and just pass through all of the input information to the output. Note that you’ll remove most of the logic here for copying the scalar fields. You should check out some of the other simple filters (such as GeometrySmoother, DistanceField, and SphereFromPoint) to see other examples of how data is passed through for future reference.

Make sure to test your code using all three methods to deploy it: as a ParaView plugin, as a command line tool, and as a GUI-based tool. After you’ve completed this, use the scripts/releaseProject.sh to create a working subdirectory (release/ComputeGenus) with your module and all of its dependencies. Edit the README file and be sure to add your name, email address, and report the number of vertices, edges, faces, and genus for each of the four models I’ve provided above. You may want to use either ParaView or the GUI to verify that the genus is correct for each of these.

Submission and Grading

Submit this entire release folder as a subdirectory to your git repository on bitbucket. We will follow a pattern similar to this for the remaining coding projects in the class.

Your grade for this assignment will be based on the following:

  • 25% Creating a working ParaView plugin
  • 25% Creating a working command line program
  • 25% Creating a working GUI-based program
  • 25% Completing the report.

This percentage will be scaled to the total value of this assignment for your final grade (7%). Extra credit may be assigned for going beyond the specifications of the assignment.