htrdr

commit 51f34dd8f409ee95b731c1d58ec70aef30d3f59d
parent 8abea678a3a099cb774aa8bf020911a29bba6329
Author: Vincent Forest <vincent.forest@meso-star.com>
Date:   Fri, 27 Mar 2020 18:46:49 +0100

Write the htrdr-obj man page

Diffstat:
M
cmake/doc/CMakeLists.txt
 | 
2
+-
A
doc/htrdr-obj.5.txt
 | 
69
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

2 files changed, 70 insertions(+), 1 deletion(-)
diff --git a/cmake/doc/CMakeLists.txt b/cmake/doc/CMakeLists.txt
@@ -29,7 +29,7 @@ endif()
 ################################################################################
 # Copy doc files
 ################################################################################
-set(MAN_NAMES htrdr-image.5 htrdr-materials.5)
+set(MAN_NAMES htrdr-image.5 htrdr-materials.5 htrdr-obj.5)
 
 set(MAN_FILES)
 foreach(_name IN LISTS MAN_NAMES)
diff --git a/doc/htrdr-obj.5.txt b/doc/htrdr-obj.5.txt
@@ -0,0 +1,69 @@
+// Copyright (C) 2018, 2019, 2020 |Meso|Star> (contact@meso-star.com)
+// Copyright (C) 2018-2019 CNRS, Université Paul Sabatier
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <http://www.gnu.org/licenses/>.
+:toc:
+
+htrdr-obj(5)
+============
+
+NAME
+----
+htrdr-obj - file format of the ground geometry in htrdr(1)
+
+DESCRIPTION
+-----------
+A *htrdr-obj* file is a regular OBJ [1] composed only of triangular
+meshes. Each triangle must be included in a material group as defined by
+the 'usemtl' directive. The name of the material group must be of the
+form "<__front-mtl-name__>:<__back-mtl-name__>", where
+<__front-mtl-name__> and <__back-mtl-name__> are strings separated by a
+colon mark (:) defining the name of the front and back facing materials,
+respectively. These names can be composed of any characters expected
+spaces and tabulations. Note that regarding the *htrdr*(1) convention, a
+triangle side is said "front facing" when its vertices are clock-wise
+ordered.
+
+The grammar of a *htrdr-obj* file is thus a subset of the OBJ file
+format [1] with only a specific convention regarding the material name.
+As a consequence, any software supporting the OBJ file format can be
+used to create or visualise an *htrdr-obj* file.
+
+EXAMPLE
+-------
+Define a quad at the interface between the air medium and the concrete
+material.
+
+[verse]
+-------
+v -5.0  -5.0  0
+v -5.0   5.0  0
+v  5.0  -5.0  0
+v  5.0   5.0  0
+
+usemtl air:concrete
+f 1 2 3
+f 3 2 4
+-------
+
+NOTES
+-----
+
+1. OBJ file format -
+  <http://www.martinreddy.net/gfx/3d/OBJ.spec>
+
+SEE ALSO
+--------
+
+*htrdr*(1)