Background

A "plume" in DIRSIG is used to refer to a column of one released material being dispersed into another medium as it is acted upon by the environment (e.g. the wind and surrounding air temperature). These processes are not built directly into the DIRSIG5 model itself. Instead, a plume description is provided by a plugin and the local optical properties and temperatures are provided at run time (either calculated on-the-fly or pre-generated and sampled). The radiometry is handled by DIRSIG itself, calculating the emitted, scattered and transmitted (background) radiances. Note that depending on the type of model, environmental parameters such as the wind speed and direction can be obtained from the larger simulation environment.

The PlumeVDB plugin is provided to allow for bringing in arbitrary external descriptions of plumes using the OpenVDB voxel description. The plume VDB consists of one or two density, or "fog" grids that describe:

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

  2. the temperature of the plume in Kelvin [K] (the temperature is optional, but no emission will be calculated if it does not exist)

In the case of describing both properties, the grids exist in the same file and are not required to define the same voxelization. Each file represents a single temporal instantiation of the plume (i.e. it is instantaneous). Dynamic plumes are described below.

The concentration of the plume is not sufficient for describing it’s optical properties and the corresponding absorption and scattering coefficients are calculated by giving the model concentration dependent spectral descriptions with units of inverse [ppm m] such that the final absorption and scattering coefficients have units of [1/m]. Note that any particular combination of concentration and dependent optical properties could be used as long as they are consistent.

Plume Geometry

Static plumes

A static plume is represented by a single OpenVDB file.

Dynamic plumes

A dynamic plume is described as a sequence of OpenVDB files representing the plume state at constant time intervals. Each individual file is no different from a static plume description and all of the concentration dependent optical properties are shared between frames.

The sequence is indicated by an indexing convention in the filename that uses a fixed width, zero-padded value (the width is arbitrary and only needs to be wide enough to cover the number of frames being used, e.g. a width of two if the indexes are always less than 100, a width of 4 if the indexes are greater than 999. It is also possible to only use a subset of indexes, where the first index used corresponds to the start of the simulation. See the vdb_filename variable for more details.

When providing a dynamic plume, the filename incorporates a range of frame indexes into the filename (the first frame coincides with the start of the simulation regardless of the index numbers). The format is:

<path_to_files>/<base_name>[NNNN:MMMM].vdb

(additional text can be included after the frame numbers if desired as long as it is the same in all files being used). The NNNN and MMMM correspond to the first and last index in a sequence that is formatted to be fixed width with zeros (0) prepended if necessary.

As an example, if we have a set of 15 .vdb files in sequence:

A sequence of 15 VDB files.
plume_frame00.vdb
plume_frame01.vdb
plume_frame02.vdb
...
plume_frame14.vdb

By default, the time delta between frames is assumed to be a second, so we could tell DIRSIG to start with frame "05" and cover a 5 second sequence with plume_frame[05:10].vdb. If another spacing is desired then the frame_delta parameter can be used.

Optical Properties

Spectral Absorption and Scattering

The optical properties description is provided in an external text file that gives the wavelength or wavenumber, the concentration dependent absorption coefficient and (optionally) the concentration dependent scattering coefficient. The spectral units are assumed to be wavenumbers, unless an optional [units] header is provided, e.g.

3700.000000	4.019800e-02
3699.500000	1.237900e-02
3699.000000	5.621300e-03
3698.500000	3.779900e-03
3698.000000	2.733500e-03
3697.500000	2.178500e-03
3697.100000	1.772400e-03
3696.600000	1.508800e-03
3696.100000	1.294800e-03
...

describes the absorption (only) as a function of wavenumbers, while:

[microns]
2.600000 1.957900e-04  1.649700e-03
3.100000 2.048500e-04  1.817000e-03
3.600000 2.139700e-04  1.997900e-03
4.000000 2.241600e-04  2.293100e-03
4.500000 2.344500e-04  2.651600e-03
...

describes both absorption and scattering as a function of the wavelength in Microns. The general format is:

([units])
[spectral point] <del> [absorption coefficient] <del> ([scattering coefficient])
...

Where:

  • the delimiter (<del>) can be any amount of whitespace and/or a comma

  • the optional spectral units can be [wavenumbers], [nanometers], or [microns]

Scattering Coefficients

If scattering coefficients are provided then it is expected that a file will be provided that describes the scattering phase function (assumed rotationally symmetric around the forward direction). If one isn’t provided then nominal water vapor characteristics will be used.

The scattering phase function (SPF) is dependent both on the angle (as measured from the forward direction) and on the wavelength being modeled. As such the SPF file is structured as:

[list of SPF wavelengths separated by <del> and given in ┬Ám]
[0] <del> [N SPF values separated by <del> (N = number of wavelengths)]
[angle (deg)] <del> [N SPF values and separated by <del> (N = number of wavelengths)]
...
[180] <del> [N SPF values and separated by <del> (N = number of wavelengths)]

where the 0 and 180 degree entries are mandatory and other angles should be given in increasing order (note that they do not have to be regularly sampled).

Configuration

Single Plumes

The plume plugin follows the basic plugin format in DIRSIG5 as described JSIM manual, but in the context of the medium list. There are currently no parameters that affect all plume types, so the options section can be left out.

    "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.gas"
                    }
                }
            ]
        }
    ],

All files are assumed to be described relative to the folder in which the simulation is being run.

vdb_filename (required)

