LidarMultiStatic1
=================

Keywords:

== Summary ==
This demonstrates a multi-static (multi-vehicle) LIDAR collection scenario.
It features a single transmitter and two receivers distributed on three
separate vehicles.

== Details ==
A multi-static lidar collection system can have multiple transmitter
and/or receiver systems distributed across one or more vehicles.
The goal of this demo is to show how to configure such a scenario
in DIRSIG.  In this demo, a single single transmitter and two
receivers are mounted on three separate vehicles.  To keep things
simple, this demo has both the transmitter and receiver vehicle
statically positioned and only a single pulse is fired.  However,
this is not a limitation of the model and multiple pulse collections
with independenly moving vehicles is certainly supported.

In addition to covering the basics of a multi-static lidar collection
scenario, this demo covers the following topics:

* Using the DIRSIG5 JSIM file to configure multiple sensor plugins 
  for a single simulation.
* Using the "receiver path fraction" option in the detection model to
  handle asymmetric transmitter to target and target to receiver paths.


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

=== The JSIM ===
This simulation configuration requires use of the DIRSIG5-specific
JSIM file, which allos the user to directly configure the plugins
used in the simulation.  This is required in order to run this
multi-static collection as a single simulation because three instances
of the *BasicPlatform* plugin are required (one for the transmitter
and one for each receiver).  The DIRSIG4-era XML `.sim` file support
in DIRSIG5 is there for backwards compatibility, and it will only
create a single instance of the *BasicPlatform* plugin.

NOTE: If you want to approximate this demo using the DIRSIG4-era XML
      `.sim` file method, you would need to make a pair of bi-static 
      platform files, a pair of XML sim files and run each as a 
      separate simulation.  However, the transmitter configuration
      would now be duplicated in each bi-static system setup, which
      would make it more difficult to centralize the configuration
      of that component.

The contents of the `demo.jsim` file are shown below, showing how
to request and configure multiple plugins:

.The `demo.jsim` file.
----
[{
    "scene_list" : [
        { "inputs" : "./demo.scene" }
    ],
    "plugin_list" : [
        {
            "name" : "BasicAtmosphere",
            "inputs" : { "atmosphere_filename" :"./simple.atm" }
        },
        {
            "name" : "BasicPlatform",
            "inputs" : {
                "platform_filename" : "./tx.platform",
                "motion_filename" : "./tx.ppd",
                "tasks_filename" : "./demo.tasks"

            }
        },
        {
            "name" : "BasicPlatform",
            "inputs" : {
                "platform_filename" : "./rx.platform",
                "motion_filename" : "./rx1.ppd",
                "tasks_filename" : "./demo.tasks",
                "output_prefix" : "rx1_"
            }
        },
        {
            "name" : "BasicPlatform",
            "inputs" : {
                "platform_filename" : "./rx.platform",
                "motion_filename" : "./rx2.ppd",
                "tasks_filename" : "./demo.tasks",
                "output_prefix" : "rx2_"
            }
        }
    ]
}]
----

After the scene list is the plugin list for the simulation. The
first plugin is an instance of the *BasicAtmosphere* plugin, which
provides backward compatibility with DIRSIG4 atm configurations.
In this case, the `simple.atm` file configures a classic DIRSIG4-era
"simple" atmosphere.  

The remaining three plugins are all instances of the *BasicPlatform*
plugin, each with a slightly different set of input files.  They
are all part of a common collection, so they all use the same
`demo.tasks` file.  This task file contains a single, zero duration
task that results in a single pulse being fired and received.

NOTE: The shared use of a single task by all the *BasicPlatform* plugin
      instances is not a requirement but rather a choice to make this
      scenario easy to understand.

The remaining sensor plugin files will be discussed separately in the
sections below:

=== The Transmitter Vehicle ===
The transmitter system is described in the `tx.platform` file.
Note that this platform only contains a transmitter instrument.
This platform file could be created with the graphical *Platform Editor*
by adding a "bi-static source instrument" to the platform.  The
transmitter instrument related portion of this file is shown below:

.Relevant portion of the `tx.ppd` file.
----
        ...
        <instrument type="laser" name="Transmitter">
          <clock type="independent" temporalunits="hertz">
            <rate>2000</rate>
            <offset>0</offset>
          </clock>
          <properties spatialunits="meters"/>
          <source policy="standard">
            <spectral spectralunits="microns">
              <shape type="gaussian">
                <center>1.064</center>
                <width>0.0003</width>
              </shape>
            </spectral>
            <spatial symmetry="radial" angularunits="radians">
              <shape type="supergaussian">
                <center>0</center>
                <width>0.016</width>
                <order>1</order>
              </shape>
            </spatial>
            <temporal energyunits="joules" temporalunits="seconds">
              <pulseenergy>0.001</pulseenergy>
              <shape type="gaussian">
                <center>0</center>
                <width>2e-09</width>
              </shape>
            </temporal>
            <polarizer type="none"/>
            <throughput>1</throughput>
          </source>
        </instrument>
        ...
