commit 60d5057cdbe6b7f9feb292aca7e3e3b1b010a1b0
parent 30199ca8ecbf902c68781b8e49a53c6a62717ba8
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 10 Mar 2020 16:04:27 +0100
Update the man pages
Update the htrdr(1) man page and write the htrdr-materials(5) one.
Diffstat:
3 files changed, 86 insertions(+), 17 deletions(-)
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)
+set(MAN_NAMES htrdr-image.5 htrdr-materials.5)
set(MAN_FILES)
foreach(_name IN LISTS MAN_NAMES)
diff --git a/doc/htrdr-materials.5.txt b/doc/htrdr-materials.5.txt
@@ -0,0 +1,66 @@
+// 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-materials(5)
+=================
+
+NAME
+----
+htrdr-materials - list of materials used by the ground geometry in htrdr(1)
+
+DESCRIPTION
+-----------
+A *htrdr-materials* file lists the materials that can be used by the ground
+geometry of the *htrdr*(1) program. Each line of the file gives the name of
+the material and the path toward the *mrumtl*(5) file storing the spectral
+properties of its associated Bidirectional Reflectance Distribution Function.
+The material name can be composed of any characters excepted spaces and
+tabulations. The path toward the *mrumtl*(5) file must be a valid path
+regarding the file system.
+
+Characters behind the hash mark (#) are considered as comments and are thus
+ignored. Empty lines, i.e. lines without any characters or composed of spaces
+tabulations, are simply skipped.
+
+GRAMMAR
+-------
+
+[verse]
+-------
+<htrdr-materials> ::= <material>
+ [ <material> ... ]
+<material> ::= <name> <mrumtl-path>
+<name> ::= STRING
+<mrumtl-path> ::= PATH
+-------
+
+EXAMPLE
+-------
+
+The following file lists 2 materials. The first one named *grass* has its
+spectral BRDF defines in the *A001.mrumtl* file. The second one is named
+*sand* and has its spectral properties saved in the *B002.mrumtl* file.
+
+[verse]
+-------
+grass /opt/materials/A001.mrumtl
+sand /opt/materials/B002.mrumtl
+-------
+
+SEE ALSO
+--------
+*htrdr*(1), *mrumtl*(5)
diff --git a/doc/htrdr.1.txt.in b/doc/htrdr.1.txt.in
@@ -73,13 +73,6 @@ OPTIONS
Path toward the file containing the gas optical properties of the atmosphere.
Data must be formatted according to the fileformat described in [1].
-*-b* <diffuse|specular>::
- Define how light is reflected at the ground surface. When set to diffuse, the
- reflections are lambertian while a specular surface simulates a perfect
- mirror. By default, the ground surface is diffuse. Note that this option
- controls only the directional part of the surface reflections; the amount of
- reflected energy is defined by the *-e* option.
-
*-c* _clouds_::
Submit a *htcp*(5) file describing the properties of the clouds. If not
defined, only the atmosphere properties submitted through the *-a* option
@@ -122,17 +115,21 @@ OPTIONS
by the octree node. In the _output_ file, each octree is separated of the
previous one by a line with three minus characters, i.e. '---'.
-*-e* _reflectivity_::
- Reflectivity of the ground geometry in [0, 1]. By default it is set to
- @HTRDR_ARGS_DEFAULT_GROUND_REFLECTIVITY@. This parameter is fixed for the
- whole visible range and defines the amount of reflected energy. Refer to the
- *-b* option to control how the light is reflected on the ground surface.
-
*-f*::
Force overwrite of the _output_ file.
*-g* _ground_::
- Path toward an OBJ file [2] representing the ground geometry.
+ Path toward an OBJ file [2] representing the ground geometry. Note that only
+ triangular meshes are handled. Furthermore, each triangle must have a
+ material, i.e. it must belongs to a *usemtl* group as defined by the OBJ file
+ format. The name of the *usemtl* 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 (:). Each
+ string must reference the name of a material listed in the
+ *htrdr-materials*(5) file submitted through the *-M* option.
+ <__front-mtl-name__> and <__back-mtl-name__> are the name of the front and
+ back facing materials, respectively. In *htrdr*(1), a triangle side is said
+ "front facing" if its vertices are clock-wise ordered.
*-h*::
List short help and exit.
@@ -156,6 +153,9 @@ OPTIONS
*-r*::
Infinitely repeat the _clouds_ along the X and Y axis.
+*-M* _materials_::
+ Path toward a *htrdr-materials*(5) file listing the ground materials.
+
*-m* _mie_::
Path toward a *htmie*(5) file defining the optical properties of water
droplets.
@@ -180,6 +180,7 @@ OPTIONS
*-T* _threshold_::
Optical thickness used as threshold criteria to partition the properties of
the clouds. By default its value is @HTRDR_ARGS_DEFAULT_OPTICAL_THICKNESS_THRESHOLD@.
+ This option is ignored if a cache file is used (option *-O*).
*-t* _threads-count_::
Hint on the number of threads to use. By default use as many threads as CPU
@@ -188,7 +189,8 @@ OPTIONS
*-V* **_x_**,**_y_**,**_z_**::
Define the maximum definition of the acceleration data structure that
partitions the cloud properties. By default the finest definition is the
- definition of the submitted *htcp*(5) file.
+ definition of the submitted *htcp*(5) file. This option is ignored if a cache
+ file is used (option *-O*).
*-v*::
Make *htrdr* verbose.
@@ -286,4 +288,5 @@ SEE ALSO
*htcp*(5),
*htmie*(5),
*htpp*(1),
-*htrdr-image*(5)
+*htrdr-image*(5),
+*htrdr-materials*(5)
