LidarWhisk1
===========

Keywords: lidar

== Summary ==
This demonstrates a nadir viewing LIDAR system that whisk scans across the
scene.  In this demo, we shoot 12 pulses as the system scans.

== Details ==
This demo models a LIDAR system with a simple transmitter and a 128 x 128 
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 both a Linear mode and Geiger mode detector model to produce 
ASCII/Text XYZ point clouds.  The LIDAR 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): 2000 Hz
Pulse length: 2 ns
Pulse energy: 1 mJ
----

==== Receiver ====
----
Focal length: 400 mm
Array size: 128 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]
...
Pulse #1:
    Minimum total photons in a pixel = 9.09949
    Maximum total photons in a pixel = 24.3864
    Pixels with zero total photons = 0/16384 (0%)
    Average background photons per pixel = 3.05467e-05
    Average total photons per pixel = 17.8523

...

Pulse #12:
    Minimum total photons in a pixel = 9.09505
    Maximum total photons in a pixel = 24.3765
    Pixels with zero total photons = 0/16384 (0%)
    Average background photons per pixel = 2.96592e-05
    Average total photons per pixel = 17.845

Complete!
----


=== Run the Linear-mode (Lm) Detector Model ===
To generate a linear mode detector model on the spatial x spatial x time
data captured in the `demo.bin` file, the detector model should be run
in _linear_ mode with the following parameters:

* A delay time of *2 ns*
* A dead time of *2 ns*

Generating the Linear-mode point cloud product can be accomplished using
the graphical interface to the *LIDAR Detector Model* or via the
command-line:
----
$ simple_processor --input_filenames=demo.bin \
    --model=linear \
    --delay_time=2.0e-09 --dead_time=2.0e-09 --return_count=3 \
    --output_format=ascii --output_filename=demo_linear.xyz
----

This produces the "demo_linear.xyz" file, which is an ASCII/text point
cloud, that can be visualized in most 3D point cloud viewers or generic
plotting tools.


=== Run the Geiger-mode (Gm) Detector Model ===
The Geiger-mode detector model simulation uses detector specifications
commonly found in commercial Geiger-mode array devices:

* Photon detection efficiency (PDE) of *0.5*
* Dark count rate (DCR) of *5 kHz*

Generating the Geiger-mode point cloud product can be accomplished using
the graphical interface to the general detector model or via the
command-line:
----
$ simple_processor --input_filenames=demo.bin \
    --model=geiger --pde=0.5 --dcr=5.0e+03 \
    --output_format=las --output_filename=demo_geiger.las
----

NOTE: The large average link budget (nearly 30 photons/pixel) is
      significantly higher than an actual Geiger-mode system would use.
      Expected link budgets for a Geiger-mode system is usually less than
      1 photon/pixel.


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

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

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

