This document provides an overview of the DIRSIG5 JSON formatted simulation description, referred to as JSIM.

Introduction

DIRSIG5 utilizes a suite of plugin modules to assemble the desired simulation capabilities at execution time. The initial set of plugins were written to establish backward compatibility with DIRSIG4 atmospheric and sensor descriptions. As DIRSIG5 has matured, more features have been added to the overall model through plugins.

Important Although JSIM is a powerful tool for configuring DIRSIG5 simulations, there is not a graphical editor for creating and modifying these files at this time.

DIRSIG4 XML Simulation Files

The DIRSIG4 era XML simulation file contained a specific list of input files to describe the single scene to be used, the atmospheric conditions for that scene and the sensor collection description.

<simulation>
  <scene                 externalfile="./demo.scene" />
  <atmosphericconditions externalfile="./demo.atm" />
  <platform              externalfile="./demo.platform" />
  <platformmotion        externalfile="./demo.ppd" />
  <tasklist              externalfile="./demo.tasks" />
</simulation>

To provide backward compatibility with DIRSIG4 era simulations, the DIRSIG5 main executable has an XML input simulation file parser that configures the appropriate plugins that provide DIRSIG4 capabilities. Under the hood, the BasicAtmosphere plugin handles DIRSIG4 atmospheric modeling responsibilities and the BasicPlatform plugin handles the data collection responsibilities.

DIRSIG5 JSON Simulation Files

In addition to using the plugins distributed with DIRSIG5, end users will eventually be able to create their own plugins to use with their simulations. In order to directly configure which plugins are to be used and what inputs should be supplied to them, a new simulation input file was needed. The new simulation input file is a JSON formatted document that contains a list of scenes and a list of plugins to be utilized in the simulation. The example below is the JSON equivalent of the XML simulation file example from the last section:

[{
    "scene_list" : [
        { "inputs" : "./demo.scene" }
    ],
    "plugin_list" : [
        {
            "name" : "BasicAtmosphere",
            "inputs" : {
                "atmosphere_filename" : "./demo.atm"
            }
        },
        {
            "name" : "BasicPlatform",
            "inputs" : {
                "platform_filename" : "./demo.platform",
                "motion_filename" : "./demo.ppd",
                "tasks_filename" : "./demo.tasks"
            }
        }
    ]
}]

The top-level components of the file are the "scene list" and "plugin list". These will be described further in the following sections.

Scene List

One of the features of DIRSIG5 is that it can utilize multiple scenes in a simulation. This gives scene builders more flexibility when constructing large or complex scenes and it gives the model the ability to progressively load scenes into a simulation. The scene_list lets the user define the list of scenes that will be used in a simulation.

Each scene entry in the array has the following variables:

inputs (required)

The filename for the input scene file. This can be either the .scene file or the .scene.hdf file.

name (optional)

A user-defined name associated with the scene. This can make simulations that use many scenes more manageable. Specifically, it makes it possible to request material abundance truth for a specific material in a specific scene.

offset (optional)

The 2D offset (the Z is ignored) in the Scene ENU coordinate system for a scene relative to the first scene defined (see below).

Combining Scenes

In order to avoid the headaches of manipulating massive scene geometry models, a common approach to large-area scene construction has been to divide the scene into multiple "parts" or "tiles". This is the approach that has been used at RIT for scenes including MegaScene1. In the case of MegaScene1, each tile of the five tiles were constructed using a shared Scene ENU coordinate system, which means each scene file has the same geographic location for the Scene ENU origin. In DIRSIG4, these scene tiles had to be combined by having either a GLIST or scene file combine the geometry for the desired scenes (e.g. tile_1.scene, tile_1_2.scene, tile_1_2_3.scene, etc.). In DIRSIG5, these scenes can be combined at simulation time by providing the list of scene files that describe each tile.

