commit 2125a45c2cd1a06fdc5574ad5e27e3e04eaac6e0
parent dbd3fb5de94c0d23af45c1de8796fe2686f3cccd
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 3 Apr 2020 16:50:46 +0200
Fix and small update of the man pages
Diffstat:
4 files changed, 68 insertions(+), 63 deletions(-)
diff --git a/doc/htrdr-image.5.txt b/doc/htrdr-image.5.txt
@@ -31,21 +31,21 @@ integers that represent the image definition, i.e. the number of pixels per
line and per column. Then each line stores 8 pixel components.
If the image is a regular rendering in the visible part of the spectrum, the
-pixel components are actually 4 pairs of floating points data
-representing the pixel color encoded in the CIE 1931 XYZ color space and the
-time spent per realisation to estimate the pixel. The first, second and third
-pair encodes the estimated radiance in W.sr^-1.m^-2 of the X, Y and Z pixel
-components, respectively. The first value of each pair is the expected value of
-the estimated radiance while the second one is its associated standard
-deviation. The fourth pair saves the estimate in microseconds of the per
-radiative path computation time and its standard error.
+pixel components are actually 4 pairs of floating points data representing the
+pixel color encoded in the CIE 1931 XYZ color space and the per radiative path
+computation time. The first, second and third pair encode the estimated
+radiance in W.sr^-1.m^-2 of the X, Y and Z pixel components, respectively. The
+first value of each pair is the expected value of the estimated radiance while
+the second one is its associated standard deviation. The fourth pair saves the
+estimate in microseconds of the per radiative path computation time and its
+standard error.
If the image is an infrared rendering, the first and second pixel components
store the expected value and the standard error, respectively, of the
estimated brightness temperature in Kelvin. The third and fourth component
-saves the expected values and the standard error of its corresponding radiance
-in W.sr^-1.m^-2. The fifth and sixth pixel components are unused. Finally the
-last 2 pixel components saves, as for a regular rendering, the estimate in
+save the expected value and standard deviation of the pixel radiance in
+W.sr^-1.m^-2. The fifth and sixth pixel components are unused. Finally the
+last 2 pixel components save, as for a regular rendering, the estimate in
microseconds of the per radiative path computation time and its standard
error.
@@ -55,7 +55,7 @@ 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.
-Note that the *htpp*(1) program can be used to convert an *htrdr-image* in a
+Note that the *htpp*(1) program can be used to convert an *htrdr-image* into a
regular PPM image [1].
GRAMMAR
@@ -91,12 +91,13 @@ GRAMMAR
EXAMPLE
-------
-The following output is emitted by *htrdr*(1) invoked to render an image of
-*800* by *600* pixels. Note that actually the comments or the blank lines are
-not necessarily written as it by *htrdr*(1); they are used here only to help
-in understanding 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.
+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]
------
diff --git a/doc/htrdr-materials.5.txt b/doc/htrdr-materials.5.txt
@@ -29,8 +29,8 @@ geometry provided through a *htrdr-obj*(5) file to the *htrdr*(1) program.
Each line of the file gives the name of the material and the path toward the
*mrumtl*(5) file storing the spectral properties of its associated
Bidirectional Reflectance Distribution Function. The material name can be
-composed of any characters excepted spaces and tabulations. The path toward
-the *mrumtl*(5) file must be a valid path regarding the file system.
+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
diff --git a/doc/htrdr-obj.5.txt b/doc/htrdr-obj.5.txt
@@ -24,16 +24,19 @@ htrdr-obj - file format of the ground geometry in htrdr(1)
DESCRIPTION
-----------
-A *htrdr-obj* file is a regular OBJ [1] composed only of triangular
-meshes. Each triangle must be included in a material group as defined by
-the 'usemtl' directive. The name of the material group must be of the
-form "<__front-mtl-name__>:<__back-mtl-name__>", where
-<__front-mtl-name__> and <__back-mtl-name__> are strings separated by a
-colon mark (:) defining the name of the front and back facing materials,
-respectively. These names can be composed of any characters expected
-spaces and tabulations. Note that regarding the *htrdr*(1) convention, a
-triangle side is said "front facing" when its vertices are clock-wise
-ordered.
+A *htrdr-obj* file is a regular OBJ [1] composed only of triangular meshes.
+Each triangle must be included in a material group as defined by the 'usemtl'
+directive. The name of the material group must be of the form
+"<__front-mtl-name__>:<__back-mtl-name__>", where <__front-mtl-name__> and
+<__back-mtl-name__> are strings separated by a colon (:) defining the name of
+the front and back facing materials, respectively. These 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.
@@ -57,8 +60,8 @@ f 1 2 3
f 3 2 4
-------
-Define a wooden cube whose faces aligned with the Z axis are pasted to a brick
-material. The remaining faces are in contact with the air.
+Define a wooden cube whose faces Z-aligned faces are against a brick material.
+The remaining faces are in contact with the air.
[verse]
-------
diff --git a/doc/htrdr.1.txt.in b/doc/htrdr.1.txt.in
@@ -48,28 +48,30 @@ the X and Y axis by setting the *-r* and the *-R* options, respectively.
underlying algorithm is based on a Monte-Carlo method: it consists in
simulating a given number of optical paths originating from the camera,
directed into the atmosphere, taking into account light absorption and
-scattering phenomena. In regular image rendering, the computation is performed
-over 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 required observation position. In
-long waves, the rendering is performed for the range of wavelengths defined by
-the *-l* option. The estimated radiance per pixel is then converted to its
-brightness temperature and both are saved in the output image.
+scattering phenomena. When rendering in the visible part of the spectrum, the
+computation is performed over 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. In long waves, the rendering is performed for the range
+of wavelengths defined by the *-l* option. The estimated radiance per pixel is
+then converted to its brightness temperature and both are saved in the output
+image.
In *htrdr* the spatial unit 1.0 corresponds to one meter, the estimated
radiance is given in W.sr^-1.m^-2 and the temperatures are expressed in Kelvin.
-The pixels are written into the _output_ file or to the standard output whether
-the *-o* option is defined or not, respectively. The output image is a list of
-raw ASCII data formatted with respect to the *htrdr-image*(5) file format.
-Since *htrdr* relies on the Monte-Carlo method, each estimation is given with
-its numerical accuracy.
-
-During simulation, *htrdr* dynamically loads/unloads cloud properties to handle
-clouds whose data do not feat in main memory. *htrdr* also supports shared
-memory parallelism and relies on the Message Passing Interface specification
-[3] to parallelise its computations in a distribute memory environment; it can
-thus be run either directly or through a MPI process launcher like *mpirun*(1).
+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. Since *htrdr*
+relies on the Monte-Carlo method, each estimation is given with its numerical
+accuracy.
+
+During the simulation, *htrdr* dynamically loads/unloads cloud properties to
+handle clouds whose data that do not feat in main memory. *htrdr* also supports
+shared memory parallelism and relies on the Message Passing Interface
+specification [3] 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
-------
@@ -116,7 +118,7 @@ OPTIONS
the radiative transfer computations in the clouds. The written data are
octrees saved in the VTK file format [2]. 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 of the
+ 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*::
@@ -166,7 +168,7 @@ OPTIONS
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 of the ones used to setup the cache; leading to a significant speed-up
+ 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.
@@ -204,14 +206,13 @@ 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 material are listed in
-the *material.mtl* file. The camera is positioned at *400* meters high 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:
+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 -D0,90 -a gas.txt -m Mie.nc -g quad.obj -R \
-M materials.mtl \
@@ -221,8 +222,8 @@ stops and the *output* file remains unchanged:
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 repeated to the
-infinity without visual glitches. Use the *-f* option to write the rendered
+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 [4]:
