demo
Figure 1. Output image for the demo (non-linear stretch for visualization)

Keywords: volume bulk water

Summary

This example shows how to use the HDF medium interface plugin to describe a water medium in DIRSIG. In contrast to an OBJ based interface (see Caustics1), the HDF interface is intended to bring in external data from arbitrary wave models and to extend that data in both time and space.

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

  • Related Tutorials

    • None.

Details

The scene is minimal (a single submarine with simplistic reflectance properties) and the sensor is obliquely viewing a patch of ocean. All HDF surfaces are repeated outside of their native coverage region (it is therefore beneficial to make them seamless if that is the intended usage). The default version of the scene also minimizes the complexity (it uses pure, clear water, for instance), but notes are made where a more complex option can be substituted.

Important Files

wave_surface.hdf

definition of the air-water interface

clear_water.iop

simple inherent optical property definition (for speed)

demo.jsim

this is the input file to the simulation that defines the inputs to the water plugin

case1.iop

more realistic IOPs based on Mobley’s Light&Water example

libhdfinterface_plugin.so

the shared library (could have a .so, .dyld or .dll extension) containing the plugin for handling the hdf water format; this not found in the demo folders, but in the installed plugins folder

HDF file

The HDF file for defining the air-water interface has a specific format that describes each set of heights, slopes and white water fractions used with the plugin. The format is described below and an example HDF file is given (wave_surface.hdf)

Top level attributes

CoxMunkBRDF

This is an enumerated flag (8-bit enum (FALSE = 0 TRUE = 1)) indicating whether or not the built-in Cox-Munk BRDF should be used. If true, the default air-water interface material is replaced by a Cox-Munk distribution of slopes that drive a microfacet model (representing unresolved wavelets). It is parameterized by wind inputs that are also attributes If the Cox-Munk BRDF model is used, then the model outputs are stored in a cache file (for the specific wind speed being run) so that it can be re-used in future simulations.

WhitewaterReflectivity

This is a 32-bit floating-point scalar that tells DIRSIG to use a Lambertian (uniform) model of reflectance of the given total reflectance (DHR) whenever white water is encountered (see the WhitewaterFraction Dataset). Valid number are between 0 and 1.

WindDirection

32-bit floating-point scalar that gives the direction of the wind in degrees measured CCW from the scene’s x-axis.

WindSpeed

32-bit floating-point scalar giving the surface wind speed in meters / second

dt,dx,dy

32-bit floating-point scalar step sizes for the spatio-temporal Datasets (time, spatial x, and spatial y, respectively).

Datasets

The Datasets (one level below the top) are all 3-dimensional 32-bit floating-point data objects organized as [nx, ny, nt], where n is the number of elements in the x, y, and temporal dimensions. In terms of the HDF "SimpleExtentDims", dims[0] = nt, dims[1] = nx, and dims[2] = ny. The number elements in each dimension should be the same for each dataset.

WaveHeight

Describes the height variation across the interface, in meters

WaveSlopeX and WaveSlopeY

Describes the slope along the x/y-axis at every point in the height field (this is preferred for the normal relative to computing a cross product of neighboring cell edges)

WhiteWaterFraction

Indicates the fraction of the surface covered by white water (see the WhitewaterReflectivity, above) at that point in the heightfield.

For each dataset, points are defined at discrete posting and interpolated (via barycentric/area coordinates) when looking at a point between the definitions.

When nt is greater than one, the data is changed every time the current time is exceeded (by as many steps as needed). In the future the values will be interpolated between time steps.

Simulation JSIM File

The demo.jsim JSIM file uses the newer JSON based inputs (in contrast to the older "sim" file format that uses an XML format). The new medium models are configured in the JSIM via a JSON array named medium_list (currently only one medium per scene is supported). Within that array we define an object of type Water:

The medium_list from the demo.jsim file.
    "medium_list" : [
        {
            "type" : "Water",
            "plugin_list" : [
                {
                    "name" : "HdfInterface",
                    "inputs" : { "hdf_filename" : "wave_surface.hdf" }
                },
                {
                    "name" : "IOPModel",
                    "inputs" : { "iop_filename" : "clear_water.iop" }
                }
            ],
            "options" : {
                "bounding_box_min"          : "-20000,-20000,-20",
                "bounding_box_max"          : "+20000,+20000,  1",
                "force_default_material"    : "true",
                "early_exit"                : "true",
                "early_exit_threshold"      : 1e-6,
                "cache_folder"              : "./cache"
            }
                
        }
    ],

There are two water APIs that must be implemented: a medium interface (here supplied as HdfInterface) and an inherent optical property model (here supplied as IOPModel and using the same plugin as other water sims). Each of these plugins take a single input that is the file they should be loading (note that the key names hdf_filename and iop_filename must be used for these plugins and no additional parameters are available.

The last element of the water object is a list of options for the simulation. The following options are available and are either required or optional with a default value:

bounding_box_min and bounding_box_max

each are a triplet of values describing the minimum/maximum corners of a bounding box encapsulating the water; for the HDF interface plugin, if the horizontal extent of the bounding box is larger than the horizontal extent of the surface, then the surface will be tiled. The tile grids is currently always setup so that the minimum corner is set to 0,0 in scene space (the option to translate/rotate the interface will be added in the future).

force_default_material

flag that indicates that the Cox-Munk BRDF model should be ignored even if the flag was set to 1 in the HDF (default is false)

early_exit

flag that indicates the radiometry engine should stop walking along a ray in the path when the change in radiance due to a path contribution falls below a certain value (default is true); if false, computation will only be subjected to global importance thresholds (such as the convergence input)

early_exit_threshold

value that is compared against when choosing whether or not to continue a path integral

cache_folder

Path to the location that the Cox-Munk BRDF model output will be stored in a cache for future re-use (cache file names are based on the wind speed).

Setup

To run the simulation, perform the following steps:

  1. Generate an HDF of the scene

  2. Run the DIRSIG demo.jsim file using DIRSIG5

Compiling and running the simulation.
$ scene2hdf demo.scene
$ dirsig5 demo.jsim

Results

The stretched radiance output is shown in Figure 1. Additional truth outputs are shown below. Note that ID truth is given for the first surface encountered within the volume whereas geometric intersection truth is provided for the interface.

mu
Figure 2. Cosine of the view angle relative to the air-water interface
primitiveid
Figure 3. Primitive (facet) ID of the first in-water object encountered

Additional Notes

The demo complexity can be increased by switching to non-pure water IOPs (a Case 1 water setup is provided) or by collecting over a limited time (the hdf covers 2 seconds in 0.1 second increments). The Cox-Munk BRDF can be turned on by simply turning off the force default material flag. Note that the first run with the Cox-Munk interface for any wind speed will be much longer as a cache is generated.