----

Note that the clock for the transmitter is specified as `2000` Hz (or 2 kHz)
with a `0` absolute time offset. When working with a multi-static system,
the use of independent clocks with coordinated rates and offsets is
important to synchronizing the various transmitter and receiver
instruments.

The second component of the transmitter vehicle is the platform motion
file.  The `tx.ppd` file, which places the vehicle directly over the scene
ENU origin at 2000 m (location is `0,0,2000`).  The rotation angles are
all `0`, which results in the system shooting pulses straight down.

NOTE: Replacing the platform motion with realistic, dynamic motion is
      certainly allowed but was not performed here to keep the scenario
      easier to understand.

.The `tx.ppd` file
----
    ...
    <entry>
      <datetime type="relative">0</datetime>
      <position>
        <scenelocation>
          <point><x>0</x><y>0</y><z>2000</z></point>
        </scenelocation>
      </position>
      <orientation>
        <eulerangles>
          <cartesiantriple><x>0</x><y>0</y><z>0</z></cartesiantriple>
        </eulerangles>
      </orientation>
    </entry>
    ...
----


=== The Receiver Vehicles ===
Although there are two receiver platforms in this simulation, there
is only one receiver platform file (see `rx.platform`).  This platform
file could be created in the graphical *Platform Editor* by adding a
"bi-static receiver instrument" to the platform.  Inspection of this
platfrom will reveal that is contains a single focal plane instrument
with the appropriate range gate for the expected time of flight based
on the collection geometry.  It is important to note that the clock
for the receiver instrument is `2000 Hz` with an absolute offset
of `0` seconds, which identical to the transmitter.  The use of
matched clocks tied to the same absolute time offset is how this
multi-static collection system is synchronized.

The use of a single platform file for both receiver instruments is not
a requirement as each receiver can have a unique configuration.
Instead this approach was chosen to show how one or more perfect clones
of platform can be created and used in a simulation.  Reviewing the
JSIM file, you will see that each receiver vehicle (the two instances
of the *BasicPlatform* plugin using the `rx.platform` file) has a
unique platform motion file.  This is what creates the multi-static
collection geometry.  The two receiver instruments are looking at
the target area from the same altitude (2000 m) but from a 45 degree
off-nadir direction. The first vehicle is offset 2000 meters to the
south (-2000 Y in Scene ENU, as specified in the `rx1.ppd` file) and
the second vehicle is offset 200 meters to the east (+2000 in X in
Scene ENU, as specified in the `rx2.ppd` file).  Each PPD file has
the appropriate orientation rotation to point the receiver vehicle
toward the target area at the scene origin (`0,0,0`).

.The location and orientation for the 1st receiver from the `rx1.ppd` file.
----
    ...
    <entry>
      <datetime type="relative">0</datetime>
      <position>
        <scenelocation>
          <point><x>0</x><y>-2000</y><z>2000</z></point>
        </scenelocation>
      </position>
      <orientation>
        <eulerangles>
          <cartesiantriple><x>0.785398</x><y>0</y><z>0</z></cartesiantriple>
        </eulerangles>
      </orientation>
    </entry>
    ...
----

.The location and orientation for the 2nd receiver from the `rx2.ppd` file.
----
    ...
    <entry>
      <datetime type="relative">0</datetime>
      <position>
        <scenelocation>
          <point><x>2000</x><y>0</y><z>2000</z></point>
        </scenelocation>
      </position>
      <orientation>
        <eulerangles>
          <cartesiantriple><x>0</x><y>0.785398</y><z>0</z></cartesiantriple>
        </eulerangles>
      </orientation>
    </entry>
    ...
----

Since the same platform file is being used for both receiver vehicles,
the output files generated by both vehicles will be written to the
same file (in this case, `demo.bin`).  Instead, we want to separate
the output from each receiver vehicle.  This could be accomplished
by making copies of the `rx.platform` file and changing the names
of the output files.  However, one of the goals of this demo was
to show how the receiver instrument could be cloned by using the
exact same `rx.platform` file.  To avoid each receiver from writing
to the same `demo.bin` file (which would result in each instance
clobbering the output of the other), the *BasicPlatform* plugin
supports "output folder" and "output prefix" options via the JSIM
description. These options are the same as the command-line
`--output_folder` and `--output_prefix` options, but more importantly
the JSIM mechanism lets you specify these _for each plugin instance_.
In this case, the output prefix for the first and second receivers
are `rx1_` and `rx2_`, respectively, which will result in the final
files produced by the simulation being `rx1_demo.bin` and `rx2_demo.bin`.

