Merge pull request #2743 from rinkk/utilitydocumentation

Utility documentation

Applications/Utils/FileConverter/GocadTSurfaceReader.cpp

@@ -36,30 +36,29 @@ int main(int argc, char* argv[])
             "(http://www.opengeosys.org)",
         ' ', GitInfoLib::GitInfo::ogs_version);
 
-    TCLAP::ValueArg<std::string> input_arg(
-        "i", "input-file", "Gocad triangular surfaces file (*.ts)", true, "",
-        "filename.ts");
-    cmd.add(input_arg);
-
-    TCLAP::ValueArg<std::string> output_arg(
-        "o", "output-dir", "output directory", true, "",
-        "output dir");
-    cmd.add(output_arg);
-
     TCLAP::SwitchArg write_binary_arg(
         "b", "write-binary",
         "if set, OGS-Meshes will be written in binary format");
     cmd.add(write_binary_arg);
 
+    TCLAP::SwitchArg export_surfaces_arg(
+        "s", "surfaces-only",
+        "if set, only TSurf datasets will be parsed from the input file");
+    cmd.add(export_surfaces_arg);
+
     TCLAP::SwitchArg export_lines_arg(
         "l", "lines-only",
         "if set, only PLine datasets will be parsed from the input file");
     cmd.add(export_lines_arg);
 
-    TCLAP::SwitchArg export_surfaces_arg(
-        "s", "surfaces-only",
-        "if set, only TSurf datasets will be parsed from the input file");
-    cmd.add(export_surfaces_arg);
+    TCLAP::ValueArg<std::string> output_arg(
+        "o", "output-dir", "output directory", true, "", "output dir");
+    cmd.add(output_arg);
+
+    TCLAP::ValueArg<std::string> input_arg(
+        "i", "input-file", "Gocad triangular surfaces file (*.ts)", true, "",
+        "filename.ts");
+    cmd.add(input_arg);
 
     cmd.parse(argc, argv);
 

Applications/Utils/FileConverter/Mesh2Raster.cpp

@@ -37,18 +37,17 @@ int main(int argc, char* argv[])
             "Copyright (c) 2012-2019, OpenGeoSys Community "
             "(http://www.opengeosys.org)",
         ' ', GitInfoLib::GitInfo::ogs_version);
-    TCLAP::ValueArg<std::string> input_arg("i", "input-file",
-                                           "Mesh input file (*.vtu, *.msh)",
-                                           true, "", "string");
-    cmd.add(input_arg);
-    TCLAP::ValueArg<std::string> output_arg(
-        "o", "output-file", "Raster output file (*.asc)", true, "", "string");
-    cmd.add(output_arg);
     TCLAP::ValueArg<double> cell_arg("c", "cellsize",
                                      "edge length of raster cells in result",
                                      false, 1, "real");
     cmd.add(cell_arg);
-
+    TCLAP::ValueArg<std::string> output_arg(
+        "o", "output-file", "Raster output file (*.asc)", true, "", "string");
+    cmd.add(output_arg);
+    TCLAP::ValueArg<std::string> input_arg("i", "input-file",
+                                           "Mesh input file (*.vtu, *.msh)",
+                                           true, "", "string");
+    cmd.add(input_arg);
     cmd.parse(argc, argv);
 
     INFO("Rasterising mesh...");

Applications/Utils/FileConverter/TecPlotTools.cpp

@@ -148,7 +148,7 @@ void resetDataStructures(std::size_t const& n_scalars,
     val_count = 0;
 }
 
-/// Writes one section/zone into a seperate TecPlot file
+/// Writes one section/zone into a separate TecPlot file
 void writeTecPlotSection(std::ofstream& out,
                          std::string const& file_name,
                          std::size_t& write_count,
@@ -169,7 +169,7 @@ void writeTecPlotSection(std::ofstream& out,
     }
 }
 
-/// Writes one section/zone into a seperate OGS-mesh
+/// Writes one section/zone into a separate OGS-mesh
 int writeDataToMesh(std::string const& file_name,
                     std::size_t& write_count,
                     std::vector<std::string> const& vec_names,
@@ -239,7 +239,7 @@ void skipGeometrySection(std::ifstream& in, std::string& line)
     }
 }
 
