commit a09fa9e1afca7ed0a8c5108316465f6abc8104d7
parent 7b8c4185bcde6e63531e814145ead833e1a600fb
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Thu, 26 Jan 2023 10:22:40 +0100
Additions to the man pages
Diffstat:
2 files changed, 115 insertions(+), 8 deletions(-)
diff --git a/doc/city_generator2-output.5.txt b/doc/city_generator2-output.5.txt
@@ -23,18 +23,125 @@
== NAME
-city_generator2-output - naming-scheme of city_generator2(1) generated files.
+city_generator2-output - naming-scheme for city_generator2(1) generated files.
== DESCRIPTION
-Blah.
+The output of *city_generator2* is a set of *STL* files, either in ascii or in
+binary format, that describe the ground and the building parts, along with all
+their boundaries. As expected for use by most solvers, including *stardis*(1),
+the output meshes are conformal. The various output files for buildings are
+named after the name of the building they are part of, as well as the name of
+the part they mesh.
-== NOTES
+== NAMING SCHEME
-1. YAML syntax -
- <https://yaml.org/>
+Some conventions apply in file names, regardless of which part of the output is
+concerned:
+
+- The name starts with either "ground", or a building name; the later obviously
+ indicates this file is part of the output for this building.
+
+- The next part of the name is a capital letter that indicates which type of
+ mesh the file describes: *B* if the file describes a boundary (a frontier with
+ the external fluid), *C* if the file describes a connection (a frontier
+ between two solids or between a solid and the internal fluid), *F* is the file
+ describes a fluid closed volume, and *S* if the file describes a solid closed
+ volume.
+
+- The final part of the name indicates which part is described.
+
+- The parts are separated with *_*.
+
+The simplest part of the output is the ground. The mesh describing the ground is
+provided both in a single file named *ground_B.stl* and in 6 files, one file per
+side, named *ground_B_0.stl* to *ground_B_5.stl*. The shape of the mesh is the
+box described in the city map file used in input (see
+*city_generator2-intput*(5)) punched with 1 hole per building, according to
+building footprints.
+
+The connection between the ground and each building is part of the building
+description. If a closed volume for the ground is needed, it can be obtained as
+the union of the meshes in *ground_B.stl* and **_C_ground.stl*.
+
+Each building on the map is described by various files, depending on its
+construction mode.
+
+Buildings of construction mode *Construction_Mode_0* produce the following
+output files:
+
+- The solid for the walls.
+
+- The solid for the floor.
+
+- The solid for the roof.
+
+- The internal fluid.
+
+- The 3 solid-fluid connections between the internal fluid and the 3 solids.
+
+- The solid-solid connection between the building and the ground.
+
+- The boundary of the walls.
+
+- The boundary of the roof.
+
+Note that the many solid-solid connections between the different building layers
+are not part of the output.
+
+Buildings of construction mode *Construction_Mode_1* produce the following
+output files, some being optional:
+
+- The solid for the walls.
+
+- The solid for the floor.
+
+- The solid for the roof.
+
+- The solid for the glazing.
+
+- The solid for the foundation (optional).
+
+- The solid for the intermediate floors (optional, all levels merged).
+
+- The solid for the internal insulation (optional).
+
+- The solid for the external insulation (optional).
+
+- The solid for the attic insulation (optional).
+
+- The solid for the floor insulation (optional).
+
+- The solid for the roof insulation (optional).
+
+- The internal fluid in the attic (optional).
+
+- The internal fluid in the crawlspace (optional).
+
+- The internal fluid for the other levels (all levels merged).
+
+- Various solid-fluid connections between an internal fluid and a solid.
+ Depending on optional layer presence, the connection can be between a fluid
+ and an optional layer, or between a fluid and the next layer.
+
+- The solid-solid connection between the building and the ground.
+
+- The boundary of the various solids, including optional ones, that are part of
+ the external layer of the building.
+
+Note that the many solid-solid connections between the different building layers
+are not part of the output.
+
+== MESH ORIENTATION
+
+All the meshes enclosing either a fluid or a solid are defined with all
+triangles having their direct normal (right-hand rule) pointing to the outside.
+
+Additionally, all the meshes, either defining an enclosure or a connection or a
+boundary, comply with a consistency requirement regarding normal orientation
+(all the normals on the same side).
== SEE ALSO
*city_generator2*(1),
-rcity_generator2-input*(5),
+*city_generator2-input*(5),
diff --git a/doc/city_generator2.1.txt.in b/doc/city_generator2.1.txt.in
@@ -45,8 +45,8 @@ The output of *city_generator2* is a set of *STL* files, either in ascii or in
binary format, that contain the various meshes of the ground layers and
building parts, along with all their boundaries. As expected for use by most
solvers, including *stardis*(1), the output meshes are conformal.
-The various output files are named after the name of the building they are part
-of, as well as the name of the part they mesh.
+The various output files for buildings are named after the name of the building
+they are part of, as well as the name of the part they mesh.
Please refer to *city_generator2-output*(5) for the complete description of
this naming scheme.
