TrackingMount1
==============
:source-highlighter: highlight.js

Keywords: mount

== Summary ==
This scene demonstrates the *Tracking* mount, which will always
point at a specific target geometry instance.  The mount accounts
for both platform and target motion.  It is useful for setting up
scenarios such as a UAV with a camera ball that follows a vehicle
on the ground.

== Details ==
The scene contains a moving fighter jet and a moving truck.  The
imaging platform is moving due east and stares at the fighter jet.
The tracking mount will dynamically compute the platform-relative
pointing during the simulation to have the attached camera stare
at either the fighter jet or the truck.

== Important Files ==
There are two components to setting up a tracking mount:

. The geometry list (http://www.dirsig.org/docs/new/glist.html[GLIST]) file
  must have a unique name (or tag) assigned to the instance to be tracked.
. The http://www.dirsig.org/docs/new/mounts.html#TrackingMount[tracking mount]
  must be selected and configured in the platform file.

=== Scene Geometry ===
The `geometry/tracking.glist` GLIST file contains the scene gometry including
a ground plane, a moving jet fighter and a moving truck.  The truck and
fighter each have a single "named" instance.  A "named" instance is an
instance with the `name` attribute set to unique string.  This name can be
used for a variety of purposes.  In this scenario, the name will be used to
tell the tracking mount which object to track.

The following excerpt from the `geometry/demo.glist` GLIST file shows
the setup for the fighter jet, including the name `EnemyFighter` being
assigned to the one `<dynamicinstance>`:

[source,xml]
----
include::geometry/demo.glist[lines=14..23]
----

The truck inserted via the `geometry/demo.glist` GLIST file has
a single dynamic instance with the name `EnemyTruck` assigned to it:

[source,xml]
----
include::geometry/demo.glist[lines=25..34]
----


=== Mount Configuration ===
As of the DISIG 4.6.5 release, this mount can be configured in the
graphical *Platform Editor*.  However, the mount can be manually
configured by hand-editing the `.platform` file.  To select this
mount, the `type` attribute within the `<mount>` element must be
set to `tracking`.  The `<targetname>` element must be set to the
name of a named instance in the scene.  The example below the named
instance `EnemyFighter` has be specified:

[source,xml]
----
include::demo.platform[lines=23..29]
----

Note that by default the mount will point to the (0,0,0) coordinate in the
target geometry's local coordinate space.  It is possible to modify this
location using the `<targetoffset>` element, which specifies the location
in the instances local coordinate system that the mount will stare at.
For example, this could be used to have the mount stare at the front or 
rear of the fighter rather than the middle (where the fighter's origin is).
  
NOTE: To switch the tracked target from the figher to the truck, simply
      change the `<targetname>` element for the mount from `EnemyFighter`
      to `EnemyTruck`. 

The camera attached to the tracking mount has a 4 Hz read out rate and the
task has a duration of 5 seconds.  The simulation will therefore produce 20
individual image files.

== Simulations and Results ==
=== Fighter Tracking Scenario
The time-lapse animation below shows the frames from the simple camera
staring at the fighter jet as the imaging platform flies across the scene.

.Time-lapse of the camera tracking the fighter during the platform fly-by.
image::images/fighter.gif[]

=== Truck Tracking Scenario
If the `<targetname>` is changed to `EnemyTruck` then the camera follows
the truck:

.Time-lapse of the camera tracking the truck during the platform fly-by.
image::images/truck.gif[]

=== In-the-Loop Video Encoding
This demo also includes an "in-the-loop" video encoding example using the
inline processing option in the 
http://www.dirsig.org/docs/new/basicplatform_plugin.html#InlineProcessing[BasicPlatform]
plugin.  This is captured in the `encode.jsim` setup, which uses the
`encode.platform` file.  This is essentially the same platfrom setup
except that it includes a pair of post-processing tasks:

. At the end of each capture (`schedule="capture_completed"`), each
  radiance image is converted to a PNG file using the DIRSIG
  http://www.dirsig.org/docs/new/image_tool.html#Convert[image_tool] utility.
. At the end of the simulation (`schedule="simulation_completed"`), the
  PNG files are encoded into a MP4 video file using the
  https://ffmpeg.org[FFmpeg] utility (note, *FFmpeg* must be installed
  separately).

Post-processing tasks must be manually configured in the `.platform` XML
file.  The setup for this scenario is shown below:

[source,xml]
----
include::encode.platform[lines=72..92]
----
