PointCollectors1
================

Keywords: plugins, pointcollectors

== Summary ==
This demo provides a working example of the 
http://www.dirsig.org/manuals/pointcollectors_plugin.html[PointCollectors]
sensor plugin.  This plugin allows the user to arbitrarily place a
number of point radiometers in the scene and they can be configured to
collect in a variety of modes.  This type of sensor can be useful for
measuring the illumination within a scene as either a function of location,
time or both.

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

* Related Demos
** The http://www.dirsig.org/demos/#Fireball1[Fireball1] demo.
* Related Manuals
** The http://www.dirsig.org/manuals/pointcollectors_plugin.html[PointCollectors]
plugin manual.
* Related Tutorials
** None.

== Details ==
This demo leverages a specific illumination configuration combined
with specially crafted scene geometry that results in specific
locations in the scene to receive and reflect specific radiometric
fluxes.  Rather than use a conventional imaging array to verify the
computed values at the limited number of predictable locations, this
plugin allows the values at those locations to be directly measured.


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

=== The Scene ===
The scene used in this simulation is a copy of a scene referred to
as the "SkyTubes" scene, which is used behind-the-scenes for DIRSIG
testing.  The scene is composed of 9 cylinder "tubes" of various
depths. The bottoms of the tubes have a 100% Lambertian reflector
and the sides of the tubes are 100% absorbers (0% Lambertian
reflector).  The depth of the tubes were calculated to yield specific
reflected radiance steps based on the uniform sky illumination
conditions.  For example, the 1st tube is the deepest and "sees"
the least amount of sky so the least amount of illumination reaches
the bottom.  In contrast, the 9th tube is the the shallowest and
"sees" the most sky and the most illumination reaches the bottom.

.A slant-view rendering of the "SkyTubes" scene used in this demo.
image::images/slant_view.png[width=320]


=== The PointCollectors Configuration ===
The PointCollectors plugin is configured via a a DIRSIG5 
http://www.dirsig.org/manuals/jsim.html[JSIM] file.  The details of
the configuration options are discussed in detail in the 
http://www.dirsig.org/manuals/pointcollectos_plugin.html[PointCollectors]
plugin manual.  There are three simulations, and in all three setups
there are point collectors positioned just above the bottom of each
tube.  The three simulations exercise the three different types of
collectors:

. Spherical,
. Hemispherical, and
. Directional

The spherical collectors are collecting the energy from the bottom and
sides of the tubes plus some portion of the sky.  The hemispherical
collectors are pointed up, effectively ignoring the reflected energy
from the bottom of the tubes but still collecting comse amount of sky
radiance.  The directional collectors are pointing down at the bottoms
and only collecting the reflected energy.

Because of the design of the scene, we expect the radiance for all three
simulations to be the same.  Remeber that although the three collectors
are collecting over dramatically different angles, they are outputting
in radiance, which is normalized by solid angle.  For example, even though
the spherical collector is gathering energy from the bottom of the tube
and the hemispherical collector is not, they are both weighted by their
respective solid angles.  Hence, the spherical collector might gather 2x
as many photons, but it will get normalized by a 2x larger solid angle.

Below is the contents of the `points_spherical.jsim` file. The primary
difference in the three point collector JSIM files is the type of 
collector and the direction of the collector.

.Contents of the `points_spherical.jsim` file.
[source,xml]
----
include::points_spherical.jsim[]
----

== Simulations and Results ==
This section includes any step-by-step instructions for running and
visualizing the simulations included in this demo.

=== The Framing Array Simulation
The visualize the scene, a traditional framing array simulation has been
provided.

To run the simulation using DIRSIG4:

----
$ dirsig4 framing.sim
----

or using DIRSIG5:

----
$ dirsig5 framing.sim
----

The simulation produces a broad-band, panchromatic radiance image and
truth.  The image is captured from overhead looking down into the tubes.
The Z intersection truth (below) illustrates the relative depth of the 9
tubes.

.Linearly-scaled DIRSIG "Z intersection" truth is an easy way to visualize the depths of the tubes.
image::images/z_truth.png[width=320]