TIP: Any time you find yourself making copies of a platform file
     simply to change the output filenames, consider using these
     output folder and/or prefix options instead.

It should be noted that the primary reason the same platform file can
be used for both receivers in this scenario is because the time of flight
is the same to both receivers.  Although each receiver is positioned
in a different location and at a different orientation, the time of 
flight for both is the same.  If each receiver is going to have a
unique time of flight, then the a unique platform file with the
corresponding listening window (range gate) would need to be created.


== Setup ==
This section includes any step-by-step instructions for running and
visualizing the simulation.

=== Radiometry Simulation ===
To run the simulation, perform the following steps:

. Run the DIRSIG `demo.jsim` file from the command-line using DIRSIG5.

NOTE: JSIM simulations *cannot* be loaded and/or run from the graphical
      user interface at this time.

=== Detection Simulation ===
The second component of any DIRSIG lidar simulation is running the 
radiometric product through the detection model to generate time of
flight (ToF) triggers, and then convert those triggers into a 3D point
cloud.  There are two aspects of this demo that are unique compared 
to most of the other DIRSIG lidar demos:

. This demo had two receiver and each produced a separate BIN file
  that will need to be processed, and
. This demo has an asymmetric transmit and receive path geometry (the
  time of flight from the transmitter to the scene is not the same as
  the time of flight from the scene to the receiver).

The `simple_processor` already supports the ingestion of multiple
BIN files and will produce a single point cloud that merges the
points generated by each receiver. Using this approach means that
the characteristics of each receiver will be identical.  If you
want each receiver to have unique detection properties (detector
characteristics, knowledge errors, etc.) then you would need to
process each BIN file separately and provide the appropriate receiver
parameters for each.

A typical mono-static system or even a bi-static system on the same
vehicle can generally make the assumption that the range to the
scene element that reflected (scattered) the transmitted pulse back
to the receiver can be found by assuming it was half way through
the total time of flight.  This is because the time of flight from
the transmitter to the scene is assumed to be the same as the time
of flight from the scene to the receiver.  However, for this scenario
the receiver is off-axis from the transmitted (45-degrees), which
makes the relative Tx/Rx path ratio 1/sqrt(2).  This asymmetric Tx
and Rx path time of flight scenario means that assuming the reflection
(scattering) event occured half way along the total path is wrong.
We cannot ask photons where they have been and how long they took
to go there, so addressing this asymmetry involves supplying
additional knowledge.  The `simple_processor` has an option called
`--rx_path_fraction` that allows the user to specify the fraction
of the total time of flight that corresponds to the path from the
reflection (scattering) event to the receiver.  The default is `0.5`
(mono-satic symmetry assumption).  For this collection scenario
both receivers see a total path that would nominally include the
2,000.0 meters from the transmitter to the scene and then 2,828.4
meters from the scene to the transmitter. That results in receiver
path fraction being `0.5857`.

IMPORTANT: It should be recognized that this knowledge of path
           asymmetry is not a limitation of DIRSIG but rather a
           fundamental aspect of these sorts of collections.

The command line below shows how to run the detection model on both
receiver BIN files using an ideal GmAPD system (unity photon detection
efficiency (PDF) and zero dark count rate (DCR)) with the computed
recieve path fraction and producing a single LAS with the points
from both receivers merged:

----
$ simple_processor --model=geiger --rx_path_fraction=0.5857 --input_filenames=rx1_demo.bin,rx2_demo.bin --output_eog=false --output_format=las --output_filename=multi-static.las
----

NOTE: The specific detection model used in the above example is not
      important. The key in this example is (1) the comma-separated list
      of BIN files supplied to the `--input_filenames` and (2) the use
      of the `--rx_path_fraction` option.

== Results ==
The point cloud below illustrates what happens if the Rx and Tx
paths are assumed to be symmetric. By assuming the wrong fraction of
the total time of flight, the computed range from the reciever to the
reflection event that caused the return is wrong, resulting in an
offset of the points for that receiver. Since each receiver was in a
different location, the offset results in the generation of offset
points that is unique to each receiver and they do not overlap as
expected.

.The resulting point cloud assuming Rx and Tx path symmetry.
image:images/assuming_path_symmetry.png[width=480]

When using the `--rx_path_fraction` option, the correct fraction of
the total time of flight is used and now the points from the two
receivers overlap at the right location.

.The resulting point cloud assuming Rx and Tx path asymmetry.
image:images/assuming_path_asymmetry.png[width=480]
