Keywords: FourCurveAtmosphere

Summary

This example shows how to use the simplified atmosphere representation in the FourCurveAtmosphere plugin. The main simulation included is a video over the course of a single day of the scene from the BundledObject1 demo to show how the atmospheric effects vary as a function of solar declination angle. This demo also highlights a feature of the FourCurveAtmosphere plugin, which is that DIRSIG is distributed with a pre-built database of atmospheric conditions. This demo will also cover how to create your own atmospheric database to be used by the plugin.

Important
 The BundledObject1 scene used in this demo uses material and texture maps that are defined in the material database file, and the Material Database Editor does not understand how to handle these (yet). If you open and save the various material files used in this demo, these map configurations will be lost. These material configurations must be manually edited at this time.

Details

DIRSIG5 introduces a new, low-fidelity atmospheric representation that characterizes the atmosphere through four curves. The four curves are:

  • Ground-reaching solar irradiance

  • Path radiance per meter

  • Path extinction per meter

  • Integrated hemispherical sky irradiance

All four of these curves are a function of solar declination angle. This demo is responsible for showing the effects of this plugin, as well as how to create a FourCurveAtmosphere database through the use of the fourcurve_builder tool.

Important Files

Atmospheric Databases

The FourCurveAtmosphere plugin has two options for the atmospheric database to use: (1) the default database and (2) a user created database.

The Default Atmospheric Database

Each DIRSIG5 release includes a pre-built atmospheric database for the FourCurveAtmosphere atmosphere. This database is stored in the $DIRSIG_HOME/lib/data/atm folder, which contains not only the HDF database file, but also the input files used to create the database and a README describing the conditions contained in the database. At the time of this writing, the database contains 30 permutations of profiles (tropical, MLS and MLW), aerosol models (rural and urban) and visibilities (5, 10, 15, 25 and 50 km).

Making Your Own Atmospheric Database

The user can also make their own database, using the fourcurve_builder utility. This program uses the same backend capabilities as the atm_builder, which means you can currently configure it to run with a variety of MODTRAN releases (see the NewAtm Toolchain Manual for more details). The fourcurve_builder utility requires a JSON configuration file, that contains the atmospheric model backend configuration and the conditions to be modeled. An example JSON configuration file is included in this demo (see the user_defined_atm.json file). The contents of this file are shown below:

The user_defined_atm.json file.
{
  "backend": {
    "name": "modtran_tape",
    "modtran_profile": "MODTRAN4"
  },
  "bandpass" : {
    "units"   : "microns",
    "minimum" : 0.380,
    "maximum" : 1.200,
    "delta"   : 0.001
  },
  "relative_azimuth_samples" : [ 0, 5, 15, 30, 45, 90, 120, 150, 165, 175, 180 ],
  "conditions": [
    {
      "name": "mls_rural_5km",
      "backend_input": {
        "tape5_filename": "tp5/mls_rural_5km.tp5"
      }
    },
    {
      "name": "mls_rural_10km",
      "backend_input": {
        "tape5_filename": "tp5/mls_rural_10km.tp5"
      }
    },
    {
      "name": "mls_rural_25km",
      "backend_input": {
        "tape5_filename": "tp5/mls_rural_25km.tp5"
      }
    }
  ]
}

This file specifies that the database should contain spectral data from 0.38 → 1.20 microns at 0.001 micron sampling (the spectral data in this database will be resampled at run-time by the FourCurveAtm plugin). The FourCurve atmosphere database contains a generic set of paths through the atmosphere. For each solar declination angle, the ground reaching solar irradiance and full sky radiance are computed. For a series of path declination angles, the path extinction is computed. And for a series of path declination, solar declination and relative azimuth angles, the path radiance is compute. The default samples defined by the fourcurve_builder for these angles are:

  • Solar declination angles are 0 → 80 degrees, at 10 degree intervals. These can be overridden with the solar_declination_samples variable.

  • Path declination angles are 0 → 80 degrees, at 10 degree intervals. These can be overridden with the path_declination_samples variable.

  • Relative azimuth angles are 0 → 180 degrees, at 10 degree intervals. These can be overridden with the relative_azimuth_samples variable.

The example builder configuration file for this demo (shown above) explicitly changed the relative azimuth angles to use fewer samples. This was only performed to make the build time for the database shorter for routine testing and is not a recommended settings for user’s creating their own databases.

The backend specifies that the MODTRAN tape5 backend should be used to generate the database including which MODTRAN profile from your DIRSIG preference to use and the name of the database file to produce. The conditions array contains a list of conditions for the database, with each entry containing a name (as it will referenced in the databased) and the backend specific input for that condition. In this example, a subset of the example MODTRAN tape5 files in the tp5 subdirectory are used to define 3 conditions. However, the database can contain any number of conditions.

Note
 You might need to change the name of the "profile" to match your user settings, or leverage any of the other MODTRAN configuration options decribed in the atm_builder documentation.

This demo includes a copy of the user_defined_atm.hdf database created from this configuration as a reference. To regenerate the atmospheric database, run the following command:

$ fourcurve_builder --input=user_defined_atm.json --output=user_defined_atm.hdf
Using MODTRAN 'tape' backend
    MODTRAN tape5 = 'tp5/mls_rural_5km.tp5'
    MODTRAN profile = 'MODTRAN5'
    MODTRAN executable = '/Users/dirsig/pkg/Modtran5.2.2/mod5_cons'
    MODTRAN DATA = '/Users/dirsig/pkg/Modtran5.2.2/DATA/'
    MODTRAN modroot = 'modroot5.in'
    Process count = '8'

