The make_adb Manual

When the make_adb tool runs, it is executing MODTRAN simulations that are specific to a given simulation. The specifics of the simulation that are captured by make_adb in the ADB file include:

The list above includes the words "mean", "average" and "accumulated" because the resulting ADB file contains a single set of tables for the simulation. The general assumption of the ClassicAtm model is that the atmosphere is temporally frozen during the simulation. When the simulation is a single-frame at a point in time, this assumption is easily satisfied. However, when the simulation has a non-zero length collection window and involves a moving platform and/or a scanning sensor(s), then this assumption needs to be accounted for. In these non-instantaneous scenarios, the database is created to span the extents of the simulation in the following ways:

During the initialization of the make_adb tool, the tool is gathering the information (date, time, altitude, FOV, wavelengths, etc.) and generating the list of MODTRAN simulations that will need to be run to construct the database required for the simulation.

The make_adb tool runs MODTRAN by repeatedly modifying an input MODTRAN "tape5" file, running MODTRAN with that modified input, reading the MODTRAN output and storing it in the atmospheric database. The user-supplied MODTRAN input "tape5" file is referred to as the "template" file since it provides the basis for all the MODTRAN runs executed by the tool. The template "tape5" file is primarily used for it’s card #1 and #2 data (and all the subcards), which describe the optical properties of the atmosphere. In general, the make_adb utility updates the card #3 and #4 data, which contains specifics about the type of path to be modeled, the geometry of that path, the wavelengths, etc. In general, if a tape5 variable describes what the atmosphere looks like, make_adb leaves it alone. If a tape5 variable describes something specific to the DIRSIG simulation, make_adb modifies it. The table below attempts to document which variables are modified. The tool will run 100s of MODTRAN simulations, so different variables are modified at different times depending on the type of MODTRAN simulation being performed.

In DIRSIG3, the MODTRAN installation specifics were captured in a configuration file that was contained in the software installation (e.g., $DIRSIG_HOME/config/make_adb). By default, the versions of make_adb included in DIRSIG3 would load this file to get information about the MODTRAN installation to be used. An example of this file is shown below:

In DIRISG4, this mechanism was replaced with a newer mechanism (see below). However, the DIRISG4 version of make_adb still supported a command-line option (see the -use_config option) to specify the path to one of these DIRSIG3 era configuration files. Although not encouraged, this option can still be used to simplify the deployment or execution of make_adb in complex compute environments.

The primary limitations of the MODTRAN configuration method utilized in DIRSIG3 was that:

This was addressed in DIRSIG4 by relocating the MODTRAN installation specifics to the user’s DIRSIG personal settings. These settings are stored using the common platform specific mechanisms on each host operating system (e.g., user registry entries on Windows, an application PLIST file on MacOS, etc.). Because they are stored in the user’s account, the MODTRAN settings are not lost between upgrades and the user can easily customize their configuration. In addition, the new mechanism allows the user to have multiple MODTRAN installations configured and choose which to use. The MODTRAN installations can be viewed and modified in the DIRSIG graphical user interface Simulation Editor (DIRSIG or DIRSIG.exe) by opening the settings (File → Settings menu item, or DIRSIG → Preferences on MacOS) and going to the MODTRAN tab.

The major development in MODTRAN6 is a shift from the old "tape5" style inputs to a new JSON (JavaScript Object Notation) style input. In addition to improving the general readability of the input, the JSON document format is much easier to read in, modify and write back out. However, the DIRSIG4-era ClassicAtm model and make_adb tool will not be updated to use the new JSON input format since feature enhancements on this tool have been suspended in favor of the DIRSIG5-era NewAtm model and atm_builder tool. Instead, the solution for continued use of make_adb is to make a script that wraps around the MODTRAN6 executable and perform some basic file manipulations so that the script makes MODTRAN6 "look like" older versions of MODTRAN. As a result, MODTRAN6 can be used with any existing version of make_adb without any code modifications to DIRSIG or installation updates for the end-user. The example script below assumes DIRSIG wrote to the file tape5, it renames that file to mod6_tmp.tp5 and then launches MODTRAN6 supplying mod6_tmp.tp5 as a command-line argument. Note that this rename approach was selected over the option of converting the input file to JSON in order to avoid the run-time associated with that conversion. Additionally, DIRSIG expects the output files to be named tape6, tape7, etc. so this script also renames the output files after MODTRAN6 has finished execution.

