Level-0 MuSES Import
====================
:stem: latexmath
:source-highlighter: highlight.js

Keywords: muses

== Summary
This demo focuses on the most basic (aka Level-0) import mechanism to
incorporate the output of a
https://www.thermoanalytics.com/muses[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
http://www.dirsig.org/docs/new/muses_plugin.html[MuSES plugin] in 
DIRSIG5 and is shown in the
http://www.dirsig.org/demos/#Muses2[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
http://www.dirsig.org/docs/new/glist.html#MusesImport[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.
[source,xml]
----
include::geometry/demo.glist[lines=8..24]
----

The GLIST `<assign>` syntax to re-assign materials became universal
in the DIRSIG5 http://www.dirsig.org/docs/new/scene2hdf.html[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.
[source,xml]
----
include::geometry/demo_d4.glist[lines=8..26]
----

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 http://www.dirsig.org/docs/new/scene2hdf.html[scene compiler]
      is far less verbose when importing a TDF file unless the 
      http://www.dirsig.org/docs/new/scene2hdf.html#_controlling_console_message_verbosity[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.

.The PAN channel image shows the imported MuSES geometry (gamma scaling)
image::images/pan.png[]

The image below is the LWIR radiance image.

.The LWIR channel image shows the imported MuSES geometry (linear scaling)
image::images/lwir.png[]

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.

.Temperature truth shows the MuSES vehicle temperature signatures.
image::images/temp_truth.png[]


== 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
http://www.dirsig.org/docs/new/muses_plugin.html[MuSES plugin].
