PlumeOpenVDB1
=============

Keywords: plumes, openvdb, emission, absorption

== Summary ==
This demo provides a working example of the
http://www.dirsig.org/docs/new/vdb_plugins.html#PlumeVDB[PlumeVDB] plugin
in DIRSIG, which allows the user to import a plume using the using
the https://www.openvdb.org[OpenVDB] voxel description. Plume
modeling is usually concerned with scattering at visible wavelengths
(e.g. the scattering of water vapor) and absorption and emission
at thermal wavelengths (particularly the spectral absorption
signatures of various chemicals). This demo is for the latter type
of plume and information about scattering specific inputs can be
found in the online documentation and in other examples.

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

* Related Demos
** None.
* Related Manuals
** The http://www.dirsig.org/docs/new/vdb_plugins.html[VDB Plugins] manual.
** The http://www.dirsig.org/docs/new/blackadar_plume.html[Blackadar Plume] model manual.
* Related Tutorials
** None.


== Details ==
The demonstration consists of a single plume release of a single
absorbing gas over a nominal factory "plant" geometry (primarily
to provide background clutter).

* For the VIS simulation, this gas is either water vapor or a
  approximation for wildfire smoke.
* For the SWIR simulation, this gas is Methane (CH~4~)
* For the LWIR simulation, this gas is Sulfur Hexafluoride (CF~6~)

The plume itself was generated using an implementation of a "Blackadar"
plume model (from the book "Turbulence and Diffusion in the Atmosphere"
by Alfred K. Blackadar) that was then converted to the OpenVDB
format as both density in [ppm] (concentration of the material) and
temperature in [K] (from the externally modeled temperature at
release and cooling as the plume propagates under certain environmental
conditions).

Specifically, plumes are modeled as one or two sparse voxelization
grids in a single OpenVDB file. Those grids define:

. The concentration of the plume in parts per million [ppm] (or
  arbitrary concentration units if the dependent IOPs match), and
. The temperature of the plume in Kelvin [K] (the temperature is
  optional, but no emission will be calculated if it does not exist) 

Aside from the spatial distributions of density and temperature
captured in the voxelization, the user is responsible for providing
concentration dependent scattering and absorption coefficients in
inverse [ppm m] units.

NOTE: While [ppm] units are commonly used, any appropriate concentration
      metric may be represented in the plume voxelization as long
      as the supplied optical properties will result in
      absorption/scattering coefficients with [1/m] units after
      scaling by the concentration.


== Important Files ==

`materials/h2o_ext.txt`, `materials/smoke_ext.txt`, `materials/ch4_ext.txt` and `materials/sf6_ext.txt`::
A two column text file defining the spectral extinction and/or
scattering of water vapor, smoke, CH~4~ and SF~6~ (respectively)
as a function of wavenumber (see the plume plugin documentation
for how to supply values with wavelengths). Plots of these files
are included below:

image::images/h2o_ext.png[]

image::images/smoke_ext.png[]

image::images/ch4_ext.png[]

image::images/sf6_ext.png[]

`geometry/objects/plant3.obj`::
The geometry of the plant (an attribution file accompanies it since the
geometry was externally acquired).

`geometry/plume.xml`::
The inputs for the Blackadar plume model (described in the
http://www.dirsig.org/docs/new/blackadar_plume.html[Blackadar Plume]
model manual).

`geometry/plume.vbd`::
The plume OpenVDB voxelization with two internal grids (concentration
and temperature). This file may be loaded into any OpenVDB software
including the standard _vdb_view_ program that is distributed with
the OpenVDB library.

`uniform.atm`::
For demonstration purposes, the "atmosphere" is setup such that no
energy comes from the sun (and moon/sky, accordingly); all signal
in the simulation comes directly from the self-emission of the
objects and plume

`vis_h2o.jsim`, `vis_smoke.jsim`, `swir_ch4.jsim` and `lwir_sf6.jsim`::
There are the JSON style simulation files that includes the definition
of the plugin and its inputs; for more details about the syntax and
the `medium_list` being used in general, please see the
http://www.dirsig.org/docs/new/plumevdb_plugin.html[PlumeVDB plugin]
manual.


== Setup
=== Generating the plume 
The plume VDB file (see `geometry/plume.vdb`) can be regenerated
from the Blackadar input file (see `geometry/plume.xml`) using the
stand-alone, command-line Blackadar plume model utility:

.The XML input plume description.
[source,xml]
----
include::geometry/plume.xml[]
----

