Summary
The FourCurveAtmosphere
plugin was created to provide a lightweight,
physics-driven but lower fidelity atmospheric modeling capability in
DIRSIG5. Simulations requiring a full model of the atmosphere should
use the NewAtmosphere
plugin. However, if that level of fidelity
is not required, then this plugin may serve as an option that
requires less computation to be spent on atmospheric calculations.
This capability is currently divided into two major components:
-
The fourcurve_builder tool, which interfaces with the externally developed physics-based atmospheric models to construct an HDF database of atmospheric data tables.
-
The FourCurveAtmosphere plugin, which uses the HDF atmospheric database to drive the atmospheric contributions in a DIRSIG5 execution.
Four Curve Model
This plugin models the atmosphere through 4 spectral curves, which are all a function of the solar declination (or zenith) angle. The four curves are:
-
Ground-reaching solar irradiance - Units are
W / (cm^2 micron)
. -
Path radiance per meter - Units are
W / (cm^2 sr m micron)
. Since this plugin does not account for view geometry, this is modeled along a vertical path and applied at all angles. -
Path extinction per meter - Units are
1 / m.
. Since this plugin does not account for view geometry, this is modeled along a vertical path and applied at all angles. -
Hemispherical sky irradiance - Units are
W / (cm^2 micron)
.
Data Model
The data model for this plugin is fairly straightforward. A single database
can contain one or more atmospheric conditions (conditions
). A set of
conditions
captures a specific combination of atmospheric state variables,
including air temperature, air pressure, humidity, aerosol type and aerosol
densities distributions within the atmosphere. All conditions
in a database
share a set of spectral samples
that define the wavelengths at which the
spectral curves are sampled and a set of solar declination samples
that define
the solar declination angles at which the four curves are modeled.
Each conditions
in that database
has a distinct and non-null name
. Then
for each angle in the solar declination samples
, there is a set of four
spectral curves
, which were described in the
Four Curve Model section. Each spectral curve
has a value
for every wavelength in the spectral samples
.
The data model can currently be stored in an HDF5 database file. The interface control document for this file can be found here.
Plugin Input
The inputs to the plugin is a JSON object that is embedded directly into the
JSIM file where the plugin is requested (via the inputs
section). Below is a generalized example of the JSON object:
{ "database": "atm.hdf", "conditions": "mls_rural_5km_dis8.tp5" "ephemeris": { "type": "cspice" } }
In this example, database
is the path to a file containing the data model.
If the database
is not provided, then the default database will be used
(see below). The conditions
variable contains the name of the atmospheric
conditions inside of the database to use for defining the curves, as only
one can be used in a single simulation.
Finally, ephemeris
is an EphemerisConfig
JSON object that specifies what
ephemeris model to use. Normally, the 'cspice' type is used, but a fixed
ephemeris can also be specified like:
"ephemeris": { "type": "fixed", "parameters": { "sun": { "zenith": 0.2, "azimuth": 0.4 } } }
Default Database
Each DIRSIG release includes a default database that contains a
variety of conditions. This database is stored in
$DIRSIG_HOME/lib/data/atm
and a more detailed README file is
located there with details about the database. The default database
contains 30 separate atmospheric conditions, encompassing the
permutations of the following three main variables:
- Profiles
-
Tropical, Mid-Latitude Summer (MLS) and Mid-Latitude Winter (MLW)
- Aerosols
-
Rural and Urban aerosols
- Visibilities
-
5, 10, 15, 30 and 50 km
The corresponding condition names are:
-
Mid-Latitude Summer (MLS,) Rural aerosols
-
mls_rural_5km
-
mls_rural_10km
-
mls_rural_15km
-
mls_rural_30km
-
mls_rural_50km
-
-
Mid-Latitude Summer (MLS,) Urban aerosols
-
mls_urban_5km
-
mls_urban_10km
-
mls_urban_15km
-
mls_urban_30km
-
mls_urban_50km
-
-
Mid-Latitude Winter (MLW), Rural aerosols
-
mlw_rural_5km
-
mlw_rural_10km
-
mlw_rural_15km
-
mlw_rural_30km
-
mlw_rural_50km
-
-
Mid-Latitude Winter (MLW), Urban aerosols
-
mlw_urban_5km
-
mlw_urban_10km
-
mlw_urban_15km
-
mlw_urban_30km
-
mlw_urban_50km
-
-
Tropical, Rural aerosols
-
trop_rural_5km
-
trop_rural_10km
-
trop_rural_15km
-
trop_rural_30km
-
trop_rural_50km
-
-
Tropical, Urban aerosols
-
trop_urban_5km
-
trop_urban_10km
-
trop_urban_15km
-
trop_urban_30km
-
trop_urban_50km
-
Producing a Database
Included in the DIRSIG distribution is a program called fourcurve_builder
that can be used to generate HDF databases. The input for this program is a
JSON object that can either be given in an input file via the -i
or --input
flags or through the standard input stream. An example of the JSON object is
given below:
{ "bandpass" : { "units" : "microns", "minimum" : 0.380, "maximum" : 2.520, "delta" : 0.001 }, "backend" : { "name": "modtran_tape", "modtran_profile": "MODTRAN4", "tape5_filenames": [ "tp5/mls_rural_5km.tp5", "tp5/mls_rural_10km.tp5", "tp5/mls_rural_25km.tp5" ] } }
The bandpass
defines the spectral range and sampling that the database
fill be created for.
The backend
object is identical to the
NewAtmosphere input JSON and specifies what backend
model to use to generate the curves. When using MODTRAN, a list of tape5 files
is given as input and each tape5 results in a set of conditions, with the path
becoming the name of conditions.
![]() |
Since HDF does not allow slashes in data set or group names, all slashes
(/ ) are replaced by colons (: ).
|
For more details, see the command-line help for fourcurve_builder
.
Demos
The FourCurveAtm1
demo contains a simple demonstration of how to use both the
plugin and fourcurve_builder
. It contains the above example of
fourcurve_builder
JSON in the atm.json
file and produces a video of a simple
scene over the course of a day to show how the atmosphere varies as a function
of solar declination angle.