# Level-0 MuSES Import

Keywords: muses

## Summary

This demo focuses on the most basic (aka Level-0) import mechanism to incorporate the output of a MuSES simulation (geometry and temperatures) into a DIRSIG simulation. This simulation consists of a vehicle (a pickup truck, provided by ThemoAnalytics, Inc (TAI)) sitting on a flat plate.

A more advanced Level-1 integration with MuSES is facilitated by the MuSES plugin in DIRSIG5 and is shown in the Muses2 demonstration.

Important | MuSES support is only available on Windows and Linux.

## Details

This basic MuSES import mechanism works as follows:

- The user creates a working MuSES simulation of the object of interest.

  - The geometry of the object and the output of the MuSES simulation of that object are stored in a MuSES TDF file.

- The TDF file for the MuSES simulation, containing both the geometry and the predicted temperatures (for one or more simulated times) is imported into the DIRSIG simulation.

  - This import process extracts the geometry and a set of temperature predictions from the MuSES TDF file.

- The TDF import operation is performed during the DIRSIG initialization, and requires the user to:

  - Instruct DIRSIG which simulated time to use for the DIRSIG simulation.

  - Optionally instruct DIRSIG how to remap MuSES materials to DIRSIG materials.

- The imported geometry is attributed with the DIRSIG native materials (based on a user-supplied remapping of the with MuSES materials) and MuSES predicted temperatures (based on the time result requested by the user).

## Important Files

- The MuSES vehicle simulation to import is contained in the file `truck_cold_to_idle_2020R1.tdf`, which can be found in the `geometry` folder.

- The MuSES TDF file is incorporated into the DIRSIG simulation via the `demo.glist` file, which can also be found in the `geometry` folder.

## Setup

This simulation consists of a 2D framing camera mounted to a platform that is statically positioned (a single location and orientation entry) over the scene. The TDF file is inserted into the scene directly via the GLIST file. The setup in the GLIST file handles the material remapping and which simulation time to import. In a similar syntax to that used for the GDB and OBJ file, the TDF file is specified in the `<basegeometry>` via the `<tdf>` element:

- The `filename` element specifies the name of the TDF file.

- The (optional) `resulttimestepindex` element specifies which of the temperature results contained in the TDF file to import.

### The TDF Filename

The `filename` element provides the name of the TDF file to be imported. The filename can include the absolute path to the file, the relative path to the file with respect to the simulation file or the relative path to the GDB file path provided in the `scene` file.

### The (optional) material remappings

The list of material ID remappings is composed of series `remap` elements that contain MuSES and DIRSIG material ID pairs. The MuSES object employs the following material IDs and names:

- [1] Steel (mild)

- [4] Cast Iron

- [12] Glass, Conventional Automotive

- [31] Aluminum

- [32] Rubber, Hard

- [33] Nylon, Bonded

- [34] Polyvinyl Chloride

- [35] Stainless Steel, 430

If these material IDs are defined in the DIRSIG material database, then the optional remapping mechanism does not need to be employed.

Important | The material IDs used by MuSES can change over time. However, the material names generally have not.

Note | The MuSES and DIRSIG material ID schemes are completely independent, however, if you are creating and managing both simulations then you might consider making the material IDs the same in both tools.

But in this demo, we chose to show an example of mapping MuSES materials to a smaller set of DIRSIG materials. This is primarily done to simplify the demonstration, but the approach might have practical applications. Keep in mind that the temperatures of the target have already been computed by MuSES. Hence, the DIRSIG materials are primarily there to define their optical properties. In this case, the "Steel (mild)" and "Aluminum" MuSES material might both be painted with the same paint. Hence, they could be mapped to the same DIRSIG material.

Note | The remampping mechanism isn’t an "all or nothing" choice. You can choose to remamp none of the materials, all of the materials or anything in between.

As it was mentioned earlier, the alternative approach is to skip the remapping mechanism and define DIRSIG materials that use the same labels as the MuSES materials.

### The (optional) result index

The MuSES TDF file must contain one or more simulated temperature predictions. The `resulttimestepindex` element specifies which of these predictions to associate with the geometry as it is imported. To determine the index corresponding to the date/time of a specific result, open the TDF file in MuSES and browse the results.

### Instances

Just like any other object, the GLIST will allow you to instance this MuSES object multiple times using one or more `staticinstance` or `dynamicinstance` specifications. Please consider the implications of re-orienting the object as part of the instance description that are discussed below.

Below is the key section of the `geometry/demo.glist` file used in this simulation:

A GLIST file importing a TDF file for use with DIRSIG5.

      <object>
        <basegeometry>
          <tdf>
            <filename>truck_cold_to_idle_2020R1.tdf</filename>
            <assign id="muses_metal">Steel (mild)</assign>
            <assign id="muses_metal">Cast Iron</assign>
            <assign id="muses_metal">Aluminum</assign>
            <assign id="muses_glass">Glass, Conventional Automotive</assign>
            <assign id="muses_rubber">Rubber, Hard</assign>
            <assign id="muses_metal">Nylon, Bonded</assign>
            <assign id="muses_metal">Polyvinyl Chloride</assign>
            <assign id="muses_metal">Stainless Steel, 430</assign>
            <resulttimestepindex>8</resulttimestepindex>
          </tdf>
        </basegeometry>
        <staticinstance/>
      </object>

