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

Keywords: space


== Summary ==
This demo simulations "earth shine" or the reflection of the Earth
is a space-based object.  In this case a reflective sphere has been
placed above the Earth.  This DIRSIG simulation models the earth
via the
http://www.dirsig.org/docs/new/earthmodels.html#Grid[EarthGrid]
plugin.


== 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.
** The http://www.dirsig.org/docs/new/ephemeris.html#Spice[SpiceEphemeris]
   plugin manual.
* Related Tutorials
** N/A

== Details ==
This section explains any technical details of the simulation.

== Important Files ==

=== The Sphere
The sphere hovering above the earth is modeled using a 
http://www.dirsig.org/docs/new/glist.html#_sphere[built-in sphere]
object that is positioned using the
http://www.dirsig.org/docs/new/flex_motion.html[FlexMotion] model
with a fixed, geodetic coordinate:

.Contents of the `sphere.glist` file.
[source, xml]
----
include::sphere.glist[]
----

NOTE: The sphere instance has the `::IMPORTANT::` tag assigned to
      it, which will be used by the BasicPlatform plugin to enable
      http://www.dirsig.org/docs/new/basicplatform_plugin.html#Hypersampling[hypersampling].
      This is done to capture the low probability, reflected earth
      contributions in the darker regions of the partially diffuse
      sphere and to test hypersampling when operating in an ECEF
      coordiate system.


=== The Earth
The Earth is modeled using the
http://www.dirsig.org/docs/new/earthmodels.html#Grid[EarthGrid]
plugin in the JSIM file:

.The `EarthGrid` plugin setup in the `demo.jsim` file.
[source,json]
----
include::demo.jsim[lines=6..13]
----


=== The Sensor
The sensor is modeled with an RGB framing array camera.  This is a
fairly vanilla BasicPlatform setup, however, the 
http://www.dirsig.org/docs/new/basicplatform_plugin.html#Hypersampling[hypersampling multiplier]
is set to `50`, which increases the min and max samples by 50x on
pixels that overlap the sphere.  As noted above, this is to capture
low probability reflections of the earth in the partially diffused
sphere.

The sensor is position is defined using the
http://www.dirsig.org/docs/new/flex_motion.html[FlexMotion] model
and leveraging the 
http://www.dirsig.org/docs/new/flex_motion.html#LookAt[lookat] engine
to look at the sphere's location:

.Contents of the `demo.motion` file.
[source, xml]
----
include::demo.motion[]
----


== Simulations and Results ==
The simulation can be run using the following command-line syntax:
----
$ dirsig5 demo.jsim
----

Load the resulting `demo.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 --gamma=1 demo.img
----

.The single-frame simulation.
image:images/full_frame.png[width=640]

.Zoom of the reflection if the Earth in the sphere.
image:images/zoom.png[width=640]
