htrdr 0.9.1

htrdr-planeto(1)

NAME

htrdr-planeto - simulate radiative transfer in 3D planetary atmosphere

SYNOPSIS

htrdr-planeto [option] ... -G ground -g gas

DESCRIPTION

htrdr-planeto 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 and 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-planeto is mainly a renderer that calculates an image (option -i) for a given observation position (option -C). Its internal rendering algorithm is based on Monte-Carlo integration, which consists for each pixel of simulating a given number of optical paths from the sensor, taking into account the phenomena of light absorption and scattering.

htrdr-planeto offers three ways to perform spectral integration (-s option). 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, and finally the entire image of the scene as seen from the observation position. 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-planeto, the spatial unit 1.0 corresponds to one meter and temperatures are expressed in Kelvin. The estimated radiances are given in W/sr/m², except for monochromatic calculations where the calculated spectral radiance is defined in W/sr/m²/nm.

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

OPTIONS

-a <aerosol-parameter:...>

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

mesh=path

Path to the smsh(5) file that stores the aerosol tetrahedral mesh.

name=string

Name assigned to the aerosol.

radprop=path

Path to the sars(5) file that stores the radiative properties of the aerosol. Radiative properties are defined per volumetric mesh node and, therefore, this file and the volumetric mesh file (see mesh parameter) must be consistent with each other.

phasefn=path

Path to the rnsl(5) file that lists the rnsf(5) files to load; each of these files stores an aerosol phase function. The phase function to be used per volumetric mesh node is defined in another file (see phaseids parameter).

phaseids=path

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 (see phasefn parameter). Note that this file must be consistent with the volumetric mesh defined in the mesh parameter.

-C <camera-parameter:...>

