NAME

htrdr‑planets — simulate radiative transfer in 3D planetary atmosphere

SYNOPSIS

DESCRIPTION

htrdr‑planets simulates the radiative transfer of a terrestrial planet in the visible or the infrared part of the spectrum. The planet's ground (option -G) can be any set of triangles with BRDFs and temperatures defined per triangle. The atmosphere is composed of a gas mixture (option -g) and a potentially empty set of aerosols (option -a). Both can have arbitrary tetrahedral meshes with per-node radiative properties. Rayleigh is used as a gas phase function. The temperature of the gas is defined on the mesh nodes. Aerosol phase functions (Henyey and Greenstein or user defined) are also defined per node.

htrdr‑planets is a renderer that calculates an image (option -i) for a given observation position (option -C). In addition to rendering images, it can also be used to estimate the volumic radiative budget for a set of tetrehedra (option -r). Its algorithms are based on Monte Carlo integration, which involves simulating a given number of optical paths for each estimate, taking into account light absorption and scattering phenomena. Thanks to the Monte Carlo, htrdr‑planets calculates not only the quantities of interest, but also their uncertainty (standard deviation of the distribution of weights) at no extra cost.

htrdr‑planets offers three ways to perform spectral integration (option -s). By default, it calculates an image for the visible part of the spectrum between 380 and 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 two methods are to explicitly define the longwave or shortwave spectral range to be integrated and continuously sample a wavelength in this range. In fact, longwave and shortwave are keywords that mean that the source of radiation is either internal or external to the medium, respectively. In shortwave, only radiance is evaluated and stored in the output image. For longwave rendering, this estimated radiance is then converted to brightness temperature and both are recorded in the image.

In htrdr‑planets, the spatial unit 1.0 corresponds to one meter and temperatures are expressed in Kelvin. The 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. Finally, the estimated volumic radiative budgets is given in W/m^3.

htrdr‑planets 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‑planets can therefore be launched either directly or via a process launcher such as mpirun(1) to distribute the rendering on several computers.

The options are as follows:

-a aerosol_opt[:aerosol_opt ...]

Define an aerosol. Use this option once per aerosol, and duplicate it as many times as necessary.

The aerosol options are as follows:

mesh=volume_mesh

Aerosol tetrahedral mesh saved in smsh(5) format.

name=string

Name assigned to the aerosol.

radprop=radiative_properties

Radiatve properties of the aerosol saved in sars(5) format. Radiative properties are defined per volumetric mesh node. This file and the tetrahedral mesh (option mesh) must therefore be consistent with each other, i.e. the nodes must be listed in the same order.

phasefn=phase_functions_list

List in rnsl(5) format of phase functions to be loaded. Each phase function is saved in rnsf(5) format. The correspondence between these phase functions and the nodes of the volumetric mesh is defined in another file (option phaseids).

phaseids=per_node_phase_function

Path to the rnpfi(5) file that stores the index of the phase function to be used per volumetric mesh node. The list of phase function is defined in another file (option phasefn). Note that this file and the tetrahedral mesh (option mesh) must be consistent with each other, i.e. the nodes must be listed in the same order.

-b accel_struct_build_opt[:accel_struct_build_opt ...]

Configure the building of the acceleration structures.

The acceleration structures building options are as follows:

def=definition

Advice on the definition of the atmospheric acceleration structures. Default is 512.

nthreads=threads_count

Advice on the number of threads to use. This number is different from that defined by the -t option, as the construction of acceleration structures is not based on the same parallelization model as Monte Carlo integration. This construction may not benefit from too many threads, on the contrary.

The default value is 8, i.e. a maximum of 8 threads are used to build acceleration structures.

proc=processes

This option is only used when htrdr‑planets is run with multiple processes (see mpirun(1)). It defines the processes that must build the acceleration structures.

The value all means that all processes build their own set of acceleration structures. This is the de facto configuration when no storage is used (i.e. the storage parameter is not set).

