commit 8cd9531c30cc844ad3e8ed3fd63a71c42f3ac94d
parent e8c6c02c26cce0c04e4dce4589ef852be8c39929
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 4 Oct 2023 16:53:04 +0200
Translate htrdr-planeto man page to mdoc
In the course of translation, its content has been updated. In
particular, we have added the missing "EXIT STATUS" section. References
to the MPI 2.0 and OpenMP 2.0 specifications have been added to the new
STANDARDS section, along with the ISO/CIE standard defining the CIE 1931
color space. The COPYRIGHT and LICENSE sections have been removed, as
they are not part of conventional Linux manuals (mandoc doesn't mention
them at all). Finally, the entire text has been revised to make it
clearer and more in line with mandoc conventions
Diffstat:
3 files changed, 634 insertions(+), 5 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -15,3 +15,4 @@ htrdr-atmosphere.1
htrdr-combustion
htrdr-combustion.1
htrdr-planeto
+htrdr-planeto.1
diff --git a/Makefile b/Makefile
@@ -575,8 +575,8 @@ install: all
$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man1" htrdr-atmosphere.1; fi
@if [ "$(COMBUSTION)" = "ENABLE" ]; then \
$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man1" htrdr-combustion.1; fi
-# @if [ "$(PLANETO)" = "ENABLE" ]; then \
-# $(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man1" htrdr-planeto.1; fi
+ @if [ "$(PLANETO)" = "ENABLE" ]; then \
+ $(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man1" htrdr-planeto.1; fi
uninstall:
rm -f "$(DESTDIR)$(PREFIX)/bin/htrdr"
@@ -589,7 +589,7 @@ uninstall:
rm -f "$(DESTDIR)$(PREFIX)/share/man/man1/htrdr.1"
rm -f "$(DESTDIR)$(PREFIX)/share/man/man1/htrdr-atmosphere.1"
rm -f "$(DESTDIR)$(PREFIX)/share/man/man1/htrdr-combustion.1"
-# rm -f "$(DESTDIR)$(PREFIX)/share/man/man1/htrdr-planeto.1"
+ rm -f "$(DESTDIR)$(PREFIX)/share/man/man1/htrdr-planeto.1"
# rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/htrdr-image.5"
# rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/htrdr-materials.5"
# rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/htrdr-obj.5"
@@ -598,7 +598,7 @@ uninstall:
################################################################################
# Man pages
################################################################################
-man: htrdr-atmosphere.1 htrdr-combustion.1
+man: htrdr-atmosphere.1 htrdr-combustion.1 htrdr-planeto.1
htrdr-atmosphere.1: htrdr-atmosphere.1.in
sed -e 's/@HTRDR_ATMOSPHERE_ARGS_DEFAULT_OPTICAL_THICKNESS_THRESHOLD@/$(HTRDR_ATMOSPHERE_ARGS_DEFAULT_OPTICAL_THICKNESS_THRESHOLD)/g' \
@@ -644,8 +644,24 @@ htrdr-combustion.1: htrdr-combustion.1.in
-e 's/@HTRDR_ARGS_DEFAULT_RECTANGLE_SZ@/$(HTRDR_ARGS_DEFAULT_RECTANGLE_SZ)/g'\
$@.in > $@
+htrdr-planeto.1: htrdr-planeto.1.in
+ sed -e 's/@HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MIN@/$(HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MIN)/g' \
+ -e 's/@HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MAX@/$(HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MAX)/g' \
+ -e 's/@HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOCAL_DST@/$(HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOCAL_DST)/g' \
+ -e 's/@HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOV@/$(HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOV)/g' \
+ -e 's/@HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_LENS_RADIUS@/$(HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_LENS_RADIUS)/g' \
+ -e 's/@HTRDR_ARGS_DEFAULT_CAMERA_POS@/$(HTRDR_ARGS_DEFAULT_CAMERA_POS)/g' \
+ -e 's/@HTRDR_ARGS_DEFAULT_CAMERA_TGT@/$(HTRDR_ARGS_DEFAULT_CAMERA_TGT)/g' \
+ -e 's/@HTRDR_ARGS_DEFAULT_CAMERA_UP@/$(HTRDR_ARGS_DEFAULT_CAMERA_UP)/g' \
+ -e 's/@HTRDR_ARGS_DEFAULT_IMG_WIDTH@/$(HTRDR_ARGS_DEFAULT_IMG_WIDTH)/g' \
+ -e 's/@HTRDR_ARGS_DEFAULT_IMG_HEIGHT@/$(HTRDR_ARGS_DEFAULT_IMG_HEIGHT)/g' \
+ -e 's/@HTRDR_ARGS_DEFAULT_IMG_SPP@/$(HTRDR_ARGS_DEFAULT_IMG_SPP)/g' \
+ -e 's/@HTRDR_PLANETO_ARGS_DEFAULT_OPTICAL_THICKNESS_THRESHOLD@/$(HTRDR_PLANETO_ARGS_DEFAULT_OPTICAL_THICKNESS_THRESHOLD)/g' \
+ -e 's/@HTRDR_PLANETO_ARGS_DEFAULT_GRID_DEFINITION_HINT@/$(HTRDR_PLANETO_ARGS_DEFAULT_GRID_DEFINITION_HINT)/g' \
+ $@.in > $@
+
clean_man:
- rm -f htrdr-atmosphere.1 htrdr-combustion.1
+ rm -f htrdr-atmosphere.1 htrdr-combustion.1 htrdr-planeto.1
################################################################################
# Miscellaneous targets
@@ -670,9 +686,11 @@ distclean:\
distclean_combustion\
distclean_planeto\
distclean_core\
+ clean_man
lint: htrdr-atmosphere.1
shellcheck -o all make.sh
mandoc -Tlint -Wall htrdr.1 || [ $$? -le 1 ]
mandoc -Tlint -Wall htrdr-atmosphere.1 || [ $$? -le 1 ]
mandoc -Tlint -Wall htrdr-combustion.1 || [ $$? -le 1 ]
+ mandoc -Tlint -Wall htrdr-planeto.1 || [ $$? -le 1 ]
diff --git a/htrdr-planeto.1.in b/htrdr-planeto.1.in
@@ -0,0 +1,610 @@
+.\" Copyright (C) 2018-2019, 2022-2023 Centre National de la Recherche Scientifique
+.\" Copyright (C) 2020-2022 Institut Mines Télécom Albi-Carmaux
+.\" Copyright (C) 2022-2023 Institut Pierre-Simon Laplace
+.\" Copyright (C) 2022-2023 Institut de Physique du Globe de Paris
+.\" Copyright (C) 2018-2023 |Méso|Star> (contact@meso-star.com)
+.\" Copyright (C) 2022-2023 Observatoire de Paris
+.\" Copyright (C) 2022-2023 Université de Reims Champagne-Ardenne
+.\" Copyright (C) 2022-2023 Université de Versaille Saint-Quentin
+.\" Copyright (C) 2018-2019, 2022-2023 Université Paul Sabatier
+.\"
+.\" This program is free software: you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
+.Dd October 4, 2023
+.Dt HTRDR-PLANETO 1
+.Os
+.Sh NAME
+.Nm htrdr-planeto
+.Nd simulate radiative transfer in 3D planetary atmosphere
+.Sh SYNOPSIS
+.Nm
+.Op Fl dfhNv
+.Op Fl a Ar aerosol_opt Ns Op : Ns Ar aerosol_opt ...
+.Op Fl C Ar persp_camera_opt Ns Op : Ns Ar persp_camera_opt ...
+.Op Fl G Ar ground_opt Ns Op : Ns Ar ground_opt ...
+.Op Fl i Ar image_opt Ns Op : Ns Ar image_opt ...
+.Op Fl O Pa accel_struct_storage
+.Op Fl o Pa output
+.Op Fl S Ar source_opt Ns Op : Ns Ar source_opt ...
+.Op Fl s Ar spectral_opt Ns Op : Ns Ar spectral_opt ...
+.Op Fl T Ar optical_thickness
+.Op Fl t Ar threads_count
+.Op Fl V Ar accel_struct_definition
+.Fl g Ar gas_opt Ns Op : Ns Ar gas_opt ...
+.Sh DESCRIPTION
+.Nm
+simulates the radiative transfer of a terrestrial planet in the visible
+or the infrared part of the spectrum.
+The planet's ground
+.Pq option Fl G
+can be any set of triangles with BRDFs and temperatures defined per triangle.
+The atmosphere is composed of a gas mixture
+.Pq option Fl g
+and a potentially empty set of aerosols
+.Pq option Fl 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
+.Pq Henyey and Greenstein or user defined
+are also defined per node.
+.Pp
+.Nm
+is mainly a renderer that calculates an image
+.Pq option Fl i
+for a given observation position
+.Pq option Fl 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.
+.Pp
+.Nm
+offers three ways to perform spectral integration
+.Pq option Fl 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.
+.Pp
+In
+.Nm ,
+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.
+.Pp
+.Nm
+implements mixed parallelism.
+On a single computer
+.Pq that is, a node ,
+it uses shared memory parallelism while it relies on Message Passing
+Interface (MPI) to parallelize calculations between multiple nodes.
+.Nm
+can therefore be launched either directly or via a process
+launcher such as
+.Xr mpirun 1
+to distribute the rendering on several computers.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl a Ar aerosol_opt Ns Op : Ns Ar aerosol_opt ...
+Define an aerosol.
+Use this option once per aerosol, and duplicate it as many times as
+necessary.
+.Pp
+The aerosol options are as follows:
+.Bl -tag -width Ds
+.It Cm mesh= Ns Pa volumetric_mesh
+Aerosol tetrahedral mesh saved in
+.Xr smsh 5
+format.
+.It Cm name= Ns Ar string
+Name assined to the aerosol.
+.It Cm radprop= Ns Pa radiative_properties
+Radiatve properties of the aerosol saved in
+.Xr sars 5
+format.
+Radiative properties are defined per volumetric mesh node.
+This file and the tetrahedral mesh
+.Pq option Cm mesh
+must therefore be consistent with each other, i.e. the nodes must be
+listed in the same order.
+.It Cm phasefn= Ns Pa phase_functions_list
+List in
+.Xr rnsl 5
+format of phase functions to be loaded.
+Each phase function is saved in
+.Xr rnsf 5
+format.
+The correspondence between these phase functions and the nodes of the
+volumetric mesh is defined in another file
+.Pq option Cm phaseids .
+.It Cm phaseids= Ns Pa per_node_phase_function
+Path to the
+.Xr 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
+.Pq option Cm phasefn .
+Note that this file and the tetrahedral mesh
+.Pq option Cm mesh
+must be consistent with each other, i.e. the nodes must be
+listed in the same order.
+.El
+.It Fl C Ar persp_camera_opt Ns Op : Ns Ar persp_camera_opt ...
+Set up a pinhole or thin-lens perspective camera.
+.Pp
+The options for a perspective camera are as follows:
+.Bl -tag -width Ds
+.It Cm focal-dst= Ns Ar distance
+Distance to focus on with a thin lens camera, that is, a camera whose
+.Cm lens-radius
+is not zero.
+The default focal distance is
+@HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOCAL_DST@ meters.
+.It Cm focal-length= Ns Ar 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
+.Cm fov
+parameter.
+.It Cm fov= Ns Ar angle
+Vertical field of view of the camera in
+]@HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MIN@,
+@HTRDR_ARGS_CAMERA_PERSPECTIVE_FOV_EXCLUSIVE_MAX@[ degrees.
+The default field of view is
+@HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_FOV@ degrees.
+.It Cm lens-radius= Ar 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
+@HTRDR_ARGS_DEFAULT_CAMERA_PERSPECTIVE_LENS_RADIUS@.
+.It Cm pos= Ns Ar x , Ns Ar y , Ns Ar z
+Camera position.
+Default is @HTRDR_ARGS_DEFAULT_CAMERA_POS@.
+.It Cm tgt= Ns Ar x , Ns Ar y , Ns Ar z
+Targeted position
+Default is @HTRDR_ARGS_DEFAULT_CAMERA_TGT@.
+.It Cm up= Ns Ar x , Ns Ar y , Ns Ar z
+Upward vector that the top of the camera is pointing towards.
+Default is @HTRDR_ARGS_DEFAULT_CAMERA_UP@.
+.El
+.It Fl d
+Write atmospheric acceleration structures to
+.Pa output .
+Each structure is saved in legacy VTK format.
+To divide the resulting output into N files
+.Pq N > 1 ,
+each storing an acceleration structure, one can use the
+.Xr csplit 1
+command as below:
+.Bd -literal -offset Ds
+csplit -f octree -k output %^#\\ vtk% /^#\\ vtk/ \\
+ {$(($(grep -ce "^# vtk" output)-2))}
+.Ed
+.It Fl f
+Force overwriting of
+.Pa output
+file.
+.It Fl G Ar ground_opt Ns Op : Ns Ar ground_opt ...
+The planet's ground.
+.Pp
+The ground options are as follows:
+.Bl -tag -width Ds
+.It Cm brdf= Ns Pa brdfs_list
+List in
+.Xr rnsl 5
+format of the BRDFs to be loaded.
+Each BRDF is saved in
+.Xr mrumtl 5
+format.
+The correspondence between these BRDFs and the triangles of the surface
+mesh is defined in another file
+.Pq option Cm prop .
+.It Cm mesh= Ns Pa surface_mesh
+Ground triangular mesh saved in
+.Xr smsh 5
+format.
+.It Cm name= Ns Ar string
+Name assigned to the ground.
+.It Cm prop= Ns Ar surface_properties
+Ground surface properties, i.e. BRDF index and temperature, both defined
+by triangle.
+The list of BRDF is defined in another file
+.Pq option Cm brdf .
+Note that this file and the surface mesh must be consistent
+.Pq option Cm mesh ,
+i.e. the triangles must be listed in the same order.
+.El
+.It Fl g Ar gas_opt Ns Op : Ns Ar gas_opt ...
+Gas mixture.
+.Pp
+The gas options are as follows:
+.Bl -tag -width Ds
+.It Cm mesh= Ns Pa volumetric_mesh
+Gas tetrahedral mesh saved in
+.Xr smsh 5
+format.
+.It Cm ck= Ns Pa correlated_k
+Correlated K fof the gas saved in
+.Xr sck 5
+format.
+The correlated K are defined per volumetric mesh node.
+This file and the tetrahedral mesh
+.Pq option Cm mesh
+must therefore be consistent with each other, i.e. the nodes must be
+listed in the same order.
+.It Cm temp= Ns Pa temperature
+Gas temperatures saved in
+.Xr rngt 5
+format.
+The temperature is defined per volumetric mesh node.
+This file and the tetrahedral mesh
+.Pq option Cm mesh
+must therefore be consistent with each other, i.e. the nodes must be
+listed in the same order.
+.El
+.It Fl h
+Display short help and exit.
+.It Fl i Ar image_opt Ns Op : Ns Ar image_opt ...
+Configure sensor image.
+.Pp
+The image options are as follows:
+.Bl -tag -width Ds
+.It Cm def= Ns Ar width Ns x Ns Ar height
+Image definition.
+Default is
+@HTRDR_ARGS_DEFAULT_IMG_WIDTH@x@HTRDR_ARGS_DEFAULT_IMG_HEIGHT@.
+.It Cm spp= Ns Ar samples_per_pixel
+Number of samples to solve the Monte Carlo estimation of each pixel.
+Default is @HTRDR_ARGS_DEFAULT_IMG_SPP@.
+.El
+.It Fl 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.
+.It Fl O Pa accel_struct_storage
+File where atmospheric acceleration structures are stored/loaded.
+.Pp
+If
+.Pa accel_struct_storage
+does not exist, it is created and is used to store the built
+acceleration structures.
+.Pp
+If
+.Pa accel_struct_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
+.Pa accel_struct_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.
+.It Fl o Pa output
+Output file.
+If not defined, data is written to standard output.
+.It Fl S Ar source_opt Ns Op : Ns Ar source_opt ...
+Define the external source.
+.Pp
+The source options are as follows:
+.Bl -tag -width Ds
+.It Cm lat= Ns Ar latitude
+The latitude of the source, i.e. its angle between
+.Bq -90, 90
+degrees about the Y axis.
+The default latitude of 0 is that of the X axis.
+.It Cm lon= Ns Ar 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.
+.It Cm dst= Ns Ar distance
+Distance in kilometers from source to origin.
+Default is 0.
+.It Cm rad= Ns Ar radiance_distribution
+Source radiance distribution saved in
+.Xr rnrl 5
+format.
+This option is not compatible with the temperature setting of the source
+.Pq option Cm temp
+which also defines its radiance distribution.
+.It Cm radius= Ns Ar real
+Source radius in kilometers.
+.It Cm temp= Ns Ar 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
+.Cm rad
+option that explicitly defines the source radiance distribution.
+.El
+.It Fl s Ar spectral_opt Ns Op : Ns Ar spectral_opt ...
+Configure spectral integration.
+.Pp
+The spectral integration options are as follows:
+.Bl -tag -width Ds
+.It Cm cie_xyz
+Calculate the radiance for the visible part of the spectrum between
+.Bq 380, 780
+nanometers using the XYZ CIE 1931 color matching functions.
+This is the default behavior.
+.It Cm lw= Ns Ar wlen_min , Ns Ar 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).
+.Pp
+Calculations are performed between
+.Bq Ar wlen_min , Ar wlen_max
+nanometers according to Planck's function for a reference temperature
+defined as the maximum ground temperature.
+.Pp
+If
+.Ar wlen_min
+and
+.Ar wlen_max
+are equal, the calculation is monochromatic.
+.It Cm sw= Ns Ar wlen_min , Ns Ar wlen_max
+Calculate the radiance using the external source of radiance
+.Pq option Fl S .
+.Pp
+Calculations are performed between
+.Bq Ar wlen_min , Ar wlen_max
+nanometers according to the radiance distribution of the external
+source
+.Pq see Fl S No option
+.Pp
+If
+.Ar wlen_min
+and
+.Ar wlen_max
+are equal, the calculation is monochromatic.
+.El
+.It Fl T Ar optical_thickness
+Optical thickness used as threshold criterion for building the acceleration
+structures.
+Default is @HTRDR_PLANETO_ARGS_DEFAULT_OPTICAL_THICKNESS_THRESHOLD@.
+.It Fl t
+Advice on the number of threads to use.
+By default,
+.Nm
+uses many threads as processor cores.
+.It Fl V Ar accel_struct_definition
+Advice on the definition of the atmospheric acceleration structures.
+Default is @HTRDR_PLANETO_ARGS_DEFAULT_GRID_DEFINITION_HINT@.
+.It Fl v
+Make
+.Nm
+verbose.
+.El
+.Sh OUTPUT IMAGE
+Images calculated by
+.Nm
+are saved in
+.Xr htrdr-image 5
+format.
+This section describes the nature and arrangement of image data
+depending on the type of calculation performed.
+.Ss XYZ image
+For an image rendering in the visible part of the spectrum
+.Pq default behavior or option Fl s Cm 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.
+.Ss Longwave image
+For infrared calculations
+.Pq option Fl s Cm lw= Ns Ar wlen_min , Ns Ar 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.
+.Ss Shortwave image
+For shortwave calculations
+.Pq option Fl s Cm sw= Ns Ar wlen_min , Ns Ar 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.
+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.
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+The following command line runs
+.Nm
+in a verbose way
+.Pq option Fl v
+to calculate an
+.Ar 800 No by Ar 600
+pixel image by sampling
+.Ar 64
+radiative paths per pixel
+.Pq option Fl i
+for the 3 components of the CIE 1931 XYZ color
+space
+.Pq option Fl s .
+The external source is positioned at
+.Ar -45
+degrees longitude and
+.Ar 50
+degrees latitude relative to the absolute referential
+.Pq option Fl S .
+The camera
+.Pq option Fl C
+looks at the origin
+.Pq Cm tgt= Ns Ar 0 , Ns Ar 0 , Ns Ar 0
+and is positioned at
+.Ar 1.5e7
+meters along the Y axis with an image plane aligned along the Z axis
+.Pq Cm up= Ns Ar 0 , Ns Ar 0 , Ns Ar 1 .
+Its vertical field of view is
+.Ar 70
+degrees.
+The gas of the planetary atmosphere is described by the tetrahedral mesh
+recorded in the
+.Pa gas.smsh
+file, while its spectral data and temperature are given by the files
+.Pa gas.sck
+and
+.Pa gas.rngt ,
+respectively.
+Two aerosols complete the planetary atmosphere: one for
+.Ar clouds
+and one for
+.Ar haze .
+Their respective meshes are stored in the
+.Pa a.smsh No and Pa b.smsh
+files while their radiative properties are given by the
+.Pa a.sars No and Pa b.sars
+files.
+Finally, their phase functions are described by a set of 2 files: the
+.Pa a.rnsf No and Pa b.rnsf
+files which list the aerosol phase functions,
+and the
+.Pa a.rnpfi No and Pa b.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
+.Pq option Fl N .
+The ground geometry is stored in the
+.Pa ground.smsh
+file with its triangle properties
+.Pq temperature and BRDF
+defined in the
+.Pa ground.rnsp
+file.
+The referenced BRDFs are listed in the
+.Pa ground.rnsl
+file.
+The definition of acceleration structures
+cannot exceed
+.Ar 512^3
+and its voxels can be merged until their optical thickness
+is greater than
+.Ar 10 .
+These structures are either reloaded from
+.Pa storage_cie.bin
+or built from scratch and stored in
+.Pa storage_cie.bin
+depending on whether that file exists or not.
+Finally, the calculated images are
+stored in the
+.Pa image_CIE_XYZ.ht
+file even if the file already exists
+.Pq options Fl fo :
+.Bd -literal -offset Ds
+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=a.smsh:radprop=a.sars:phasefn=a.rnsf:phaseids=a.rnpfi:name=clouds \\
+-a mesh=b.smsh:radprop=b.sars:phasefn=b.rnsf:phaseids=b.rnpfi:name=haze \\
+-G mesh=ground.smsh:prop=ground.rnsp:brdf=ground.rnsl:name=namek \\
+-V 512 -T 10 -O storage_cie.bin \\
+-fo image_CIE_XYZ.ht
+.Ed
+.Pp
+The next command line is the same as the previous one, except that it calculates
+an infrared image between
+.Ar 10,000
+nm and
+.Ar 20,000
+nm
+.Pq option Fl s .
+Note that the acceleration structure storage file is no longer the same
+.Pq Pa storage_lw.bin No rather than Pa storage_cie.bin .
+Indeed, the previous one records the acceleration structures for the
+spectral range of the CIE 1931 XYZ color space
+.Pq i.e. between Bo 380, 780 Bc 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
+.Pq see Fl O No option .
+.Bd -literal -offset Ds
+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=a.smsh:radprop=a.sars:phasefn=a.rnsf:phaseids=a.rnpfi:name=clouds \\
+-a mesh=b.smsh:radprop=b.sars:phasefn=b.rnsf:phaseids=b.rnpfi:name=haze \\
+-G mesh=ground.smsh:prop=ground.rnsp:brdf=ground.rnsl:name=namek \\
+-V 512 -T 10 -O storage_lw.bin \\
+-fo image_infrared.ht
+.Ed
+.Sh SEE ALSO
+.Xr htrdr-image 5 ,
+.Xr mrumtl 5 ,
+.Xr rngt 5 ,
+.Xr rnpfi 5 ,
+.Xr rnrl 5 ,
+.Xr rnsf 5 ,
+.Xr sars 5 ,
+.Xr sck 5 ,
+.Xr smsh 5
+.Sh STANDARDS
+.Rs
+.%A International Organization for Standardization / CIE
+.%R ISO/CIE 11664-1:2019
+.%D June 2019
+.%T Colorimetry - Part 1: CIE standard colorimetric observers
+.Re
+.Pp
+.Rs
+.%A OpenMP Architecture Review Board
+.%D March 2002
+.%T OpenMP C and C++ Application Interface
+.%O version 2.0
+.Re
+.Pp
+.Rs
+.%A Message Passing Interface Forum
+.%D July 1997
+.%T MPI-2: Extensions to The Message-Passing Interface
+.Re
+.Sh HISTORY
+.Nm
+has been developed as part of
+.Li ANR-21-CE49-0020
+RaD-net project.
