EarthShine1
===========

Keywords: space situational awareness

== Summary ==
This demo shows how to setup an exo-atmospheric sensor that is looking at a
second exo-atmospheric object (a satellite).  In this scene, the earth serves
as a backdrop for the satellite.  Specifically, the earth is reflected in
the bottom of the satellite.  This makes the earth a secondary source of
radiance for that object.


== Details ==
Some of the key elements of this simulation inolve the positioning of
exo-atmospheric objects.  In this case, both the imaging platform and our
satellite will be exo-atmospheric.  The Earth-Centered Earth-Fixed
(link:http://www.dirsig.org/docs/new/coordinates.html#_the_earth_centered_earth_fixed_ecef_coordinate_system[ECEF])
coordinate system is employed, which is a more natural choice than 
link:http://www.dirsig.org/docs/new/coordinates.html#_the_scene_east_north_up_scene_enu_coordinate_system[Scene ENU]
coordinate system for this scenario.  Therefore, this simulation uses
link:http://www.dirsig.org/docs/new/glist.html[GLIST] files rather than
a link:http://www.dirsig.org/docs/new/odb.html[ODB] files because
the GLIST file allows you to specify the location and orientation using
the ECEF coordinate system.  

The two ECEF locations are key to this simulation.  They were _not_
selected to mimic any real-world scenario.

Imaging Satellite Location::
    ECEF -689390.0, 6340312.0, 2741500.0

Target Satellite Location::
    ECEF -689350.0, 6340300.0, 2741500.0


== Important Files ==
Some of the important aspects of this simulation scenario include the
geometry of the scene and the approach used to map materials onto the earth
object.
  
=== Geometry ===
This scene employs a few tricks to make the geometry for the scene.  All of
the geometry is in the `geometry` folder.

crinkle_tube.obj::
    This OBJ file is a simple cylinder that has been slightly deformed to
    resemble the "crinkle" of the multi-layer insulation (MLI) usually
    applied on the exterior of spacecraft.

simple_sat.odb::
    A "simple satellite" is the target object being observed by our
    imaging platform in the simulation.  The object is created using
    primitive constructive geometry.  It is composed of two instances
    of the `crinkle_tube.obj` file (a cylinder).  One instance has the
    scales set such that it is slightly longer but has a smaller
    diameter than the other.

simple_sat.glist::
    This is the file that positions our simple satellite in the scene.  
    It has a single instance that places the `simple_sat.odb` file at
    the ECEF coordinate defined earlier.

earth.glist::
    A simple earth object sits in the background (behind the simple
    satellite) in this simulation.  The geometry for this object utilizes
    the GLIST file's
    link:http://www.dirsig.org/docs/new/glist.html#_sphere[sphere]
    geometry primitive.  The radius of the sphere is set to the earth's
    equatorial radius.  The static instance for the sphere performs
    two tasks: (1) it scales the sphere in the Z dimension to make the
    sphere an oblate spheroid and (2) is places the sphere center at
    the ECEF origin.  The Z axis rotation can be used to rotate the
    Earth so that different parts of the Earth appear behind the
    satellite.


=== Materials ===
The Earth sphere (defined in the `earth.glist` file) has the surface
materials defined by MODIS derived class map (reprocessed to create
4 material classes).  This material map setup is defined in the
`.scene` file.

=== Atmosphere ===
This scenario utilizes the *Uniform* atmopshere model, which permits
positioning of the Sun directly above the satellite.

=== Platform Positioning ===
The platform positioning (motion) for this scenario uses the *Flexible
Motion* model.  The setup locates the image platform at one ECEF location
and the orientation is defined to look at the ECEF location where the
target satellite is located.

----
<motion type="flexible">
  <locationengine type="fixed">
    <location type="ecef">
      <x>-689390.0</x><y>6340312.0</y><z>2741500.0</z>
    </location>
  </locationengine>
  <orientationengine type="lookat">
    <locationengine type="fixed">
      <location type="ecef">
        <x>-689350.0</x><y>6340300.0</y><z>2741500.0</z>
      </location>
    </locationengine>
  </orientationengine>
</motion>
----

== Setup ==
The target location, camera location, camera focal length and pixel
pitch are purely notional, and not meant to represent any currently
existing system. 

To run the simulation, perform the following steps:

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


== Results ==
The resulting RGB image using the *Selected Two Percent Scaling*
in the DIRSIG built-in image viewer is shown below.  The target
satellite appears in the middle of the image.  The illumination on
the underside of the satellite is light reflected by the Earth
below.

.The resulting RGB image with the two percent scaling
image::images/radiance_two_percent.png[]