If acceleration structure storage is defined (storage parameter), a value of all should only be used if each process has its own disk space on which its own set of acceleration structures is stored. If processes share a common disk space, the value should be master. This means that only the main process builds the acceleration structures, which are in fine shared with the other processes by storing the saved acceleration structures on a common disk space.

The default value is master.

storage=accel_struct_file

File where atmospheric acceleration structures are stored/loaded.

If accel_struct_file does not exist, it is created and is used to store the built acceleration structures.

If accel_struct_file exists, acceleration structures are loaded from it rather than built from scratch, resulting in significant acceleration of the preprocessing step. Note that if the data structures stored in accel_struct_file are not as expected (that is, the input atmospheric data or construction parameters are different), an error is notified and execution is stopped, thus avoiding the use of incorrect acceleration structures.

By default, no storage file is used, i.e. acceleration structures are built from scratch and stored in memory.

tau=optical_thickness

Optical thickness used as threshold criterion for building the acceleration structures. Default is 1.

-C persp_camera_opt[:persp_camera_opt ...]

Set up a pinhole or thin-lens perspective camera.

The options for a perspective camera are as follows:

focal-dst=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.

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 set through the fov parameter.

fov=angle

Vertical field of view of the camera in ]0.0, 180.0[ degrees. The default field of view is 70 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. The default lens radius is 0.

pos=x,y,z

Camera position. Default is 0,0,0.

tgt=x,y,z

Targeted position Default is 0,1,0.

up=x,y,z

Upward vector that the top of the camera is pointing towards. Default is 0,0,1.

-d

Write atmospheric acceleration structures to output. Each structure is saved in legacy VTK format. To divide the resulting output into N files (N > 1), each storing an acceleration structure, one can use the csplit(1) command as below:

csplit -f octree -k output %^#\ vtk% /^#\ vtk/ \
       {$(($(grep -ce "^# vtk" output)-2))}

-f

Force overwriting of output file.

-G ground_opt[:ground_opt ...]

The planet's ground.

The ground options are as follows:

brdf=brdfs_list

List in rnsl(5) format of the BRDFs to be loaded. Each BRDF is saved in mrumtl(5) format. The correspondence between these BRDFs and the triangles of the surface mesh is defined in another file (option prop).

mesh=surface_mesh

Ground triangular mesh saved in smsh(5) format.

name=string

Name assigned to the ground.

prop=surface_properties

Ground surface properties, i.e. BRDF index and temperature, both defined by triangle. The list of BRDF is defined in another file (option brdf). Note that this file and the surface mesh must be consistent (option mesh), i.e. the triangles must be listed in the same order.

-g gas_opt[:gas_opt ...]

Gas mixture.

The gas options are as follows:

mesh=volumetric_mesh

Gas tetrahedral mesh saved in smsh(5) format.

ck=correlated_k

Correlated K fof the gas saved in sck(5) format. The correlated K are defined per volumetric mesh node. This file and the tetrahedral mesh (option mesh) must therefore be consistent with each other, i.e. the nodes must be listed in the same order.

temp=temperature

Gas temperatures saved in rngt(5) format. The temperature is defined per volumetric mesh node. This file and the tetrahedral mesh (option mesh) must therefore be consistent with each other, i.e. the nodes must be listed in the same order.

-h

Display short help and exit.

-i image_opt[:image_opt ...]

Configure sensor image.

The image options are as follows:

def=widthxheight

Image definition. Default is 320x240.

spp=samples_per_pixel

Number of samples to solve the Monte Carlo estimation of each pixel. Default is 1.

-N

Precalculate tetrahedron normals. This speeds up runtime performance by calculating normals once and for all rather than re-evaluating them every time a tetrahedron is queried at a given position. In return, the memory space used to store normals increases the memory footprint.

-o output

Output file. If not defined, data is written to standard output.

-P ortho_camera_opt[:ortho_camera_opt ...]

Set up an orthographic camera.

The options for an orthographic camera are as follows:

height=lenght

Image plane height. Its width is calculated from this length and the image ratio to guarantee square pixels (see -i option).

pos=x,y,z

Camera position. Default is 0,0,0.

tgt=x,y,z

Targeted position. Default is 0,1,0.

up=x,y,z

Upward vector that the top of the camera is pointing towards. Default is 0,0,1.

-r volrad_budget_opt[:volrad_budget_opt ...]

Define the calculation of the volumic radiative budget. Calculation is no longer a rendering: neither a camera (option -C) nor an image (option -i) is required.

The volumic radiative budget options are as follows:

mesh=volume_mesh

Tetrahedral mesh in smsh(5) format on which the volumic radiative budget is estimated per tetrahedron.

spt=samples_per_tetrahedron

Number of samples to estimate the volumic radiative budget of each tetrahedron. Default is 1000.

-S source_opt[:source_opt ...]

Define the external source.

The source options are as follows:

lat=latitude

The latitude of the source, i.e. its angle between [-90, 90] degrees about the Y axis. The default latitude of 0 is that of the X axis.

lon=longitude

The longitude of the source, i.e. its angle between [-180, 180] degrees about the Z axis. The default longitude of 0 is that of the X axis.

dst=distance

Distance in kilometers from source to origin. Default is 0.

rad=radiance_distribution

Source radiance distribution saved in rnrl(5) format. This option is not compatible with the temperature setting of the source (option temp) which also defines its radiance distribution.

radius=real

Source radius in kilometers.

temp=temperature

Source temperature in Kelvin. When this option is set, the radiance distribution of the source is Planck, at the specified temperature. This option is not compatible with the rad option that explicitly defines the source radiance distribution.

-s spectral_opt[:spectral_opt ...]

Configure spectral integration.

The spectral integration options are as follows:

cie_xyz

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.

lw=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 defined as the maximum ground temperature.

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

sw=wlen_min,wlen_max

Calculate the radiance using the external source of radiance (option -S).

Calculations are performed between [wlen_min, wlen_max] nanometers according to the radiance distribution of the external source (see -S option)

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

-t thread_count

Advice on the number of threads to use. By default, htrdr‑planets uses many threads as processor cores.

-v

Make htrdr‑planets verbose.

OUTPUT DATA

The output of htrdr‑planets depends on the type of calculation invoked. This section describes the nature and layout of these output data.

EXIT STATUS

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

EXAMPLES

An htrdr‑planets command line can be lengthy due to the options required to describe the system to be simulated. For editing reasons, the command lines given as examples in this section will take up several lines by using the backslash character (\). While there's nothing original about this practice, we'd like to emphasize the importance of spaces or their absence before the backslash character, particularly for options defining aerosols (option -a) or ground (option -G): their argument must be a single character string with no spaces other than those that may be required for file names.

The following command line runs htrdr‑planets in a verbose way (option -v) to calculate an 800 by 600 pixel image by sampling 64 radiative paths per pixel (option -i) for the 3 components of the CIE 1931 XYZ color space (option -s). The external source is positioned at -45 degrees longitude and 50 degrees latitude relative to the absolute referential (option -S). The camera (option -C) looks at the origin (tgt=0,0,0) and is positioned at 1.5e7 meters along the Y axis with an image plane aligned along the Z axis (up=0,0,1). Its vertical field of view is 70 degrees. The gas of the planetary atmosphere is described by the tetrahedral mesh recorded in the gas.smsh file, while its spectral data and temperature are given by the files gas.sck and gas.rngt, respectively. Two aerosols complete the planetary atmosphere: one for clouds and one for haze. Their respective meshes are stored in the clouds_tetrahedra.smsh and haze_tetrahedra.smsh files while their radiative properties are given by the clouds_properties.sars and haze_properties.sars files. Finally, their phase functions are described by a set of 2 files: the clouds_phase_functions.rnsf and haze_phase_functions.rnsf files which list the aerosol phase functions, and the clouds_phase_function_ids.rnpfi and haze_phase_function_ids.rnpfi files which reference them by volumetric mesh node. To speed up rendering time, the normals of the tetrahedral meshes of the gas and aerosols are precalculated once and for all (option -N). The ground geometry is stored in the ground_triangles.smsh file with its triangle properties (temperature and BRDF) defined in the ground_properties.rnsp file. The referenced BRDFs are listed in the ground_brdfs.rnsl file. The definition of acceleration structures cannot exceed 512^3 and its voxels can be merged until their optical thickness is greater than 10. These structures are either reloaded from storage_cie.bin or built from scratch and stored in storage_cie.bin depending on whether that file exists or not. Finally, the calculated images are stored in the image_CIE_XYZ.ht file even if the file already exists (options -fo):

htrdr-planets -v -N \
              -i def=800x600:spp=64 \
              -s cie_xyz \
              -S lon=-45:lat=50:dst=1.5e8:radius=6.9e5:temp=5778 \
              -C pos=0,1.5e7,0:tgt=0,0,0:up=0,0,1:fov=70 \
              -g mesh=gas.smsh:ck=gas.sck:temp=gas.rngt \
              -a name=clouds\
:mesh=clouds_tetrahedra.smsh\
:radprop=clouds_properties.sars\
:phasefn=clouds_phase_functions.rnsf\
:phaseids=clouds_phase_function_ids.rnpfi \
              -a name=haze\
:mesh=haze_tetrahedra.smsh\
:radprop=haze_properties.sars\
:phasefn=haze_phase_functions.rnsf\
:phaseids=haze_phase_function_ids.rnpfi \
              -G name=namek\
:mesh=ground_triangles.smsh\
:prop=ground_properties.rnsp\
:brdf=ground_brdfs.rnsl \
              -b def=512:tau=10:storage=storage_cie.bin \
              -fo image_CIE_XYZ.ht

The next command line is the same as the previous one, except that it calculates an infrared image between 10,000 nm and 20,000 nm (option -s). Note that the acceleration structure storage file is no longer the same (storage_lw.bin rather than storage_cie.bin). Indeed, the previous one records the acceleration structures for the spectral range of the CIE 1931 XYZ color space (i.e. between [380, 780] nm), while one wants to store/reload the acceleration structures for a spectral range between 10 and 20 microns. In any case, if the previous storage had been submitted, the command would have stopped with an error message, thus avoiding the use of the wrong acceleration structures:

htrdr-planets -v -N \
              -i def=800x600:spp=64 \
              -s lw=10000,20000 \
              -C pos=0,1.5e7,0:tgt=0,0,0:up=0,0,1:fov=70 \
              -g mesh=gas.smsh:ck=gas.sck:temp=gas.rngt \
              -a name=clouds\
:mesh=clouds_tetrahedra.smsh\
:radprop=clouds_properties.sars\
:phasefn=clouds_phase_functions.rnsf\
:phaseids=clouds_phase_function_ids.rnpfi \
              -a name=haze\
:mesh=haze_tetrahedra.smsh\
:radprop=haze_properties.sars\
:phasefn=haze_phase_functions.rnsf\
:phaseids=haze_phase_function_ids.rnpfi \
              -G name=namek\
:mesh=ground_triangles.smsh\
:prop=ground_properties.rnsp\
:brdf=ground_brdfs.rnsl \
              -b def=512:tau=10:storage=storage_lw.bin \
              -fo image_infrared.ht

SEE ALSO

htrdr-image(5), mrumtl(5), rngt(5), rnpfi(5), rnrl(5), rnsf(5), sars(5), sck(5), smsh(5)

STANDARDS

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.

HISTORY

htrdr‑planets has been developed as part of ANR-21-CE49-0020 RaD-net project.