## Spherical Triangular Tessellation (STT) Generator

### Introduction

The spherical triangular tessellation is a kind of partition of the spherical surface composed by only triangular cells. This program could generate the STT based on an icosahedron. The STT generated by the program could be refined around given points, lines, polygons and circles on the spherical surface. The exterior and interior outlines of the STT could also be customized.

### Files and folders

1. **CMakeLists.txt** CMake project file;
2. **\*.h and \*.cpp** Source files;
3. **README.md** This file;
4. **stt-example.png** Screen short of an example output;
5. **archived** Old source files;
6. **doc** Example files.

#### Source file lists

```shell
head_functions.cc
head_functions.h
main.cc
progress_bar.cc
progress_bar.h
struct_functions.cc
struct_functions.h
stt_class.h
stt_close_surface.cc
stt_create_branch.cc
stt_create_tree.cc
stt_cut_hole.cc
stt_cut_outline.cc
stt_delete_tree.cc
stt_get_control_circle.cc
stt_get_control_line.cc
stt_get_control_point.cc
stt_in_poly_outline.cc
stt_in_triangle_circle.cc
stt_in_triangle_line.cc
stt_in_triangle_point.cc
stt_in_triangle_polygon.cc
stt_initial_icosahedron.cc
stt_out_poly_outline.cc
stt_output_msh_file.cc
stt_output_neighbor.cc
stt_output_triangle_center_location.cc
stt_output_vertex_location.cc
stt_return_branch_depth.cc
stt_return_depth.cc
stt_return_leaf.cc
stt_routine.cc
stt_set_command_record.cc
stt_set_icosahedron_orient.cc
stt_set_pole_equator_radius.cc
stt_set_tree_depth.cc
stt_sort_neighbor.cc
```

### Installation

This program is a toolkit that is developed and maintained by Dr. Yi Zhang (zhangyiss@icloud.com) , which could be compiled and installed using the [CMake](https://cmake.org) software. Follow the instructions bellow to compile this program:

```shell
mkdir build
cd build
make install
```

### Usage

```bash
Usage: stt -d<minimal-depth>/<maximal-depth> [-r'WGS84'|'Earth'|'Moon'|<equator-radius>/<pole-radius>|<equator_radius>,<flat-rate>] [-o<orient-longitude>/<orient-latitude>] [-m<output-msh-filename>] [-v<output-vert-loc-filename>] [-t<output-tri-cen-filename>] [-n<output-tri-neg-filename>] [-p<control-point-filename>] [-l<control-line-filename>] [-g<control-poly-filename>] [-c<control-circle-filename>] [-s<outline-shape-filename>] [-k<hole-shape-filename>] [-h]
```

#### Options

+ __-d__: Minimal and maximal depths of the quad-tree structures used to construct the STT.
+ __-r__: Coordinate reference system of the output files.
+ __-o__: Orientation of the top vertex of the base icosahedron.
+ __-m__: Output filename of the Gmsh(.msh) file.
+ __-v__: Output filename of the vertices' location.
+ __-t__: Output filename of the triangles' center location.
+ __-n__: Output filename of the triangles' neighbor.
+ __-p__: Input filename of control points' location.
+ __-l__: Input filename of control lines' location.
+ __-g__: Input filename of control polygons' location.
+ __-c__: Input filename of control circles' location.
+ __-s__: Input filename of outline shapes' location.
+ __-k__: Input filename of hole shapes' location.
+ __-h__: show help information.

#### Input File Formats

##### Point format

The format of the control points' location is a plain text file. Each line of the file has the information of one control point which contains the spherical coordinates, maximal quad-tree depth, minimal resolution and physical group of the point. The program takes both the tree depth and resolution to control the fineness of the refined STT. The refinement of the STT will stop which ever the two conditions has been reached. Note that any line that starts with '#' or any empty line will be skipped. An example file:

```bash
# <longitude> <latitude> <maximal-depth> <minimal-resolution> <physical-group>
-45 -45 5 1.0 7
45 -45 5 1.0 7
45 45 5 1.0 7
-45 45 5 1.0 7
```

##### Circle format 

The format of the control circles' location is a plain text file. Each line of the file has the information of one control circle which contains the spherical coordinates, spherical cap degree, maximal quad-tree depth, minimal resolution and physical group of the circle. The program takes both the tree depth and resolution to control the fineness of the refined STT. The refinement of the STT will stop which ever the two conditions has been reached. Note that any line that starts with '#' or any empty line will be skipped. An example file:

```bash
# <longitude> <latitude> <spherical-cap-degree> <maximal-depth> <minimal-resolution> <physical-group>
45 60 30 5 0.1 12
-20 -45 20 6 0.1 13
```

##### Line format

The format of the control lines', polygons', outlines', and holes' location is a plain text file. Blocks separated by empty lines contain information of control units. For each block, the first line has the number of the spherical locations, maximal quad-tree depth, minimal resolution and physical group of the unit. Followed by spherical coordinates of the unit.The program takes both the tree depth and resolution to control the fineness of the refined STT. The refinement of the STT will stop which ever the two conditions has been reached. Note that any line that starts with '#' or any empty line will be skipped. An example file:

```bash
# <number-of-points> <maximal-depth> <minimal-resolution> <physical-group>
# <longitude> <latitude>
# <longitude> <latitude>
# ... ...
4 6 0.1 5
-10 10
50 15
60 55
-15 50
```

### Examples

An example of multi-resolution STT:

```bash
stt -d 3/7 -m example.msh -l doc/control_lines.txt -g doc/control_poly.txt -c doc/control_circle.txt
```

![stt-example](doc/stt-example.png)