The GLIST `<assign>` syntax to re-assign materials became universal in the DIRSIG5 scene compiler. However, in DIRSIG4 there was a different syntax specific to the TDF import (see the `geometry/demo_d4.glist` file, which is used by the alternate `demo_d4.scene` and `demo_d4.sim` files):

A GLIST file importing a TDF file for use with DIRSIG4.

      <object>
        <basegeometry>
          <tdf>
            <filename>truck_cold_to_idle_2020R1.tdf</filename>
            <materialidremappings>
              <remap><tdfid>1</tdfid><dirsigid>muses_metal</dirsigid></remap>
              <remap><tdfid>4</tdfid><dirsigid>muses_metal</dirsigid></remap>
              <remap><tdfid>12</tdfid><dirsigid>muses_glass</dirsigid></remap>
              <remap><tdfid>31</tdfid><dirsigid>muses_metal</dirsigid></remap>
              <remap><tdfid>32</tdfid><dirsigid>muses_rubber</dirsigid></remap>
              <remap><tdfid>33</tdfid><dirsigid>muses_metal</dirsigid></remap>
              <remap><tdfid>34</tdfid><dirsigid>muses_metal</dirsigid></remap>
              <remap><tdfid>35</tdfid><dirsigid>muses_metal</dirsigid></remap>
            </materialidremappings>
            <resulttimestepindex>8</resulttimestepindex>
          </tdf>
        </basegeometry>
        <staticinstance/>
       </object>

Important | The material index mapping mechanism used in DIRSIG4 relied on the TDF material IDs. Unfortunately these IDs can change with MuSES updates. If DIRSIG4 reports an error with an unknown material, it is most likely because these IDs were updated in MuSES and the remapping table needs to be updated.

## Results

When the simulation is run, the console output should include this section where the TDF file is loaded and the options are displayed:

Run-time messages displayed by DIRSIG4 when loading a TDF file.

    Reading in MuSES TDF file: /dirsig/demos/Muses1/geometry/truck_cold_to_idle_2020R1.tdf
        File created with version '2020.1.0'
        Material list:
            [1] Steel (mild)
            [4] Cast Iron
            [12] Glass, Conventional Automotive
            [26] Aluminum
            [27] Rubber, Hard
            [28] Nylon, Bonded
            [29] Polyvinyl Chloride
            [30] Stainless Steel, 430
        Material remappings (MuSES -> DIRSIG):
            [1] Steel (mild) -> muses_metal
            [4] Cast Iron -> muses_metal
            [12] Glass, Conventional Automotive -> muses_glass
            [26] Aluminum -> muses_metal
            [27] Rubber, Hard -> muses_rubber
            [28] Nylon, Bonded -> muses_metal
            [29] Polyvinyl Chloride -> muses_metal
            [30] Stainless Steel, 430 -> muses_metal
        Result index     = 8 of 9 (date/time = 2004-07-01T08:00:00.0000+00:00)
        Part count       = 55
        Facet count      = 44900
        Bounding box min = [-4.26468, -1.64401, -0.018224]
        Bounding box max = [0.828718, 0.489358, 1.89973]

Note | The DIRSIG5 scene compiler is far less verbose when importing a TDF file unless the message verbosity option is set to `debug`.

Running the simulation produces PAN and LWIR radiance images from the respective PAN and LWIR focal planes. There is also a truth image set for the PAN and LWIR focal planes. The image below is from the PAN focal plane. The vehicle geometry was imported from the MuSES TDF file and the geometry was generally assigned a glossy paint. The background was introduced separately and is assigned a grass material.

Figure 1. The PAN channel image shows the imported MuSES geometry (gamma scaling)

The image below is the LWIR radiance image.

Figure 2. The LWIR channel image shows the imported MuSES geometry (linear scaling)

The image below is the Avg. Temperature truth. The vehicle temperature signature (including the hot spot on the hood) was externally predicted by MuSES and imported into the simulation. The temperature of the grass background was predicted by the built-in THERM temperature solver using the supplied weather and material thermodynamic properties.

Figure 3. Temperature truth shows the MuSES vehicle temperature signatures.

## Limitations

The following limitations should be considered. Most of the limitations are because this basic Level-0 import mechanism assumes the user is aware that the simulation conditions in MuSES and DIRSIG must be consistent:

- As it was mentioned earlier, the user can remap a MuSES material that had a high thermal emissivity to a DIRSIG material that has a dramatically different emissivity. There is no mechanism for DIRSIG to flag this as a potential error in your setup at this time.

- This basic import mechanism does not support any automatic time synchronization between the models. If the supplied result time index corresponds to 11 PM at night and DIRSIG is run for 9 AM in the morning, there is no way for DIRSIG to flag this as a potential error in your setup at this time.

- The orientation of the object can be changed in DIRSIG. Therefore, a vehicle that was simulated with the driver’s side facing east can be inserted into the DIRSIG scene with that side of the vehicle facing west. There is currently no mechanism in DIRSIG to flag this as a potential error in your setup at this time.

All of these limitations are addressed by the Level-1 integration facilitated by the MuSES plugin.