commit eed0504708c464cfac59fce5724d668e703505a2
parent 51f34dd8f409ee95b731c1d58ec70aef30d3f59d
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 27 Mar 2020 18:46:59 +0100
Document in the map pages the infrared rendering
Diffstat:
4 files changed, 136 insertions(+), 93 deletions(-)
diff --git a/doc/htrdr-image.5.txt b/doc/htrdr-image.5.txt
@@ -28,7 +28,10 @@ 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 4 pairs of floating points data
+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
@@ -37,6 +40,15 @@ 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
+microseconds of the per radiative path computation time and its standard
+error.
+
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
@@ -59,11 +71,18 @@ GRAMMAR
<width> ::= INTEGER
<height> ::= INTEGER
-<pixel> ::= <X> <Y> <Z> <time>
+<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
diff --git a/doc/htrdr-materials.5.txt b/doc/htrdr-materials.5.txt
@@ -25,12 +25,12 @@ htrdr-materials - list of materials used by the ground geometry in htrdr(1)
DESCRIPTION
-----------
A *htrdr-materials* file lists the materials that can be used by the ground
-geometry of the *htrdr*(1) program. Each line of the file gives the name of
-the material and the path toward the *mrumtl*(5) file storing the spectral
-properties of its associated Bidirectional Reflectance Distribution Function.
-The material name can be composed of any characters excepted spaces and
-tabulations. The path toward the *mrumtl*(5) file must be a valid path
-regarding the file system.
+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.
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
@@ -63,4 +63,4 @@ sand /opt/materials/B002.mrumtl
SEE ALSO
--------
-*htrdr*(1), *mrumtl*(5)
+*htrdr*(1), *htrdr-obj*(5), *mrumtl*(5)
diff --git a/doc/htrdr.1.txt.in b/doc/htrdr.1.txt.in
@@ -29,42 +29,46 @@ SYNOPSIS
DESCRIPTION
-----------
-*htrdr* is an image renderer in the visible part of the spectrum, for scenes
-composed of an atmospheric gas mixture, clouds, and a ground. It uses spectral
-data that should be provided for the pressure and temperature atmospheric
-vertical profile [1] (*-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 provide: the characteristics of the simulated camera (*-C*
-_camera_), the sensor definition (*-i* _image_), and the position of the sun
-(*-D* _azimuth_,_elevation_). It is also possible to provide an OBJ [2]
-representing the ground geometry with a diffuse reflectivity (*-g* _ground_).
-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.
-
-*htrdr* 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 camera,
+*htrdr* is an image renderer of scenes composed of an atmospheric gas mixture,
+clouds, and a ground. Images can be rendered 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 [1] (*-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 provide: the characteristics of the
+simulated camera (*-C* _camera_), the sensor definition (*-i* _image_), and the
+position of the sun (*-D* _azimuth_,_elevation_). 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.
+
+*htrdr* 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 camera,
directed into the atmosphere, taking into account light absorption and
-scattering phenomena. The computation is performed over the whole visible part
-of the spectrum, 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 *htrdr* the spatial unit 1.0 corresponds to one meter. The estimated
-radiance of each pixel component is given in W.sr^-1.m^-2. 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, the estimated radiance of a pixel
-component is provided with its numerical accuracy.
+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.
+
+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
-[4] to parallelise its computations in a distribute memory environment; it can
+[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).
OPTIONS
@@ -110,7 +114,7 @@ OPTIONS
*-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
+ 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
previous one by a line with three minus characters, i.e. '---'.
@@ -119,17 +123,7 @@ OPTIONS
Force overwrite of the _output_ file.
*-g* _ground_::
- Path toward an OBJ file [2] representing the ground geometry. Note that only
- triangular meshes are handled. Furthermore, each triangle must have a
- material, i.e. it must belongs to a *usemtl* group as defined by the OBJ file
- format. The name of the *usemtl* group must be of the form
- "<__front-mtl-name__>:<__back-mtl-name__>", where <__front-mtl-name__> and
- <__back-mtl-name__> are strings separated by a colon mark (:). Each
- string must reference the name of a material listed in the
- *htrdr-materials*(5) file submitted through the *-M* option.
- <__front-mtl-name__> and <__back-mtl-name__> are the name of the front and
- back facing materials, respectively. In *htrdr*(1), a triangle side is said
- "front facing" if its vertices are clock-wise ordered.
+ Path toward a *htrdr-obj*(5) representing the ground geometry.
*-h*::
List short help and exit.
@@ -142,10 +136,17 @@ OPTIONS
@HTRDR_ARGS_DEFAULT_IMG_WIDTH@x@HTRDR_ARGS_DEFAULT_IMG_HEIGHT@.
**spp**=**_samples-count_**;;
- Number of samples per pixel and per component. i.e. the estimation of a
- pixel will use "3 * _samples-count_" Monte-Carlo realisations, one set of
+ 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. By default, *spp* is set to @HTRDR_ARGS_DEFAULT_IMG_SPP@.
+ XYZ color space. In long wave rendering (*-l* option) only one set of
+ _samples-count_ is used to estimate the pixel radiance and the resulting
+ brightness temperature for the submitted range of wavelengths. By default,
+ *spp* is set to @HTRDR_ARGS_DEFAULT_IMG_SPP@.
+
+*-l* __wlen-min__,__wlen-max__::
+ Switch in infrared rendering for the long wave interval in [__wlen-min__,
+ __wlen-max__] nanometers.
*-R*::
Infinitely repeat the _ground_ along the X and Y axis.
@@ -203,33 +204,47 @@ 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 Mie data are provided through the *Mie.nc* file and
-the ground geometry is a quad repeated to the infinity. 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 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:
$ htrdr -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 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 image to *output* even though the file already exists.
-Fianlly, use the *htpp*(1) command to convert the *htrdr-image*(5) saved in
-output in a regular PPM image [5]:
-
- $ htrdr -D0,90 -a gas.txt -m Mie.nc -g mountains.obj -R -c clouds.htcp \
+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
+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]:
+
+ $ htrdr -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:
+
+ $ htrdr -l 9200,10000 -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
+
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
@@ -237,7 +252,9 @@ 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 -D120,40 -a gas.txt -m Mie.nc -g mountains.obj -R -c clouds.htcp \
+ $ htrdr -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 -
@@ -255,7 +272,9 @@ Use *mpirun*(1) to launch *htrdr* on several hosts defined in the *my_hosts*
file. Make the clouds infinite along the X and Y axis:
$ mpirun --hostfile my_hosts htrdr \
- -D120,40 -a gas.txt -m Mie.nc -g mountains.obj -R -c clouds.htcp -r \
+ -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
@@ -264,12 +283,10 @@ NOTES
-----
1. High-Tune: Gas Optical Properties file format -
<https://www.meso-star.com/projects/high-tune/downloads/gas_opt_prop_en.pdf>
-2. OBJ file format -
- <http://www.martinreddy.net/gfx/3d/OBJ.spec>
-3. VTK file format -
+2. 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>
+3. MPI specifications - <https://www.mpi-forum.org/docs/>
+4. Portable PixMap - <http://netpbm.sourceforge.net/doc/ppm.html>
COPYRIGHT
---------
@@ -290,3 +307,4 @@ SEE ALSO
*htpp*(1),
*htrdr-image*(5),
*htrdr-materials*(5)
+*htrdr-obj*(5)
diff --git a/src/htrdr_args.c b/src/htrdr_args.c
@@ -34,14 +34,15 @@ print_help(const char* cmd)
ASSERT(cmd);
printf("Usage: %s [OPION]... -a ATMOSPHERE\n", cmd);
printf(
-"Render an image for scenes composed of an atmospheric gas mixture, clouds\n"
-"and a ground.\n\n");
+"Render an image for scenes composed of an atmospheric gas mixture,\n"
+"clouds and a ground.\n\n");
printf(
" -a ATMOSPHERE gas optical properties of the atmosphere.\n");
printf(
" -c CLOUDS properties of the clouds.\n");
printf(
-" -C <camera> define the rendering point of view.\n");
+" -C <camera> define the rendering point of view. Refer to the\n"
+" htrdr man page for the list of camera options.\n");
printf(
" -D AZIMUTH,ELEVATION\n"
" direction in degrees toward the sun center. By default\n"
@@ -57,22 +58,25 @@ print_help(const char* cmd)
printf(
" -h display this help and exit.\n");
printf(
-" -i <image> define the image to compute.\n");
+" -i <image> define the image to compute. Refer to the htrdr man\n"
+" page for the list of image options\n");
printf(
" -l WLEN_MIN,WLEN_MAX\n"
-" enable long wave rendering for the wavelengths included in\n"
+" switch in infrared rendering for the long waves in\n"
" [WLEN_MIN, WLEN_MAX], in nanometers. By default, the\n"
-" rendering is performed for the visible part of the spectrum.\n");
+" rendering is performed for the visible part of the\n"
+" spectrum in [380, 780] nanometers.\n");
printf(
" -R infinitely repeat the ground along the X and Y axis.\n");
printf(
" -r infinitely repeat the clouds along the X and Y axis.\n");
printf(
-" -M MATERIALS file listing the scene ground materials.\n");
+" -M MATERIALS file listing the ground materials.\n");
printf(
" -m MIE file of Mie's data.\n");
printf(
-" -O CACHE name of the cache file used to store/restore the sky data.\n");
+" -O CACHE name of the cache file used to store/restore the sky\n"
+" data.\n");
printf(
" -o OUTPUT file where data are written. If not defined, data are\n"
" written to standard output.\n");
@@ -81,21 +85,23 @@ print_help(const char* cmd)
" building. By default its value is `%g'.\n",
HTRDR_ARGS_DEFAULT.optical_thickness);
printf(
-" -t THREADS hint on the number of threads to use. By default use as\n"
-" many threads as CPU cores.\n");
+" -t THREADS hint on the number of threads to use. By default use\n"
+" as many threads as CPU cores.\n");
printf(
-" -V X,Y,Z maximum definition of the cloud acceleration grids along\n"
-" the 3 axis. By default use the definition of the clouds\n");
+" -V X,Y,Z maximum definition of the cloud acceleration grids\n"
+" along the 3 axis. By default use the definition of\n"
+" the clouds\n");
printf(
" -v make the program verbose.\n");
printf(
" --version display version information and exit.\n");
printf("\n");
printf(
-"Copyright (C) 2018, 2019, 2020 |Meso|Star> <contact@meso-star.com>. Copyright\n"
-"(C) 2018, 2019 CNRS, Université Paul Sabatier. htrdr is free software released\n"
-"under the GNU GPL license, version 3 or later. You are free to change or\n"
-"redistribute it under certain conditions <http://gnu.org/licenses/gpl.html>\n");
+"Copyright (C) 2018, 2019, 2020 |Meso|Star> <contact@meso-star.com>.\n"
+"Copyright (C) 2018, 2019 CNRS, Université Paul Sabatier. htrdr is free\n"
+"software released under the GNU GPL license, version 3 or later. You\n"
+"are free to change or redistribute it under certain conditions\n"
+"<http://gnu.org/licenses/gpl.html>\n");
}
static INLINE res_T
