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

Keywords: geolocation

This demo includes various examples of geolocated objects and platforms.

== Summary ==
Scene geometry and the platform location can be specified using
geocoordinates.  DIRSIG supports the Geographic (latitude, longitude
and altitude), Universal Transverse Mercator (UTM) and Earth-Centered,
Earth-Fixed (ECEF) coordinate systems in the GLIST file (to position
geometry instances) and the 
http://www.dirsig.org/docs/new/ppd.html[PPD] file (to position and
orient scene geometry and the platform).

== Details ==
This demo focuses on different places that the user can utilize any of
the http://www.dirsig.org/docs/new/coordinates.html[geographic coordinate]
systems available in DIRSIG.  Although we strongly encourage users to 
build scenes in the *Scene ENU* coordinate system because the entire
scene can be relocated by just changing the geographic coordinate of 
the scene origin, there are clearly cases when it is preferrable to
use geographic coordinates.  This demo guides the user through the various
places where geographic coordinates can be used.

== Important Files ==
=== Scene GLIST File
The `geometry/demo.glist` file include two objects: the ground and a 
fighter.  The ground object is instanced using the Scene ENU coordinate
system:

.The ground object using a Scene ENU instance.
[source,xml]
----
include::geometry/demo.glist[lines=3..16]
----

The fighter is instanced using the geographic coordinate system:

.The fighter object using a geographic instance.
[source,xml]
----
include::geometry/demo.glist[lines=18..34]
----

=== Platform Motion Files
This demo includes examples using both the 
http://www.dirsig.org/docs/new/ppd.html[GenericMotion] and
http://www.dirsig.org/docs/new/flex_motion.html[FlexMotion] models.
For each motion model, there are then 6 separate setups, each using
a different combination of coordinate systems for the location and
orientation of the platform. The table below summarizes the coordinate
system combinations employed by each setup:

.Table of included Generic and Flex motion model files.
[options="header"]
|====
|Filename               |Motion Model      |Location       |Orientation
|`enu_enu.ppd`          |Generic           |Scene ENU      |Scene ENU
|`enu_ecef.ppd`         |Generic           |Scene ENU      |ECEF
|`ecef_enu.ppd`         |Generic           |ECEF           |Scene ENU
|`ecef_ecef.ppd`        |Generic           |ECEF           |ECEF
|`geodetic_enu.ppd`     |Generic           |Geodetic       |Scene ENU
|`geodetic_ecef.ppd`    |Generic           |Geodetic       |ECEF
|`enu_enu.motion`       |Flexible          |Scene ENU      |Scene ENU
|`enu_ecef.motion`      |Flexible          |Scene ENU      |ECEF
|`ecef_enu.motion`      |Flexible          |ECEF           |Scene ENU
|`ecef_ecef.motion`     |Flexible          |ECEF           |ECEF
|`geodetic_enu.motion`  |Flexible          |Geodetic       |Scene ENU
|`geodetic_ecef.motion` |Flexible          |Geodetic       |ECEF
|====

There is a corresponding `.sim` file for each GenericMotion setup
(i.e., `generic_ecef_enu.sim` uses `ecef_enu.ppd`) and a corresponding
`.jsim` file for each FlexMotion setup (i.e., `flex_ecef_enu.jsim` uses
`ecef_enu.motion`).
  
== Setup ==
To run any of the simulations, perform the following steps:

. Run the DIRSIG `generic_enu_enu.sim` file
. Load the resulting `demo.img` radiance file in the image viewer.

== Results ==
Below is the RGB output of the GenericMotion simulation using ECEF
location and Scene ENU orientation (i.e., `generic_ecef_enu.sim`)
using the default gamma scaling.

.Output of the GenericMotion ECEF+ENU simulation (gamma scaling).
image::images/ecef_enu_demo.img.png[width=640]

Below is the RGB output of the GenericMotion simulation using ECEF
location and ECEF orientation (i.e., `ecef_enu.sim`) using the
default gamma scaling.  The change in view orientation compared to
the ECEF+ENU simulation is due to the default image "top" or "up"
axis convention when using ECEF.

.Output of the GenericMotion ECEF+ECEF simulation (gamma scaling).
image::images/ecef_ecef_demo.img.png[width=640]