Generating database:
    Spectral range = [0.38 - 1.2] @ 0.001
    Solar declination samples = [ 0 10 20 30 40 50 60 70 80 ]
    Path declination samples = [ 0 10 20 30 40 50 60 70 80 ]
    Solar-Path relative azimuth samples = [ 0 5 15 30 45 90 120 150 165 175 180 ]
    Condition names = [ mls_rural_5km mls_rural_10km mls_rural_25km ]

Generating condition 'mls_rural_5km'
    Adding solar declination = 0
        Adding path zenith,azimuth = 0,0
        Adding path zenith,azimuth = 0,5
        ...
        Adding path zenith,azimuth = 0,180
        Adding path zenith,azimuth = 10,0
        ...
        Adding path zenith,azimuth = 80,175
        Adding path zenith,azimuth = 80,180
    Adding solar declination = 10
        Adding path zenith,azimuth = 0,0
        Adding path zenith,azimuth = 0,5
        ...
        Adding path zenith,azimuth = 0,180
        Adding path zenith,azimuth = 10,0
        ...
        Adding path zenith,azimuth = 80,175
        Adding path zenith,azimuth = 80,180
    Adding solar declination = 80
        Adding path zenith,azimuth = 0,0
        Adding path zenith,azimuth = 0,5
        ...
        Adding path zenith,azimuth = 0,180
        Adding path zenith,azimuth = 10,0
        ...
        Adding path zenith,azimuth = 80,175
        Adding path zenith,azimuth = 80,180
Generating condition 'mls_rural_10km'
...
Generating condition 'mls_rural_25km'
        Adding path zenith,azimuth = 0,0
        Adding path zenith,azimuth = 0,5
        ...
        Adding path zenith,azimuth = 80,175
        Adding path zenith,azimuth = 80,180

Running 2727 task(s)
[*][##################################################]

At the start of the execution a summary of the database parameters are displayed, including the sampled angles (which should reflect the user supplied overrides).

For each condition it will generate the tables for each solar declination, path declination and relative azimuth geometry. In the example here, this accounts for 2727 total MODTRAN requests that will get run in parallel batches of 8 (the host machine had 8 cores, your machine may have more or less).

The name of the conditions that will be available at run-time in this database correspond to the input tape5 filenames. Therefore, the user will be able to choose from either mls_rural_5km, mls_rural_10km or mls_rural_25km.

Setup

There are two simulation configurations included in this demo: one that utilizes the default database and one that utilizes the user-defined database. The difference is captured in the plugin configuration contained in the respective JSIM files. Both simulation configurations use the same sensor, tasks, etc. The result of the simulation is a series of images throughout a day.

Important
 JSIM simulations cannot be loaded into a graphical simulation editor at this time. These simulation configuration files are currently created and edited manually.

Running with the Default Atmospheric Database

The default_atm.jsim file requests the FourCurveAtmosphere plugin and the input configuration only contains the name of the desired condition from the default database. In this case that is mls_rural_50km, which corresponds to a Mid-Latitude Summer profile using the rural aerosol model with a 50 km visibility.

Note
 For a complete list of the condition names in the default database, consult the README file in the $DIRSIG_HOME/lib/data/atm folder. 
[{
  "scene_list": [
    {
      "inputs": "./demo.scene"
    }
  ],
  "plugin_list": [
    {
      "name": "FourCurveAtmosphere",
      "inputs": {
        "conditions": "mls_rural_50km"
      }
    },
    {
      "name": "BasicPlatform",
      "inputs": {
        "platform_filename": "./demo.platform",
        "motion_filename": "./demo.ppd",
        "tasks_filename": "./video.tasks"
      }
    }
  ]
}]

To run this simulation, launch DIRSIG with the JSIM file:

$ dirsig5 default_atm.jsim

Running with the User-Defined Atmospheric Database

The user_defined_atm.jsim file requests the FourCurveAtmosphere plugin and the input configuration contains the name of the local atmospheric database and the desired condition from that database.

Note
 The inclusion of the database variable is what triggers the use of a user-defined database rather than the default one. 
[{
  "scene_list": [
    {
      "inputs": "./demo.scene"
    }
  ],
  "plugin_list": [
    {
      "name": "FourCurveAtmosphere",
      "inputs": {
        "database": "user_defined_atm.hdf",
        "conditions": "mls_rural_5km"
      }
    },
    {
      "name": "BasicPlatform",
      "inputs": {
        "platform_filename": "./demo.platform",
        "motion_filename": "./demo.ppd",
        "tasks_filename": "./video.tasks"
      }
    }
  ]
}]

To run this simulation, launch DIRSIG with the JSIM file:

$ dirsig5 user_defined_atm.jsim

Results

The visualize the results of either simulation, you can generate a diurnal animation using the DIRSIG image_tool utility and the open-source FFmpeg tool. Or simply view the frames with DIRSIG image_viewer utility.

$ image_tool convert --autoscale=gamma default_atm_demo-t00*.img
$ ffmpeg -framerate 5 -i default_atm_demo-t%04d-c0000.img.png -pix_fmt yuv420p video.mp4
Output of the user_defined_atm.jsim simulation.