stt/README.md

## Spherical Triangular Tessellation (STT) Generator

### Introduction

The spherical triangular tessellation (STT) is a method to partition a spherical surface into triangular cells. This program generates STT based on an icosahedron and provides various refinement options:

1. Geometric refinement around:
   - Points
   - Lines
   - Polygons
   - Circles
2. Topographic refinement based on elevation data
3. Customizable exterior and interior boundaries

### Technical Details

#### Core Algorithm

1. **Base Structure**
   - Starts with an icosahedron (20 triangular faces)
   - Uses quad-tree data structure for adaptive refinement
   - Each face of the icosahedron becomes the root of a quad-tree

2. **Refinement Process**
   - Adaptive refinement based on various constraints
   - Uses vector calculations for spherical geometry
   - Supports multiple levels of refinement (controlled by depth parameter)

3. **Constraint Types**
   - Point constraints: Refines mesh around specific points
   - Line constraints: Refines along great circle paths
   - Polygon constraints: Refines within or around polygon boundaries
   - Circle constraints: Refines within spherical caps
   - Topographic constraints: Refines based on elevation data

4. **Coordinate Systems**
   - Supports multiple reference systems:
     * WGS84 ellipsoid
     * Spherical Earth
     * Lunar sphere
     * Custom ellipsoid
     * Custom flattened sphere
   - Configurable orientation of the base icosahedron

### Algorithm Details

1. **Initialization**
   - Creates base icosahedron
   - Sets up coordinate system and orientation
   - Initializes quad-tree structure

2. **Refinement Process**
   - Reads constraint files
   - For each triangle:
     * Tests intersection with constraints
     * Subdivides if needed based on depth and resolution
     * Maintains neighbor relationships

3. **Output Generation**
   - Generates final mesh
   - Computes vertex locations
   - Creates neighbor lists
   - Exports in various formats

4. **Memory Management**
   - Uses dynamic allocation for tree structures
   - Automatically cleans up temporary data
   - Efficient handling of large datasets

### Files and folders

1. **CMakeLists.txt**: CMake project configuration file
2. **src/**: Source code directory containing all implementation files
3. **doc/**: Example files and test cases
4. **README.md**: Documentation (this file)
5. **archived/**: Legacy source files (for reference only)

### Installation

To compile and install using [CMake](https://cmake.org):

```shell
mkdir build
cd build
cmake ..
make
make install
```

### Usage

```bash
Usage: stt -d<minimal-depth>/<maximal-depth> [options]

Required:
  -d<min>/<max>    Minimal and maximal depths of the quad-tree structure
                   Example: -d3/7 for refinement from depth 3 to 7

Optional:
  -r<ref>          Coordinate reference system:
                   - 'WGS84': WGS84 ellipsoid
                   - 'Earth': Spherical Earth
                   - 'Moon': Lunar sphere
                   - <eq-rad>/<pole-rad>: Custom ellipsoid
                   - <eq-rad>,<flat-rate>: Custom flattened sphere
  -o<lon>/<lat>    Orientation of icosahedron top vertex
                   Default: 0/90 (North Pole)
  
Output options:
  -m<file>         Output Gmsh(.msh) mesh file
  -v<file>         Output vertices' locations
  -t<file>         Output triangle centers
  -n<file>         Output triangle neighbors

Refinement control:
  -p<file>         Control points file
  -l<file>         Control lines file
  -g<file>         Control polygons file
  -c<file>         Control circles file
  -t<file>         Topography control file
  -s<file>         Outline shape file
  -k<file>         Hole shape file
  -z<file>         Topography data file
  
Help:
  -h               Show this help message
```

### Input File Formats

#### Point Control Format
Controls refinement around specific points. Each point is defined by its location and refinement parameters:

```bash
# <longitude> <latitude> <maximal-depth> <minimal-resolution> <physical-group>
# longitude, latitude: Coordinates in degrees
# maximal-depth: Maximum refinement depth for this point
# minimal-resolution: Minimum cell size in degrees
# physical-group: Group identifier for the refined region
-45 -45 5 1.0 7
45 -45 5 1.0 7
```

#### Circle Control Format
Controls refinement around spherical caps. Each circle is defined by its center, radius, and refinement parameters:

```bash
# <longitude> <latitude> <spherical-cap-degree> <maximal-depth> <minimal-resolution> <physical-group>
# spherical-cap-degree: Angular radius of the cap in degrees
45 60 30 5 0.1 12
-20 -45 20 6 0.1 13
```

#### Line/Polygon Control Format
Controls refinement along lines or around polygons. Each shape is defined by a sequence of points and refinement parameters:

```bash
# First line: <number-of-points> <maximal-depth> <minimal-resolution> <physical-group>
# Following lines: <longitude> <latitude> of each point
# Points are connected in sequence, last point connects to first for polygons
4 6 0.1 5
-10 10
50 15
60 55
-15 50
```

#### Topography Control Format
Controls refinement based on elevation data. The refinement is based on elevation variation within triangles:

```bash
# First line: <maximum-STD> <maximal-depth> <minimal-resolution> <physical-group>
# Following lines: <longitude> <latitude> <elevation(meters)>
# maximum-STD: Maximum allowed standard deviation of elevation within a triangle
200.0 10 -1 5
-179.95 89.95 -4203.20
-179.85 89.95 -4203.07
-179.75 89.95 -4203.47
```

Note: maximum-STD represents the maximum standard deviation of elevation allowed in a triangle. A triangle will be refined if the elevation variation within it exceeds this threshold.

### Examples

1. Multi-resolution STT with geometric constraints:

```bash
# Creates a mesh with depth range 3-7, refined around lines, polygons and circles
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)

2. Topography-constrained STT:

```bash
# Creates a mesh with depth range 6-10, refined based on topography data
stt -d 6/10 -m topo_example.msh -t doc/control_topo.txt
```

![topo-example](doc/topo_constraint.png)

### Contact
For any bug reports or you need some help. Please contact Dr. Yi Zhang ([yizhang-geo@zju.edu.cn](yizhang-geo@zju.edu.cn)).