Sources6
========
:stem: latexmath
:source-highlighter: highlight.js

Keywords: sources, tagging, dynamic control

== Summary ==
This demonstration shows how GLIST tags and a control file can be used to
dynamically enable/disable sources in a scene. In this example, a system of
lights (headlights, taillights, brake lights, turn signals) have been added
to a car and they are turned on and off as function of time.


== Details ==

=== Tagging System
This scenario uses the generic geometry tagging system that was
introduced in DIRSIG5.  The point of the system is to introduce named
tags to geometry in the scene that can be used to dynamically bind
features and controls to that geometry at run time.  Tags are simply
name strings that are associated with GLIST elements (including lists,
objects and instances). You can add one or more tags to any element (as
a comma separated list) and these tags are inherited by children in
the geometry list hierarchy. For example, tags assigned to a geometry
list will be inherited by objects within that list, and the instances
of those objects will inherit them as well.  When smartly planned, the
tags can be used to access extensive sets of geometry or very specific 
geometric items in the scene.

=== Dynamic Control 
The second key component of this demonstration is the use of an instance
specific "control" file that dynamically enables and disables geometry
in a given instance using the tag system.  This mechanism can be used to 
introduce site evolution mechanics to a scene, where buildings don't exist
in the scene until a specific time. Or "pattern of life" properties, where
cars populate a parking lot at specific times of day.  In this case, we
are using this mechanism to enable/disable light sources on a vehicle. 
The general mechanism employs a temporal control file that enables and
disables geometry with specific tags as a function of time.

== Important Files ==
This section highlights key files important to the simulation.
  
=== Nissan March Bundle
The primary object in the scene is a Nissan March sedan. The geometry,
materials, sources, etc. for this object are stored in the
`geometry/bundles/nissan_march` folder.  The bundle features the vehicle
geometry and a set of lights that are defined using the `<basesource>`
mechanism in the GLIST file. The vehicle bundle contains 12 individual
sources that are grouped into 6 pairs:

[source,xml]
----
<geometrylist>
  <object enabled="true" search_paths="local">
    <localmaterials>nissan_march.mat</localmaterials>
    <basegeometry>
      <obj swapyz="false">
        <filename>nissan_march.obj</filename>
        ...
        [lines deleted for documentation purposes]
        ...
      </obj>
    </basegeometry>
    <staticinstance/>
  </object>

  <object enabled="true" search_paths="local" tags="headlights_low">
    <localmaterials>nissan_march.mat</localmaterials>
    <basesource>
      <pointsource matid="headlight_low">
        <pointing><vector><x>0.0</x><y>1.0</y><z>0.0</z></vector></pointing>
      </pointsource>
    </basesource>
    <staticinstance>
      <translation>
        <point><x>-0.86</x><y>1.86</y><z>0.7</z></point>
      </translation>
    </staticinstance>
    <staticinstance>
      <translation>
        <point><x>+0.86</x><y>1.85</y><z>0.7</z></point>
      </translation>
    </staticinstance>
  </object>

  ...
  [lines deleted for documentation purposes]
  ...

  <object enabled="true" search_paths="local" tags="right_turn">
    <localmaterials>nissan_march.mat</localmaterials>
    <basesource>
      <pointsource matid="turn_light_orange">
        <pointing><vector><x>0.0</x><y>1.0</y><z>0.0</z></vector></pointing>
      </pointsource>
    </basesource>
    <staticinstance>
      <translation>
        <point><x>+0.86</x><y>+1.85</y><z>0.7</z></point>
      </translation>
    </staticinstance>
    <staticinstance>
      <translation>
        <point><x>+0.86</x><y>-1.85</y><z>0.7</z></point>
      </translation>
      <rotation units="degrees" rotationorder="xyz">
        <cartesiantriple><x>0</x><y>0</y><z>180</z></cartesiantriple>
      </rotation>
    </staticinstance>
  </object>
----

Below is a summary of the sources and the associated tag names:

* Head lights, low beam: Left and right, tag = "headlight_low"
* Tail lights: Left and right, tag = "taillight"
* Brake lights: Left and right, tag = "brakelight"
* Turn signals (left side): Front and back, tag = "left_turn"
* Turn signals (right side): Front and back, tag = "right_turn"

The tag names associated with the base source are important because they
are what is used to link the temporal enable/disable commands to the
geometry.

The material file in the bundle describes the radiometric properties of
the different sources.  These materials are associated with the sources
in the GLIST using alpha-numeric labels (IDs). Note that the turn signal
source used the `BLINK_FREQUENCY` to define the frequency at which the
turn signals will flash when they are enabled.  The "blink" mechansim
is a instantaneous and binary on/off (not too different from most modern
LEDs). If a softer on/off tranistion is desired, the appropriate frequency
spectrum can be supplied.