Example of a multi-scene configuration with explicit names.
    "scene_list" : [
        { "name" : "tile1", "inputs" : "MegaScene1/tile1.scene" },
        { "name" : "tile2", "inputs" : "MegaScene1/tile2.scene" },
        { "name" : "tile3", "inputs" : "MegaScene1/tile3.scene" },
        { "name" : "tile4", "inputs" : "MegaScene1/tile4.scene" },
        { "name" : "tile5", "inputs" : "MegaScene1/tile5.scene" }

The user can also utilize this approach to combine scenes that do not share a common Scene ENU coordinate system. In the example below, we combine the Urban scene (downtown Rochester, NY) with MegaScene1 (a suburb just north of Rochester, NY) into a single scene list.

    "scene_list" : [
        { "inputs" : "Urban/summer_day.scene" },
        { "inputs" : "MegaScene1/tile1.scene" },
        { "inputs" : "MegaScene1/tile2.scene" },
        { "inputs" : "MegaScene1/tile3.scene" },
        { "inputs" : "MegaScene1/tile4.scene" },
        { "inputs" : "MegaScene1/tile5.scene" }

To be clear about what is happening here, the Urban scene uses a geographic location to tie its local Scene ENU coordinate system to the Earth in one location and the MegaScene1 scene has it’s own geographic location that ties its local Scene ENU coordinate system to another location on the Earth. These two scenes are near each other in the real world, but these scenes don’t actually meet at the edges. Hence, there is a gap between them. If a wide-area image of the Rochester region was generated, both scenes would be visible at there respective locations in the simulation output.

Because of the precision required in the geolocation, it can be difficult to align separate scenes to cleanly meet at the edges without gaps. Therefore, when constructing a scene using a tiling method, it is strongly encouraged to use a shared coordinate system and a single geolocation for each tile. However an alternative method is also available, which is discussed next.

Relative Offsets

When relying on the geographic location of the location scene origin in individual scenes to perform relative layouts, the user can quickly get frustrated with precision and projection issues associated with the manipulating geographic locations in order to align scene edges. To simplify that process, individual scenes can be constructed in a single local Scene ENU coordinate system and then offset relative to each other when provided to the simulation. The ModularCity1 demo uses this approach to construct a simple city by quilting together an 11 x 11 set of modular city building blocks that are each 100 x 100 meters. The offset for each scene specifies where that scene is relative to the first scene in the list.

    "scene_list" : [
        { "inputs" : "./scenes/city4.scene" },
        { "offset" : "-500,-500,0", "inputs" : "./scenes/tile9.scene" },
        { "offset" : "-500,-400,0", "inputs" : "./scenes/park2.scene" },
        { "offset" : "-500,-300,0", "inputs" : "./scenes/tile4.scene" },
        { "offset" : "-500,-200,0", "inputs" : "./scenes/tile11.scene" },
        { "offset" : "-500,-100,0", "inputs" : "./scenes/tile3.scene" },
        { "offset" : "-500,0,0", "inputs" : "./scenes/tile5.scene" },
        { "offset" : "-500,100,0", "inputs" : "./scenes/park3.scene" },
        { "offset" : "-500,200,0", "inputs" : "./scenes/tile2.scene" },
        { "offset" : "-500,300,0", "inputs" : "./scenes/tile3.scene" },
        { "offset" : "-500,400,0", "inputs" : "./scenes/tile8.scene" },
        { "offset" : "-500,500,0", "inputs" : "./scenes/tile6.scene" },
        { "offset" : "-400,-500,0", "inputs" : "./scenes/park1.scene" },
        ...
        { "offset" : "400,500,0", "inputs" : "./scenes/tile7.scene" },
        { "offset" : "500,-500,0", "inputs" : "./scenes/tile12.scene" },
        { "offset" : "500,-400,0", "inputs" : "./scenes/park2.scene" },
        { "offset" : "500,-300,0", "inputs" : "./scenes/tile8.scene" },
        { "offset" : "500,-200,0", "inputs" : "./scenes/tile8.scene" },
        { "offset" : "500,-100,0", "inputs" : "./scenes/tile8.scene" },
        { "offset" : "500,0,0", "inputs" : "./scenes/tile5.scene" },
        { "offset" : "500,100,0", "inputs" : "./scenes/tile12.scene" },
        { "offset" : "500,200,0", "inputs" : "./scenes/tile5.scene" },
        { "offset" : "500,300,0", "inputs" : "./scenes/tile6.scene" },
        { "offset" : "500,400,0", "inputs" : "./scenes/tile8.scene" },
        { "offset" : "500,500,0", "inputs" : "./scenes/tile1.scene" }
    ],

Important Notes:

  • The first scene in the scene_list is considered the "anchor" scene. An offset assigned to this scene is ignored.

    • Therefore, it follows that an offset applied to a single scene simulation would be ignored.

  • The although the offset is assigned an XYZ triplet, only the X and Y values are used. The Z value of the offset is ignored.

Overlaying Scenes

The previous discussion focused on "tiling" approaches, where individual scenes do not overlap. However, combined scenes can overlap as well. Consider a scenario where the user creates a city and is modeling different traffic patterns through the city. Rather than have a single large scene that combines the baseline city geometry (buildings, roads, etc.) and a specific state of traffic, the user could separate the baseline city from the traffic. The city.scene would contain only the baseline city geometry (buildings, roads, etc.) and separate "traffic" scenes would contain only the vehicles and dynamic instance data describing the path those vehicles follow through the city. Each traffic scene could capture a different traffic pattern scenario and the city and traffic can be combined at simulation time (see below):

    "scene_list" : [
        { "inputs" : "/city.scene" },
        { "inputs" : "/traffic_weekday.scene" }
    ],

Alternatively the user can combine that same city scene with a less busy traffic pattern for the weekend.

    "scene_list" : [
        { "inputs" : "/city.scene" },
        { "inputs" : "/traffic_weekend.scene" }
    ],

Since the cars are driving along roads in the city, it would be easiest to use a shared Scene ENU coordinate system when constructing the scenes.

Plugin List

The second major component to a simulation is the list of plugins that will be used in the simulation. This list contains a group of JSON objects for each plugin to be loaded. Each JSON object includes a name and inputs array. The text assigned to the name is assumed to match the name advertised by a given plugin (part of it’s implementation). This name is used to find the requested plugin in the folders configured in the plugin search path. The inputs array is passed directly to the plugin, hence, the contents of that array are unique to each plugin.

Note Plugins are searched for in specific locations. More information on how this search is performed is described here.

For the DIRSIG4 backward compatibility plugins, the inputs array contains the name of one or more input files used by the plugin to configure itself. The example below shows that the BasicAtmosphere plugin is expecting to find the atmosphere_filename object to find the name of the DIRSIG4 era atmosphere file to configure itself from. The BasicPlatform plugin is expecting to see the names of the DIRSIG4 era platform, motion and tasks files to configure itself from.

    "plugin_list" : [
        {
            "name" : "BasicAtmosphere",
            "inputs" : {
                "atmosphere_filename" : "uniform.atm"
            }
        },
        {
            "name" : "BasicPlatform",
            "inputs" : {
                "platform_filename" : "demo.platform",
                "motion_filename" : "demo.ppd",
                "tasks_filename" : "demo.tasks"
            }
        }
    ]

However, there is nothing stopping a developer from creating a plugin that embeds the input parameters directly into the inputs array rather than read them from an external file.

    "plugin_list" : [
        {
            "name" : "MyAtmospherePlugin",
            "inputs" : {
                "sun_irradiance" : 100.0,
                "sky_irradiance" : 20.0,
                "sun_zenith" : 83.21,
                "sun_azimuth" : 210.8
            }
        },
        ...
    ]

Combination Plugins

Some plugins in DIRSIG5 are "combination plugins", which means that a single plugin implements several plugin types. For example, the ChipMaker plugin is a sensor plugin, an atmosphere plugin and an ephemeris plugin.

Multiple Plugins and Overriding Plugins

The plugin list allows the user to configure multiple plugins to be used in the simulation. Some plugin types allow multiple instances of the plugin to be used in the simulation. However, for a subset of plugin types, DIRSIG5 assumes there will only be one plugin supplied. The table below outlines which plugin types support multiple instances.

Table 1. Single vs. Multiple Plugin Types
Type Single vs. Multiple

Atmosphere

Single

Ephemeris

Single

Sensor

Multiple

Weather

Single

It is possible that a plugin list will include more than one plugin for a plugin type that only supports a single instance of that plugin. For example, the user might mistakenly configure one or more weather plugins. When this occurs, subsequent plugin requests for that plugin type will override the previous plugin request. For example, if the user requests a weather plugin named WeatherA and then WeatherB, the WeatherB plugin is the one that will be used in the simulation. The simulation startup will communicate this override in the configuration:

Setting up the 'WeatherA' plugin
Setting up the 'WeatherB' plugin
Replacing 'WeatherA' with 'WeatherB' as the weather plugin
Tip It is not uncommon to deliberately configure plugin override scenarios. For example, you might request the BasicAtmosphere plugin and provide it a DIRSIG4-era .atm file, which will automatically configure instances of the BasicAtmosphere plugin, the SpiceEphemeris plugin and the ThermWeather plugin. However, you might want to deliberately override the older ThermWeather plugin with the newer NsrdbWeather plugin. In that case, make sure you request the NsrdbWeather plugin after the BasicAtmosphere plugin.

Medium List

In addition to providing a generic way to load plugins into the simulation, the JSIM format has specific definitions to facilitate setting up simulation components that might be composed of multiple plugins and related options. The primary example of this is a medium_list that defines individual medium components that have plugins for optical properties, the boundary of the medium, and possibly medium-based geometry. A medium_list exists at the same level in the JSIM as the scene_list and plugin_list and has three base components:

[{
   "scene_list"  : [ ... ],
   "medium_list" : [
        {
            "type" : <type of medium>,
            "plugin_list" : [
                <plugin entries>
            ],
            "options" : {
                <options specific to the type of medium>
            }
        }
    ],
    "plugin_list" : [ .. ]
}]

The exact definitions of these sections are dependent on the type of medium being described and are documented elsewhere (for example, the water plugins and plume plugins). The medium_list is completely optional and will not be found in most JSIM files.

Using a JSIM file

The DIRSIG5 main executable checks to see if the supplied input file is a DIRSIG4 SIM file or a DIRSIG5 JSIM file and then parse it appropriately. Hence, using a JSIM file is as easy as:

$ dirsig5 demo.jsim