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.xmlhas 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
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
Finally, since we won’t be editing any of the scalar fields, you can replace the
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
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.