StkImport1
==========

Keywords: STK, sceneless

== Summary ==
This demo shows how to ingest mission planning reports produced by
https://www.ansys.com/products/missions/ansys-stk[Systems Toolkit (STK)].
Specifically, how the DIRSIG
http://www.dirsig.org/docs/new/flex_motion.html[FlexMotion] model can
directly read STK ephemeris (`.e`) and attitude (`.a`) reports.  This
demo is also "scene-less", in that it doesn't use a conventional DIRSIG
scene and utilizes the
http://www.dirsig.org/docs/new/earthmodels.html#Grid[EarthGrid] plugin
exclusively for the scene.

== Related Materials ==
The following demos, manuals and tutorials can provide additional
information about the topics at the focus of this demo:

* Related Demos
** N/A
* Related Manuals
** The http://www.dirsig.org/docs/new/flex_motion.html[FlexMotion] model
   manual.
** The http://www.dirsig.org/docs/new/earthmodels.html#Grid[EarthGrid]
   plugin manual.
* Related Tutorials
** N/A

== Details ==
The orbit of the WorldView-2 satellite was modeled in STK using the
Two-Line Element (TLE) for the vehicle in 2012.  A 2 minute long
portion of the orbit where the vehicle passed over Ontario Canada,
Western NY, PA, etc. was selected and exported as standard STK
ephemeris and attitude reports.  A screenshot of the selected orbital
path in STK is shown below:

.Screenshot of the WorldView-2 vehicle path in STK.
image::images/WORLDVIEW-2_35946.png[]

== Important Files ==
This section highlights key files important to the simulation.

=== The FlexMotion STK Import Setup
The STK ephemeris and attitude reports are used directly by the
http://www.dirsig.org/docs/new/basicplatform_plugin.html[BasicPlatform]
plugin directly via the STK import options available in the FlexMotion
http://www.dirsig.org/docs/new/flex_motion.html#_waypoints[waypoint] and
http://www.dirsig.org/docs/new/flex_motion.html#_quaternions[quanternion]
engines.
The `WORLDVIEW-2_35946.e` and `WORLDVIEW-2_35946.a` are the respective
ephemeris and attitude report files generated for the previously 
described orbital pass in STK.

.The `demo.motion` file featuring the direct STK import method.
[source,xml]
----
include::demo.motion[]
----

The `video.tasks` (and `demo.tasks`) file mirrors the collection start 
(`21 May 2012 16:36 UTC`) and 2 minute duration of the orbital pass
modeled and exported from STK:

.The `video.tasks` file.
[source,xml]
----
include::video.tasks[]
----

NOTE: The `demo.tasks` file captures a single frame halfway through the 2
      minute pass modeled in STK.

Although the satellite orbit at the heart of this simulation is for 
WorldView-2 (a multi-spectral pushbroom sensor), the sensor used in 
this demonstration is a 640 x 480 2D framing array sensor with RGB
channels (see `demo.platform` for more information).

The `demo.platform`, `demo.motion` and `demo.tasks` (or `video.tasks`)
are supplied to the
http://www.dirsig.org/docs/new/basicplatform_plugin.html[BasicPlatform]
plugin instance in the simulation:

.The BasicPlatform setup in the `demo.jsim` file.
[source,json]
----
include::demo.jsim[lines=24..31]
----

=== The Scene-less EarthGrid Setup
The 2nd major component of this simulation is that it demonstrates a
"scene-less" scenario.  There is not a conventional DIRSIG scene in the
simulation (the JSIM `scene_list` is empty), instead it utilizes the 
http://www.dirsig.org/docs/new/earthmodels.html#Grid[EarthGrid] plugin
to provide the primary geometry for the scene.  In this case, the
plugin is configured with a image using
https://visibleearth.nasa.gov/collection/1484/blue-marble[NASA Blue Marble]
imagery and the `major_lines` and `minor_lines` are setup so that they are
not displayed (the half width is set to `0`).

.The "scene-less" setup using the EarthGrid plugin in the `demo.jsim` file.
[source,json]
----
include::demo.jsim[lines=1..12]
    ...
  ]
  ...
}]
----

== Simulations and Results ==
=== The Single-Frame Simulation
Run the single-frame `demo.sim` file using DIRSIG5:
----
$ dirsig5 demo.jsim
----

Load the resulting `demo-t0000-c000.img` radiance file in the DIRSIG
image viewer and display the RGB bands using one of the high dynamic
range scaling options (e.g., "two sigma" or "two percent" scaling).
Alternatively, the `image_tool` provides the non-linear "gamma" scaling
option, which can be used to directly produce a PNG with the following
syntax:

----
$ image_tool convert demo-t0000-c0000.img
----

.The single-frame simulation.
image::images/demo.png[]


=== The Multi-Frame Simulation
Run the multi-frame `video.jsim` file using DIRSIG5:
----
$ dirsig5 video.sim
----

All the frames produced by the multi-frame simulation can be scaled in a
single execution of the `image_tool` by using the appropriate wildcards
for the image filename and then encoded into a video file with the
https://ffmpeg.org/[FFmpeg] video encoder:

----
$ image_tool convert --all_same demo-t0000-c*.img
$ ffmpeg -framerate 30 -i demo-t0000-c%04d.img.png -codec:v libx264 -profile:v high -pix_fmt yuv420p video.mp4
----

.An animatation of the multi-frame simulation.
video::images/video.mp4[]
