# Implementation and execution guide

This software is designed to create a collection of stream surfaces following a
frame-field in a 3D domain. A subset is then selected which is uniformly
spaced. This subset is then thickened and a surface representation is extracted.

## Installation and Dependencies

Here is an overview of the installation procedures and dependencies. Please note
that we use a linux distribution (Ubuntu 20.04 installed in Windows Subsystem
for Linux 2) and have not tested the procedures on other platforms.  
Dependencies needed, version is the latest tested version:

- GCC: Gnu Compiler Collection version 9.3.0.
- OpenMPI: version 4.0.3. (Optional)
- [GEL](https://github.com/janba/GEL): version of Nov 9 2021.
- [CVX](http://cvxr.com/cvx/): version 2.2.
- [MOSEK](https://www.mosek.com/): version 9.2

### Installation

The code is built using the Gnu Compiler Collection 9.3.0 C++ compiler and can
also be combined with the OpenMPI API to allow parallel execution. The library
**GEL** can be linked to a local installation by setting a `GEL_DIR` environment
variable.  
To compile the code, run `make`. This will compile the program into a number of
binary executables.

    > make -j

## Using the code

Each of the programs handle different steps of the pipeline. This separation
ensure each system can be run independently.

`SurfaceGeneration` will generate a number of point clouds which follow the
direction field specified in the data folder. The matlab function `subselection`
will select an optimal subset of point clouds. `SurfaceSuperSample` will
afterwards super-sample the selected point clouds and then triangulate them.
`Splatter` read these triangulations, and then use these to construct a surface
representation of the volumetric structure.

The full pipeline is called in the following order:

    > ./SurfaceGeneration.exe options.cfg
    > matlab -r "subselection();exit"
    > ./SurfaceSuperSample.exe options.cfg
    > ./Splatter.exe options.cfg

### Input data

The input data should contain an `information.csv` file containing the grid
dimensions and number of frames per element. `field.csv` should contain the
frame directions. Each line should contain the element position labelled by a
1-indexed location and the frame vectors. `width.csv` contains the list of layer
thicknesses in the same ordering as the frame list file.

[cantilever_example](cantilever_example) contains a standard cantilever example.

### Output data

The output of all programs is organized into a `results` folder by default. Most
auxiliary files are placed in the subfolder `intermediate`, this includes the
list of probe points, the exported indicator response and the list of selected
surfaces. The full set of available surfaces is located in `surfaces_full`, the
subselected set of surfaces is stored in `surfaces_optimal` and the volumetric
structure is saved to the `splatter` folder.

## Options

Here is a list of the most common options available to the user. These settings
contain information about input directories, variables used when setting up the
point clouds etc. For more options, see the "protected attributes" of the
`StreamSurfaces` and `Splatter` classes in the Doxygen documentation.

### Example of an [options.cfg](options.cfg) file

> // Simple options for constant field  
> data_name cantilever_example  
> data_location ./  
>
> surf_pds_r 1.0  
> super_sample_pds_r 0.5  
> desired_spacing 10  
>
> threshold_void 0.05  
> threshold_solid 0.95  
> splatter_toggle true  
