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.

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.

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

    "scene_list" : [
        { "inputs" : "MegaScene1/tile1.scene" },
        { "inputs" : "MegaScene1/tile2.scene" },
        { "inputs" : "MegaScene1/tile3.scene" },
        { "inputs" : "MegaScene1/tile4.scene" },
        { "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" }
    ],

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.

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
            }
        },
        ...
    ]

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