commit cee3a047a1aeedf1a82e6ec5994b4c2b47ae7f48
parent 1c6db961c413f0d6131c4db41c1d2343ae3febd9
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 1 Apr 2020 20:50:23 +0200
Write the mrumtl man page
Diffstat:
2 files changed, 136 insertions(+), 0 deletions(-)
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
@@ -84,7 +84,29 @@ if(NOT NO_TEST)
target_link_libraries(test_mrumtl_wlen m)
target_link_libraries(test_mrumtl_band m)
endif()
+endif()
+################################################################################
+# Man pages
+###############################################################################
+find_program(A2X NAMES a2x a2x.py)
+if(NOT A2X)
+ message(WARNING
+ "The `a2x' program is missing. "
+ "The mrumtl man page cannot be generated.")
+else()
+ set(_src ${PROJECT_SOURCE_DIR}/../doc/mrumtl.5.txt)
+ set(_txt ${CMAKE_CURRENT_BINARY_DIR}/mrumtl.5.txt)
+ add_custom_command(
+ OUTPUT mrumtl.5
+ COMMAND ${CMAKE_COMMAND} -E copy ${_src} ${_txt}
+ COMMAND ${A2X} -dmanpage -fmanpage ${_txt}
+ DEPENDS ${_src}
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Buid ROFF man page mrumtl.5"
+ VERBATIM)
+ add_custom_target(man-roff ALL DEPENDS mrumtl.5)
+ install(FILES ${CMAKE_CURRENT_BINARY_DIR}/mrumtl.5 DESTINATION share/man/man5)
endif()
################################################################################
diff --git a/doc/mrumtl.5.txt b/doc/mrumtl.5.txt
@@ -0,0 +1,114 @@
+// Copyright (C) 2020 |Meso|Star> (contact@meso-star.com)
+//
+// 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:
+
+mrumtl(5)
+=========
+
+NAME
+----
+mrumtl - ModRadUrb MaTeriaL file format
+
+DESCRIPTION
+-----------
+
+A *mrumtl* file defines a spectral varying Bidirectional Reflectance
+Distribution Function (BRDF). Both the parameters and the type of the function
+can vary over the spectrum. These data can be defined for a list of
+wavelengths or for a set a spectral bands. In both cases, the wavelengths or
+the band boundaries are given in nanometers and must be listed in ascending
+orders. In addition the spectral bands must not overlapped.
+
+Characters behind the hash mark (#) are considered as comments and are thus
+ignored. Empty lines, i.e. lines without any characters or composed only of
+spaces and tabulations, are simply skipped.
+
+GRAMMAR
+-------
+
+[verse]
+-------
+<mrumtl> ::= <BRDF-list-wlen>
+ | <BRDF-list-band>
+
+<BRDF-list-wlen> ::= wavelengths <wavelengths-count>
+ <BRDF-wlen>
+ [ <BRDF-wlen> ... ]
+
+<BRDF-list-band> ::= bands <bands-count>
+ <BRDF-band>
+ [ <BRDF-band> ... ]
+
+<wavelengths-count> ::= INTEGER
+<bands-count> ::= INTEGER
+
+<BRDF-wlen> ::= <wavelength> <BRDF>
+
+<BRDF-band> ::= <band-bound-min> <band-bound-max> <BRDF>
+<bound-bound-min> ::= <wavelength>
+<bound-bound-max> ::= <wavelength>
+
+<wavelength> ::= DOUBLE # in nanometer
+
+<BRDF> ::= <BRDF-lambertian>
+ | <BRDF-specular>
+
+<BRDF-lambertian> ::= lambertian <reflectivity>
+<BRDF-specular> ::= specular <reflectivity>
+<reflectivity> ::= DOUBLE
+-------
+
+EXAMPLES
+--------
+
+Describe a material with only two bands: one for the visible part of the
+spectrum and one for the long waves. In both cases use a diffuse reflectivity:
+
+[verse]
+-------
+bands 2
+380 780 lambertian 0.9 # Visible part
+1000 100000 lambertian 0.1 # Infrared
+-------
+
+Setup a material for a list of 17 wavelengths. This material is diffuse in
+short waves and specular in long waves:
+
+[verse]
+-------
+wavelengths 17
+
+# Short waves
+430 lambertian 5.2e-2
+450 lambertian 6.2e-2
+500 lambertian 6.5e-002
+600 lambertian 0.165
+750 lambertian 0.175
+
+# Long waves
+1100 specular 0.1
+1300 specular 0.17
+1400 specular 0.1
+2000 specular 0.1
+2100 specular 0.4
+2300 specular 0.18
+2500 specular 0.9
+2600 specular 0.95
+2900 specular 0.4
+3000 specular 0.3
+4000 specular 0.0
+100000 specular 0.0
+-------
+
