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

Keywords:

== Summary ==
This is a DIRSIG5-era demonstration of looking at an exo-atmospheric
object from a ground based sensor.  In this case the object is a
suspicious "moon" satellite in a static, geo-synchronous orbit position.

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

* Related Demos
** See http://www.dirsig.org/demos/#MoonSat1[MoonSat1] for the original
   DIRSIG4 version of this demo.
* Related Manuals
** The http://www.dirsig.org/docs/new/glist.html[GLIST] manual.
** The http://www.dirsig.org/docs/new/flex_motion.html[FlexMotion] manual.
* Related Tutorials
** N/A

== Details ==
The key to this demo and what makes it specific to DIRSIG5 is how
the target object and the sensor are located.  In DIRSIG4, the ray
tracer used double-precision, which allowed the user to create
scenes that could span the solar system and still have 1 mm precision.
DIRSIG5 adopted a single-precision ray tracer to reduce memory usage
and increase speed.  However, that prevents building single scenes
that include the entire earth and the moon in a single coordinate
space.  Instead, the approach for building large scenes (including
scenes with exo-atmospheric objects) is to make smaller, individual
scenes that are positioned with the Earth-Centered, Earth-Fixed
(ECEF) coordinate system.  The ECEF coordinate system in DIRSIG5
is a double-precision coordinate system that serves as the glue to
traverse between various scenes and the sensors.

Here is a brief summary of the approach in this demo:

* The "moon" object is a scene that is composed of just the moon
  object.  Although it has a traditional geographic origin in the
  `moon.scene` file, it is largely irrelevant since the only 
  object in the scene is positioned using the ECEF coordinate
  system.
** This establishes a compact, localized coordinate system for this
   object that the ray tracer uses.
* The sensor platform is also positioned via the `demo.ppd` file
  using the ECEF coordinate system.
** As a result, the DIRSIG5
  http://www.dirsig.org/docs/new/basicplatform_plugin.html[BasicPlatform]
  plug will shoot rays that are in the double-precision ECEF
  coordinate system and traverse to the local, single-precision
  coordinate system of the scenes in the simulation.

IMPORTANT: The most important aspect of small scenes and the good 
           precision management is not just the size of the scene but
           also that the scene is localized around its local origin.
           Do _not_ create a scene with geometry that is only 10 m
           across but is offset 1,000 km from the local origin.  This
           large bias in the geometry coordinates uses up valuable
           space in the single-precisions storage.  Instead, center the
           10 m scene around the local origin and then introduce the
           offset when the scene is inserted.

To summarize the setup, the "moon" is going to be statically positioned
above the Earth.  The "moon" will be imaged from a statically positioned
sensor on the Earth, looking up at the "moon".  During the 24 hours that
will be simulated, the Earth will make a complete revolution and the
"moon" will rotate with it. In the middle of the day, the sensor is
looking up at the "back side" of the moon that is facing away from the
Sun.  In the middle of the night, the sensor is looking up at the
"front side" of moon that is facing toward the Sun.  In between, we
expect to see the Sun illuminated portiong of the "moon" move across
the visible face.


== Important Files
=== Geometry
The "moon" satellite is modeled using the built-in sphere geometry
via the http://www.dirsig.org/docs/new/glist.html#_sphere[GLIST] file,
which uses the native UV mapping of the sphere to wrap a texture
around it.  The "moon" is positioned into the scene using an ECEF
location via the
http://www.dirsig.org/docs/new/flex_motion.html[FlexMotion] model.
Note that this single instance for the moon has the
http://www.dirsig.org/docs/new/glist.html#Tags[tag] `moon` associated
with it to simplify tasking our sensor to image it.

.The `moon.glist` file.
[source,xml]
----
include::moon.glist[]
----

=== Materials
The materials for this scene are incidental as the focus of the demo
is on the positioning and viewing of an exo-atmospheric object.  The
material uses the
http://www.dirsig.org/docs/new/surface_props.html#ClassicEmissivity[ClassicEmissivity]
optical property with a 
http://www.dirsig.org/docs/new/maps.html#TextureMap[texture map] to
introduce variation.  The source image for the texture map moon can be
found in `maps/moon.png`.

.The moon material file.
[source]
----
include::materials/moon.mat[]
----

=== Platform and Tasking ===
This simulation uses a platform with a simple 320 x 240 (QVGA)
camera that has a read-out rate of `0.00055555556` (a period of
1800 seconds or 30 minutes).  The `demo.tasks` file defines an
instantaneous capture and the `video.tasks` file defines a 24 hour
(84000 seconds) collection window, which produces 47 capture frames.

The platform uses the
http://www.dirsig.org/docs/new/mounts.html#TrackingMount[tracking mount]
(with the 'moon' tag associated with the moon instance in the GLIST
file) to simplify the pointing of the sensor in ECEF space.

.The platform PPD file using ECEF location and orientation.
[source,xml]
----
include::demo.ppd[]
----
 

== Simulations and Results ==
=== Single-Frame (Still) Simulation ===
To run the single-frame simulation, perform the following steps:

. Run the DIRSIG `demo.jsim` file
. Load the resulting `demo-t0000-c0000.img` file in the image viewer.

The single-frame simulation produces a single image frame.

.Output of the single-frame simulation.
image::images/demo.png[width=480]


=== Multi-Frame (video) Simulation ===
To run the multi-frame simulation, perform the following steps:

. Run the DIRSIG `video.jsim` file
. Load the resulting `demo-t0000-c0000.img`, `demo-t0000-c0001.img`, etc.
  files in the image viewer.

The imaging instrument is setup to use the "file per capture" output
schedule.  As a result, the simulation produces 47 separate image
files for the 47 captures.  The individual frames were scaled from
radiances to 8-bit PNG files using the DIRSIG
http://www.dirsig.org/docs/new/image_tool.html#Convert[image_tool] utility.
Normally `image_tool` will autoscale each input image individual,
but in this case we want the scaling used for each image to be the
same.  Furthermore, we want a fully illuminated frame to define the
scaling for all the images.  The trick used here is to add the
`--all_same` flag, which computes the scales from the first image
and applies them to the remaining images.  To get the right scaling,
we explicitly provide a fully illuminated moon frames as the first
image file and then use a wildcard to specify the rest of the image
files.  The wildcard will include this fully illuminated image as
well, which means it will get scaled a second time.  But the scaling
is a quick operation compared to the convenience of this method.

.Converting the individual frames to PNG with a common scaling.
----
$ image_tool convert --minmax --all_same demo-t0000-c0019.img demo-t0000-c00*.img
----

The video below was created from these 47 frames using the
https://ffmpeg.org[ffmpeg] tool.

.The output of the multi-frame simulation (with the default Earth disabled).
video::images/demo.mp4[width=480]

When the "moon" is fully illuminated, it is directly facing the
Sun.  At the same time, the sensor is directly away from the Sun.
Hence, the Earth is between the Sun and the "moon".  Therefore, we
should expect to see the shadow of the Earth on the "moon" in the
middle of the night (aka, it's "full moon" phase).  This can be
observed as the moon getting darker in the frame when it is expected
to be fully illuminated (see `demo-t0000-c0018.img` corresponding
to the darker frame in the above video).  To eliminate the shadow
of the Earth, you need to disable the built-in Earth core using the
`--disable_earth_core` option.  The video below was created with
this option engaged and the dark "full moon" frame is eliminated.

.The output of the multi-frame simulation with the default Earth disabled.
video::images/demo_no_earth.mp4[width=480]