=== Enable/Disable Control File
To manipulate these tagged geometry items, a Comma Separated Variable (CSV)
"control" file is created.  The first line of the file defines the tags to
be controlled.  The remaining lines specify the enable/disable state of the
list of tagged geometry items as a function of time.

NOTE: The control file can be used to enable/disable *any* geometry.  It is
      a generic mechanism that is being used here to control sources.

Consider the example control file below. The first line defines the tags
in the geometry we want to control. In this case, we have listed tags
we associated with our sources in the GLIST file.  The remaining lines
define times at which the enable/disable state for all the tag geometry
will be changed.  The simulation relative time is the first token, and the
remaining tokens represent the "state" for that tagged geometry.  A value
of `0` disables the geometry and a value of `1` enables the geometry.

NOTE: The enable/disable token can be a fraction between [0,1]. Hence, an
      alternative to the approach of having a separate set of low- and
      high-beam sources could be to change the magnitude of a single
      source. For example, "off" would be a value of `0.0`, "low" could
      be a value of `0.5` and "high" could be a value of `1.0`.  However
      high-beams are also aimed higher (further down the road) than low
      driving lights.

This demo has two instances of the same car bundle in it. One is parked
and one drives, turns into a parking spot and then stops.  Each instance
will have it's own control file.

The control file for the parked car can be found as
`geometry/control/nissan_march0.txt`.  The first line is the name of the
tagged items we want to control. The remaining lines are toggle states for
the corresponding items. For the parked car, we start by making all the
lights off (everything gets state `0`) and then we turn on the headlights
and taillights 5 seconds into the simulation:

----
"headlights_low","taillights","brakelights","left_turn","right_turn"
"0.0","0","0","0","0","0"
"5.0","1","1","0","0","0"
----

The control file for the driving/parking car is found as
`geometry/control/nissan_march1.txt`.
In this case, we start with the low headlights and taillights enabled.
A second later we switch from the low to high headlights by disabling one
and enabling the other. Shortly later, we switch back. At t = 2 seconds the
brakelights are enabled, followed by the left turn signals. As a reminder,
the turn signal sources have an inherent blink frequency and do not need
to be toggled on/off in this control file. After the turn into the parking
spot, the left turn signals and brakelights are disabled. The brakelights
come on one last time as the car comes to a stop. And finally, all the
lights are turned off:

----
"headlights_low","taillights","brakelights","left_turn","right_turn"
"0.0","1","1","0","0","0"
"1.5","1","1","1","0","0"
"2.0","1","1","1","1","0"
"5.5","1","1","0","0","0"
"7.5","1","1","1","0","0"
"8.5","0","0","0","0","0"
----

IMPORTANT: The use of double-quotes is important to the parsing of a CSV
           file.  This allows the CSV tokens to contain whitespace and
           other commas.


=== Binding the Bundle and Commands
The control file is bound to a specific instance of a GLIST `<object>`,
which allows each instance to have a unique set of commands associated
with it.  This is done using the `control` attribute in either a
`<staticinstance>` or `<dynamicinstance>` element.  Below is a portion of
the main GLIST file for the simulation (see `geometry/demo.glist`).  Here
we can see the two instances (one static and one dynamic) being defined
and each getting a unique control file assigned to it:

[source,xml]
----
  <object enabled="true">
    <basegeometry>
      <glist>
        <filename>bundles/nissan_march/nissan_march.glist</filename>
      </glist>
    </basegeometry>
    <staticinstance tags="nissan_march0" control="control/nissan_march0.txt">
      <translation>
        <point><x>-2.6</x><y>6.0</y><z>0.0</z></point>
      </translation>
      <rotation units="degrees" rotationorder="xyz">
        <cartesiantriple><x>0</x><y>0</y><z>90</z></cartesiantriple>
      </rotation>
    </staticinstance>
    <dynamicinstance tags="nissan_march1" control="control/nissan_march1.txt">
      <motion type="generic">
        <filename>motion/nissan_march1.ppd</filename>
      </motion>
    </dynamicinstance>
  </object>
----


== Setup ==
This section includes any step-by-step instructions for running and
visualizing the simulation.  Since this is a night (low-light) scene,
the convergence parameters should be adjusted to use a lower threshold.

To run the single-frame simulation, use the following syntax:
----
$ dirsig5 --convergence=50,300,1e-12 demo.sim
----

or to run the multi-frame (animation) simulation, use the following syntax:
----
$ dirsig5 --convergence=50,300,1e-12 video.sim
----


== Results ==
The `video.sim` simulation produces 72 image frames that spans the 9
second task window. 

.Animation of video simulation.
image::video.gif[]