.Generating a Blackadar plume using `vdb_tool`:
----
$ vdb_tool blackadar geometry/plume.xml -o geometry/plume.vdb
----

=== The plume plugin
The plume plugin is provided via the `medium_list` section of the
JSIM file.  The details of the input parameters are described in
the http://www.dirsig.org/docs/new/plumevdb_plugin.html[PlumeVDB]
plugin manual.

.The plume plugin configration in the `lwir_sf6.jsim` file.
[source,json]
----
include::lwir_sf6.jsim[lines=5..21]
----

NOTE: The differences for the `swir_ch4.jsim` plume comes down to using a
      different extinction file (see the `ext_filename` variable).

=== The sensor plugin
For this simulation simulation a simple
http://www.dirsig.org/docs/new/orthoimage_plugin.html[OrthoImage]
setup to allow for quickly changing the spectral sampling and ground
sample distance while giving an overview of the scene.

.The sensor plugin configuration in the `lwir_sf6.jsim` file.
----
include::lwir_sf6.jsim[lines=29..51]
----

NOTE: The differences for the `swir_ch4.jsim` plume comes down to using a
      different spectral windows (see the `bandpass` object).


This sensor plugin can be easily replaced with a full sensor model
if desired. The plant has been placed such that the one stack at
80m height (the height at which the plume was modeled) is at the
scene origin, also matching the location of the plume) and the
`OrthoImage` plugin has been translated away from that point. The
original plume has also been rotated 90 degrees around the z-axis
(i.e. the "up" axis) at the origin so that it passes over the factory
and the various pipework can be seen through the plume.


== Simulations and Results ==
As with all DIRSIG5 setups, make sure to compile the scene file
first using `scene2hdf`.

----
$ scene2hdf demo.scene
----

Even without scattering, there are significant media transitions
in this simulation in and out of the plume along detector paths.
Because of this, the default maximum number of nodes should be
increased to a value that is 6 (or higher) otherwise the path may
truncate prematurely and the plume will appear to be darker in parts
than it should be.

Additionally, because every object in the scene is effectively a
"source" it is recommended to use a higher per pixel sampling rate
than you would for a passive scene illuminated by the sun. Altogether,
a good set of command line parameters would be:

----
$ dirsig5 --convergence=50,500,1e-6 --max_nodes=10 ...
----

=== Visible Water Vapor Simulation

.RGB of the water vapor simulation (using 2% scaling)
image::images/vis_h2o_10nodes.png[width=640]


=== Visible Smoke Simulation
In the absence of a published absorption and scattering
file for wildfire smoke, the `materials/smoke_ext.txt` file
was created as a blend of water vapor and soot.

.RGB of the smoke simulation (using 2% scaling)
image::images/vis_smoke_10nodes.png[width=640]


=== SWIR CH~4~ Simulation
Because CH~4~ has a significant absorption feature at 2.37 microns
(the 275st spectral sample), that is what we use for the images
below (using two sigma scaling).  In the SWIR and at the slightly
elevated (compared to ambient) exit temperature, the plume is
primarily an absorber.

.Band 275 (2.37 microns) for the SWIR CH~4~ simulation (using 2% scaling).
image::images/swir_ch4_10nodes.png[width=640]

NOTE: Since the SWIR CH~4~ simulation uses the same `plume.vdb` file as
      the LWIR SF~6~ plume, the desired difference in concentration for
      the two gases needs to be accounted for.  The plume plugin
      `scale_concentration` variable in the `swir_ch4.jsim` file is set
      to `5000` to account for the fact that we want the methane
      concentration to be significantly higher.


=== LWIR SF~6~ Simulation
Because SF~6~ has a significant absorption feature at 10.4 microns
(the 41st spectral sample), that is what we use for the images below
(using the min/max scaling).  In the LWIR and at the slightly
elevated (compared to ambient) exit temperature, the plume is
primarily an emitter near the stack (warmer) and shifts into an
absorper downwind as the temperature decreases.

.Band 41 (10.4 microns) of the LWIR SF~6~ simulation (using min/max scaling).
image::images/lwir_sf6_10nodes.png[width=640]

To demonstrate the impacts on the number of nodes used in the simulation,
this simulation was also run with only 4 nodes (the default) and that
image is shown below.  Note the darkening around the plume, especially
near the release and over the pipes.

.Output image made from band 41 using only 4 nodes for each path.
image::images/lwir_sf6_04nodes.png[width=640]
