commit c25a55f28267ef02340689816d2851c9bc600246
parent 3e1f6f3e57ad5bb35afe0b3e535c28fce4de13a2
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 19 Oct 2022 18:17:33 +0200
Convert the man page sources from asciidoc to scdoc
Diffstat:
13 files changed, 1331 insertions(+), 1388 deletions(-)
diff --git a/cmake/doc/CMakeLists.txt b/cmake/doc/CMakeLists.txt
@@ -20,61 +20,46 @@ set(HTRDR_DOC_DIR ${PROJECT_SOURCE_DIR}/../doc)
################################################################################
# Look for the a2x program
################################################################################
-find_program(A2X NAMES a2x a2x.py)
-if(NOT A2X)
+find_program(SCDOC NAMES scdoc)
+if(NOT SCDOC)
message(WARNING
- "The `a2x' program is missing. "
+ "The `scdoc' program is missing. "
"The htrdr man pages cannot be generated.")
return()
endif()
################################################################################
-# Copy doc files
+# ROFF man pages
################################################################################
-set(MAN_NAMES htrdr.1 htrdr-image.5 htrdr-materials.5 htrdr-obj.5)
-
-set(MAN_FILES)
-foreach(_name IN LISTS MAN_NAMES)
- set(_src ${HTRDR_DOC_DIR}/${_name}.txt)
- set(_dst ${CMAKE_CURRENT_BINARY_DIR}/${_name}.txt)
- add_custom_command(
- OUTPUT ${_dst}
- COMMAND ${CMAKE_COMMAND} -E copy ${_src} ${_dst}
- DEPENDS ${_src}
- COMMENT "Copy the asciidoc ${_src}"
- VERBATIM)
- list(APPEND MAN_FILES ${_dst})
-endforeach()
-add_custom_target(man-copy ALL DEPENDS ${MAN_FILES})
+set(MAN_SOURCES
+ ${HTRDR_DOC_DIR}/htrdr.1.scd
+ ${HTRDR_DOC_DIR}/htrdr-image.5.scd
+ ${HTRDR_DOC_DIR}/htrdr-materials.5.scd
+ ${HTRDR_DOC_DIR}/htrdr-obj.5.scd)
if(HTRDR_BUILD_ATMOSPHERE)
- configure_file(${HTRDR_SOURCE_DIR}/../doc/htrdr-atmosphere.1.txt.in
- ${CMAKE_CURRENT_BINARY_DIR}/htrdr-atmosphere.1.txt @ONLY)
- list(APPEND MAN_NAMES htrdr-atmosphere.1)
+ configure_file(${HTRDR_DOC_DIR}/htrdr-atmosphere.1.scd.in
+ ${CMAKE_CURRENT_BINARY_DIR}/htrdr-atmosphere.1.scd @ONLY)
+ list(APPEND MAN_SOURCES ${CMAKE_CURRENT_BINARY_DIR}/htrdr-atmosphere.1.scd)
endif()
if(HTRDR_BUILD_COMBUSTION)
- configure_file(${HTRDR_SOURCE_DIR}/../doc/htrdr-combustion.1.txt.in
- ${CMAKE_CURRENT_BINARY_DIR}/htrdr-combustion.1.txt @ONLY)
- list(APPEND MAN_NAMES htrdr-combustion.1)
+ configure_file(${HTRDR_DOC_DIR}/htrdr-combustion.1.scd.in
+ ${CMAKE_CURRENT_BINARY_DIR}/htrdr-combustion.1.scd @ONLY)
+ list(APPEND MAN_SOURCES ${CMAKE_CURRENT_BINARY_DIR}/htrdr-combustion.1.scd)
endif()
-################################################################################
-# ROFF man pages
-################################################################################
-set(A2X_OPTS -dmanpage -fmanpage)
set(MAN_FILES)
set(MAN5_FILES)
set(MAN1_FILES)
-foreach(_name IN LISTS MAN_NAMES)
- set(_man ${CMAKE_CURRENT_BINARY_DIR}/${_name})
- set(_txt ${CMAKE_CURRENT_BINARY_DIR}/${_name}.txt)
+foreach(_src IN LISTS MAN_SOURCES)
+ get_filename_component(_man ${_src} NAME_WLE)
+ message(STATUS "${_man}")
add_custom_command(
OUTPUT ${_man}
- COMMAND ${A2X} ${A2X_OPTS} ${_txt}
- DEPENDS man-copy ${_txt}
- WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMAND ${SCDOC} < ${_src} > ${_man}
+ DEPENDS ${_src}
COMMENT "Build ROFF man page ${_man}"
VERBATIM)
list(APPEND MAN_FILES ${_man})
@@ -82,9 +67,9 @@ foreach(_name IN LISTS MAN_NAMES)
string(REGEX MATCH "^.*.5$" _man5 ${_man})
string(REGEX MATCH "^.*.1$" _man1 ${_man})
if(_man1)
- list(APPEND MAN1_FILES ${_man1})
+ list(APPEND MAN1_FILES ${CMAKE_CURRENT_BINARY_DIR}/${_man1})
elseif(_man5)
- list(APPEND MAN5_FILES ${_man5})
+ list(APPEND MAN5_FILES ${CMAKE_CURRENT_BINARY_DIR}/${_man5})
else()
message(FATAL_ERROR "Unexpected man type")
endif()
@@ -93,4 +78,3 @@ add_custom_target(man-roff ALL DEPENDS ${MAN_FILES})
install(FILES ${MAN1_FILES} DESTINATION share/man/man1)
install(FILES ${MAN5_FILES} DESTINATION share/man/man5)
-
diff --git a/doc/htrdr-atmosphere.1.scd.in b/doc/htrdr-atmosphere.1.scd.in
@@ -0,0 +1,498 @@
+htrdr-atmosphere(1)
+
+; Copyright (C) 2018, 2019, 2020, 2021 |Meso|Star> (contact@meso-star.com)
+; Copyright (C) 2018, 2019, 2021 CNRS
+; Copyright (C) 2018, 2019 Université Paul Sabatier
+; (contact-edstar@laplace.univ-tlse.fr)
+;
+; 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/>.
+
+# NAME
+
+htrdr-atmosphere - simulate radiative transfer in cloudy atmospheres
+
+# SYNOPSIS
+
+htrdr-atmosphere [_option_]... -a _atmosphere_
+
+# DESCRIPTION
+
+*htrdr-atmosphere* simulates radiative transfer in scenes composed of an
+atmospheric gas mixture, clouds, and a ground. It evaluates the intensity
+incoming on each pixel of the sensor array. The underlying algorithm is based
+on a Monte-Carlo method: it consists in simulating a given number of optical
+paths originating from the sensor, directed into the atmosphere, taking into
+account light absorption and scattering phenomena. This algorithm and the way
+it is efficiently implemented in *htrdr-atmosphere* is presented in the
+following article: "A path-tracing Monte Carlo library for 3-D radiative
+transfer in highly resolved cloudy atmospheres", N. Villefranque et al, JAMES
+2019 [1].
+
+Radiative transfer can be evaluated in the visible or the infrared part of the
+spectrum. It uses spectral data that should be provided for the pressure and
+temperature atmospheric vertical profile [2] (*-a* _atmosphere_), the liquid
+water content in suspension within the clouds stored in a *htcp*(5) file (*-c*
+_clouds_), and the optical properties of water droplets that have been obtained
+from a Mie code and formatted according to the *htmie*(5) file format (*-m*
+_mie_). The user also has to set the position of the sun (*-D*
+_azimuth_,_elevation_), the sensor type (*-C* _camera_ or *-p* _rectangle_) and
+its definition (*-i* _image_). It is also possible to provide an *htrdr-obj*(5)
+file representing the ground geometry (*-g* _ground_) whose materials are
+listed in the *htrdr-material*(5) file provided through the *-M* option. Both,
+the clouds and the ground, can be infinitely repeated along the X and Y axis by
+setting the *-r* and the *-R* options, respectively.
+
+Four types of sensor are supported by *htrdr-atmosphere*. The pinhole and thin
+lens camera (*-C* _camera_) are used to render an image of the scene from the
+given point of view. The orthographic camera (*-P* _camera_) render the scene
+with a parallel projection rather than a perspective projection. Finally, the
+rectangle sensor (*-p* _rectangle_) is used to compute a flux map.
+
+Spectral dimension can be integrated in many ways (*-s* option). When rendering
+an image (*-C* _camera_), the computation is by default performed for the
+visible part of the spectrum in [380, 780] nanometers, for the three components
+of the CIE 1931 XYZ colorimetric space that are subsequently recombined in
+order to obtain the final color for each pixel, and finally the whole image of
+the scene as seen from the set observation position. The two other ways consist
+in explicitly defining the longwave or shortwave spectral range to handle and
+continuously sampling a wavelength in this range. Actually longwave and
+shortwave are keywords that mean that the source of radiation is whether
+external or internal to the medium, respectively. In shortwave rendering, only
+the pixel radiance is evaluated and stored in the output image. For longwave
+rendering this estimated radiance is then converted to its brightness
+temperature and both are saved in the image. When computing a flux map (*-p*
+_rectangle_), the per pixel flux is saved into the output map whether spectral
+domain is longwave or shortwave.
+
+In *htrdr-atmosphere* the spatial unit 1.0 corresponds to one meter and the
+temperatures are expressed in Kelvin. The estimated radiances are given in
+W/sr/m² excepted for monochromatic computations where the computed spectral
+radiance is defined in W/sr/m²/nm. The flux densities are saved in W/m². The
+results are written to the output file if the *-o* option is defined and the
+standard output otherwise. The output image is a list of raw ASCII data
+formatted with respect to the *htrdr-image*(5) file format.
+
+*htrdr-atmosphere* supports shared memory parallelism and relies on the Message
+Passing Interface specification [4] to parallelise its computations in a
+distributed memory environment; it can thus be run either directly or through a
+MPI process launcher like *mpirun*(1).
+
+# OPTIONS
+
+*-a* _atmosphere_
+ Path toward the file containing the gas optical properties of the atmosphere.
+ Data must be formatted according to the fileformat described in [2].
+
+*-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
+ are taken into account.
+
+*-C* <_camera-parameter_:...>
+ Define a perspective camera. Available parameters are:
+
+ *focal-dst*=_dst_
+ Distance to focus on with a thin lens camera, that is, a camera whose
+ *lens-radius* is not zero. The default focal distance is
+ @HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOCAL_DST@ meter.
+
+ *focal-length*=_length_
+ Focal length of a camera lens. It is another way to control the field of
+ view of a thin lens camera. By default, the field of view is directly set
+ through the *fov* parameter.
+
+ *fov*=_angle_
+ Vertical field of view of the camera in
+ \]@HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MIN@,
+ @HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MAX@\[ degrees. By
+ default _angle_ is set to
+ @HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOV@ degrees.
+
+ *lens-radius*=_radius_
+ Radius of the camera lens. A non-zero radius means that the camera is a thin
+ lens camera while a zero radius defines a pinhole camera. By default the
+ lens radius is @HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_LENS_RADIUS@.
+
+ *pos*=_x_,_y_,_z_
+ Camera lens position. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_CAMERA_POS@}.
+
+ *tgt*=_x_,_y_,_z_
+ Position targeted by the camera. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_CAMERA_TGT@}.
+
+ *up*=_x_,_y_,_z_
+ Up vector of the camera. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_CAMERA_UP@}.
+
+*-D* <_azimuth_,_elevation_>
+ Direction toward the sun center. The direction is defined by two angles in
+ degrees: the _azimuth_ angle in [0, 360[ and the _elevation_ angle in [0,
+ 90]. Following the right-handed convention, the azimuthal rotation is
+ counter-clockwise, with 0 degree on the X axis. The elevation starts from 0
+ degree for a direction in the XY plane, up to 90 degrees at zenith. Thus
+ *-D* _0_,_0_ *-D* _90_,_0_ -*D* _180_,_0_ and *-D* _270_,_0_ will produce solar
+ vectors {+1,0,0} {0,+1,0} {-1,0,0} and {0,-1,0} respectively, while
+ *-D* _azimuth_,_90_ will produce {0,0,+1} regardless of _azimuth_ value.
+
+*-d*
+ Write in _output_ the space partitioning data structures used to speed up
+ the radiative transfer computations in the clouds. The written data are
+ octrees saved in the VTK file format [3]. Each octree node stores the minimum
+ and the maximum of the extinction coefficients of the cloud cells overlapped
+ by the octree node. In the _output_ file, each octree is separated from the
+ previous one by a line with three minus characters, i.e. '---'.
+
+*-f*
+ Force overwrite of the _output_ file.
+
+*-g* _ground_
+ Path toward a *htrdr-obj*(5) representing the ground geometry.
+
+*-h*
+ List short help and exit.
+
+*-i* <_image-parameter_:...>
+ Define the sensor array. Available image parameters are:
+
+ *def*=<_width_>x<_height_>
+ Definition of the image. By default the image definition is
+ @HTRDR_ARGS_DEFAULT_IMG_WIDTH@x@HTRDR_ARGS_DEFAULT_IMG_HEIGHT@.
+
+ *spp*=_samples-count_
+ Number of samples per pixel estimation. In regular image rendering, a pixel
+ will use "3 \* _samples-count_" Monte-Carlo realisations, one set of
+ _samples-count_ realisations for each X, Y and Z component of the CIE 1931
+ XYZ color space. In shortwave/longwave rendering or flux computation, only
+ one set of _samples-count_ is used. By default, *spp* is set to
+ @HTRDR_ARGS_DEFAULT_IMG_SPP@.
+
+*-R*
+ Infinitely repeat the _ground_ along the X and Y axis.
+
+*-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.
+
+*-n* _sky-mtl_
+ Name of the material representing the sky in the *htrdr-materials*(5) file.
+ By default, _sky-mtl_ is @HTRDR_ATMOSPHERE_ARGS_DEFAULT_SKY_MTL_NAME@.
+
+*-O* _cache_
+ File used to cache the sky data. If the _cache_ file does not exists, it is
+ created and filled with the sky data built from the _clouds_, the _atmosphere_
+ and the _mie_ input files. This cached data can then be reused in the next
+ runs as long as the input files provided on the command are the same as the
+ ones used to setup the cache; leading to a significant speed-up of the
+ pre-processing step. If _cache_ contains data generated from input files that
+ are not the ones submitted on the command line, an error is notified and the
+ execution is stopped, avoiding the use of wrong cached data. Note that when
+ the cache is used, *htrdr-atmosphere* ignores the arguments used to
+ parametrise the structures partitioning the sky data, i.e. the *-T* and *-V*
+ options.
+
+*-o* _output_
+ File where *htrdr-atmosphere* writes its _output_ data. If not defined, write
+ results to standard output.
+
+*-P* <_camera-parameter_:...>
+ Define an orthographic camera. Available parameters are:
+
+ *height*=_radius_
+ Height of the image plane. By default it is set to
+ @HTRDR_ARGS_DEFAULT_CAMERA_ORTHOGRAPHIC_HEIGHT@.
+
+ *pos*=_x_,_y_,_z_
+ Camera lens position. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_CAMERA_POS@}.
+
+ *tgt*=_x_,_y_,_z_
+ Position targeted by the camera. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_CAMERA_TGT@}.
+
+ *up*=_x_,_y_,_z_
+ Up vector of the camera. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_CAMERA_UP@}.
+
+*-p* <_rectangle-parameter_:...>
+ Switch in flux map computation. The flux is computed for the part of the
+ sensor that is outside any geometry. The rectangular sensor onto which the
+ flux is integrated is defined by the following parameters:
+
+ *pos*=_x_,_y_,_z_
+ Position of the center of the rectangle. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_RECTANGLE_POS@}.
+
+ *tgt*=_x_,_y_,_z_
+ Position targeted by the rectangle, i.e. *tgt* - *pos* is the rectangle
+ normal. By default it is set to {@HTRDR_ARGS_DEFAULT_RECTANGLE_TGT@}.
+
+ *up*=_x_,_y_,_z_
+ Up vector of the rectangle. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_RECTANGLE_UP@}.
+
+ *sz*=_width_,_height_
+ Size of the rectangle. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_RECTANGLE_SZ@}.
+
+*-s* <_spectral-parameter_:...>
+ Define the type and the range of the spectral integration. Available
+ spectral parameters are:
+
+ *cie_xyz*
+ the radiance is computed for the visible part of the spectrum in [380, 780]
+ nanometers with respect to the XYZ CIE 1931 tristimulus values. This is the
+ default comportment of *htrdr-atmosphere*.
+
+ *lw*=_wlen-min_,_wlen-max_
+ perform the spectral sampling continuously in the [_wlen-min_, _wlen-max_]
+ wavelength range (wavelength must be provided in nanometers) according to
+ the Planck function for a reference temperature. If _wlen-min_ and
+ _wlen-max_ are equals the computation is monochromatic. *lw* means for
+ longwave but is here a code word that really means "computation of radiance
+ using the internal source of radiation": in other words, radiation is
+ emitted by the medium and its boundaries (ground and space). Because the
+ application is for the terrestrial atmosphere, internal radiation is
+ emitted in the thermal longwave part of the electromagnetic spectrum.
+ Therefore the default value of the reference temperature used in the
+ spectral sampling is fixed at 290 K.
+
+ *sw*=_wlen-min_,_wlen-max_
+ perform the spectral sampling continuously in the [_wlen-min_, _wlen-max_]
+ wavelength range (wavelength must be provided in nanometers) according to
+ the Planck function for a reference temperature. If _wlen-min_ and
+ _wlen-max_ are equals the computation is monochromatic. In the present
+ case, *sw* means that the source of radiation is external to the medium:
+ because the application is for the terrestrial atmosphere, the value of the
+ reference temperature is by default fixed at 5778 K, i.e. the blackbody
+ temperature of the Sun.
+
+ *Tref*=_temperature_
+ reference temperature of the Planck function used to continuously sample the
+ longwave/shortwave spectral range. In longwave, it is set to 290 K by
+ default while in shortwave its default value is the blackbody temperature of
+ the sun (i.e. 5778 K).
+
+*-T* _threshold_
+ Optical thickness used as threshold criteria to partition the properties of
+ the clouds. By default its value is
+ @HTRDR_ATMOSPHERE_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
+ cores.
+
+*-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. This option is ignored if a cache
+ file is used (option *-O*).
+
+*-v*
+ Make *htrdr-atmosphere* verbose.
+
+# OUTPUT IMAGE
+
+Images calculated by *htrdr-atmosphere* are saved in the *htrdr-image*(5) file
+format. This section describes the nature and arrangement of image data
+depending on the type of calculation performed by *htrdr-atmosphere*.
+
+## XYZ image
+
+For an image rendering in the visible part of the spectrum (default behavior or
+*-s cie_xyz* option), the pixel components store 4 estimates. The first,
+second, and third pairs of floating point values encode the estimated
+integrated radiance in W/sr/m² for the X, Y, and Z components of the CIE
+1931 XYZ color space. The first value of each pair is the expected value of the
+average radiance of the pixel. The second value is its associated standard
+deviation. The fourth and final pair records the microsecond estimate of the
+computation time per radiative path and its standard error.
+
+## Longwave image
+
+If the image is an infrared rendering (option *-s* *lw*=_wlen-min_,_wlen-max_)
+the first and second pixel components store the expected value and the standard
+error of the estimated brightness temperature (in K), respectively. The third
+and fourth components record the expected value and the standard deviation of
+the pixel radiance which is either an integrated radiance in W/sr/m² or a
+spectral radiance in W/sr/m²/nm depending on whether this radiance was
+calculated for a spectral range or at a single wavelength. The fifth and sixth
+pixel components are not used. Finally, the last 2 components of the pixel
+record the estimate in microseconds of the computation time per radiative path
+and its standard error.
+
+## Shortwave image
+
+For shortwave renderings (option *-s* *sw*=_wlen-min_,_wlen-max_), the data
+written to the output image are formatted as for a longwave image except
+that the first and second components of the pixels are not used because no
+brightness temperature has been evaluated.
+
+## Flux density map (shortwave and longwave)
+
+A flux density map (option *-p*) is saved in an *htrdr-image*(5) storing the
+expected value and the standard error of the pixel radiative flux density (in
+W/m²) on its first and second component. All other components are unused
+excepted the seventh and eighth components that store the estimate of the
+radiative path computation time in microseconds and its standard error.
+
+# EXAMPLES
+
+Render a clear sky scene, i.e. a scene without any cloud, whose sun is at
+zenith. The vertical atmospheric gaz mixture along the Z axis is described in
+the _gas.txt_ file. The ground geometry is a quad repeated to the infinity
+whose materials are listed in the _material.mtl_ file. The camera is positioned
+at _400_ meters height and looks toward the positive Y axis. The definition of
+the rendered image is _800_ by _600_ pixels and the radiance of each pixel
+component is estimated with _64_ Monte-Carlo realisations. The resulting image
+is written to _output_ excepted if the file already exists; in this case an
+error is notified, the program stops and the _output_ file remains unchanged:
+
+```
+htrdr-atmosphere -D0,90 -a gas.txt -m Mie.nc -g quad.obj -R \
+ -M materials.mtl \
+ -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
+ -i def=800x600:spp=64 \
+ -o output
+```
+
+Add clouds to the previous scene and use a more complex geometry to represent
+the ground. The Mie data are provided through the _Mie.nc_ file. The ground
+geometry was carefully designed to be cyclic and can be thus infinitely
+repeated without visual glitches. Use the _-f_ option to write the rendered
+image to _output_ even though the file already exists. Finally, use the
+*htpp*(1) command to convert the *htrdr-image*(5) saved in output in a regular
+PPM image [5]:
+
+```
+htrdr-atmosphere -D0,90 -a gas.txt -m Mie.nc -g mountains.obj -R \
+ -M materials.mtl \
+ -c clouds.htcp \
+ -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
+ -i def=800x600:spp=64 \
+ -f -o output
+htpp -o image.ppm output
+```
+
+Render the previous scene in infrared for the wavelengths in [_9200_, _10000_]
+nanometers with a reference temperature of _300_ Kelvin:
+
+```
+htrdr-atmosphere -a gas.txt -m Mie.nc -g mountains.obj -R \
+ -M materials.mtl \
+ -c clouds.htcp \
+ -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
+ -i def=800x600:spp=64 \
+ -s lw=9200,10000:Tref=300 \
+ -f -o output
+```
+
+Move the sun by setting its azimuthal and elevation angles to _120_ and _40_
+degrees respectively. Use the *-O* option to enable the cache mechanism on
+sky data. Increase the image definition to _1280_ by _720_ and set the
+number of samples per pixel component to _1024_. Write results on standard
+output and convert the resulting image in PPM before visualising it through the
+*feh*(1) image viewer:
+
+```
+htrdr-atmosphere -D120,40 -a gas.txt -m Mie.nc -g mountains.obj -R \
+ -M materials.mtl \
+ -c clouds.htcp \
+ -O my_cache \
+ -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
+ -i def=1280x720:spp=1024 | htpp | feh -
+```
+
+Compute the downward flux for the shortwave interval [_350_, _4000_] nanometers
+on a square of _100_ meters side positionned at the origin at *1* meter height.
+The resolution of the flux map is _500_ by _500_ pixels and _1000_ realisations
+is used to estimate the flux per pixel. It is saved in the _flux_map.txt_ file
+even though this file already exists:
+
+```
+htrdr-atmosphere -D0,90 -a gas.txt -m Mie.nc -g plane.obj -R \
+ -M materials.mtl \
+ -c clouds.htcp \
+ -O my_cache \
+ -p pos=0,0,1:tgt=0,0,2:up=0,1,0:sz=100,100 \
+ -i def=500x500:spp=1000 \
+ -s sw=350,4000 \
+ -f -o flux_map.txt
+```
+
+Write into _output_ the data structures used to partition the clouds properties.
+Use the *csplit*(1) Unix command to extract from _output_ the list of the
+generated grids and save each of them in a specific VTK file whose name is
+_cloud_grid<NUM>.vtk_ with _NUM_ in [0, N-1] where N is the number of grids
+written into _output_:
+
+```
+htrdr-atmosphere -a gas.txt -m Mie.nc -c clouds.htcp -d -f -o output
+csplit -f cloud_grid_ -b %02d.vtk -z --suppress-matched output /^---$/ {*}
+```
+
+Use *mpirun*(1) to launch *htrdr-atmosphere* on several hosts defined in the
+_my_hosts_ file. Make the clouds infinite along the X and Y axis:
+
+```
+mpirun --hostfile my_hosts htrdr-atmosphere \
+ -D120,40 -a gas.txt -m Mie.nc -g mountains.obj -R \
+ -M materials.mtl \
+ -c clouds.htcp -r \
+ -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
+ -i def=1280x720:spp=1024 \
+ -f -o output
+```
+
+# COPYRIGHT
+
+Copyright (C) 2018, 2019, 2020, 2021 |Méso|Star> <contact@meso-star.com>++
+Copyright (C) 2018, 2019, 2021 Centre National de la Recherche Scientifique++
+Copyright (C) 2018, 2019 Université Paul Sabatier <contact-edstar@laplace.univ-tlse.fr>
+
+# LICENSE
+
+*htrdr-atmosphere* is free software released under the GPLv3+ license: GNU GPL
+version 3 or later <https://gnu.org/licenses/gpl.html>. You are free to change
+and redistribute it. There is NO WARRANTY, to the extent permitted by law.
+
+# SEE ALSO
+
+. A path-tracing Monte Carlo library for 3-D radiative transfer in highly
+ resolved cloudy atmospheres. N. Villefranque et al, JAMES 11, 2449-2473, 2019 -
+ <https://doi.org/10.1029/2018MS001602>
+. High-Tune: Gas Optical Properties file format -
+ <https://www.meso-star.com/projects/high-tune/downloads/gas_opt_prop_en.pdf>
+. VTK file format -
+ <http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf>
+. MPI specifications - <https://www.mpi-forum.org/docs/>
+. Portable PixMap - <http://netpbm.sourceforge.net/doc/ppm.html>
+
+*csplit*(1),
+*feh*(1),
+*mpirun*(1),
+*htcp*(5),
+*htmie*(5),
+*htpp*(1),
+*htrdr*(1),
+*htrdr-image*(5),
+*htrdr-materials*(5)
+*htrdr-obj*(5)
diff --git a/doc/htrdr-atmosphere.1.txt.in b/doc/htrdr-atmosphere.1.txt.in
@@ -1,504 +0,0 @@
-// Copyright (C) 2018, 2019, 2020, 2021 |Meso|Star> (contact@meso-star.com)
-// Copyright (C) 2018, 2019, 2021 CNRS
-// Copyright (C) 2018, 2019 Université Paul Sabatier
-// (contact-edstar@laplace.univ-tlse.fr)
-//
-// 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-atmosphere(1)
-===================
-
-NAME
-----
-htrdr-atmosphere - simulate radiative transfer in cloudy atmospheres
-
-SYNOPSIS
---------
-[verse]
-*htrdr-atmosphere* [_option_]... -a _atmosphere_
-
-DESCRIPTION
------------
-*htrdr-atmosphere* simulates radiative transfer in scenes composed of an
-atmospheric gas mixture, clouds, and a ground. It evaluates the intensity
-incoming on each pixel of the sensor array. The underlying algorithm is based
-on a Monte-Carlo method: it consists in simulating a given number of optical
-paths originating from the sensor, directed into the atmosphere, taking into
-account light absorption and scattering phenomena. This algorithm and the way
-it is efficiently implemented in *htrdr-atmosphere* is presented in the
-following article: "A path-tracing Monte Carlo library for 3-D radiative
-transfer in highly resolved cloudy atmospheres", N. Villefranque et al, JAMES
-2019 [1].
-
-Radiative transfer can be evaluated in the visible or the infrared part of the
-spectrum. It uses spectral data that should be provided for the pressure and
-temperature atmospheric vertical profile [2] (*-a* _atmosphere_), the liquid
-water content in suspension within the clouds stored in a *htcp*(5) file (*-c*
-_clouds_), and the optical properties of water droplets that have been obtained
-from a Mie code and formatted according to the *htmie*(5) file format (*-m*
-_mie_). The user also has to set the position of the sun (*-D*
-_azimuth_,_elevation_), the sensor type (*-C* _camera_ or *-p* _rectangle_) and
-its definition (*-i* _image_). It is also possible to provide an *htrdr-obj*(5)
-file representing the ground geometry (*-g* _ground_) whose materials are
-listed in the *htrdr-material*(5) file provided through the *-M* option. Both,
-the clouds and the ground, can be infinitely repeated along the X and Y axis by
-setting the *-r* and the *-R* options, respectively.
-
-Four types of sensor are supported by *htrdr-atmosphere*. The pinhole and thin
-lens camera (*-C* _camera_) are used to render an image of the scene from the
-given point of view. The orthographic camera (*-P* _camera_) render the scene
-with a parallel projection rather than a perspective projection. Finally, the
-rectangle sensor (*-p* _rectangle_) is used to compute a flux map.
-
-Spectral dimension can be integrated in many ways (*-s* option). When rendering
-an image (*-C* _camera_), the computation is by default performed for the
-visible part of the spectrum in [380, 780] nanometers, for the three components
-of the CIE 1931 XYZ colorimetric space that are subsequently recombined in
-order to obtain the final color for each pixel, and finally the whole image of
-the scene as seen from the set observation position. The two other ways consist
-in explicitly defining the longwave or shortwave spectral range to handle and
-continuously sampling a wavelength in this range. Actually longwave and
-shortwave are keywords that mean that the source of radiation is whether
-external or internal to the medium, respectively. In shortwave rendering, only
-the pixel radiance is evaluated and stored in the output image. For longwave
-rendering this estimated radiance is then converted to its brightness
-temperature and both are saved in the image. When computing a flux map (*-p*
-_rectangle_), the per pixel flux is saved into the output map whether spectral
-domain is longwave or shortwave.
-
-In *htrdr-atmosphere* the spatial unit 1.0 corresponds to one meter and the
-temperatures are expressed in Kelvin. The estimated radiances are given in
-W/sr/m^2 excepted for monochromatic computations where the computed spectral
-radiance is defined in W/sr/m^2/nm. The flux densities are saved in W/m^2. The
-results are written to the output file if the *-o* option is defined and the
-standard output otherwise. The output image is a list of raw ASCII data
-formatted with respect to the *htrdr-image*(5) file format.
-
-*htrdr-atmosphere* supports shared memory parallelism and relies on the Message
-Passing Interface specification [4] to parallelise its computations in a
-distributed memory environment; it can thus be run either directly or through a
-MPI process launcher like *mpirun*(1).
-
-OPTIONS
--------
-*-a* _atmosphere_::
- Path toward the file containing the gas optical properties of the atmosphere.
- Data must be formatted according to the fileformat described in [2].
-
-*-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
- are taken into account.
-
-*-C* <__camera-parameter__:...>::
- Define a perspective camera. Available parameters are:
-
- **focal-dst**=**_dst_**;;
- Distance to focus on with a thin lens camera, that is, a camera whose
- *lens-radius* is not zero. The default focal distance is
- @HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOCAL_DST@ meter.
-
- **focal-length**=**_length_**;;
- Focal length of a camera lens. It is another way to control the field of
- view of a thin lens camera. By default, the field of view is directly set
- through the **fov** parameter.
-
- **fov**=**_angle_**;;
- Vertical field of view of the camera in
- ]@HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MIN@,
- @HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MAX@[ degrees. By
- default _angle_ is set to
- @HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOV@ degrees.
-
- **lens-radius**=**_radius_**;;
- Radius of the camera lens. A non-zero radius means that the camera is a
- thin lens camera while a zero radius defines a pinhole camera. By default
- the lens radius is @HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_LENS_RADIUS@.
-
- **pos**=**_x_**,**_y_**,**_z_**;;
- Camera lens position. By default it is set to
- {@HTRDR_ARGS_DEFAULT_CAMERA_POS@}.
-
- **tgt**=**_x_**,**_y_**,**_z_**;;
- Position targeted by the camera. By default it is set to
- {@HTRDR_ARGS_DEFAULT_CAMERA_TGT@}.
-
- **up**=**_x_**,**_y_**,**_z_**;;
- Up vector of the camera. By default it is set to
- {@HTRDR_ARGS_DEFAULT_CAMERA_UP@}.
-
-*-D* <__azimuth__,__elevation__>::
- Direction toward the sun center. The direction is defined by two angles in
- degrees: the __azimuth__ angle in [0, 360[ and the __elevation__ angle in [0,
- 90]. Following the right-handed convention, the azimuthal rotation is
- counter-clockwise, with 0 degree on the X axis. The elevation starts from 0
- degree for a direction in the XY plane, up to 90 degrees at zenith. Thus
- -D0,0 -D90,0 -D180,0 and -D270,0 will produce solar vectors {+1,0,0} {0,+1,0}
- {-1,0,0} and {0,-1,0} respectively, while -D__azimuth__,90 will produce
- {0,0,+1} regardless of _azimuth_ value.
-
-*-d*::
- Write in _output_ the space partitioning data structures used to speed up
- the radiative transfer computations in the clouds. The written data are
- octrees saved in the VTK file format [3]. Each octree node stores the minimum
- and the maximum of the extinction coefficients of the cloud cells overlapped
- by the octree node. In the _output_ file, each octree is separated from the
- previous one by a line with three minus characters, i.e. '---'.
-
-*-f*::
- Force overwrite of the _output_ file.
-
-*-g* _ground_::
- Path toward a *htrdr-obj*(5) representing the ground geometry.
-
-*-h*::
- List short help and exit.
-
-*-i* <__image-parameter__:...>::
- Define the sensor array. Available image parameters are:
-
- **def**=**_width_**x**_height_**;;
- Definition of the image. By default the image definition is
- @HTRDR_ARGS_DEFAULT_IMG_WIDTH@x@HTRDR_ARGS_DEFAULT_IMG_HEIGHT@.
-
- **spp**=**_samples-count_**;;
- Number of samples per pixel estimation. In regular image rendering, a pixel
- will use "3 * _samples-count_" Monte-Carlo realisations, one set of
- _samples-count_ realisations for each X, Y and Z component of the CIE 1931
- XYZ color space. In shortwave/longwave rendering or flux computation, only
- one set of _samples-count_ is used. By default, *spp* is set to
- @HTRDR_ARGS_DEFAULT_IMG_SPP@.
-
-*-R*::
- Infinitely repeat the _ground_ along the X and Y axis.
-
-*-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.
-
-*-n* _sky-mtl_::
- Name of the material representing the sky in the *htrdr-materials*(5) file.
- By default, _sky-mtl_ is @HTRDR_ATMOSPHERE_ARGS_DEFAULT_SKY_MTL_NAME@.
-
-*-O* _cache_::
- File used to cache the sky data. If the _cache_ file does not exists, it is
- created and filled with the sky data built from the _clouds_, the
- _atmosphere_ and the _mie_ input files. This cached data can then be reused
- in the next runs as long as the input files provided on the command are the
- same as the ones used to setup the cache; leading to a significant speed-up
- of the pre-processing step. If _cache_ contains data generated from input
- files that are not the ones submitted on the command line, an error is
- notified and the execution is stopped, avoiding the use of wrong cached data.
- Note that when the cache is used, *htrdr-atmosphere* ignores the arguments
- used to parametrise the structures partitioning the sky data, i.e. the *-T*
- and *-V* options.
-
-*-o* _output_::
- File where *htrdr-atmosphere* writes its _output_ data. If not defined, write
- results to standard output.
-
-*-P* <__camera-parameter__:...>::
- Define an orthographic camera. Available parameters are:
-
- **height**=**_radius_**;;
- Height of the image plane. By default it is set to
- @HTRDR_ARGS_DEFAULT_CAMERA_ORTHOGRAPHIC_HEIGHT@.
-
- **pos**=**_x_**,**_y_**,**_z_**;;
- Camera lens position. By default it is set to
- {@HTRDR_ARGS_DEFAULT_CAMERA_POS@}.
-
- **tgt**=**_x_**,**_y_**,**_z_**;;
- Position targeted by the camera. By default it is set to
- {@HTRDR_ARGS_DEFAULT_CAMERA_TGT@}.
-
- **up**=**_x_**,**_y_**,**_z_**;;
- Up vector of the camera. By default it is set to
- {@HTRDR_ARGS_DEFAULT_CAMERA_UP@}.
-
-*-p* <__rectangle-parameter__:...>::
- Switch in flux map computation. The flux is computed for the part of the
- sensor that is outside any geometry. The rectangular sensor onto which the
- flux is integrated is defined by the following parameters:
-
- **pos**=**_x_**,**_y_**,**_z_**;;
- Position of the center of the rectangle. By default it is set to
- {@HTRDR_ARGS_DEFAULT_RECTANGLE_POS@}.
-
- **tgt**=**_x_**,**_y_**,**_z_**;;
- Position targeted by the rectangle, i.e. *tgt* - *pos* is the rectangle
- normal. By default it is set to {@HTRDR_ARGS_DEFAULT_RECTANGLE_TGT@}.
-
- **up**=**_x_**,**_y_**,**_z_**;;
- Up vector of the rectangle. By default it is set to
- {@HTRDR_ARGS_DEFAULT_RECTANGLE_UP@}.
-
- **sz**=**_width_**,**_height_**;;
- Size of the rectangle. By default it is set to
- {@HTRDR_ARGS_DEFAULT_RECTANGLE_SZ@}.
-
-*-s* <__spectral-parameter__:...>::
- Define the type and the range of the spectral integration. Available spectral
- parameters are:
-
- **cie_xyz**;;
- the radiance is computed for the visible part of the spectrum in [380, 780]
- nanometers with respect to the XYZ CIE 1931 tristimulus values. This is the
- default comportment of *htrdr-atmosphere*.
-
- **lw**=*_wlen-min_*,*_wlen-max_*;;
- perform the spectral sampling continuously in the [_wlen-min_, _wlen-max_]
- wavelength range (wavelength must be provided in nanometers) according to
- the Planck function for a reference temperature. If _wlen-min_ and
- _wlen-max_ are equals the computation is monochromatic. *lw* means for
- longwave but is here a code word that really means "computation of radiance
- using the internal source of radiation": in other words, radiation is
- emitted by the medium and its boundaries (ground and space). Because the
- application is for the terrestrial atmosphere, internal radiation is
- emitted in the thermal longwave part of the electromagnetic spectrum.
- Therefore the default value of the reference temperature used in the
- spectral sampling is fixed at 290 K.
-
- **sw**=*_wlen-min_*,*_wlen-max_*;;
- perform the spectral sampling continuously in the [_wlen-min_, _wlen-max_]
- wavelength range (wavelength must be provided in nanometers) according to
- the Planck function for a reference temperature. If _wlen-min_ and
- _wlen-max_ are equals the computation is monochromatic. In the present
- case, *sw* means that the source of radiation is external to the medium:
- because the application is for the terrestrial atmosphere, the value of the
- reference temperature is by default fixed at 5778 K, i.e. the blackbody
- temperature of the Sun.
-
- **Tref**=**_temperature_**;;
- reference temperature of the Planck function used to continuously sample the
- longwave/shortwave spectral range. In longwave, it is set to 290 K by
- default while in shortwave its default value is the blackbody temperature
- of the sun (i.e. 5778 K).
-
-*-T* _threshold_::
- Optical thickness used as threshold criteria to partition the properties of
- the clouds. By default its value is
- @HTRDR_ATMOSPHERE_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
- cores.
-
-*-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. This option is ignored if a cache
- file is used (option *-O*).
-
-*-v*::
- Make *htrdr-atmosphere* verbose.
-
-OUTPUT IMAGE
-------------
-
-Images calculated by *htrdr-atmosphere* are saved in the *htrdr-image*(5) file
-format. This section describes the nature and arrangement of image data
-depending on the type of calculation performed by *htrdr-atmosphere*.
-
-XYZ image
-~~~~~~~~~
-
-For an image rendering in the visible part of the spectrum (default behavior or
-*-s cie_xyz* option), the pixel components store 4 estimates. The first,
-second, and third pairs of floating point values encode the estimated
-integrated radiance in W/sr/m^2 for the X, Y, and Z components of the CIE
-1931 XYZ color space. The first value of each pair is the expected value of the
-average radiance of the pixel. The second value is its associated standard
-deviation. The fourth and final pair records the microsecond estimate of the
-computation time per radiative path and its standard error.
-
-Longwave image
-~~~~~~~~~~~~~~
-
-If the image is an infrared rendering (option *-s* *lw*=_wlen-min_,_wlen-max_)
-the first and second pixel components store the expected value and the standard
-error of the estimated brightness temperature (in K), respectively. The third
-and fourth components record the expected value and the standard deviation of
-the pixel radiance which is either an integrated radiance in W/sr/m^2 or a
-spectral radiance in W/sr/m^2/nm depending on whether this radiance was
-calculated for a spectral range or at a single wavelength. The fifth and sixth
-pixel components are not used. Finally, the last 2 components of the pixel
-record the estimate in microseconds of the computation time per radiative path
-and its standard error.
-
-Shortwave image
-~~~~~~~~~~~~~~~
-
-For shortwave renderings (option *-s* *sw*=_wlen-min_,_wlen-max_), the data
-written to the output image are formatted as for a longwave image except
-that the first and second components of the pixels are not used because no
-brightness temperature has been evaluated.
-
-Flux density map (shortwave and longwave)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A flux density map (option *-p*) is saved in an *htrdr-image*(5) storing the
-expected value and the standard error of the pixel radiative flux density (in
-W/m^2) on its first and second component. All other components are unused
-excepted the seventh and eighth components that store the estimate of the
-radiative path computation time in microseconds and its standard error.
-
-EXAMPLES
---------
-
-Render a clear sky scene, i.e. a scene without any cloud, whose sun is at
-zenith. The vertical atmospheric gaz mixture along the Z axis is described in
-the *gas.txt* file. The ground geometry is a quad repeated to the infinity
-whose materials are listed in the *material.mtl* file. The camera is positioned
-at *400* meters height and looks toward the positive Y axis. The definition of
-the rendered image is *800* by *600* pixels and the radiance of each pixel
-component is estimated with *64* Monte-Carlo realisations. The resulting image
-is written to *output* excepted if the file already exists; in this case an
-error is notified, the program stops and the *output* file remains unchanged:
-
- $ htrdr-atmosphere -D0,90 -a gas.txt -m Mie.nc -g quad.obj -R \
- -M materials.mtl \
- -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
- -i def=800x600:spp=64 \
- -o output
-
-Add clouds to the previous scene and use a more complex geometry to represent
-the ground. The Mie data are provided through the *Mie.nc* file. The ground
-geometry was carefully designed to be cyclic and can be thus infinitely
-repeated without visual glitches. Use the *-f* option to write the rendered
-image to *output* even though the file already exists. Finally, use the
-*htpp*(1) command to convert the *htrdr-image*(5) saved in output in a regular
-PPM image [5]:
-
- $ htrdr-atmosphere -D0,90 -a gas.txt -m Mie.nc -g mountains.obj -R \
- -M materials.mtl \
- -c clouds.htcp \
- -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
- -i def=800x600:spp=64 \
- -f -o output
- $ htpp -o image.ppm output
-
-Render the previous scene in infrared for the wavelengths in [*9200*, *10000*]
-nanometers with a reference temperature of *300* Kelvin:
-
- $ htrdr-atmosphere -a gas.txt -m Mie.nc -g mountains.obj -R \
- -M materials.mtl \
- -c clouds.htcp \
- -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
- -i def=800x600:spp=64 \
- -s lw=9200,10000:Tref=300 \
- -f -o output
-
-Move the sun by setting its azimuthal and elevation angles to *120* and *40*
-degrees respectively. Use the *-O* option to enable the cache mechanism on
-sky data. Increase the image definition to *1280* by *720* and set the
-number of samples per pixel component to *1024*. Write results on standard
-output and convert the resulting image in PPM before visualising it through the
-*feh*(1) image viewer:
-
- $ htrdr-atmosphere -D120,40 -a gas.txt -m Mie.nc -g mountains.obj -R \
- -M materials.mtl \
- -c clouds.htcp \
- -O my_cache \
- -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
- -i def=1280x720:spp=1024 | htpp | feh -
-
-Compute the downward flux for the shortwave interval [*350*, *4000*] nanometers
-on a square of *100* meters side positionned at the origin at *1* meter height.
-The resolution of the flux map is *500* by *500* pixels and *1000* realisations
-is used to estimate the flux per pixel. It is saved in the *flux_map.txt* file
-even though this file already exists:
-
- $ htrdr-atmosphere -D0,90 -a gas.txt -m Mie.nc -g plane.obj -R \
- -M materials.mtl \
- -c clouds.htcp \
- -O my_cache \
- -p pos=0,0,1:tgt=0,0,2:up=0,1,0:sz=100,100 \
- -i def=500x500:spp=1000 \
- -s sw=350,4000 \
- -f -o flux_map.txt
-
-Write into *output* the data structures used to partition the clouds
-properties. Use the *csplit*(1) Unix command to extract from *output* the list
-of the generated grids and save each of them in a specific VTK file whose name
-is *cloud_grid_*<__NUM__>*.vtk with __NUM__ in [0, N-1] where N is the number
-of grids written into *output*:
-
- $ htrdr-atmosphere -a gas.txt -m Mie.nc -c clouds.htcp -d -f -o output
- $ csplit -f cloud_grid_ -b %02d.vtk -z --suppress-matched output /^---$/ {*}
-
-Use *mpirun*(1) to launch *htrdr-atmosphere* on several hosts defined in the
-*my_hosts* file. Make the clouds infinite along the X and Y axis:
-
- $ mpirun --hostfile my_hosts htrdr-atmosphere \
- -D120,40 -a gas.txt -m Mie.nc -g mountains.obj -R \
- -M materials.mtl \
- -c clouds.htcp -r \
- -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
- -i def=1280x720:spp=1024 \
- -f -o output
-
-NOTES
------
-
-1. A path-tracing Monte Carlo library for 3-D radiative transfer in highly
-resolved cloudy atmospheres. N. Villefranque et al, JAMES 11, 2449-2473, 2019 -
-<https://doi.org/10.1029/2018MS001602>
-
-2. High-Tune: Gas Optical Properties file format -
-<https://www.meso-star.com/projects/high-tune/downloads/gas_opt_prop_en.pdf>
-
-3. VTK file format -
-<http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf>
-
-4. MPI specifications - <https://www.mpi-forum.org/docs/>
-
-5. Portable PixMap - <http://netpbm.sourceforge.net/doc/ppm.html>
-
-COPYRIGHT
----------
-Copyright © 2018, 2019, 2020, 2021 |Meso|Star> <contact@meso-star.com>.
-
-Copyright © 2018, 2019, 2021 CNRS
-
-Copyright © 2018, 2019 Université Paul Sabatier
-<contact-edstar@laplace.univ-tlse.fr>.
-
-LICENSE
--------
-
-*htrdr-atmosphere* is free software released under the GPLv3+ license: GNU GPL
-version 3 or later <https://gnu.org/licenses/gpl.html>. You are free to change
-and redistribute it. There is NO WARRANTY, to the extent permitted by law.
-
-SEE ALSO
---------
-*csplit*(1),
-*feh*(1),
-*mpirun*(1),
-*htcp*(5),
-*htmie*(5),
-*htpp*(1),
-*htrdr*(1),
-*htrdr-image*(5),
-*htrdr-materials*(5)
-*htrdr-obj*(5)
diff --git a/doc/htrdr-combustion.1.scd.in b/doc/htrdr-combustion.1.scd.in
@@ -0,0 +1,450 @@
+htrdr-combustion(1)
+
+; Copyright (C) 2018, 2019, 2020, 2021 |Meso|Star> (contact@meso-star.com)
+; Copyright (C) 2018, 2019, 2021 CNRS
+; Copyright (C) 2018, 2019 Université Paul Sabatier
+; (contact-edstar@laplace.univ-tlse.fr)
+;
+; 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/>.
+
+
+# NAME
+
+htrdr-combustion - simulate radiative transfer in combustion medium
+
+# SYNOPSIS
+
+htrdr-combustion [_option_]... -m _tetrahedra_ -p _thermoprops_ -r _refract_ids_
+
+# DESCRIPTION
+
+The purpose of *htrdr-combustion* is to perform radiative transfer computations
+in a scene representing a semi-transparent medium enlightened by a laser sheet.
+The combustion medium may be surrounded by solid boundaries (inner limits of
+the combustion chamber). The program will currently compute, in the visible at
+a given frequency, the monochromatic image or the radiative flux density of the
+combustion medium: collected light comes from the laser, and is scattered by
+soot aggregates within the flame before eventually reaching the sensor.
+
+Data about the gaseous medium have to be provided on the vertices of a
+unstructured tetrahedral mesh: pressure, temperature and concentrations of H2O,
+CO2 and CO have to be provided for every spatial position used to define this
+mesh. These data have to be provided in anticipation of future developments for
+the longwave range: since the gas is assumed to be transparent in the visible,
+it is not currently used.
+
+Soot optical properties are computed using the Rayleigh-Debye Gans theory, for
+Fractal Aggregates (RDG-FA) [1]. This requires the knowledge of: soot volumic
+fraction, soot number density (number of primary particles per aggregate) and
+primary particles diameter, over each vertex of the tetrahedron mesh. For any
+position in the volume, these quantities are first interpolated from the values
+retrieved at the nodes of the current tetrahedron, and are then interpolated
+for the position of interest. Which then makes possible to compute the
+absorption and scattering cross-sections of soot aggregates, as well as their
+scattering function.
+
+The Monte-Carlo algorithm that accounts for the visible intensity is inspired
+from the algorithm used for solar radiation in the *htrdr-atmosphere*(1)
+command. It was adapted to partially illuminated scenes in order to solve
+convergence issues. The algorithm is presented in the following article:
+"Null-collision meshless Monte-Carlo - a new reverse Monte-Carlo algorithm
+designed for laser-source emission in absorbing/scattering inhomogeneous
+media". M. Sans et al, JQSRT, 2021 [2].
+
+In *htrdr-combustion* the spatial unit 1.0 corresponds to one meter while the
+estimated monochromatic radiances and flux densities are saved in W/sr/m² and
+W/m² respectively. Computed images are stored in the *htrdr-image*(5) file
+format.
+
+*htrdr-combustion* implements a mixed parallelism: on one computer (i.e. a
+node) it uses a shared memory parallelism, and it relies on the message passing
+interface [4] to parallelize the computations between several nodes. We can
+thus launch *htrdr-combustion* either directly, or via a process launcher
+like *mpirun*(1) to distribute the rendering over several nodes.
+
+# OPTIONS
+
+*-C* <_camera-parameter_:...>
+ Define the camera. Available parameters are:
+
+ *focal-dst*=_dst_
+ Distance to focus on with a thin lens camera, that is, a camera whose
+ *lens-radius* is not zero. The default focal distance is
+ @HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOCAL_DST@ meter.
+
+ *focal-length*=_length_
+ Focal length of a camera lens. It is another way to control the field of
+ view of a thin lens camera. By default, the field of view is directly set
+ through the **fov** parameter.
+
+ *fov*=_angle_
+ Vertical field of view of the camera in
+ \]@HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MIN@,
+ @HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MAX@[ degrees. By
+ default _angle_ is set to
+ @HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOV@ degrees.
+
+ *lens-radius*=_radius_
+ Radius of the camera lens. A non-zero radius means that the camera is a thin
+ lens camera while a zero radius defines a pinhole camera. By default the
+ lens radius is @HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_LENS_RADIUS@.
+
+ *pos*=_x_,_y_,_z_
+ Camera lens position. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_CAMERA_POS@}.
+
+ *tgt*=_x_,_y_,_z_
+ Position targeted by the camera. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_CAMERA_TGT@}.
+
+ *up*=_x_,_y_,_z_
+ Up vector of the camera. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_CAMERA_UP@}.
+
+*-D* _flux_density_
+ Flux density of the laser in W/m². By default it is set to
+ @HTRDR_COMBUSTION_ARGS_DEFAULT_LASER_FLUX_DENSITY@.
+
+*-d* <_laser_|_octree_>
+ When define with the _laser_ argument, write in _output_ the geometry of the
+ laser sheet saved in the VTK file format [3]. With the _octree_ argument,
+ write in _output_ a VTK file that stores the octree leaves of the space
+ partitioning data structure used to speed up the radiative transfer
+ computations in the combustion medium. Each leaf stores the minimum and the
+ maximum of the extinction coefficients of the tetrahedra that the leaf
+ overlaps.
+
+*-F* <_fractal-coefficients_:...>
+ Fractal parameters of the RDG-FA model. This option disable the *-I* option
+ if it was previously set. Available fractal coefficients are:
+
+ *dimension*=_real_
+ Fractal dimension. By default it is set to
+ @HTRDR_COMBUSTION_ARGS_DEFAULT_FRACTAL_DIMENSION@.
+
+ *prefactor*=_real_
+ Fractal prefactor. By default it is set to
+ @HTRDR_COMBUSTION_ARGS_DEFAULT_FRACTAL_PREFACTOR@.
+
+*-f*
+ Force overwrite of the _output_ file.
+
+*-g* <_geometry-parameter_:...>
+ Define the geometry of the combustion chamber. Note that this geometry does
+ not prevent the camera from viewing the medium or the laser from illuminating
+ it, even if they are outside the combustion chamber. The rendering algorithm
+ ensures that they are not occluded by this geometry like with a two-way
+ mirror. When the laser is out of geometry, its emissive surface is seen as if
+ it were following the interior surface of the chamber. Likewise, the radiance
+ seen by the camera outside the chamber is the radiance that reaches it as if
+ its image plane were following the surface of the geometry. Available
+ geometry parameters are:
+
+ *mats*=_materials_
+ Path to the *htrdr-materials*(5) that defines the media and materials used
+ by the combustion chamber geometry.
+
+ *obj*=_mesh_
+ Path to the *htrdr-obj*(5) file that represents the mesh of the combustion
+ chamber. Following the *htrdr-obj*(5) fileformat, the interface of the
+ submitted mesh must be defined as a thin interface, i.e. it must be composed
+ of 3 components separated by the ':' character. By convention,
+ *htrdr-combustion* expects the outside environment to be called "air" and
+ the medium inside the combustion chamber to be called "chamber". No
+ assumption is made on the name of the surface material excepted that it has
+ to reference a valid material.
+
+*-h*
+ List short help and exit.
+
+*-I*
+ Use an isotropic phase function rather than the RDG-FA model.
+
+*-i* <_image-parameter_:...>
+ Define the sensor array. Available image parameters are:
+
+ *def*=<_width_>x<_height_>
+ Definition of the image. By default the image definition is
+ @HTRDR_ARGS_DEFAULT_IMG_WIDTH@x@HTRDR_ARGS_DEFAULT_IMG_HEIGHT@.
+
+ *spp*=_samples-count_
+ Number of samples per pixel estimation. By default, *spp* is set to
+ @HTRDR_ARGS_DEFAULT_IMG_SPP@.
+
+*-l* <_laser-parameter_:...>
+ Define the laser surface emission. Available laser parameters are:
+
+ *pos*=_x_,_y_,_z_
+ Position of the center of the surface emission. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_RECTANGLE_POS@}.
+
+ *tgt*=_x_,_y_,_z_
+ Position targeted by the laser, i.e. *tgt* - *pos* is normal of the laser
+ surface. By default it is set to {@HTRDR_ARGS_DEFAULT_RECTANGLE_TGT@}.
+
+ *up*=_x_,_y_,_z_
+ Up vector of the laser surface. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_RECTANGLE_UP@}.
+
+ *sz*=_width_,_height_
+ Size of the laser surface. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_RECTANGLE_SZ@}.
+
+*-m* _tetrahedra_
+ Path to the *smsh*(5) file that stores the volumetric mesh of the combustion
+ medium.
+
+*-N*
+ Precompute the normals of the tetrahedra. This option should speed up the
+ computation since the normals are computed once per tetrahedron rather than
+ reevaluated each time a tetrahedron is queried at a given position. On the
+ other hand, the storage required by these normals increases the memory
+ footprint.
+
+*-O* _cache_
+ Path to the file used to cache the acceleration structure that partitions the
+ combustion medium. If the _cache_ file does not exist, it is created and
+ populated with the octree built from the _tetrahedra_, _thermoprops_ and
+ _refract_ids_ input files. This cached acceleration structure can then be
+ reused in future runs as long as the input data provided on the command line
+ is the same as that used to configure the cache; leading to a significant
+ acceleration of the pretreatment step. If _cache_ contains data generated
+ from input data that is not that submitted on the command line, an error is
+ notified and execution is stopped, thus avoiding the use of bad cached data.
+
+*-o* _output_
+ Path to the file where *htrdr-combustion* writes the output data. If not set,
+ data is written to standard output.
+
+*-P* <_camera-parameter_:...>
+ Define an orthographic camera. Available parameters are:
+
+ *height*=_radius_
+ Height of the image plane. By default it is set to
+ @HTRDR_ARGS_DEFAULT_CAMERA_ORTHOGRAPHIC_HEIGHT@.
+
+ *pos*=_x_,_y_,_z_
+ Camera lens position. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_CAMERA_POS@}.
+
+ *tgt*=_x_,_y_,_z_
+ Position targeted by the camera. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_CAMERA_TGT@}.
+
+ *up*=_x_,_y_,_z_
+ Up vector of the camera. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_CAMERA_UP@}.
+
+*-p* _thermprops_
+ Path to the *atrtp*(5) file that stores the thermodynamic properties of the
+ combustion medium.
+
+*-R* <_rectangle-parameter_:...>
+ Compute a radiatve flux density map rather than an image. The rectangular
+ sensor onto which the flux is integrated is defined by the following
+ parameters:
+
+ *pos*=_x_,_y_,_z_
+ Position of the center of the rectangle. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_RECTANGLE_POS@}.
+
+ *tgt*=_x_,_y_,_z_
+ Position targeted by the rectangle, i.e. *tgt* - *pos* is the rectangle
+ normal. By default it is set to {@HTRDR_ARGS_DEFAULT_RECTANGLE_TGT@}.
+
+ *up*=_x_,_y_,_z_
+ Up vector of the rectangle. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_RECTANGLE_UP@}.
+
+ *sz*=_width_,_height_
+ Size of the rectangle. By default it is set to
+ {@HTRDR_ARGS_DEFAULT_RECTANGLE_SZ@}.
+
+*-r* _refract_ids_
+ Path the the *atrri*(5) file that lists the spectrally varying refractive
+ indices of the combustion medium.
+
+*-s*
+ Use of Single Instruction, Multiple Data (SIMD) instruction sets if
+ available. This should speed up the computation time.
+
+*-T*
+ Optical thickness used as threshold criteria to build the acceleration
+ structure the combustion medium. By default its value is
+ @HTRDR_COMBUSTION_ARGS_DEFAULT_OPTICAL_THICKNESS_THRESHOLD@.
+
+*-t* _threads-count_
+ Hint on the number of threads to use. By default use as many threads as CPU
+ cores.
+
+*-V* <_definition_>
+ definition of the grid of the upper bound field of radiative coefficients
+ from which the volumetric acceleration structure is built. The grid extent
+ corresponds to the axis aligned bounding box of the volumetric mesh
+ representing the combustion medium. Grid definition can be set in two ways:
+
+ _x_,_z_,_z_
+ Explicitly set the grid definition along the X, Y, and Z extents.
+
+ _hint_
+ Provide an hint on the expected definition of the grid along its major
+ extent. The definition along the two remaining axes are then internally
+ computed. This is the default comportment with an _hint_ set to
+ @HTRDR_COMBUSTION_ARGS_DEFAULT_GRID_DEFINITION_HINT@.
+
+*-v*
+ Make *htrdr-combustion* verbose.
+
+*-w*
+ Define the wavelength of the laser in nanometre. By default it is set to
+ @HTRDR_COMBUSTION_ARGS_DEFAULT_WAVELENGTH@.
+
+# OUTPUT IMAGE
+
+Images calculated by *htrdr-combustion* are saved in the *htrdr-image*(5) file
+format. This section describes the nature and arrangement of image data
+depending on the type of calculation performed by *htrdr-combustion*.
+
+## Shortwave monochromatic image
+
+For a monochromatic image rendering, the expected value and the standard
+deviation of the pixel radiance (in W/sr/m²) are saved on the first and the
+second components. All other components are unused excepted the seventh and
+eighth components that store the estimate of the radiative path computation
+time in microseconds and its standard error.
+
+## Shortwave flux density map
+
+A flux density map (option *-R*) is saved in an *htrdr-image*(5) storing the
+expected value and the standard error of the pixel radiative flux density (in
+W/m²) on its first and second component. All other components are unused
+excepted the seventh and eighth components that store the estimate of the
+radiative path computation time in microseconds and its standard error.
+
+# EXAMPLES
+
+Make htrdr-combustion verbose (option *-v*) and render an image of a combustion
+medium whose tetrahedral mesh is stored in _tetra.smsh_ and its associated
+thermodynamic properties are saved in _thermprops.atrtp_. The spectrally
+varying indices of the medium are listed in the _refract_ids.atrri_ file. The
+center of the laser surface emission is positioned at the origin and its
+direction is aligned to the Y axis. The definition of the rendered image is
+_800_ by _600_ pixels and the monochromatic radiance of each pixel is estimated
+at _500_ nanometre with _64_ Monte-Carlo realisations. The resulting image is
+written to _output_ excepted if it already exists; in this case an
+error is notified, the program stops and the _output_ file remains unchanged.
+
+```
+htrdr-combustion -v \
+ -m tetra.smsh \
+ -p thermprops.atrtp \
+ -r refract_ids.atrri \
+ -l pos=0,0,0:tgt=0,1,0:up=0,0,1:sz=0.001,0.2 \
+ -w 500 \
+ -C pos=0.06,0,0.01:tgt=0.05,0,0.01:up=0,0,1:fov=30 \
+ -i def=800x600:spp=64 \
+ -o output
+```
+
+Add a combustion chamber to the previous example: its mesh is defined in
+_chamber.obj_ while its materials are listed in _materials.mtls_. Save the
+volumetric acceleration structure in _octree.cache_ or reused it if it was
+already populated in a previous run with compatible input data. Set the finest
+resolution of this acceleration structure to _1000_ along the major extend of the
+medium and use a optical thickness criterion of _5_ to build it. Use the *-f*
+option to force the overwrite of the _output_ file if it exists and use *-s* to
+speed up the rendering with the available SIMD instruction sets.
+
+```
+htrdr-combustion -v \
+ -m tetra.smsh \
+ -p thermprops.atrtp \
+ -r refract_ids.atrri \
+ -g obj=chamber.obj:mats=materials.mtls \
+ -l pos=0,0,0:tgt=0,1,0:up=0,0,1:sz=0.001,0.2 \
+ -w 500 \
+ -C pos=0.06,0,0.01:tgt=0.05,0,0.01:up=0,0,1:fov=30 \
+ -i def=800x600:spp=64 \
+ -O octree.cache \
+ -V 1000 \
+ -T 5 \
+ -o output -f -s
+```
+
+Compute a flux density map whose definition is _500_ by _500_ pixels. The flux
+density per pixel is estimated with _64_ realisations; the flux density for the
+entire sensor is thus calculated with 16 million realisations (500 \* 500
+\* 64). The sensor on which the flux density is calculated is a square with
+sides measuring _0.05_ meter. Its center is positioned at the origin and points
+to the Z axis.
+
+```
+htrdr-combustion -v \
+ -m tetra.smsh \
+ -p thermprops.atrtp \
+ -r refract_ids.atrri \
+ -l pos=0,0,0:tgt=0,1,0:up=0,0,1:sz=0.001,0.2 \
+ -w 500 \
+ -R pos=0,0,0:tgt=0,0,1:up=0,1,0:sz=0.05,0.05 \
+ -i def=500x500:spp=64 \
+ -O octree.cache \
+ -V 1000 \
+ -T 5 \
+ -o map.txt -f -s
+```
+
+Write into _octree.vtk_ a representation of the volumetric acceleration
+structure.
+
+```
+htrdr-combustion -v \
+ -m tetra.smsh \
+ -p thermprops.atrtp \
+ -r refract_ids.atrri \
+ -O octree.cache \
+ -d octree -o octree.vtk
+```
+
+# COPYRIGHT
+
+Copyright © 2018, 2019, 2020, 2021 |Méso|Star> <contact@meso-star.com>++
+Copyright © 2018, 2019, 2021 Centre National de la Recherche Scientifique++
+Copyright © 2018, 2019 Université Paul Sabatier <contact-edstar@laplace.univ-tlse.fr>
+
+# LICENSE
+
+*htrdr-combustion* is free software released under the GPLv3+ license: GNU GPL
+version 3 or later <https://gnu.org/licenses/gpl.html>. You are free to change
+and redistribute it. There is NO WARRANTY, to the extent permitted by law.
+
+# SEE ALSO
+
+. Effects of multiple scattering on radiative properties of soot
+ fractal aggregates. J. Yon et al, JQSRT 133, 374-381, 2014 -
+ <https://doi.org/10.1016/j.jqsrt.2013.08.022>
+. Null-collision meshless Monte-Carlo - a new reverse Monte-Carlo algorithm
+ designed for laser-source emission in absorbing/scattering inhomogeneous media. M.
+ Sans et al, JQSRT, 2021 - <https://doi.org/10.1016/j.jqsrt.2021.107725>
+. VTK file format -
+ <http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf>
+. MPI specifications - <https://www.mpi-forum.org/docs/>
+
+*atrtp*(5),
+*atrri*(5),
+*htrdr-atmosphere*(1),
+*htrdr-image*(5),
+*htrdr-obj*(5),
+*htrdr-materials*(5),
+*mpirun*(1),
+*smsh*(5)
diff --git a/doc/htrdr-combustion.1.txt.in b/doc/htrdr-combustion.1.txt.in
@@ -1,459 +0,0 @@
-// Copyright (C) 2018, 2019, 2020, 2021 |Meso|Star> (contact@meso-star.com)
-// Copyright (C) 2018, 2019, 2021 CNRS
-// Copyright (C) 2018, 2019 Université Paul Sabatier
-// (contact-edstar@laplace.univ-tlse.fr)
-//
-// 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-combustion(1)
-===================
-
-NAME
-----
-htrdr-combustion - simulate radiative transfer in combustion medium
-
-SYNOPSIS
---------
-[verse]
-*htrdr-combustion* [_option_]... -m _tetrahedra_ -p _thermoprops_ -r _refract_ids_
-
-DESCRIPTION
------------
-The purpose of *htrdr-combustion* is to perform radiative transfer computations
-in a scene representing a semi-transparent medium enlightened by a laser sheet.
-The combustion medium may be surrounded by solid boundaries (inner limits of
-the combustion chamber). The program will currently compute, in the visible at
-a given frequency, the monochromatic image or the radiative flux density of the
-combustion medium: collected light comes from the laser, and is scattered by
-soot aggregates within the flame before eventually reaching the sensor.
-
-Data about the gaseous medium have to be provided on the vertices of a
-unstructured tetrahedral mesh: pressure, temperature and concentrations of H2O,
-CO2 and CO have to be provided for every spatial position used to define this
-mesh. These data have to be provided in anticipation of future developments for
-the longwave range: since the gas is assumed to be transparent in the visible,
-it is not currently used.
-
-Soot optical properties are computed using the Rayleigh-Debye Gans theory, for
-Fractal Aggregates (RDG-FA) [1]. This requires the knowledge of: soot volumic
-fraction, soot number density (number of primary particles per aggregate) and
-primary particles diameter, over each vertex of the tetrahedron mesh. For any
-position in the volume, these quantities are first interpolated from the values
-retrieved at the nodes of the current tetrahedron, and are then interpolated
-for the position of interest. Which then makes possible to compute the
-absorption and scattering cross-sections of soot aggregates, as well as their
-scattering function.
-
-The Monte-Carlo algorithm that accounts for the visible intensity is inspired
-from the algorithm used for solar radiation in the *htrdr-atmosphere*(1)
-command. It was adapted to partially illuminated scenes in order to solve
-convergence issues. The algorithm is presented in the following article:
-"Null-collision meshless Monte-Carlo - a new reverse Monte-Carlo algorithm
-designed for laser-source emission in absorbing/scattering inhomogeneous
-media". M. Sans et al, JQSRT, 2021 [2].
-
-In *htrdr-combustion* the spatial unit 1.0 corresponds to one meter while the
-estimated monochromatic radiances and flux densities are saved in W/sr/m^2 and
-W/m^2 respectively. Computed images are stored in the *htrdr-image*(5) file
-format.
-
-*htrdr-combustion* implements a mixed parallelism: on one computer (i.e. a
-node) it uses a shared memory parallelism, and it relies on the message passing
-interface [4] to parallelize the computations between several nodes. We can
-thus launch *htrdr-combustion* either directly, or via a process launcher
-like *mpirun*(1) to distribute the rendering over several nodes.
-
-OPTIONS
--------
-
-*-C* <__camera-parameter__:...>::
- Define the camera. Available parameters are:
-
- **focal-dst**=**_dst_**;;
- Distance to focus on with a thin lens camera, that is, a camera whose
- *lens-radius* is not zero. The default focal distance is
- @HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOCAL_DST@ meter.
-
- **focal-length**=**_length_**;;
- Focal length of a camera lens. It is another way to control the field of
- view of a thin lens camera. By default, the field of view is directly set
- through the **fov** parameter.
-
- **fov**=**_angle_**;;
- Vertical field of view of the camera in
- ]@HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MIN@,
- @HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MAX@[ degrees. By
- default _angle_ is set to
- @HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOV@ degrees.
-
- **lens-radius**=**_radius_**;;
- Radius of the camera lens. A non-zero radius means that the camera is a
- thin lens camera while a zero radius defines a pinhole camera. By default
- the lens radius is @HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_LENS_RADIUS@.
-
- **pos**=**_x_**,**_y_**,**_z_**;;
- Camera lens position. By default it is set to
- {@HTRDR_ARGS_DEFAULT_CAMERA_POS@}.
-
- **tgt**=**_x_**,**_y_**,**_z_**;;
- Position targeted by the camera. By default it is set to
- {@HTRDR_ARGS_DEFAULT_CAMERA_TGT@}.
-
- **up**=**_x_**,**_y_**,**_z_**;;
- Up vector of the camera. By default it is set to
- {@HTRDR_ARGS_DEFAULT_CAMERA_UP@}.
-
-*-D* _flux_density_::
- Flux density of the laser in W/m^2. By default it is set to
- @HTRDR_COMBUSTION_ARGS_DEFAULT_LASER_FLUX_DENSITY@.
-
-*-d* <__laser__|__octree__>::
- When define with the _laser_ argument, write in _output_ the geometry of the
- laser sheet saved in the VTK file format [3]. With the _octree_ argument,
- write in _output_ a VTK file that stores the octree leaves of the space
- partitioning data structure used to speed up the radiative transfer
- computations in the combustion medium. Each leaf stores the minimum and the
- maximum of the extinction coefficients of the tetrahedra that the leaf
- overlaps.
-
-*-F* <__fractal-coefficients__:...>::
- Fractal parameters of the RDG-FA model. This option disable the *-I* option
- if it was previously set. Available fractal coefficients are:
-
- **dimension**=_real_;;
- Fractal dimension. By default it is set to
- @HTRDR_COMBUSTION_ARGS_DEFAULT_FRACTAL_DIMENSION@.
-
- **prefactor**=_real_;;
- Fractal prefactor. By default it is set to
- @HTRDR_COMBUSTION_ARGS_DEFAULT_FRACTAL_PREFACTOR@.
-
-*-f*::
- Force overwrite of the _output_ file.
-
-*-g* <__geometry-parameter__:...>::
- Define the geometry of the combustion chamber. Note that this geometry does
- not prevent the camera from viewing the medium or the laser from illuminating
- it, even if they are outside the combustion chamber. The rendering algorithm
- ensures that they are not occluded by this geometry like with a two-way
- mirror. When the laser is out of geometry, its emissive surface is seen as if
- it were following the interior surface of the chamber. Likewise, the radiance
- seen by the camera outside the chamber is the radiance that reaches it as if
- its image plane were following the surface of the geometry. Available
- geometry parameters are:
-
- **mats**=__materials__;;
- Path to the *htrdr-materials*(5) that defines the media and materials used
- by the combustion chamber geometry.
-
- **obj**=_mesh_;;
- Path to the *htrdr-obj*(5) file that represents the mesh of the combustion
- chamber. Following the *htrdr-obj*(5) fileformat, the interface of the
- submitted mesh must be defined as a thin interface, i.e. it must be
- composed of 3 components separated by the ':' character. By convention,
- *htrdr-combustion* expects the outside environment to be called "air" and
- the medium inside the combustion chamber to be called "chamber". No
- assumption is made on the name of the surface material excepted that it has
- to reference a valid material.
-
-*-h*::
- List short help and exit.
-
-*-I*::
- Use an isotropic phase function rather than the RDG-FA model.
-
-*-i* <__image-parameter__:...>::
- Define the sensor array. Available image parameters are:
-
- **def**=**_width_**x**_height_**;;
- Definition of the image. By default the image definition is
- @HTRDR_ARGS_DEFAULT_IMG_WIDTH@x@HTRDR_ARGS_DEFAULT_IMG_HEIGHT@.
-
- **spp**=**_samples-count_**;;
- Number of samples per pixel estimation. By default, *spp* is set to
- @HTRDR_ARGS_DEFAULT_IMG_SPP@.
-
-*-l* <__laser-parameter__:...>::
- Define the laser surface emission. Available laser parameters are:
-
- **pos**=**_x_**,**_y_**,**_z_**;;
- Position of the center of the surface emission. By default it is set to
- {@HTRDR_ARGS_DEFAULT_RECTANGLE_POS@}.
-
- **tgt**=**_x_**,**_y_**,**_z_**;;
- Position targeted by the laser, i.e. *tgt* - *pos* is normal of the laser
- surface. By default it is set to {@HTRDR_ARGS_DEFAULT_RECTANGLE_TGT@}.
-
- **up**=**_x_**,**_y_**,**_z_**;;
- Up vector of the laser surface. By default it is set to
- {@HTRDR_ARGS_DEFAULT_RECTANGLE_UP@}.
-
- **sz**=**_width_**,**_height_**;;
- Size of the laser surface. By default it is set to
- {@HTRDR_ARGS_DEFAULT_RECTANGLE_SZ@}.
-
-*-m* _tetrahedra_::
- Path to the *sth*(5) file that stores the volumetric mesh of the combustion
- medium.
-
-*-N*::
- Precompute the normals of the tetrahedra. This option should speed up the
- computation since the normals are computed once per tetrahedron rather than
- reevaluated each time a tetrahedron is queried at a given position. On the
- other hand, the storage required by these normals increases the memory
- footprint.
-
-*-O* _cache_::
- Path to the file used to cache the acceleration structure that partitions the
- combustion medium. If the _cache_ file does not exist, it is created and
- populated with the octree built from the _tetrahedra_, _thermoprops_ and
- _refract_ids_ input files. This cached acceleration structure can then be
- reused in future runs as long as the input data provided on the command line
- is the same as that used to configure the cache; leading to a significant
- acceleration of the pretreatment step. If _cache_ contains data generated
- from input data that is not that submitted on the command line, an error is
- notified and execution is stopped, thus avoiding the use of bad cached data.
-
-*-o* _output_::
- Path to the file where *htrdr-combustion* writes the output data. If not set,
- data is written to standard output.
-
-*-P* <__camera-parameter__:...>::
- Define an orthographic camera. Available parameters are:
-
- **height**=**_radius_**;;
- Height of the image plane. By default it is set to
- @HTRDR_ARGS_DEFAULT_CAMERA_ORTHOGRAPHIC_HEIGHT@.
-
- **pos**=**_x_**,**_y_**,**_z_**;;
- Camera lens position. By default it is set to
- {@HTRDR_ARGS_DEFAULT_CAMERA_POS@}.
-
- **tgt**=**_x_**,**_y_**,**_z_**;;
- Position targeted by the camera. By default it is set to
- {@HTRDR_ARGS_DEFAULT_CAMERA_TGT@}.
-
- **up**=**_x_**,**_y_**,**_z_**;;
- Up vector of the camera. By default it is set to
- {@HTRDR_ARGS_DEFAULT_CAMERA_UP@}.
-
-*-p* _thermprops_::
- Path to the *atrtp*(5) file that stores the thermodynamic properties of the
- combustion medium.
-
-*-R* <__rectangle-parameter__:...>::
- Compute a radiatve flux density map rather than an image. The rectangular
- sensor onto which the flux is integrated is defined by the following
- parameters:
-
- **pos**=**_x_**,**_y_**,**_z_**;;
- Position of the center of the rectangle. By default it is set to
- {@HTRDR_ARGS_DEFAULT_RECTANGLE_POS@}.
-
- **tgt**=**_x_**,**_y_**,**_z_**;;
- Position targeted by the rectangle, i.e. *tgt* - *pos* is the rectangle
- normal. By default it is set to {@HTRDR_ARGS_DEFAULT_RECTANGLE_TGT@}.
-
- **up**=**_x_**,**_y_**,**_z_**;;
- Up vector of the rectangle. By default it is set to
- {@HTRDR_ARGS_DEFAULT_RECTANGLE_UP@}.
-
- **sz**=**_width_**,**_height_**;;
- Size of the rectangle. By default it is set to
- {@HTRDR_ARGS_DEFAULT_RECTANGLE_SZ@}.
-
-*-r* _refract_ids_::
- Path the the *atrri*(5) file that lists the spectrally varying refractive
- indices of the combustion medium.
-
-*-s*::
- Use of Single Instruction, Multiple Data (SIMD) instruction sets if
- available. This should speed up the computation time.
-
-*-T*::
- Optical thickness used as threshold criteria to build the acceleration
- structure the combustion medium. By default its value is
- @HTRDR_COMBUSTION_ARGS_DEFAULT_OPTICAL_THICKNESS_THRESHOLD@.
-
-*-t* _threads-count_::
- Hint on the number of threads to use. By default use as many threads as CPU
- cores.
-
-*-V* <__definition__>::
- definition of the grid of the upper bound field of radiative coefficients
- from which the volumetric acceleration structure is built. The grid extent
- corresponds to the axis aligned bounding box of the volumetric mesh
- representing the combustion medium. Grid definition can be set in two ways:
-
- **_x_**,**_z_**,**_z_**;;
- Explicitly set the grid definition along the X, Y, and Z extents.
-
- **_hint_**;;
- Provide an hint on the expected definition of the grid along its major
- extent. The definition along the two remaining axes are then internally
- computed. This is the default comportment with an _hint_ set to
- @HTRDR_COMBUSTION_ARGS_DEFAULT_GRID_DEFINITION_HINT@.
-
-*-v*::
- Make *htrdr-combustion* verbose.
-
-*-w*::
- Define the wavelength of the laser in nanometre. By default it is set to
- @HTRDR_COMBUSTION_ARGS_DEFAULT_WAVELENGTH@.
-
-OUTPUT IMAGE
-------------
-
-Images calculated by *htrdr-combustion* are saved in the *htrdr-image*(5) file
-format. This section describes the nature and arrangement of image data
-depending on the type of calculation performed by *htrdr-combustion*.
-
-Shortwave monochromatic image
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For a monochromatic image rendering, the expected value and the standard
-deviation of the pixel radiance (in W/sr/m^2) are saved on the first and the
-second components. All other components are unused excepted the seventh and
-eighth components that store the estimate of the radiative path computation
-time in microseconds and its standard error.
-
-Shortwave flux density map
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A flux density map (option *-R*) is saved in an *htrdr-image*(5) storing the
-expected value and the standard error of the pixel radiative flux density (in
-W/m^2) on its first and second component. All other components are unused
-excepted the seventh and eighth components that store the estimate of the
-radiative path computation time in microseconds and its standard error.
-
-EXAMPLES
---------
-
-Make htrdr-combustion verbose (option *-v*) and render an image of a combustion
-medium whose tetrahedral mesh is stored in *tetra.sth* and its associated
-thermodynamic properties are saved in *thermprops.atrtp*. The spectrally
-varying indices of the medium are listed in the *refract_ids.atrri* file. The
-center of the laser surface emission is positioned at the origin and its
-direction is aligned to the Y axis. The definition of the rendered image is
-*800* by *600* pixels and the monochromatic radiance of each pixel is estimated
-at *500* nanometre with *64* Monte-Carlo realisations. The resulting image is
-written to *output* excepted if it already exists; in this case an
-error is notified, the program stops and the *output* file remains unchanged.
-
- $ htrdr-combustion -v \
- -m tetra.sth \
- -p thermprops.atrtp \
- -r refract_ids.atrri \
- -l pos=0,0,0:tgt=0,1,0:up=0,0,1:sz=0.001,0.2 \
- -w 500 \
- -C pos=0.06,0,0.01:tgt=0.05,0,0.01:up=0,0,1:fov=30 \
- -i def=800x600:spp=64 \
- -o output
-
-Add a combustion chamber to the previous example: its mesh is defined in
-*chamber.obj* while its materials are listed in *materials.mtls*. Save the
-volumetric acceleration structure in *octree.cache* or reused it if it was
-already populated in a previous run with compatible input data. Set the finest
-resolution of this acceleration structure to *1000* along the major extend of the
-medium and use a optical thickness criterion of *5* to build it. Use the *-f*
-option to force the overwrite of the *output* file if it exists and use *-s* to
-speed up the rendering with the available SIMD instruction sets.
-
- $ htrdr-combustion -v \
- -m tetra.sth \
- -p thermprops.atrtp \
- -r refract_ids.atrri \
- -g obj=chamber.obj:mats=materials.mtls \
- -l pos=0,0,0:tgt=0,1,0:up=0,0,1:sz=0.001,0.2 \
- -w 500 \
- -C pos=0.06,0,0.01:tgt=0.05,0,0.01:up=0,0,1:fov=30 \
- -i def=800x600:spp=64 \
- -O octree.cache \
- -V 1000 \
- -T 5 \
- -o output -f -s
-
-Compute a flux density map whose definition is *500* by *500* pixels. The flux
-density per pixel is estimated with *64* realisations; the flux density for the
-entire sensor is thus calculated with 16 million realisations (`500 * 500
-* 64`). The sensor on which the flux density is calculated is a square with
-sides measuring *0.05* meter. Its center is positioned at the origin and points
-to the Z axis.
-
- $ htrdr-combustion -v \
- -m tetra.sth \
- -p thermprops.atrtp \
- -r refract_ids.atrri \
- -l pos=0,0,0:tgt=0,1,0:up=0,0,1:sz=0.001,0.2 \
- -w 500 \
- -R pos=0,0,0:tgt=0,0,1:up=0,1,0:sz=0.05,0.05 \
- -i def=500x500:spp=64 \
- -O octree.cache \
- -V 1000 \
- -T 5 \
- -o map.txt -f -s
-
-Write into *octree.vtk* a representation of the volumetric acceleration
-structure.
-
- $ htrdr-combustion -v \
- -m tetra.sth \
- -p thermprops.atrtp \
- -r refract_ids.atrri \
- -O octree.cache \
- -d octree -o octree.vtk
-
-NOTES
------
-
-1. Effects of multiple scattering on radiative properties of soot
-fractal aggregates. J. Yon et al, JQSRT 133, 374-381, 2014 -
-<https://doi.org/10.1016/j.jqsrt.2013.08.022>
-
-2. Null-collision meshless Monte-Carlo - a new reverse Monte-Carlo algorithm
-designed for laser-source emission in absorbing/scattering inhomogeneous media. M.
-Sans et al, JQSRT, 2021 - <https://doi.org/10.1016/j.jqsrt.2021.107725>
-
-3. VTK file format -
-<http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf>
-
-4. MPI specifications - <https://www.mpi-forum.org/docs/>
-
-COPYRIGHT
----------
-Copyright © 2018, 2019, 2020, 2021 |Meso|Star> <contact@meso-star.com>.
-
-Copyright © 2018, 2019, 2021 CNRS.
-
-Copyright © 2018, 2019 Université Paul Sabatier
-<contact-edstar@laplace.univ-tlse.fr>.
-
-LICENSE
--------
-
-*htrdr-combustion* is free software released under the GPLv3+ license: GNU GPL
-version 3 or later <https://gnu.org/licenses/gpl.html>. You are free to change
-and redistribute it. There is NO WARRANTY, to the extent permitted by law.
-
-SEE ALSO
---------
-*atrtp*(5),
-*atrri*(5),
-*htrdr-atmosphere*(1),
-*htrdr-image*(5),
-*htrdr-obj*(5),
-*htrdr-materials*(5),
-*mpirun*(1),
-*sth*(5)
diff --git a/doc/htrdr-image.5.scd b/doc/htrdr-image.5.scd
@@ -0,0 +1,119 @@
+htrdr-image(5)
+
+; Copyright (C) 2018, 2019, 2020, 2021 |Meso|Star> (contact@meso-star.com)
+; Copyright (C) 2018, 2019, 2021 CNRS
+; Copyright (C) 2018, 2019 Université Paul Sabatier
+; (contact-edstar@laplace.univ-tlse.fr)
+;
+; 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/>.
+
+# NAME
+
+htrdr-image - two dimensional image format
+
+# DESCRIPTION
+
+The *htrdr-image* is a raw image file format where data are stored in plain
+text. Characters after the '#' character are considered as comments and are
+thus ignored as well as empty lines. The first valid line stores 2 unsigned
+integers that represent the image definition, i.e. the number of pixels per
+line and per column. Then each line stores 8 floating point components per
+pixel.
+
+Pixels are sorted line by line, with the origin defined at the top left corner
+of the image. With an image definition of N by M pixels, with N the number of
+pixels per line and M the overall number of lines in the image, the first N
+pixels correspond to the pixels of the top line of the image, the following N
+pixels are the pixels of the second line and so on.
+
+The *htpp*(1) program can be used to convert an *htrdr-image* into a regular
+PPM image [1]. Note that the nature and unit of the data stored in an
+*htrdr-image* is not determined by the file format itself. Refer to the
+program that generates the image for a full description of the data it
+contains.
+
+# GRAMMAR
+
+```
+<htrdr-image> ::= <definition>
+ <pixel>
+ [ <pixel> ... ]
+
+<definition> ::= <width> <height>
+<width> ::= INTEGER
+<height> ::= INTEGER
+
+<pixel> ::= <pixel-sw>
+ | <pixel-lw>
+
+<pixel-sw> ::= <X> <Y> <Z> <time>
+<pixel-lw> ::= <temperature> <radiance> 0 0 <time>
+
+<X> ::= <estimate>
+<Y> ::= <estimate>
+<Z> ::= <estimate>
+<time> ::= <estimate>
+<temperature> ::= <estimate>
+<radiance> ::= <estimate>
+
+<estimate> ::= <expected-value> <standard-error>
+<expected-value> ::= REAL
+<standard-error> ::= REAL
+```
+
+# EXAMPLE
+
+The following output was produced by *htrdr*(1) invoked to render an image of
+_800_ by _600_ pixels. Note that actually the comments and blank lines were
+not necessarily written by *htrdr*(1); they are used here only to help the
+reader understand the data layout. The comment after each pixel gives the
+two-dimensional index of the pixel in the image: the first and second integer
+is the index of the line and the column of the pixel in the image,
+respectively.
+
+```
+800 600 # Image definition
+
+# Pixels of the 1st line
+2.55e-4 2.90e-5 3.75e-4 4.48e-5 3.20e-4 3.16e-5 306.484 259.723 # (1,1)
+2.95e-4 3.37e-5 3.39e-4 4.16e-5 3.38e-4 4.60e-5 18.3633 2.66317 # (2,1)
+3.76e-4 5.43e-5 3.13e-4 3.48e-5 3.38e-4 3.32e-5 19.6252 2.67015 # (3,1)
+ ...
+7.13e-4 1.14e-4 7.66e-4 1.35e-4 7.97e-4 1.26e-4 119.820 93.7820 # (799,1)
+6.59e-4 1.14e-4 7.47e-4 1.41e-4 4.39e-4 7.33e-5 24.8655 2.46348 # (800,1)
+
+# Pixels of the 2nd line
+3.33e-4 6.02e-5 4.21e-4 7.66e-5 3.44e-4 3.81e-5 19.4580 2.50692 # (1,2)
+3.50e-4 4.93e-5 3.23e-4 2.52e-5 3.03e-4 2.42e-5 102.566 81.2936 # (2,2)
+2.72e-4 4.69e-5 3.41e-4 4.12e-5 2.52e-4 2.06e-5 25.5801 5.37736 # (3,2)
+ ...
+7.52e-4 1.31e-4 8.91e-4 1.84e-4 5.48e-4 1.30e-4 46.5418 12.4728 # (799,2)
+6.82e-4 1.42e-4 6.61e-4 7.85e-5 4.44e-4 5.99e-5 59.8728 32.1468 # (800,2)
+
+ ...
+
+# Pixels of the 600th line
+2.69e-4 7.44e-5 2.31e-4 2.56e-5 1.95e-4 2.30e-5 43.8242 15.0047 # (1,600)
+4.32e-4 1.25e-4 2.22e-4 2.22e-5 2.04e-4 2.60e-5 25.5498 1.73942 # (2,600)
+2.78e-4 5.81e-5 2.75e-4 4.99e-5 2.17e-4 3.30e-5 38.4448 7.16199 # (3,600)
+ ...
+3.54e-4 4.32e-5 3.07e-4 3.80e-5 2.38e-4 2.49e-5 102.893 36.9865 # (799,600)
+3.07e-4 2.61e-5 4.60e-4 1.13e-4 2.69e-4 4.29e-5 42.75070 11.913 # (800,600)
+```
+
+# SEE ALSO
+
+. Portable PixMap - <http://netpbm.sourceforge.net/doc/ppm.html>
+
+*htpp*(1), *htrdr*(1)
diff --git a/doc/htrdr-image.5.txt b/doc/htrdr-image.5.txt
@@ -1,126 +0,0 @@
-// Copyright (C) 2018, 2019, 2020, 2021 |Meso|Star> (contact@meso-star.com)
-// Copyright (C) 2018, 2019, 2021 CNRS
-// Copyright (C) 2018, 2019 Université Paul Sabatier
-// (contact-edstar@laplace.univ-tlse.fr)
-//
-// 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-image(5)
-==============
-
-NAME
-----
-htrdr-image - two dimensional image format
-
-DESCRIPTION
------------
-The *htrdr-image* is a raw image file format where data are stored in plain
-text. Characters after the '#' character are considered as comments and are
-thus ignored as well as empty lines. The first valid line stores 2 unsigned
-integers that represent the image definition, i.e. the number of pixels per
-line and per column. Then each line stores 8 floating point components per
-pixel.
-
-Pixels are sorted line by line, with the origin defined at the top left corner
-of the image. With an image definition of N by M pixels, with N the number of
-pixels per line and M the overall number of lines in the image, the first N
-pixels correspond to the pixels of the top line of the image, the following N
-pixels are the pixels of the second line and so on.
-
-The *htpp*(1) program can be used to convert an *htrdr-image* into a regular
-PPM image [1]. Note that the nature and unit of the data stored in an
-*htrdr-image* is not determined by the file format itself. Refer to the
-program that generates the image for a full description of the data it
-contains.
-
-GRAMMAR
--------
-
-[verse]
--------
-<htrdr-image> ::= <definition>
- <pixel>
- [ <pixel> ... ]
-
-<definition> ::= <width> <height>
-<width> ::= INTEGER
-<height> ::= INTEGER
-
-<pixel> ::= <pixel-sw>
- | <pixel-lw>
-
-<pixel-sw> ::= <X> <Y> <Z> <time>
-<pixel-lw> ::= <temperature> <radiance> 0 0 <time>
-
-<X> ::= <estimate>
-<Y> ::= <estimate>
-<Z> ::= <estimate>
-<time> ::= <estimate>
-<temperature> ::= <estimate>
-<radiance> ::= <estimate>
-
-<estimate> ::= <expected-value> <standard-error>
-<expected-value> ::= REAL
-<standard-error> ::= REAL
--------
-
-EXAMPLE
--------
-The following output was produced by *htrdr*(1) invoked to render an image of
-*800* by *600* pixels. Note that actually the comments and blank lines were
-not necessarily written by *htrdr*(1); they are used here only to help the
-reader understand the data layout. The comment after each pixel gives the
-two-dimensional index of the pixel in the image: the first and second integer
-is the index of the line and the column of the pixel in the image,
-respectively.
-
-[verse]
-------
-800 600 # Image definition
-
-# Pixels of the 1st line
-2.55e-4 2.90e-5 3.75e-4 4.48e-5 3.20e-4 3.16e-5 306.484 259.723 # (1,1)
-2.95e-4 3.37e-5 3.39e-4 4.16e-5 3.38e-4 4.60e-5 18.3633 2.66317 # (2,1)
-3.76e-4 5.43e-5 3.13e-4 3.48e-5 3.38e-4 3.32e-5 19.6252 2.67015 # (3,1)
- ...
-7.13e-4 1.14e-4 7.66e-4 1.35e-4 7.97e-4 1.26e-4 119.820 93.7820 # (799,1)
-6.59e-4 1.14e-4 7.47e-4 1.41e-4 4.39e-4 7.33e-5 24.8655 2.46348 # (800,1)
-
-# Pixels of the 2nd line
-3.33e-4 6.02e-5 4.21e-4 7.66e-5 3.44e-4 3.81e-5 19.4580 2.50692 # (1,2)
-3.50e-4 4.93e-5 3.23e-4 2.52e-5 3.03e-4 2.42e-5 102.566 81.2936 # (2,2)
-2.72e-4 4.69e-5 3.41e-4 4.12e-5 2.52e-4 2.06e-5 25.5801 5.37736 # (3,2)
- ...
-7.52e-4 1.31e-4 8.91e-4 1.84e-4 5.48e-4 1.30e-4 46.5418 12.4728 # (799,2)
-6.82e-4 1.42e-4 6.61e-4 7.85e-5 4.44e-4 5.99e-5 59.8728 32.1468 # (800,2)
-
- ...
-
-# Pixels of the 600th line
-2.69e-4 7.44e-5 2.31e-4 2.56e-5 1.95e-4 2.30e-5 43.8242 15.0047 # (1,600)
-4.32e-4 1.25e-4 2.22e-4 2.22e-5 2.04e-4 2.60e-5 25.5498 1.73942 # (2,600)
-2.78e-4 5.81e-5 2.75e-4 4.99e-5 2.17e-4 3.30e-5 38.4448 7.16199 # (3,600)
- ...
-3.54e-4 4.32e-5 3.07e-4 3.80e-5 2.38e-4 2.49e-5 102.893 36.9865 # (799,600)
-3.07e-4 2.61e-5 4.60e-4 1.13e-4 2.69e-4 4.29e-5 42.75070 11.913 # (800,600)
-------
-
-NOTES
------
-1. Portable PixMap - <http://netpbm.sourceforge.net/doc/ppm.html>
-
-SEE ALSO
---------
-*htpp*(1), *htrdr*(1)
diff --git a/doc/htrdr-materials.5.scd b/doc/htrdr-materials.5.scd
@@ -0,0 +1,71 @@
+htrdr-materials(5)
+
+; Copyright (C) 2018, 2019, 2020, 2021 |Meso|Star> (contact@meso-star.com)
+; Copyright (C) 2018, 2019, 2021 CNRS
+; Copyright (C) 2018, 2019 Université Paul Sabatier
+; (contact-edstar@laplace.univ-tlse.fr)
+;
+; 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/>.
+
+# NAME
+
+htrdr-materials - list of materials used by the geometries in htrdr(1)
+
+# DESCRIPTION
+
+A *htrdr-materials* file lists the materials that can be used by geometries
+provided through a *htrdr-obj*(5) file to the *htrdr*(1) program. Each line
+of the file gives the name of the material. For opaque materials the material
+name is followed by the path toward the *mrumtl*(5) file storing the spectral
+properties of its associated Bidirectional Reflectance Distribution Function.
+Furthermore, the temperature of the material must be defined too.
+
+The material name can be composed of any characters excepted for spaces and
+tabulations. The path toward the *mrumtl*(5) file must be a valid path
+relative to 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
+and tabulations, are simply skipped.
+
+# GRAMMAR
+
+```
+<htrdr-materials> ::= <material>
+ [ <material> ... ]
+<material> ::= <name> <properties>
+<name> ::= STRING
+<properties> ::= none | <mrumtl-path> <temperature>
+<mrumtl-path> ::= PATH
+<temperature> ::= REAL # In Kelvin
+```
+
+# EXAMPLE
+
+The following file lists 3 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. Both
+materials have a temperature of 300 Kelvin. The last material is a
+semi-transparent material named _air_ with no additionnal properties defined
+in this file.
+
+```
+grass /opt/materials/A001.mrumtl 300
+sand /opt/materials/B002.mrumtl 300
+air none
+```
+
+# SEE ALSO
+
+*htrdr*(1), *htrdr-obj*(5), *mrumtl*(5)
diff --git a/doc/htrdr-materials.5.txt b/doc/htrdr-materials.5.txt
@@ -1,77 +0,0 @@
-// Copyright (C) 2018, 2019, 2020, 2021 |Meso|Star> (contact@meso-star.com)
-// Copyright (C) 2018, 2019, 2021 CNRS
-// Copyright (C) 2018, 2019 Université Paul Sabatier
-// (contact-edstar@laplace.univ-tlse.fr)
-//
-// 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 geometries in htrdr(1)
-
-DESCRIPTION
------------
-A *htrdr-materials* file lists the materials that can be used by geometries
-provided through a *htrdr-obj*(5) file to the *htrdr*(1) program. Each line
-of the file gives the name of the material. For opaque materials the material
-name is followed by the path toward the *mrumtl*(5) file storing the spectral
-properties of its associated Bidirectional Reflectance Distribution Function.
-Furthermore, the temperature of the material must be defined too.
-
-The material name can be composed of any characters excepted for spaces and
-tabulations. The path toward the *mrumtl*(5) file must be a valid path
-relative to 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
-and tabulations, are simply skipped.
-
-GRAMMAR
--------
-
-[verse]
--------
-<htrdr-materials> ::= <material>
- [ <material> ... ]
-<material> ::= <name> <properties>
-<name> ::= STRING
-<properties> ::= none | <mrumtl-path> <temperature>
-<mrumtl-path> ::= PATH
-<temperature> ::= REAL # In Kelvin
--------
-
-EXAMPLE
--------
-
-The following file lists 3 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. Both
-materials have a temperature of 300 Kelvin. The last material is a
-semi-transparent material named *air* with no additionnal properties defined
-in this file.
-
-[verse]
--------
-grass /opt/materials/A001.mrumtl 300
-sand /opt/materials/B002.mrumtl 300
-air none
--------
-
-SEE ALSO
---------
-*htrdr*(1), *htrdr-obj*(5), *mrumtl*(5)
diff --git a/doc/htrdr-obj.5.scd b/doc/htrdr-obj.5.scd
@@ -0,0 +1,98 @@
+htrdr-obj(5)
+
+; Copyright (C) 2018, 2019, 2020, 2021 |Meso|Star> (contact@meso-star.com)
+; Copyright (C) 2018, 2019, 2021 CNRS
+; Copyright (C) 2018, 2019 Université Paul Sabatier
+; (contact-edstar@laplace.univ-tlse.fr)
+;
+; 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/>.
+
+# 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_>:[<_interface-mtl-name_>:]<_back-mtl-name_>", where
+<_front-mtl-name_>, <_interface-mtl-name_> and <_back-mtl-name_> are
+strings separated by a colon (:) defining the name of the front, interface,
+and back facing materials, respectively. The interface material name is
+optionnal: it is used for thin geometries, i.e. geometries with no thickness.
+Material names can be composed of any characters expected for spaces and
+tabulations. Note that regarding the *htrdr*(1) convention, a triangle side is
+said "front facing" when its vertices are clock-wise ordered.
+
+Note that to be a valid *htrdr-obj*(5) file for *htrdr*(1), the front and the
+back facing names must reference a material listed in *htrdr-materials*(5)
+file submitted to the *htrdr*(1) command line.
+
+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.
+
+# EXAMPLES
+
+Define a quad at the interface between the air medium and the concrete
+material.
+
+```
+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
+```
+
+Define a wooden cube whose Z-aligned faces are against a brick material.
+The remaining faces are in contact with the air.
+
+```
+v 0 0 0
+v 1 0 0
+v 0 1 0
+v 1 1 0
+v 0 0 1
+v 1 0 1
+v 0 1 1
+v 1 1 1
+
+usemtl wood:air
+f 1 3 2
+f 2 3 4
+f 1 5 3
+f 3 5 7
+f 5 6 7
+f 7 6 8
+f 4 8 2
+f 2 8 6
+
+usemtl wood:brick
+f 3 7 4
+f 4 7 8
+f 1 2 5
+f 5 2 6
+```
+
+# SEE ALSO
+
+. OBJ file format - <http://www.martinreddy.net/gfx/3d/OBJ.spec>
+
+*htrdr*(1)
diff --git a/doc/htrdr-obj.5.txt b/doc/htrdr-obj.5.txt
@@ -1,107 +0,0 @@
-// Copyright (C) 2018, 2019, 2020, 2021 |Meso|Star> (contact@meso-star.com)
-// Copyright (C) 2018, 2019, 2021 CNRS
-// Copyright (C) 2018, 2019 Université Paul Sabatier
-// (contact-edstar@laplace.univ-tlse.fr)
-//
-// 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__>:[<__interface-mtl-name__>:]<__back-mtl-name__>", where
-<__front-mtl-name__>, <__interface-mtl-name__> and <__back-mtl-name__> are
-strings separated by a colon (:) defining the name of the front, interface,
-and back facing materials, respectively. The interface material name is
-optionnal: it is used for thin geometries, i.e. geometries with no thickness.
-Material names can be composed of any characters expected for spaces and
-tabulations. Note that regarding the *htrdr*(1) convention, a triangle side is
-said "front facing" when its vertices are clock-wise ordered.
-
-Note that to be a valid *htrdr-obj*(5) file for *htrdr*(1), the front and the
-back facing names must reference a material listed in *htrdr-materials*(5)
-file submitted to the *htrdr*(1) command line.
-
-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.
-
-EXAMPLES
---------
-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
--------
-
-Define a wooden cube whose Z-aligned faces are against a brick material.
-The remaining faces are in contact with the air.
-
-[verse]
--------
-v 0 0 0
-v 1 0 0
-v 0 1 0
-v 1 1 0
-v 0 0 1
-v 1 0 1
-v 0 1 1
-v 1 1 1
-
-usemtl wood:air
-f 1 3 2
-f 2 3 4
-f 1 5 3
-f 3 5 7
-f 5 6 7
-f 7 6 8
-f 4 8 2
-f 2 8 6
-
-usemtl wood:brick
-f 3 7 4
-f 4 7 8
-f 1 2 5
-f 5 2 6
--------
-
-NOTES
------
-
-1. OBJ file format -
- <http://www.martinreddy.net/gfx/3d/OBJ.spec>
-
-SEE ALSO
---------
-
-*htrdr*(1)
diff --git a/doc/htrdr.1.scd b/doc/htrdr.1.scd
@@ -0,0 +1,73 @@
+htrdr(1)
+
+; Copyright (C) 2018, 2019, 2020, 2021 |Meso|Star> (contact@meso-star.com)
+; Copyright (C) 2018, 2019, 2021 CNRS
+; Copyright (C) 2018, 2019 Université Paul Sabatier
+; (contact-edstar@laplace.univ-tlse.fr)
+;
+; 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/>.
+
+# NAME
+
+htrdr - the Monte-Carlo radiative transfert simulator
+
+# SYNOPSIS
+
+htrdr [--version] [--help] <_mode_> [<_args_>]
+
+# DESCRIPTION
+
+*htrdr* computes images of scenes composed of semi transparent materials and
+geometries with spectral varying reflectivities. The way the scenes are
+described and the solved Monte-Carlo algorithms are controlled by the _mode_
+argument that defines the computation context.
+
+# OPTIONS
+
+*--help*
+ Print short help and exit.
+
+*--version*
+ Display version information and exit.
+
+# MODES
+
+Each *htrdr* _mode_ is actually a mapping to a seperate command line named
+_htrdr-<mode>_ with its own set of arguments. Refer to their corresponding
+man page for their complete description.
+
+The available _htrdr-<mode>_ commands are:
+
+*htrdr-atmosphere*(1)
+ Radiative transfer computations in a cloudy atmosphere.
+
+*htrdr-combustion*(1)
+ Radiative transfer computations in a combustion medium.
+
+# COPYRIGHT
+
+Copyright © 2018, 2019, 2020, 2021 |Méso|Star> <contact@meso-star.com>++
+Copyright © 2018, 2019, 2021 Centre National de la Recherche Scientifique++
+Copyright © 2018, 2019 Université Paul Sabatier <contact-edstar@laplace.univ-tlse.fr>
+
+# LICENSE
+
+*htrdr* is free software released under the GPLv3+ license: GNU GPL version 3
+or later <https://gnu.org/licenses/gpl.html>. You are free to change and
+redistribute it. There is NO WARRANTY, to the extent permitted by law.
+
+# SEE ALSO
+
+*htrdr-atmosphere*(1),
+*htrdr-combustion*(1)
diff --git a/doc/htrdr.1.txt b/doc/htrdr.1.txt
@@ -1,77 +0,0 @@
-// Copyright (C) 2018, 2019, 2020, 2021 |Meso|Star> (contact@meso-star.com)
-// Copyright (C) 2018, 2019, 2021 CNRS
-// Copyright (C) 2018, 2019 Université Paul Sabatier
-// (contact-edstar@laplace.univ-tlse.fr)
-//
-// 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(1)
-========
-
-NAME
-----
-htrdr - the Monte-Carlo radiative transfert simulator
-
-SYNOPSIS
---------
-[verse]
-*htrdr* [--version] [--help] <__mode__> [<__args__>]
-
-DESCRIPTION
------------
-*htrdr* computes images of scenes composed of semi transparent materials and
-geometries with spectral varying reflectivities. The way the scenes are
-described and the solved Monte-Carlo algorithms are controlled by the _mode_
-argument that defines the computation context.
-
-OPTIONS
--------
-*--help*::
- Print short help and exit.
-
-*--version*::
- Display version information and exit.
-
-MODES
------
-
-Each *htrdr* _mode_ is actually a mapping to a seperate command line named
-*htrdr-<__mode__>* with its own set of arguments. Refer to their corresponding
-man page for their complete description.
-
-The available *htrdr-<__mode__>* commands are:
-
-*htrdr-atmosphere*(1)::
- Radiative transfer computations in a cloudy atmosphere.
-
-*htrdr-combustion*(1)::
- Radiative transfer computations in a combustion medium.
-
-COPYRIGHT
----------
-Copyright © 2018, 2019, 2020, 2021 |Meso|Star> <contact@meso-star.com>.
-Copyright © 2018, 2019, 2021 CNRS.
-Copyright © 2018, 2019 Université Paul Sabatier <contact-edstar@laplace.univ-tlse.fr>.
-
-LICENSE
--------
-*htrdr* is free software released under the GPLv3+ license: GNU GPL version 3
-or later <https://gnu.org/licenses/gpl.html>. You are free to change and
-redistribute it. There is NO WARRANTY, to the extent permitted by law.
-
-SEE ALSO
---------
-*htrdr-atmosphere*(1),
-*htrdr-combustion*(1)
