Background

This plugin provides advanced integration between DIRSIG and the MuSES signature prediction model. The plugin supports having multiple MuSES targets and/or multiple instances of the same target(s) in a single DIRSIG simulation.

Important MuSES and the MuSES plugin described in this demo are only supported in Windows and Linux.

Level-0 Integration

Previously, the user could import the output of an externally computed MuSES run through a feature in the GLIST file. The Muses1 demo is an example of a this simple "level-0" integration. The limitations of this method are that the conditions in the DIRSIG simulation can be very different than those in the MuSES simulation. For example:

  • MuSES could have been run with the object in a different location than where it is in the DIRSIG simulation (e.g., it was at the equator in MuSES and then inserted into a DIRSIG scene at a much higher latitude).

  • MuSES could have been run with the object facing in a different direction than how it is inserted into the DIRSIG simulation. (e.g., it was facing East in MSES then inserted into a DIRSIG scene facing West).

  • MuSES could have been run on a dramatically different date and/or time than the date and time being modeled in DIRSIG (e.g., it was modeled on July 1 at Noon in MuSES but is inserted into the DIRSIG simulation for December 31 at 11 PM).

  • MuSES could have been run with different weather data than what is used in the DIRSIG simulation.

  • MuSES could have been run with different material optical properties (reflectance and/or emissivity) than the ones mapped to the object by DIRSIG.

Level-1 Integration

The MuSES plugin utilized here is an example of a "level-1" integration. That means that DIRSIG runs the MuSES model on-the-fly and that the MuSES simulation is synchronized to the conditions present in DIRSIG. That includes:

  • The geographic location and orientation,

  • The date and time,

  • The weather, and

  • The materials (emissivity).

This MuSES plugin works as follows:

  1. The user provides an existing MuSES TDF file. It is assumed that the TDF has the geometry and materials for the MuSES simulation fully configured.

  2. During initialization, DIRSIG will load the geometry (facets) from the original TDF file and create a MuSES weather file from the weather plugin being used in the DIRSIG simulation.

  3. During a given temporal state change in DIRSIG, the plugin will update a copy of the original TDF (defined by a user-supplied prefix) so that the conditions match those in DIRSIG for the state.

  4. MuSES is then run and the temperature results and materials (MuSES supports temperature dependent emissivities) for each of the facets are loaded into DIRSIG and mapped back to the geometry.

Limitations

  • Static solar positioning (e.g., the fixed ephemeris model) is not supported at this time and the SPICE ephemeris plugin is recommended.

  • Thermal emissivities are pulled from the TDF file on a time and facet basis and the materials are assumed to be diffuse at this time.

  • Only static instancing is supported at this time.

Configuration

The request and configuration of the MuSES plugin(s) occurs in the DIRSIG JSIM file by adding instances of the plugin to the plugin_list.

Variables

The plugin’s input section contains a series of variables that are described below:

tdf_filename (required)

This is the source TDF that defines the target to be added to the DIRSIG scene. It is assumed to have all the geometry and materials configured.

prefix (required)

This is the prefix string that will be added to the temporary files created for this instance of the plugin. This prefix must be unique across all instances of the plugin.

location (required)

The location for the TDF object in DIRSIG’s Scene ENU coordinate system (meters).

muses_exe_path (optional)

The absolute path to the MuSES executable. Defaults to ${MUSES_EXE} (which looks for the MUSES_EXE environment variable to define the path to the MuSES executable). An environment variable is indicated as a string wrapped by ${ and }. If an incorrectly formatted variable is found, or the indicated variable does not exist, an error will occur.

heading (optional)

The heading or Z rotation for the TDF object (degrees East of North). The default value is 0.

tdf_time_duration (optional)

This is the duration of the simulation computed by MuSES in seconds (see below for more information). The default is 1800 seconds (30 mins).

tdf_time_resolution (optional)

This is how often temperatures are computed by MuSES in seconds (see below for more information). The default is 900 seconds (15 mins).

Understanding Time

The tdf_time_duration variable defines the duration that is modeled in MuSES when the model is executed, and the tdf_time_resolution defines how many times will be modeled during that duration. When the DIRSIG simulation starts for the first time, the temporary MuSES TDF file (unique to each instance of the plugin) will (most likely) not contain any results that are appropriate for the simulation. During the first temporal state change (right before the first frame of data is generated), the plugin will sync the appropriate variables to the TDF file and spawn the MuSES model as a sub-process. Rather than compute the single time needed for the state change, the model is usually run for a non-zero length duration (defined by the tdf_time_duration variable) so that future state changes can possibly leverage existing MuSES results rather than have to stop and rerun MuSES.

The tdf_time_resolution variable is provided so that the user can control how often the MuSES model is run to create a new set of temperatures. If the user is simulating a 10 Hz video system, it might be overkill for MuSES to recompute temperatures every 1/10th of a second. Doing so would result in a large number of MuSES executions (slow) and a large temporary MuSES result file. This variable allows the user to indicate that the MuSES result can be computed on a slower time scale than the one DIRSIG is operating at (for example 1 second, 10 seconds, etc.).

With the default values for these two variables, the plugin will start by having MuSES compute 3 times for 0, 900 and 1800 seconds after the initial start date/time. If the simulated data collection extends beyond that 1800 second time window, then the plugin will automatically run the MuSES model again to generate the data for those requested times. Extending the default tdf_time_duration window will force more MuSES results to be computed during each run, but those results might not be needed by a given simulation. In general, the default duration and resolution variables are good starting points and the user will usually know under what conditions they need to be modified.

Note Increasing the tdf_time_duration and/or decreasing the tdf_time_resolution will result in a larger TDF file.

Command-Line Options

The --disable_muses_runs command-line option can be provided at run-time to disable the execution of the MuSES model during the DIRSIG simulation. This can be useful when repeating a simulation and the MuSES temperatures do not need to be recomputed or when deploying a DIRSIG simulation to a compute platform that does not have MuSES installed (cloud and/or parallel computing). As long as the temporary results from a previous DIRSIG run with MuSES are deployed with the simulation, then this flag can be used to import those previously computed solutions as if they were run just-in-time.

Single Instances

An instance of the plugin is requested via the plugin name Muses and the example below

Example JSIM configuration for the MuSES plugin.
    { 
      "name": "Muses",
      "inputs": {
        "tdf_filename": "geometry/truck_cold_to_idle_2020R1.tdf",
        "prefix": "geometry/truck_inst1_",
        "heading": 135,
        "location": [5,-7,0],
        "tdf_time_resolution": 300
      }
    },

Multiple Instances

Multiple instances of the plugin can be used to insert multiple objects into the simulation. Unique instances can use the same TDF input file (see the tdf_filename variable) but the prefix must be unique for each instance.

Examples

The Muses2 demo contains a working example of this plugin, including instancing the same base TDF file multiple times. The images below show the radiance and temperature truth outputs for that demo.

lwir 2 percent
Figure 1. The LWIR radiance image (2% scaling) for the Muses2 demo.

Due to the simple materials in the scene and the MuSES TDF files, the temperature truth image is visually very similar:

tempK 2 percent
Figure 2. The temperature truth image (2% scaling) for the Muses2 demo.