+ Of course instead of downloading TTK we will use our own repo
+ If you encounter errors during the installation, you might have to install more dependencies, or you can turn off certain features. If for example the compiler complains about the "Eigen3" library, then you can turn it off during the TTK cmake step.
+ If you get stuck don't hesitate to contact *Jonas Lukasczyk* at jl@jluk.de.
## Creating your own filters
1. Just clone an existing module (aka filter) instead of creating your own from scratch
+ Navigate into ttk folder
+ Run `./scripts/cloneTTKmodule.sh Blank YourModuleName`
(do not add the ttk prefix)
+ You will see some warnings as the *Blank* filter does not have standalone apps (but that doesn't matter for us)
+ This will generate the following directories that match the layers described earlier:
+`ttk/core/base/YourModuleName/`
+`ttk/core/vtk/ttkYourModuleName/`
+`ttk/paraview/YourModuleName/`
+ Note that this will still compile.
2. The files in these directories are well documented. Please read all the comments.
+ Start by looking at the `.h` and `.cpp` file at the **core** layer in `ttk/core/base/YourModuleName/`
+ The method `computeBoundingBox` just generates a bounding box that is scaled by a parameter
+ Note that the function writes its output into the `boundingBoxCoords` array that is passed as an argument
+ Next, go to the `.h` file of the **vtk** layer in `ttk/core/vtk/ttkYourModuleName/` and confirm for yourself that
+ The input of the filter inherits from `vtkPointSet`.
+ The output of the filter is a `vtkUnstructuredGrid`.
+ The constructor sets default parameters.
+ The **vtk** wrapper holds a private instance of the **core** code class.
+ Now check out the `.cpp` file of the **vtk** layer in `ttk/core/vtk/ttkYourModuleName/`
+ The `RequestData` method first fetches the input and output of the VTK filter (which is automatically provided by the VTK pipeline based on the information we specified in the header).
+ Next, the method initializes vectors that are passed to the function of the **base** code.
+ Finally, it convert the output to a `vtkUnstructuredGrid` (as promised in the header).
+ Lastly, open the `.xml` file in `ttk/paraview/YourModuleName/`
+ A lot of the things you can specify here are unfortunately unintuitive.
+ Have a look at the XML files of other filters to see how to specify text, double, integer, and bool input UI elements. The Cinema filters are a good resource as they cover a lot of different input/output scenarios.
3. Try out your filter:
+ Inside the TTK build folder run "cmake .." and then "make -jN install" where N is the number of cores on your machine.
+ Open ParaView.
+ As the new filter requires an input, lets just create a sphere (Sources/Sphere).
+ Hit apply and then select your filter which should be under (Filters/TTK - VFT/...).
+ After you hit apply you should see a quad.
+ Note the SomeIntParameter that can be used to scale the quad.
+ A Cinema database is a folder with the extension **.cdb** containing any kind of data product
+ The Cinema folder must contain at its root a **data.csv** file (comma separated value file) that lists all paths to these products (relative to the cdb folder) in a **FILE** column, and other columns record their associated parameters.
Generating a CDB is easy, especially within TTK (see below). Alternatively, to create a CDB from scratch:
1. Create a folder with the extension **.cdb**
2. Add all data products to that folder
+ Products can be of any kind, but it is strongly recommended to store products in a VTK file format such .vti or .vtu
3. Generate the **data.csv** file
+ A nice trick to automatically generate most of the data.csv file is to use the terminal to navigate to the database folder and then run **find**
```
cd Example.cdb
find * ./ > data.csv
```
+ If the filepaths contain some pattern (e.g., SimName_Time_Threshold.vti) then a simple search-replace with a regular expression can automatically detect parameter values. For example, in the tool **gedit** one can split a filename like **A/B_C.D** with the regular expression
```
(.*)(/)(.*)(_)(.*)(.)(.*)
```
into chunks, and the individual chunks can be referenced by **\i**, where i is the chunk index in the search pattern. Thus, replacing **A/B_C.D** with the expression
```
\1\2\3\4\5\6\7, \1, \3, \5
```
will generate the string **A/B_C.D, A, B, C**. Finally, it is only necessary to add the column names in the first row, e.g.,
```
FILE, A, B, C
```
Note the convention that the column containing the filepath is named **FILE**
## 2.5 Database Exploration
It is important to understand that Cinema only specifies that data products need to be stored in a folder, and that these products are listed in a **data.csv** together with the associated parameters. It is up to the user to create an application-dependent interface to their specific database.
For example, a database might contain color images of an object taken at every timestep from locations on a spherical grid. So the first two lines of the **data.csv** file could read as
```
FILE, Time, Phi, Theta
/data/img_0_45_90.jpg, 0, 45, 90
```
In this specific case, a simple viewer could contain a time-slider and a viewport where mouse movement controls the phi-theta values. Every time a parameter value changes, the viewer searches the **data.csv** file for the row that matches the parameters best and retrieves the corresponding image.
## 2.6 TTK / VTK Interface
TTK provides a very abstract and versatile interface to CDBs through the following filters:
+**ttkCinemaReader:** Opens the data.csv file of a CDB and converts it to a vtkTable.
+**ttkCinemaQuery:** convertes 1..n input vtkTables into an in-memory SQL database, runs a user-specified SQL command on the database, and returns the results as a vtkTable.
+**ttkCinemaProductReader:** Reads the actual data products referenced by some column (default: FILE) in vtkFormat.
+**ttkCinemaWriter:** Stores the input data product in a CDB and updates the data.csv file (field data attached to the product provides values for the csv columns).
# Further Resources
-[VTK Users' Guide](https://www.kitware.com/products/books/VTKUsersGuide.pdf) – outdated but still has a lot of relevant information. Chapter 3.1 describes the general architecture and data flow of VTK.
-[VTK Doxygen manuals](https://www.vtk.org/doc/nightly/html/) – documents all classes in VTK, e.g. [`vtkDataSet`](https://www.vtk.org/doc/nightly/html/classvtkDataSet.html).
