HTRDR-ATMOSPHERE(1) General Commands Manual HTRDR-ATMOSPHERE(1)

htrdr‑atmosphere — simulate radiative transfer in cloudy atmospheres

htrdr‑atmosphere [-dfhRrv] [-c clouds] [-C persp_camera_opt[:persp_camera_opt ...]] [-D sun_azimuth,sun_elevation] [-g ground] [-i image_opt[:image_opt ...]] [-M materials] [-m mie] [-n sky_mtl] [-O cache] [-o output] [-P ortho_camera_opt[:ortho_camera_opt ...]] [-p flux_sensor_opt[:flux_sensor_opt ...]] [-s spectral_opt[:spectral_opt ...]] [-T optical_thickness] [-t threads_count] [-V x,y,z] -a atmosphere

htrdr‑atmosphere simulates radiative transfer in scenes composed of an atmospheric gas mixture, liquid 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.

Radiative transfer can be evaluated in any part of the spectrum. It uses the k distributions to be provided for the vertical profile of atmospheric pressure and temperature (option -a). For clouds, the user must define the liquid water content suspended in clouds (option -c), and the optical properties of water droplets (option -m). All that remains is to define the position of the sun (option -D), the properties of the sensor (options -C, -P or -p) and the definition of the image (option -i). You can also enter the geometry of the ground (option -g) and its associated materials (option -M). Note that clouds and ground can be infinitely repeated along the X and Y axis (option -r and -R).

Four types of sensor are provided. The pinhole camera and the thin-lens camera (option -C) are used to calculate the image of the scene from a given viewpoint. Unlike these two cameras, the orthographic camera (option -P) uses parallel projection rather than perspective projection. Finally, the rectangular sensor (option -p) is used to calculate flux maps.

The spectral dimension can be integrated in various ways (option -s). When rendering an image (options -C and -P) the calculation is by default performed for the visible part of the spectrum between [380, 780] nanometers, for the three components of the CIE 1931 XYZ color space which are then recombined to obtain the final color for each pixel. The other method consists of explicitly defining the longwave or shortwave spectral range to be processed and continuously sampling a wavelength within this range. Longwave and shortwave are key words here meaning that the source of radiation is either internal or external to the medium. For short-wave images the radiance of the pixel is evaluated and stored at the output. For long-wave images this estimated radiance is then converted into brightness temperature and both are stored at the output. When calculating a flux map (option -p) the flux per pixel is stored in the output map regardless of whether the spectral range is longwave or shortwave.

In htrdr‑atmosphere the spatial unit 1.0 corresponds to one meter and temperatures are expressed in Kelvin. Estimated radiances are given in W/sr/m^2 except for monochromatic calculations where the calculated spectral radiance is defined in W/sr/m^2/nm. Flux densities are recorded in W/m^2. The results are written to the output file if the -o option is set and otherwise to standard output. The output image is a list of raw ASCII data formatted using the htrdr-image(5) file format.

htrdr‑atmosphere implements mixed parallelism. On a single computer (that is, a node), it uses shared memory parallelism while it relies on Message Passing Interface (MPI) to parallelize calculations between multiple nodes. htrdr‑atmosphere can therefore be launched either directly or via a process launcher such as mpirun(1) to distribute the calculation on several computers.

The options are as follows:

atmosphere
Optical properties of atmospheric gases saved in htgop format.
clouds
Cloud properties saved in htcp(5) format.
persp_camera_opt[:persp_camera_opt ...]
Set up a pinhole or thin-lens perspective camera.

The options for a perspective camera are as follows:

distance
Distance to focus on with a thin lens camera, that is, a camera whose lens-radius is not zero. The default focal distance is 1 meters.
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 set through the fov parameter.
angle
Vertical field of view of the camera in ]0.0, 180.0[ degrees. The default field of view is 70 degrees.
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. The default lens radius is 0.
x,y,z
Camera position. Default is 0,0,0.
x,y,z
Targeted position Default is 0,1,0.
x,y,z
Upward vector that the top of the camera is pointing towards. Default is 0,0,1.
sun_azimuth,sun_elevation
Direction toward the sun center. The direction is defined by two angles in degrees: the sun_azimuth angle in [0, 360[ and the sun_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 sun_azminuth,90 will produce (0,0,+1) regardless of sun_azimuth value.

Write to output the space partitioning data structures used to speed up cloud radiative transfer calculations. The data written are octrees saved in legacy VTK file format. Each octree node stores the minimum and maximum extinction coefficients of the cloud cells covered by the octree node. In the output file, each octree is separated from the previous one by a line containing three minus characters, i.e. ---.
Force overwriting of output file.
ground
Ground geometry saved in htrdr-obj(5) format.
Display short help and exit.
image_opt[:image_opt ...]
Configure sensor image.

The image options are as follows:

widthxheight
Image definition. Default is 320x240.
samples_per_pixel
Number of samples to solve the Monte Carlo estimation of each pixel. In normal image rendering, a pixel will be estimated with 3 * samples_per_pixel of Monte Carlo realisations, one set of samples_per_pixel for each X, Y and Z component of the CIE 1931 XYZ color space. In shortwave and longwave rendering or flux calculation, only one set of samples_per_pixel is used. By default, spp is set to 1.
Repeat the ground along the X and Y axes to infinity.
Repeat the clouds along the X and Y axes to infinity.
materials
Ground materials saved in htrdr-materials(5) format.
mie
Optical properties of water droplets saved in htmie(5) format.
sky_mtl
Name in the materials file representing the sky, i.e. the semi-transparent material. Default is "air".
cache
File where atmospheric acceleration structures are stored/loaded. If the cache file does not exist, it is created and filled with acceleration structures constructed from the clouds (option -c), atmosphere (option -a) and mie (option -m) input files. This cached data can then be reused in subsequent executions, provided that the input files supplied to the command are the same as those used to set up the cache, thus considerably speeding up the pre-processing stage.

If cache contains data generated from input files that are not those submitted on the command line, an error is notified and execution is aborted, thus avoiding the use of bad cached data.

Note that when the cache is used, htrdr‑atmosphere ignores the options used to build acceleration structures (options -T and -V).

output
Output file. If not defined, data is written to standard output.
ortho_camera_opt[:ortho_camera_opt ...]
Set up an orthographic camera.

The options for an orthographic camera are as follows:

lenght
Image plane height. Its width is calculated from this length and the image ratio to guarantee square pixels (see -i option).
x,y,z
Camera position. Default is 0,0,0.
x,y,z
Targeted position. Default is 0,1,0.
x,y,z
Upward vector that the top of the camera is pointing towards. Default is 0,0,1.
flux_sensor_opt[:flux_sensor_opt ...]
Set up a flux sensor. The flux is computed for the part of the sensor that is outside any geometry.

The flux sensor options are as follow:

x,y,z
Sensor center. Default is 0,0,0.
x,y,z
Targeted position. Default is 0,0,1.
x,y,z
Upward vector that the top of the sensor is pointing towards. Default is 0,1,0.
width,height
Sensor size in meters. Default is 1,1.
spectral_opt[:spectral_opt ...]
Configure spectral integration.

The spectral integration options are as follows:

Calculate the radiance for the visible part of the spectrum between [380, 780] nanometers using the XYZ CIE 1931 color matching functions. This is the default behavior.
wlen_min,wlen_max
Calculate the radiance using the internal source of radiation, i.e. the radiance emitted by the medium and its boundaries (ground and space).

Calculations are performed between [wlen_min, wlen_max] nanometers according to Planck's function for a reference temperature. As the application mainly concerns the earth's atmosphere, internal radiation is emitted in the thermal, longwave part of the electromagnetic spectrum. Consequently, the default reference temperature is set at 290 K.

If wlen_min and wlen_max are equal, the calculation is monochromatic.

wlen_min,wlen_max
Calculate the radiance using the external source of radiance, i.e. the sun.

Calculations are performed between [wlen_min, wlen_max] nanometers according to Planck's function for a reference temperature. As the application mainly concerns the earth's atmosphere, the default reference temperature is 5778 K, i.e. the temperature of the sun's black body.

If wlen_min and wlen_max are equal, the calculation is monochromatic.

temperature
Reference temperature when integrating with respect to the Planck function. The default value is 290 K or 5778 K, depending on whether the radiation source is internal (option lw) or external (option sw).
optical_thickness
Optical thickness used as threshold criterion for building acceleration structures. Default is 1. This option is ignored if a cache is used (option -O).
Advice on the number of threads to use. By default, htrdr‑atmosphere uses many threads as processor cores.
x,y,z
Maximum definition of acceleration structures. By default, the finest definition is that of clouds. This option is ignored if a cache is used (option -O).
Make htrdr‑atmosphere verbose.

Images calculated by htrdr‑atmosphere are saved in htrdr-image(5) format. This section describes the nature and arrangement of image data depending on the type of calculation performed.

For an image rendering in the visible part of the spectrum (default behavior or option -s cie_xyz), 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.

For infrared calculations (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.

For shortwave calculations (option -s sw=wlen_min,wlen_max) the output image is formatted as for a longwave image except that the first and second components of the pixels are not used, as no brightness temperature has been evaluated.

A flux density map (option -p) store on its first and second component the expected value and the standard error of the pixel radiative flux density (in W/m^2). 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.

The htrdr‑atmosphere utility exits 0 on success, and >0 if an error occurs.

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 -D 0,90 \
                 -a gas.txt \
                 -Rg quad.obj \
                 -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; it has been carefully designed to be cyclical and can therefore be repeated ad infinitum without visual glitches. Use the -f option to write the rendered image to output even though the file already exists. Use htpp(1) to convert the output htrdr-image(5) in a regular PPM image:

htrdr-atmosphere -D 0,90 \
                 -a gas.txt \
                 -Rg mountains.obj \
                 -M materials.mtl \
                 -c clouds.htcp \
                 -m Mie.nc \
                 -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
                 -i def=800x600:spp=64 \
                 -fo 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 \
                 -Rg mountains.obj -R \
                 -M materials.mtl \
                 -c clouds.htcp \
                 -m Mie.nc \
                 -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
                 -i def=800x600:spp=64 \
                 -s lw=9200,10000:Tref=300 \
                 -fo 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 of acceleration structures. Increase the image definition to 1280 by 720 pixels and set the number of samples per pixel component to 1024:

htrdr-atmosphere -D 120,40 \
                 -a gas.txt \
                 -Rg mountains.obj \
                 -M materials.mtl \
                 -c clouds.htcp \
                 -m Mie.nc \
                 -O my_cache \
                 -C pos=0,0,400:tgt=0,1,0:up=0,0,1 \
                 -i def=1280x720:spp=1024 \
                 -fo output

Compute the downward flux for the shortwave interval [350, 4000] nanometers on a square of 100 meters side positioned 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 -D 0,90 \
                 -a gas.txt \
                 -Rg plane.obj \
                 -M materials.mtl \
                 -c clouds.htcp \
                 -m Mie.nc \
                 -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 \
                 -fo flux_map.txt

Write cloud acceleration structures as output. Use csplit(1) to save each of them in a specific VTK file named octreeID, ID being between [0, N-1] and N being the total number of acceleration structures (N > 1):

htrdr-atmosphere -a gas.txt -m Mie.nc -c clouds.htcp -d -fo output
N="$(grep -ce "^# vtk" output)"
sed /^---$/d output \
| csplit -f octree -k - %^#\ vtk% /^#\ vtk/ {$((${N}-2))}

mpirun(1), htcp(5), htmie(5), htrdr-image(5), htrdr-materials(5), htrdr-obj(5)

|Méso|Star>, High-Tune: gas optical properties file format, https://www.meso-star.com/projects/htrdr/downloads/gas_opt_prop_en.pdf, November 2018.

Najda Villefranque, Richard Fournier, Fleur Couvreux, Stéphane Blanco, Céline Cornet, Vincent Eymet, Vincent Forest, and Jean-Marc Trégan, A Path-Tracing Monte Carlo library for 3-D Radiative Transfer in Highly Resolved Cloudy Atmospheres, Journal of Advances in Modeling Earth Systems, 8, 11, https://dx.doi.org/10.1029/2018MS001602, 2449-2473, 2019.

International Organization for Standardization / CIE, Colorimetry - Part 1: CIE standard colorimetric observers, ISO/CIE 11664-1:2019, June 2019.

OpenMP Architecture Review Board, OpenMP C and C++ Application Interface, March 2002, version 2.0.

Message Passing Interface Forum, MPI-2: Extensions to The Message-Passing Interface, July 1997.

htrdr‑atmosphere has been initially developed as part of ANR-16-CE01-0010 High-Tune project. It was then extended in MODEVAL-URBA 2019.

January 24, 2024 UNIX