The reflected radiance in the tubes (below) is from the bottom and
arises from the fraction of the hemisphere above the bottom that
is sky.  The deeper tubes have less of the hemisphere being sky.
Within each tube, the gradient in reflected radiance across the
bottom arises from the decreased amount of sky closer to the walls
of each tube.

.Linearly-scaled DIRSIG radiance output shows the correlation with tube depth.
image::images/demo.img.png[width=320]


=== The PointCollectors Simulations
To run the point collectors simulation, you must use DIRSIG5. There are
three different point collection

----
$ dirsig5 points_spherical.jsim
$ dirsig5 points_hemispherical.jsim
$ dirsig5 points_directional.jsim
----

The primary output of this simulation is a text file, which was configured
in the `output` section of the plugin configuration.  Each simulation 
produces a uniquely named output file.

.Contents of the `points_spherical.txt` output file.
----
# DIRSIG5 'PointCollectors' plugin output file
# Generated on Thu Feb 3 17:02:55 2022
#
# Samples/collector: 100000
# Bandpass: 0.5 - 0.5 @ 0.02 (1 points)
# Time: 1 samples @ 0.1 second intervals
#
# Collectors:
#    Tube #1: [-2,-2,-2.93], [0,0,-1]
#    Tube #2: [0,-2,-1.95], [0,0,-1]
#    Tube #3: [2,-2,-1.49], [0,0,-1]
#    Tube #4: [-2,-0,-1.19], [0,0,-1]
#    Tube #5: [0,-0,-0.97], [0,0,-1]
#    Tube #6: [2,-0,-0.79], [0,0,-1]
#    Tube #7: [-2,2,-0.64], [0,0,-1]
#    Tube #8: [0,2,-0.48], [0,0,-1]
#    Tube #9: [2,2,-0.32], [0,0,-1]
#
# Output units: Radiance [W/cm^2/sr]
#
0.000e+00,[1.004e-01],[1.990e-01],[3.026e-01],[4.009e-01],[5.016e-01],[5.997e-01],[7.001e-01],[8.021e-01],[9.013e-01],
----

Since a single time was requested (the `step_time` and `step_count`
were not provided), the single, non-comment line at the end of the
file is the output of the simulation.  The first token is the time.
A multiple time step simulation would have multiple lines, with
each time token indicating the time.  The remaining 9 tokens are
the outputs for each collector (9 tubes and 1 collectors per tube).
Since the spectral radiance was requested, the tokens appear in
`[]` but since a single wavelength was requested the list contains
a single value.

The table below summarizes the output of the three different collector
scenarios with the expected values (the depths of the tubes were
externally calculated as part of the design of this scene to produce
the uniform interval in expected radiances):

.Expected and Computed Radiances
[options="header"]
|===
|Tube # |Expected       |Directional    |Hemispherical  |Spherical
|1      |0.1000         |0.1004         |0.0996         |0.1002
|2      |0.2000         |0.1990         |0.1985         |0.2015
|3      |0.3000         |0.3026         |0.2991         |0.2941
|4      |0.4000         |0.4009         |0.4013         |0.3996
|5      |0.5000         |0.5016         |0.4995         |0.4996
|6      |0.6000         |0.5977         |0.6009         |0.6017
|7      |0.7000         |0.7001         |0.7018         |0.7001
|8      |0.8000         |0.8021         |0.8008         |0.8004
|9      |0.9000         |0.9013         |0.9015         |0.9004
|===

The deviation of the predicted (computed) values vs. the analytically
derived expected values arises from the random sampling of the
sphere or hemisphere around the point.  Increasing the `sample_count`
used in the plugin will drive down the variation by using more
samples in the Monte-Carlo integral used inside the model.

General comments:

* Because the bottoms of the tubes are 100% reflectors, the total radiance
  for the hemispherical and spherical collectors is the same.
* Changing the collector output to "irradiance" would show that the total
  flux onto the spherical collectors is 2x more than the hemispherical
  collectors.
* Since a directional collector has no solid associated with it, you can
  only request "radiance" output.