-/// Splits a TecPlot file containing multiple sections/zones into seperate files
+/// Splits a TecPlot file containing multiple sections/zones into separate files
 int splitFile(std::ifstream& in, std::string file_name)
 {
     std::ofstream out;
@@ -418,14 +418,18 @@ int main(int argc, char* argv[])
             "Copyright (c) 2012-2019, OpenGeoSys Community "
             "(http://www.opengeosys.org)",
         ' ', GitInfoLib::GitInfo::ogs_version);
-    TCLAP::ValueArg<std::string> input_arg("i", "input-file", "TecPlot input file", true, "", "string");
-    cmd.add(input_arg);
-    TCLAP::ValueArg<std::string> output_arg("o", "output-file", "output mesh file", false, "", "string");
-    cmd.add(output_arg);
-    TCLAP::SwitchArg split_arg("s", "split", "split time steps into seperate files");
+    TCLAP::SwitchArg split_arg("s", "split",
+        "split time steps into separate files");
     cmd.add(split_arg);
-    TCLAP::SwitchArg convert_arg("c", "convert", "convert TecPlot data into OGS meshes");
+    TCLAP::SwitchArg convert_arg("c", "convert",
+        "convert TecPlot data into OGS meshes");
     cmd.add(convert_arg);
+    TCLAP::ValueArg<std::string> output_arg(
+        "o", "output-file", "output mesh file", false, "", "string");
+    cmd.add(output_arg);
+    TCLAP::ValueArg<std::string> input_arg(
+        "i", "input-file", "TecPlot input file", true, "", "string");
+    cmd.add(input_arg);
     cmd.parse(argc, argv);
 
     if (!input_arg.isSet())

Applications/Utils/MeshGeoTools/createIntermediateRasters.cpp

@@ -34,19 +34,19 @@ int main(int argc, char* argv[])
             "Copyright (c) 2012-2019, OpenGeoSys Community "
             "(http://www.opengeosys.org)",
         ' ', GitInfoLib::GitInfo::ogs_version);
-    TCLAP::ValueArg<std::string> input1_arg(
-        "", "file1", "First DEM-raster file", true, "", "file1.asc");
-    cmd.add(input1_arg);
-    TCLAP::ValueArg<std::string> input2_arg(
-        "", "file2", "Second DEM-raster file", true, "", "file2.asc");
-    cmd.add(input2_arg);
+    TCLAP::ValueArg<std::size_t> number_arg(
+        "n", "number", "number of rasters to be calculated", false, 1, "int");
+    cmd.add(number_arg);
     TCLAP::ValueArg<std::string> output_arg("o", "output-file",
                                             "Raster output file (*.asc)", true,
                                             "", "output.asc");
     cmd.add(output_arg);
-    TCLAP::ValueArg<std::size_t> number_arg(
-        "n", "number", "number of rasters to be calculated", false, 1, "int");
-    cmd.add(number_arg);
+    TCLAP::ValueArg<std::string> input2_arg(
+        "", "file2", "Second DEM-raster file", true, "", "file2.asc");
+    cmd.add(input2_arg);
+    TCLAP::ValueArg<std::string> input1_arg(
+        "", "file1", "First DEM-raster file", true, "", "file1.asc");
+    cmd.add(input1_arg);
 
     cmd.parse(argc, argv);
 

web/content/docs/tools/fileio/GocadTSurfaceReader/index.pandoc

