### LibTIN - C++ library of the Triangular Irregular Network (TIN)
#### Introduction
LibTIN is a stand alone C++ library for generating the Triangular Irregular Networks (TIN) using DEM data that are located at a regular grid or random locations. No dependences are needed. The generated TINs that are fully Delaunay, and neighboring information is also retrieved during the construction. Additionally, a polygon could be provided to control the outline shape of the generated TIN.
#### Installation
The LibTIN compiles using the CMake software. Typically, you need following commands to compile and install the library and tools after you navigated into the package's directory:
```shell
make build
cd build
cmake ..
make install
```
This will compile the library and two command line tools, _grd2tin_ and _rnd2tin_, which will be introduced bellow. The library and tools are installed in the directories _/usr/local/lib_ and _/usr/local/sbin_ by default. You can specify a different directory for installation using the CMAKE_INSTALL_PREFIX option.
#### Data Structures
##### vertex2dc
Vertex defined on the 2-D Cartesian coordinates. It is used to represent the vertex of the TIN or the polygon's corners. Included variables are as following:
```c++
struct vertex2dc
{
unsigned int id; // index of the vertex
double x, y; // position of the vertex
double elev; // elevation at the vertex
}
```
##### triangle
Triangular facet defined on the 2-D Cartesian coordinates. It is used to represent the facet of the TIN. Included variables are as following:
```c++
struct triangle
{
int id;
vertex2dc *vert[3]; // vertex of the triangle
triangle *neigh[3]; // neighbors of the triangle
double cx, cy; // center of the triangle's circumcircle
double cr; // radius of the circumcircle
std::vector hosted_dem; // DEM points that are located within the triangle
}
```
##### dem_point
DEM point defined on the 2-D Cartesian coordinate. It is used to store the input DEM data. Included variables are as following:
```c++
struct dem_point
{
double x, y; // position of the DEM location
double elev; // elevation at the DEM location
double err; // error of the TIN with respect to the elevation
triangle *host; // pointer of the triangle that the dem_point falls inside of
}
```
#### Tools
##### grd2tin: generation of the TIN using regular DEM data
###### usage
```shell
grd2tin -f -r/// -i/ -m [-p] [-t] [-l] [-n] [-z]
```
###### options
* **-f** Input DEM data. The program takes DEM data that are stored as a simple ASCII text file. Each line of the file contains the _x_, _y_ and _elevation_ values of a DEM point separated by spaces. Moreover, the DEM data should be stored in an order that starts from the lower-left corner of the DEM grid and travels in a row-major manner till the upper-right corner of the grid. Specially, the _x_ and _y_ values in the file could be omitted by setting the **-z** option.
* **-r** Range of the input DEM grid in the x and y directions, respectively.
* **-i** Intervals of the input DEM grid in the x and y directions, respectively.
* **-m** Output Gmsh file (.msh) of the generated TIN.
* **-p (optional)** Input text file of a polygon to control the outline shape of the generated TIN. The polygon is represented using its corners' locations. Each line of the file should contain the _x_, _y_ values of a corner vertex. The vertexes could be ordered either clockwise or anti-clockwise.
* **-t (optional)** Threshold of the maximal error of the generated TIN with respect to the input DEM grid.
* **-l (optional)** Output text file of a log file of the maximal error of the generated TIN.
* **-n (optional)** Output text file of neighbor-ships of the generated TIN.
* **-z (optional)** The input DEM grid is a 1-column z-table.
##### rnd2tin: generation of the TIN using random DEM data
###### usage
```shell
rnd2tin -f -m [-p] [-t] [-l] [-n]
```
###### options
* **-f** Input DEM data. The program takes DEM data that are stored as a simple ASCII text file. Each line of the file contains the _x_, _y_ and _elevation_ values of a DEM point separated by spaces.
* **-m** Output Gmsh file (.msh) of the generated TIN.
* **-p (optional)** Input text file of a polygon to control the outline shape of the generated TIN. The polygon is represented using its corners' locations. Each line of the file should contain the _x_, _y_ values of a corner vertex. The vertexes could be ordered either clockwise or anti-clockwise.
* **-t (optional)** Threshold of the maximal error of the generated TIN with respect to the input DEM grid.
* **-l (optional)** Output text file of a log file of the maximal error of the generated TIN.
* **-n (optional)** Output text file of neighbor-ships of the generated TIN.
#### Examples
The following is a simple example for using the library to generate the TIN you see on top of this page. More examples could be found at the _src/demo_ folder.
```c++
#include "../lib/tin.h"
#include "iostream"
#include "fstream"
#include "iomanip"
int main(int argc, char const *argv[])
{
// read dem grid
std::vector topo(10201);
std::ifstream infile("data/topo");
for (int i = 0; i < 10201; ++i)
{
infile >> topo[i];
}
infile.close();
// prepare variables and vectors
std::vector err_records;
std::vector tin_vert;
std::vector tin_ele;
// call the grd2tin function to generate the TIN
// the resultant vertexes and facets are stored in
// vectors tin_vert and tin_ele, respetively.
grd2tin(topo, 0, 1000, 0, 1000, 10, 10, tin_vert, tin_ele, 1.0, nullptr, &err_records);
// Write a log file of the construciton process
// which you can examine later.
std::ofstream logfile("data/topo_TIN.log");
logfile << "# Insertion Maxi-Error\n";
for (int i = 0; i < err_records.size(); ++i)
{
logfile << i+1 << " " << err_records[i] << std::endl;
}
logfile.close();
// Write a Gmsh's .msh file for visualization
std::ofstream outfile("data/topo_TIN.msh");
outfile << "$MeshFormat" << std::endl << "2.2 0 8" << std::endl << "$EndMeshFormat "<id + 1 << " " << std::setprecision(16)
<< tin_vert[i]->x << " " << tin_vert[i]->y << " " << tin_vert[i]->elev << std::endl;
}
outfile<<"$EndNodes"<vert[j]->id + 1;
}
outfile << std::endl;
}
outfile << "$EndElements"<< std::endl;
outfile<<"$NodeData"<id + 1 << " " << std::setprecision(16) << tin_vert[i]->elev << std::endl;
}
outfile << "$EndNodeData" << std::endl;
outfile.close();
// write a neighboring file
outfile.open("data/topo_TIN.neigh");
outfile << tin_ele.size() << std::endl;
for (int i = 0; i < tin_ele.size(); i++)
{
outfile << i + 1;
for (int j = 0; j < 3; j++)
{
if (tin_ele[i]->neigh[j] != nullptr)
{
outfile << " " << tin_ele[i]->neigh[j]->id + 1;
}
else outfile << " -1";
}
outfile << std::endl;
}
outfile.close();
// Destroy memories allocated by the grd2tin function
for (int i = 0; i < tin_vert.size(); ++i)
{
delete tin_vert[i];
}
for (int i = 0; i < tin_ele.size(); ++i)
{
delete tin_ele[i];
}
return 0;
}
```