This repository contains introductions to TTK and Cinema.

# ---------------------------------------------------<br>1 Topology ToolKit (TTK)<br>---------------------------------------------------

## 1.1 What you need to know:
+ The Topology ToolKit (TTK) is an open-source library and software collection for topological data analysis in scientific visualization.
+ Each TTK filter consists of three nested layers: **base**, **vtk**, and **paraview**.
	+ **base** layer:
		+ Contains all core algorithms
		+ The base layer should have as less dependencies as possible (especially VTK is not used at this layer)
		+ This layer knows nothing about the other layers
	+ **vtk** layer:
		+ Only manages data input-output to the **base** layer, i.e., calls **base** code with data stored on vtkObjects.
		+ Output of the **base** layer might has to be converted into vtk data structures such as *vtkUnstructuredGrid* or *vtkImageData*.
	+ **paraview** layer:
		+  Only consists of xml files that describe the UI elements provided in paraview to adjust parameters of the **vtk** layer.

## 1.2 Installation

First get and build the source code.

1. Become a member of the priest git repo
	+ TU-KL maintains its own TTK forks for certain projects that are routinely merged with the official TTK master branch
    +  send an email to 'jl@jluk.de' with the name of your priest account and you will be added to corresponding repo as a developer

2. Clone the repo
    + navigate into the folder where you want to keep the repo
    + run `git clone https://priest.cs.uni-kl.de/git/lukasczyk/CorrespondingTTKFork`

3. Follow [TTK installation guide](https://topology-tool-kit.github.io/installation.html)
    + 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.

# ---------------------------------------------------<br>2 Cinema<br>---------------------------------------------------
## 2.1 What you need to know:
+ 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.

## 2.2 Important Links
+ [Specification](https://github.com/cinemascience/cinema/blob/master/specs/dietrich/01/cinema_specD_v012.pdf)
+ [Official Homepage](https://cinemascience.github.io/)
+ [YouTube Tutorials](https://www.youtube.com/watch?v=yKyiRzPbs0U)

## 2.3 Example:

**Filesystem:**
```
.../Test.cdb/
    data.csv
    data/
	    run01_0.vti
	    run01_1.vti
	    run02_0.vti
	    run02_1.vti
	    run02_2.vti
```

**Comma Separated Value File (data.csv):**

| Sim | Time | FILE|
|---|---|---|
|run01|0|data/run01_0.vti|
|run01|1|data/run01_1.vti|
|run02|0|data/run02_0.vti|
|run02|1|data/run02_1.vti|
|run02|2|data/run02_2.vti|


## 2.4 Database Generation
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).