This is the name of the actual OpenVDB file (or file sequence, as described above) that describes the concentration and, optionally, the temperature.

Note DIRSIG will check for the presence of every file in a given sequence before starting the simulation (to derive an overall bounding volume) and each frame must be provided in unit steps.
ext_filename (required)

This is the name of the file that collectively describes the optical properties for extinction in the plume: the spectral absorption and, optionally, the spectral scattering (see above).

spf_filename (optional)

If the extinction file above has a spectral scattering column then it is possible to provide a file describing the spectral scattering phase function (see above).

resolution (optional)

Voxel units in the OpenVDB file are assumed to be in meters (i.e. one step in index in any direction is a spatial change of one meter) unless a specific resolution is provided. The possible resolutions available are 1.0 (default), 0.5, and 0.1. Scaling is done before any other transformations are applied. Note that it is only possible to uniformly scale.

frame_delta (optional)

If a dynamic plume is provided then this parameter can be used to set the time step between each "frame" of the input vdb (in [s]). By default, the frame spacing is assumed to be 1 second.

translate (optional)

The plume may be moved from it’s native location (as stored in the VDB) by providing an optional translation in meters [m].

rotate (optional)

The input VDB can be rotated around it’s origin by providing a set of axis angles that are evaluated in z, y, x order.

Note All rotation and translation transformations are performed in the order that they are given and that multiple rotations and translations may be provided.
scale_concentration (optional)

It is possible to scale the concentration values found in the OpenVDB file by an arbitrary amount. This may be useful, for instance, to change the effective units of concentration to match a new set of optical properties.

override_temperature (optional)

Sometimes it’s useful to fix the temperature of the plume for testing purposes. If provided, the override temperature (Kelvin) will be used instead of whatever is in the OpenVDB grid (and only if a temperature grid was present).

Multiple plumes

Multiple plumes can be incorporated into a simulation by supplying multiple plume entries in the medium_list:

"medium_list" : [
    {
        "type" : "Plume",
        "plugin_list" : [
            {
                "name" : "PlumeVDB",
                "inputs" : {
                    "vdb_filename" : "plume1.vdb",
                    "ext_filename" : "gas.txt",
                    "translate" : [30,0,0],
                    "rotate" : [0,0,30]
                }
            }
        ]
    },
    {
        "type" : "Plume",
        "plugin_list" : [
            {
                "name" : "PlumeVDB",
                "inputs" : {
                    "vdb_filename" : "plume2.vdb",
                    "ext_filename" : "gas.txt",
                    "translate" : [-1,0,-10],
                    "rotate" : [0,0,0]
                }
            }
        ]
    }
],

However, overlapping the active areas of the voxelizations will likely not result in appropriate behavior and should be avoided as much as possible. Plumes with the same optical properties should be mixed externally and provided in the same VDB file, but there is no way (currently) to mix two different types of plumes.

Example Outputs

Spectral Radiance Imagery

The following nadir viewing image is generated by the PlumeOpenVDB1 demo using an SF6 gas. The wavelength being visualized corresponds to the main absorption feature of SF6 and demonstrates both emission and absorption modes as the plume is released and cools off away from the stack.

plume demo
Figure 1. Image from the PlumeOpenVDB1 demo.

Relevant Truth Products

Information about the plume can be extracted from the simulation through the use of truth outputs. The plethora of plume-specific truth products available in DIRSIG4 are not readily available via the plugin approach used in DIRSIG5, but there are still many options available. In particular, the intersection truth can give information about the boundary of the plume itself (the "hit" as a path encounters the volume).

Caution The outer boundary of the voxelization corresponds to any active voxels regardless of their content. If the VDB you are using has many low valued concentrations, the boundary shown in the truth will likely be much larger than the "visible" plume in a render.

The intersection truth products are described here. The recently introduced "medium" intersection truth products report the respective coordinate of a boundary inside the plume (e.g., an object inside the plume) or the coodinate of the exit boundary. Those truth requests simply replace the "scene" in the scenex, sceney and `scenez1 with "medium". Below is the result of using the scene and medium "z" truth requests (scenez and mediumz) to view the upper and lower boundary of a plume:

ztruth
Figure 2. Upper boundary of the plume using "scenez" truth
medztruth
Figure 3. Lower boundary of the plume using "mediumz" truth

Other standard truth values have been updated to provide information about a plume as well:

temp
Figure 4. Temperature ("temperature") truth that gives the average path temperature (linear stretch, left and a non-linear stretch on the right to show that this plume is always slightly warmer than the ground)
pathradiance
Figure 5. Path radiance ("pathradiance") truth that is the sum of the atmosphere and plume radiance along the primary path (until a solid object is hit) for the reference wavelength
pathtransmission
Figure 6. Path transmission ("pathtransmission") truth that is the aggregate of the atmosphere and plume transmission along the primary path (until a solid object is hit) for the reference wavelength
Note Many of the truth products are based on the primary path through the plume (i.e. before a solid object is encountered). If the plume incorporates scattering, then the truth values are based on the (usually) non-straight path taken through the volume, averaged over all the path samples.

Finally, if you want to know the average actual path length traveled in the plume, a new truth product has been added called "volpathlength":

volpathlength
Figure 7. Volume path length ("volpathlength") truth that gives the average path length traveled within the first volume encountered (not including the atmosphere). If the path exits the plume and re-enters, only the first traversal will be included. Since the plume below does not scatter, the path length truth corresponds directly to the difference between the two intersection truth products above.