A small project in the early 2000s produced a prototype version of MODTRAN4 that had a limited set of updated scattering phase functions that enabled the prediction of polarized atmospheric path radiance. If you have access to this version of MODTRAN (referred to as MODTRAN4-P), you can configure it for use in DIRSIG.

Simply create a MODTRAN installation profile that points to the MODTRAN4-P installation and use it with the -polarized option:

If you choose to create an alternate MODTRAN installation configuration file, your command line will look something like this:

If you receive the following error while make_adb is running in polarized mode then you should verify that you are correctly running MODTRAN4-P.

The <classicradiativetransfer> element in the DIRSIG4 .atm file captures a variety of inputs for the ClassicAtm model. An example of this XML element is included below:

The <modtrantape5file> element supplies the MODTRAN template "tape5" file for MODTRAN. If the externalfile attribute is provided, it is assigned the path to the file to be used. Otherwise, this element will contain the contents of the "tape5" enclosed in an XML CDATA block (see below):

The benefit of this "internal" method is that it removes an external file dependency on the .atm file. When you share the .atm file you do not need to also share the "tape5" file referenced in the .atm file.

The <modtranprofilename> element specifies which MODTRAN installation profile will be used. In this example, the profile with the name MODTRAN6 fill be used.

The <adbfile> element contains the name of the ADB file produced by make_adb.

The <removesensorpath> element controls an option to "remove" the path between the sensor and the scene. Setting this option to true will cause the path transmission data to be reset to 1 and the path radiance data to be reset to 0 after reading the database. As a result, the radiance at the sensor is essentially the surface leaving radiance.

The <trypolarized> element mirrors the -polarized command-line option (discussed below). This option will try to run MODTRAN in polarized mode. This mode was only supported by the limited access version of MODTRAN4 that had polarization support (referred to as MODTRAN4-P). Using this option with any other version of MODTRAN will result in an error.

The <usefastsky> element controls an option to populate the angularly sampled sky irradiance data table with a single uplooking sky path from MODTRAN. Originally introduced to facilitate quick database builds when debugging the use of this option is strongly discouraged.

The -use_config option can be used to specify the path to a DIRSIG3 era MODTRAN installation configuration file.

The -show_config option will print the MODTRAN configuration(s) available.

The -max_inversion option lets the user specify the inversion altitude used to update the boundary layer data in a MODTRAN user-defined atmosphere (MODTRAN MODEL = 7) from the weather data supplied to the DIRSIG simulation.

The -max_range option is used to specify the maximum range for a simulation where the FOV of the sensor is entirely above the horizon.

The -fov_min_deltas options lets the user override the minimum zenith and azimuth angles between paths within the sensor FOV.

The -polarized option will try to run MODTRAN in polarized mode. This mode was only supported by the limited access version of MODTRAN4 that had polarization support (referred to as MODTRAN4-P). Using this option with any other version of MODTRAN will result in an error.

The -save_tapes option will preserve all the MODTRAN run directories, including the input and outputs.

The -interactive option runs the tool in the "interactive" mode, which supports DIRSIG4’s interactive mode.

The weather file used by the THERM weather plugin includes broad-band direct (solar) and diffuse (sky) insolation (broad-band irradiance) values for each time entry. However, those insolation values might not be consistent with the MODTRAN description of the atmosphere. For example, the weather file might have direct and diffuse insolation values indicative of high visibility conditions, but the MODTRAN description of the atmosphere might describe low visibility conditions. The ramifications of this apparent contradiction would manifest itself as predicted scene temperatures that are not correlated with the atmospheric conditions. For example, if the weather file insolations are for high visibility conditions, the temperatures might be higher than expected for the low visibility imaging conditions.

To help address this issue, the make_adb tool has a mode that will compute these weather file insolation values based on the MODTRAN description of the atmosphere. Running the make_adb tool with the -compute_insolations option will take the MODTRAN description of the atmosphere defined in the supplied simulation and compute appropriate broad-band solar and sky irradiance values as a function of time of day. These irradiance values are then converted to the insolation units used in the weather file and a new weather file is generated.

The primary output of this execution is a THERM weather file containing the direct and diffuse insolations computed using the MODTRAN configuration supplied. Currently the new weather file is always named new.wth and it should be appropriately renamed (to indicate its origin and how it was modified) and then referenced from your BasicAtmosphere .atm file.