# PlumeOpenVDB1

Keywords: plumes, openvdb, emission, absorption

## Summary

This demo provides a working example of the PlumeVDB plugin in DIRSIG, which allows the user to import a plume using the using the 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 VDB Plugins manual.

  - The 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 (CH4)

- For the LWIR simulation, this gas is Sulfur Hexafluoride (CF6)

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:

1. The concentration of the plume in parts per million [ppm] (or arbitrary concentration units if the dependent IOPs match), and

2. 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, CH4 and SF6 (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:

`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 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 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.

    <blackadarplume>
      <directinsolation>   600.0</directinsolation>
      <airtemperature>     300.0</airtemperature>
      <windspeed>            4.0</windspeed>
      <winddirection>       90.0</winddirection>
      <surfaceroughness>    0.01</surfaceroughness>
      <mixedaltitude>     1000.0</mixedaltitude>
      <stacklocation><point><x>0.0</x><y>0.0</y><z>0.0</z></point></stacklocation>
      <stackheight>         80.0</stackheight>
      <stackdiameter>        2.0</stackdiameter>
      <releasebuoyancy>     10.0</releasebuoyancy>
      <releasetemperature> 350.0</releasetemperature>
      <releaserate>        100.0</releaserate>
      <puffsperstep>           8</puffsperstep>
      <stepcount>            320</stepcount>
      <debugfilename>blackadar.txt</debugfilename>
    </blackadarplume>

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 PlumeVDB plugin manual.

The plume plugin configration in the `lwir_sf6.jsim` file.

        "medium_list" : [
            {
                "type" : "Plume",
                "plugin_list" : [
                    {
                        "name" : "PlumeVDB",
                        "inputs" : {
                            "input_filename" : "./geometry/plume.vdb",
                            "translate" : [0,0,0],
                            "rotate" : [0,0,90],
                            "resolution" : 0.5,
                            "ext_filename" : "./materials/sf6_ext.txt"
                        }
                    }
                ]
            }
        ],

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 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.

            {
                "name" : "OrthoImage",
                "inputs" : {
                    "bandpass" : {
                        "units"   : "microns",
                        "minimum" : 10,
                        "maximum" : 11,
                        "delta"   : 0.01
                    },
                    "date_time" : "2009-09-01T00:00:00.0000-04:00",
                    "center" : {
                        "x" : -10.0,
                        "y" : 15.0
                    },
                    "altitude" : 1000,
                    "gsd" : 0.15,
                    "size" : {
                        "x" : 320,
                        "y" : 240
                    },
                    "truth" : [
                        "scenex",
                        "sceney",

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

Figure 1. RGB of the water vapor simulation (using 2% scaling)

### 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.

Figure 2. RGB of the smoke simulation (using 2% scaling)

### SWIR CH4 Simulation

Because CH4 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.

Figure 3. Band 275 (2.37 microns) for the SWIR CH4 simulation (using 2% scaling).

Note | Since the SWIR CH4 simulation uses the same `plume.vdb` file as the LWIR SF6 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 SF6 Simulation

Because SF6 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.

Figure 4. Band 41 (10.4 microns) of the LWIR SF6 simulation (using min/max scaling).

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.

Figure 5. Output image made from band 41 using only 4 nodes for each path.