++++
+date = "2019-12-03T00:00:00+01:00"
+title = "GocadTSurfaceReader"
+author = "Karsten Rink"
+
+[menu]
+  [menu.tools]
+    parent = "Data Import/Export"
++++
+
+## Introduction
+
+This is a utility for handling GoCAD data. GoCAD has a number of possible file extensions and data types contained within those files. One file may contain multiple data sets. In addition, a file with a specific extension need not only contain data of the type that the extension suggests.
+
+At the moment, this utility can read:
+
+* VSET (Voxel Set)
+* PLINE (Polyline)
+* TSURF (Triangulated Surfaces)
+
+Expected file extensions for these data types include *.vs, *.pl, *.ts, and *.mx (the last one for **m**i**x**ed data).
+
+Another data type, SGRID (Structured Grid, usually saved to *.sg files) can be converted via the [GoCadSGridReader](../../meshing/gocadsgridreader).
+
+Parsers for additional GoCAD-datasets may be added in the future.
+
+The tool is part of the official [OpenGeoSys git repository](https://github.com/ufz/ogs).
+
+## Usage
+
+```bash
+   GocadTSurfaceReader  -i <filename.ts> -o <output dir> [-l] [-s] [-b]
+                        [--] [--version] [-h]
+
+
+Where:
+
+   -i <filename.ts>,  --input-file <filename.ts>
+     (required)  Gocad triangular surfaces file (*.ts)
+
+   -o <output dir>,  --output-dir <output dir>
+     (required)  output directory
+
+   -l,  --lines-only
+     if set, only PLine datasets will be parsed from the input file
+
+   -s,  --surfaces-only
+     if set, only TSurf datasets will be parsed from the input file
+
+   -b,  --write-binary
+     if set, OGS-Meshes will be written in binary format
+```
+
+Unless specified otherwise, the utility will convert all datasets and write them to the specified output directory. Using the flags ```-l``` and ```-s```, conversion can be limited to lines or surfaces, respectively. Datasets will usually have a name specified. This name is used for the output file. If no name is given, the file name will be used instead. Should multiple datasets have the same name (which is possible in GoCAD), a mesh-ID will be added to the file name. This ID has no function except to allow the writing of multiple datasets with the same name into the same directory.
+
+Datasets may have additional scalar data assigned to nodes. If so, this data is also added to the output data.
+
+
+## Simple example
+
+**Command:**
+```
+GocadTSurfaceReader -i d:\GoCAD_data\Top-Lower_Sandy.ts -o d:\GoCAD_data
+```
+
+**Input:**
+
+![GoCAD-Header of file containing triangulated surface.](./Surface-GoCad.png){width=66%}
+
+**Output:**
+
+![Converted surface visualised in ParaView with scalar data added to nodes.](./Surface-ParaView.png)
+

web/content/docs/tools/fileio/Mesh2Raster/index.pandoc

++++
+date = "2019-12-03T00:00:00+01:00"
+title = "Mesh2Raster"
+author = "Karsten Rink"
+
+[menu]
+  [menu.tools]
+    parent = "Data Import/Export"
++++
+
+## Introduction
+
+This utility generates an ASCII-raster file based on a 2D surface mesh. A raster is superimposed on the mesh and pixel values are set to the surface elevation at each pixel's position. If no mesh element is located beneath a pixel it's value is set to NODATA.
+
+The tool is part of the official [OpenGeoSys git repository](https://github.com/ufz/ogs).
+
+## Usage
+
+```bash
+   Mesh2Raster  -i <string> -o <string> [-c <real>]
+
+
+Where:
+
+   -i <string>,  --input-file <string>
+     (required)  Mesh input file (*.vtu, *.msh)
+
+   -o <string>,  --output-file <string>
+     (required)  Raster output file (*.asc)
+
+   -c <real>,  --cellsize <real>
+     edge length of raster cells in result
+```
+
+The parameter ```c``` specifies the cell size (i.e. pixel size) of the raster. While optional, it is still recommended to choose a value as the default will be set to the minimum edge length in the input mesh which for unstructured grids may result in a very fine and (extremely) large output raster.
+
+## Simple example
+
+**Input data:**
+
+![2D surface mesh.](./Mesh2Raster-input.png)
+
+The input mesh for this example is a homogeneous, unstructured triangle mesh with an average edge length of 100m.
+
+**Command:**
+```
+Mesh2Raster -i input.vtu -o output.asc -c 50
+```
+
+![](./Mesh2Raster-output50.png){ width=66% }
+The generated output raster has a size of 340x333 pixels and represents the original surface well. Given the average edge length of 100m in the original mesh, an even smaller cellsize would not have contained more details but resulted in a larger file size.[^1]
+
+**Command:**
+```
+Mesh2Raster -i input.vtu -o output.asc -c 200
+```
+
+![](./Mesh2Raster-output200.png)
+The generated output raster has a size of 85x84 pixels and still represents the original surface reasonably well, despite visible undersampling.
+
+**Command:**
+```
+Mesh2Raster -i input.vtu -o output.asc -c 1000
+```
+
+![](./Mesh2Raster-output1000.png)
+The generated output raster has a size of 17x17 pixels and shows severy undersampling. However, this is the resolution that a large number of weather data products are available at.
+
+## Application
+
+The resulting ASCII-rasters can be used to represent surface data in geographic information systems. In the absense of input data, a detailed raster can also be used by OpenGeoSys preprocessing tools to generate new surface meshes with different resolution or properties.
+
+[^1]: Conversely, a larger cellsize might result in artefacts due to undersampling, see [Nyquist criterion](https://en.wikipedia.org/wiki/Nyquist_rate).

web/content/docs/tools/fileio/Mesh2Shape/index.pandoc

++++
+date = "2019-12-03T00:00:00+01:00"
+title = "Mesh2Shape"
+author = "Karsten Rink"
+
+[menu]
+  [menu.tools]
+    parent = "Data Import/Export"
++++
+
+## Introduction
+
+Converts a 2D surface mesh into a shapfile such that each element is represented by a polygon. Cell attributes are transferred onto shape polygons while point attributes are ignored.
+
+The tool is part of the official [OpenGeoSys git repository](https://github.com/ufz/ogs).
+
+## Usage
+
+```bash
+   Mesh2Shape  -i <input_file.vtu> -o <output_file.shp>
+
+
+Where:
+
+   -i <input_file.vtu>,  --input-file <input_file.vtu>
+     (required)  OGS mesh file (*.vtu, *.msh)
+
+   -o <output_file.shp>,  --output-file <output_file.shp>
+     (required)  Esri Shapefile (*.shp)
+```
+
+## Simple example
+
+**Input data:**
+
+![](./Mesh2Shape-input.png){ width=66% }
+2D surface mesh with scalar data assigned to cells, here displayed via the OGS Data Explorer. In this particular case, the simulation result of groundwater flow simulation (originally assigned to mesh nodes) has been converted onto cells via VTK's PointToCell-Filter.
+
+**Command:**
+```
+Mesh2Shape -i Mueglitz2D_Point2Cell.vtu -o Mueglitz2D_Point2Cell.shp
+```
+
+![](./Mesh2Shape-output1.png){ width=66% }
+Exported shapefile displayed in a geographic information system (here, QGIS).
+
+
+![](./Mesh2Shape-output2.png)
+The result of an OGS-simulation showing the groundwater head of the Müglitz-catchment imported into QGIS and combined with other data from an existing GIS-project of this region.
+
+
+## Application
+
+The utility allows to export meshes, and in particular simulation results, into existing GIS-projects and use the data as input for subsequent workflows.

web/content/docs/tools/fileio/TecPlotTools/index.pandoc

++++
+date = "2019-12-03T00:00:00+01:00"
+title = "TecPlotTools"
+author = "Karsten Rink"
+
+[menu]
+  [menu.tools]
+    parent = "Data Import/Export"
++++
+
+## Introduction
+
+This is a utility for handling TecPlot data. At the moment, it is possible to split a file containing ```n``` time steps into ```n``` files contain one time step each, or to convert TecPlot raster data into OGS meshes. All data available for the raster will be converted into cell arrays for the OGS mesh.
+
+This tool may be extended in the future to handle more TecPlot-related functionality.
+
+The tool is part of the official [OpenGeoSys git repository](https://github.com/ufz/ogs).
+
+## Usage
+
+```bash
+   TecPlotTools -i <string> [-o <string>] [-c] [-s]
+
+
+Where:
+
+   -i <string>,  --input-file <string>
+     (required)  TecPlot input file
+
+   -o <string>,  --output-file <string>
+     output mesh file
+
+   -c,  --convert
+     convert TecPlot data into OGS meshes
+
+   -s,  --split
+     split time steps into separate files
+```
+
+## Simple example
+
+**Command:**
+```
+TecPlotTools -i Lake.plt -o Lake.vtu -c
+```
+
+**Input:**
+
+![TecPlot-Header of file containing raster data](./PoyangLake-TecPlot.png)
+
+**Output:**
+
+![Converted file visualised in ParaView with all scalar data available.](./PoyangLake-ParaView.png)
+

web/content/docs/tools/meshing/vtu2grid/index.pandoc

@@ -17,8 +17,8 @@ The tool is part of the official [OpenGeoSys git repository](https://github.com/
 ## Usage
 
 ```bash
-   Vtu2Grid.exe  -i <input.vtu> -o <output.vtu> -x <floating point number>
-                 [-y <floating point number>] [-z <floating point number>]
+   Vtu2Grid  -i <input.vtu> -o <output.vtu> -x <floating point number>
+             [-y <floating point number>] [-z <floating point number>]
 
 Where: