Introduction

DIRSIG5 provides a dedicated interface to volumetric media in a scene within the optional medium_list section of the JSIM simulation file. This is to allow related plugins to be defined together as a group, along with options governing how they are used.

The water medium describes a (dominantly) horizontal interface between the atmosphere and a body of water within the scene. A plugin is used to define the geometric boundary between the external medium and an internal, water medium as a function of horizontal position and time.

Water is often composed not only of "pure" water, but also various constituent materials that exist at some concentration throughout the volume (common constituents for natural waters are chlorophyll, suspended solids, dissolved matter, and entrained bubbles). These constituents change both the scattering and absorption characteristics of the volume and are key to understanding the radiometric behavior. A second plugin is used to define these effects, in the form of an intrinsic optical property (IOP) model that drives the effective bulk properties as well as any spatial distribution that might be present.

Tip A few pre-built characteristic water types are available within the individual IOP plugins that are useful if the specifics of the water components are not of interest.

Medium List Entry

A water medium is only definable within the DIRSIG5 JSIM input format and is placed within the medium_list section of the file rather than as a single entry in the plugin_list. An example is shown below:

[{
   "scene_list"  : [ ... ],
   "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"
            }
        }
    ],
    "plugin_list" : [ .. ]
}]

The type entry of Water is the key to triggering the appropriate plugin APIs for both the interface and the IOPs (which are then required in the plugin list). The plugins themselves follow the usual name/inputs pairing that is used for all plugin_list entries. The individual plugin implementations are described separately (see the lists below). The final options section applies to the internal radiative transfer engine implementation and are described in this document.

Note that the scene_list is commonly where geometric objects like the bottom surface of the water body (e.g. a sandy ocean floor) is defined along with vessels that may be present on the surface, piers, etc.. Individual plugins do have the ability to define their own geometry as well (e.g. integration with a bathymetry driven fluid dynamics model might define the bottom surface since it influences the interface solution), though there are limited examples of this.

Water Options

The options section of the Water entry is used to set runtime parameters that drive the behavior of the internal radiative transfer code. The available parameters are listed in the table below:

Option name Required Example/Default Description

bounding_box_min

Yes

[-1000,-1000,-100]

CSV triplet giving the minimum corner point of the volume in the primary scene’s coordinates

bounding_box_max

Yes

[+1000,+1000,1]

CSV triplet giving the maximum corner point of the volume in the primary scene’s coordinates

force_default_material

No

false

if true, overrides any surface optical properties defined by the plugin and uses the default Fresnel properties

early_exit

No

false

if true allows an in-water path to truncate if the added radiance from a segment drops below the threshold

early_exit_threshold

No

1e-6

if the early_exit flag is set, allows for changing the threshold (same units as the convergence threshold)

cache_folder

No

"./"

absolute path to a folder where any plugin-based caching is stored (for example, custom surface optical properties)

open_water

No

false

if true forces internal assumptions based based on no shadowing objects (submerged or external)

Note that the exact meaning of some of the options may be dependent on the type of plugin. For example, the HDF based air-water interface will be tiled to fill the bounding box if the defined area is too small, while the geometry in the OBJ interface will only be used once.

Water Plugins

Links to further documentation and short summaries of available plugins.

Interface Plugins

ObjInterface (documentation under construction)

defines the surface with a single, static OBJ geometry file.

HDFInterface (documentation under construction)

defines a potentially dynamic surface with a set of heightfields and slopes defined in an HDF file.

WaveSpectrum

defines a dynamic surface based on a wave frequency spectrum that forms the height field

IOP Plugins

IOPModel

port of the original, multi-component IOP model in DIRSIG4

NewCase1 (documentation under construction)

implementation of a single parameter (chlorophyll concentration) model that drives covarying constituents in Case 1 waters

ThermalWater (documentation under construction)

a placeholder water implementation intended for simulations with only thermal wavelength where the water is highly absorbing and internal path propagation can be skipped entirely

EntrainedBubbles (documentation under construction)

model of unresolved, entrained bubbles in the volume

AggregateIOPModel (documentation under construction)

a wrapper plugin to combine different IOP models at runtime (e.g. entrained bubbles with the new case 1 water model)