LidarWhisk2
===========

Keywords: lidar, gmapd

== Summary ==
This demonstrates a nadir viewing Geiger-mode Avalanche Photo-diode
(GmAPD) laser radar system that whisk scans across the scene.
The collection shoots 40 overlapping pulses over a scene composed of a
tree on a background.

== Details ==
This demo models a LIDAR system with a simple transmitter and a 32 x
128 GmAPD receiver array with 2 us long listening window and 1 ns time
resolution (resulting in 2001 time bins).  The multi pulse collection
is then run through the advanced GmAPD detector model to produce an
ASCII/Text XYZ point cloud.  The advanced GmAPD detector model has
a graphical interface available under *Tools -> Lidar Tools* in the
*Simulation Editor*, as well as a command-line interface.


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

=== Geometry and Materials ===
The scene is comprised of a single maple tree (see
`geometry/Red_Maple_1.gdb`) planted at the Scene ENU origin a flat plate.
The reflectance properties are spectrally flat and not realistic (see
`materials/demo.mat` and the optical property files in the `materials`
folder).

=== Platform ===
This section summarizes the properties of the transmitter and receiver
components of the laser radar system used in this demo. 
  
==== Transmitter ====
----
Laser wavelength: 1064 microns
Pulse repetition rate (PRF): 20,000 Hz (20 kHz)
Pulse length: 1 ns
Pulse energy: 0.5 mJ
----

==== Receiver ====
----
Focal length: 1 m
Array size: 32 x 128 elements @ 50 micron pitch
Range gate width: 2 us
Range gate resolution: 1 ns
----

== Setup ==

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

. Run the DIRSIG `demo.sim` file

This produces the file `demo.bin`.


=== Run the Analysis Tool ===
It is always useful to verify the link budget (the number of photons
arriving onto the pixels during a pulse).  The *BIN Analysis* tool
can be used to examine and summarize the radiometric values and supporting
metadata in a BIN file.  This tool can be run via the *Analyze* button
in the detector model interface or via the command-line:

----
$ bin_analyze demo.bin
...
[header summaries deleted for documentation purposes]
...
    Minimum total photons in a pixel = 0.549208
    Maximum total photons in a pixel = 3.65245
    Pixels with zero total photons = 0/4096 (0%)
    Average background photons per pixel = 6.87829e-07
    Average total photons per pixel = 1.08298

...

Pulse #40:
    Minimum total photons in a pixel = 0.549208
    Maximum total photons in a pixel = 3.80463
    Pixels with zero total photons = 0/4096 (0%)
    Average background photons per pixel = 2.00738e-06
    Average total photons per pixel = 1.00801

Complete!
----


=== The Geiger-mode (Gm) Detector Model Database ===
The advanced Geiger-mode APD (GmAPD) detector model simulation uses detector
specifications that mirror the commercial available products from Princeton
Lightwave, Inc. (see
http://www.princetonlightwave.com/mm-products/3d-ladar/128-x-32-gmapd-camera#specifications):

----
Photon detection efficiency (PDE)
    Mean = 30 (typical)
    Stddev = 5 (typical)
Dark Count Rate (DCR)
    Mean = 5 (typical)
    Stddev = 3 (typical)
----

This detector performance characteristics are captured in the GmAPD
database file (see `demo.gmapd`).  Consult the *Advanced GmAPD* modeling
manual for details about creating these databases.


=== Run the Geiger-mode (Gm) Detector Model ===
Generating the Geiger-mode point cloud product can be accomplished using
the graphical interface to the general detector model or via the
command-line:

----
$ gmapd_processor --parameters demo.xyz.params
----


== Results ==
Visualizations of the Geiger-mode point cloud in GNUplot
(a simple 2D and 3D plotting tool) are shown below:

.The Geiger-mode 3D point cloud visualized in GNUplot
image::demo.png[width=640]


