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:

  1. Ground-reaching solar irradiance - Units are W / (cm^2 micron).

  2. 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.

  3. 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.

  4. 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.

Note 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.