Configure 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 1 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 ]0.0, 180.0[ degrees. By default angle is set to 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. By default the lens radius is 0.

pos=x,y,z

Camera lens position. By default it is set to {0,0,0}.

tgt=x,y,z

Position targeted by the camera. By default it is set to {0,1,0}.

up=x,y,z

Up vector of the camera. By default it is set to {0,0,1}.

-d

Write atmospheric acceleration structures to output. Each structure is saved in VTK ASCII file format [1]. 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 overwrite the output file.

-G <ground-parameter:...>

Define the ground of the planet. Available ground parameters are:

brdf=path

Path to the rnsl(5) file that lists the mrumtl(5) files to load; each of these files stores a ground BRDF. The BRDF to be used per ground node is defined in another file (see prop parameter).

mesh=path

Path to the smsh(5) file which stores the triangular mesh of the ground.

name=string

Name assigned to the ground.

prop=path

Path to the rnsp(5) file that stores ground surface properties. The properties (BRDF index and temperature) are defined per triangle and, therefore, this file and the mesh file (see mesh parameter) must be consistent with each other.

-g <gas-parameter:...>

Define the gas mixture. Available gas parameters are:

mesh=path

Path to the smsh(5) file that stores the gas tetrahedral mesh.

ck=path

Path to the sck(5) file that stores the correlated K of the gas. The CKs are defined per volumetric mesh node and, therefore, this file and the volumetric mesh file (see mesh parameter) must be consistent with each other.

temp=path

Path to the rngt(5) file that stores the temperature of the gas. The temperature is defined per volumetric mesh node and, therefore, this file and the volumetric mesh file (see mesh parameter) must be consistent with each other.

-h

Display short help and exit.

-i <image-parameter:...>

Define the image to compute. Available image parameters are:

def=<width>x<height>

Image definition. By default the image definition is 320x240.

spp=samples-count

Number of samples to estimate one pixel, i.e. number of radiative paths sampled per pixel. By default, spp is set to 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 storage

File where atmospheric acceleration structures are stored/loaded. If storage does not exist, it is created and is used to store the built acceleration structures.

If storage 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 storage 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.

-o output

File to write the output data. The output data is either an image or atmospheric acceleration structures if the -d option is set. If it is not defined, the data is written to the standard output.

-S <source-parameter:...>

Define the external source. Available source parameters are:

lat=real

The latitude of the source, i.e. its angle between [-90, 90] degrees from the x-axis. The default latitude is set to 0.

lon=real

The longitude of the source, i.e. its angle between [-180, 180] degrees about the z-axis. The default longitude is set to 0.

dst=real

Distance in kilometers from source to origin. The default distance is 0.

rad=path

The path to the rnrl(5) file that stores the source radiance distribution. This option is not compatible with the temperature setting of the source (parameter temp) which also defines its radiance distribution.

rad=path

radius=real

Source radius in kilometers.

temp=real

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 parameter that explicitly defines the source radiance distribution.

-s <spectral-parameter:...>

Configure spectral integration. Available spectral parameters are:

cie_xyz

The radiance is calculated for the visible part of the spectrum between 380 nm and 780 nm by sampling the wavelength relative to the XYZ CIE 1931 color space. This is the default spectral integration.

lw=wlen-min,wlen-max

Perform continuous spectral sampling in the wavelength range [wlen-min, wlen-max] (wavelengths must be provided in nanometers) according to the Planck function for a reference temperature which is the maximum ground temperature, which is assumed to be the maximum scene temperature. If wlen-min and wlen-max are equal, the calculation is monochromatic. lw stands for "longwaves" but is only a keyword that actually refers to internal source (emitted within the medium, as opposed to external source like sun): in other words, radiation is emitted by the medium and its limits (ground and space).

sw=wlen-min,wlen-max

Perform continuous spectral sampling in the wavelength range [wlen-min, wlen-max] (wavelengths must be provided in nanometers) according to the Planck function for a reference temperatura which is the source temperature. If wlen-min and wlen-max are equal, the calculation is monochromatic. Here, sw means shortwaves, i.e. the radiation source is external to the medium (option -S).

-T optical-thickness

Optical thickness used as a criterion to construct atmospheric acceleration structures. Its default value is 1.

-t threads-count

Hint on the number of threads to use. Default assumes as many threads as CPU cores.

-V definition

Advice on the definition of the atmospheric acceleration structures. Its default value is 512.

-v

Make the command verbose.

OUTPUT IMAGE

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

XYZ image

For image rendering in the visible part of the spectrum (default behavior or when the -s cie_xyz option is set), each pixel stores 4 estimates, or 8 floating-point values. The first, second and third pairs of numbers store the estimated radiation in W/sr/m² for the X, Y, and Z components of the CIE 1931 XYZ color space. For each pair, the first corresponds to the expected value and the second its standard error. Finally, the fourth and last pair records the estimate of the calculation time in µs of a radiative path (expected value and standard error).

Longwave image

If the image is an infrared rendering (option -s lw=wlen-min,wlen-max), the first and second pixel values store the expected value and standard error of the estimated brightness temperature in Kelvin. The third and fourth values record the expected value and standard error of the estimated radiance, which is either integrated radiance in W/sr/m² or 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 values are not used and are therefore set to 0. Finally, the last 2 components of the pixel record the expected value and the standard error in µs of the calculation time per radiative path.

Shortwave image

For shortwave renderings (option -s sw=wlen-min,wlen-max), the image layout is the same as for infrared rendering, except for the first and second pixel values that are not used. That is, the third and fourth values record the estimated radiance per pixel and the seventh and eighth values store the estimate of the calculation time by radiative path. The other values are set to 0.

EXAMPLES

The following command line runs htrdr-planeto in a verbose way (option -v) to calculate an 800 by 600 pixel image by sampling 64 radiative paths per pixel for the 3 components of the CIE XYZ 1931 color space. The external source is positioned at -45 degrees longitude and 50 degrees latitude relative to the absolute referential. The camera 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 a<1|2>.smsh files while their radiative properties are given by the a<1|2>.sars files. Finally, their phase functions are described by a set of 2 files: the a<1|2>.rnsf file which lists the aerosol phase functions and the a<1|2>.rnpfi file which references 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.smsh file with its triangle properties (temperature and BRDF) defined in the ground.rnsp file. The referenced BRDFs are listed in the ground.rnsl file. The definition of acceleration structures cannot exceed 512³ 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 (option -f).

htrdr-planeto -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 mesh=a1.smsh:radprop=a1.sars:phasefn=a1.rnsf:phaseids=a1.rnpfi:name=clouds 
  -a mesh=a2.smsh:radprop=a2.sars:phasefn=a2.rnsf:phaseids=a2.rnpfi:name=haze 
  -G mesh=ground.smsh:prop=ground.rnsp:brdf=ground.rnsl:name=namek 
  -V 512 -T 10 -O storage_cie.bin 
  -f -o 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 XYZ color space, while one wants to store/reload the acceleration structures for a spectral range between 10 and 20 µm (see -O option). In any case, if the previous storage, incompatible with the current spectral range, had been submitted, the command would have stopped with an error message, thus avoiding the use of the wrong accelerartion structures.

htrdr-planeto -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 mesh=a1.smsh:radprop=a1.sars:phasefn=a1.rnsf:phaseids=a1.rnpfi:name=clouds 
  -a mesh=a2.smsh:radprop=a2.sars:phasefn=a2.rnsf:phaseids=a2.rnpfi:name=haze 
  -G mesh=ground.smsh:prop=ground.rnsp:brdf=ground.rnsl:name=namek 
  -V 512 -T 10 -O storage_lw.bin 
  -f -o image_infrared.ht

COPYRIGHT

Copyright © 2018-2019, 2022-2023 Centre National de la Recherche Scientifique
Copyright © 2020-2022 Institut Mines Télécom Albi-Carmaux
Copyright © 2022-2023 Institut Pierre-Simon Laplace
Copyright © 2022-2023 Institut de Physique du Globe de Paris
Copyright © 2018-2023 |Méso|Star> <contact@meso-star.com>
Copyright © 2022-2023 Observatoire de Paris
Copyright © 2022-2023 Université de Reims Champagne-Ardenne
Copyright © 2022-2023 Université de Versaille Saint-Quentin
Copyright © 2018-2019, 2022-2023 Université Paul Sabatier

LICENSE

htrdr-planeto 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.

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

OUTPUT IMAGE

XYZ image

Longwave image

Shortwave image

EXAMPLES

COPYRIGHT

LICENSE

SEE ALSO