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

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

This program is developed and maintained by Dr. Yi Zhang (yizhang-geo@zju.edu.cn). To compile and install using CMake:

mkdir build
cd build
cmake ..
make
make install

Usage

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

Required:
  -d<min>/<max>    Minimal and maximal depths of the quad-tree structure

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
  
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:

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

Circle Control Format

Controls refinement around spherical caps:

# <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/Polygon Control Format

Controls refinement along lines or around polygons:

# First line: <number-of-points> <maximal-depth> <minimal-resolution> <physical-group>
# Following lines: <longitude> <latitude> of each point
4 6 0.1 5
-10 10
50 15
60 55
-15 50

Topography Control Format

Controls refinement based on elevation data:

# First line: <maximum-STD> <maximal-depth> <minimal-resolution> <physical-group>
# Following lines: <longitude> <latitude> <elevation(meters)>
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.

Examples

1. Multi-resolution STT with geometric constraints:

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

2. Topography-constrained STT:

stt -d 6/10 -m topo_example.msh -t doc/control_topo.txt