Overview

This extension enables support for changing scene wide wetness parameters and enable runtime puddle placement on Drivesim.

Attention

This extension is not related to the SimReady Enviroment System UI. Both can coexist and will be merged at some point.

API documentation

Refer to

omni::avreality::rain for the C++ API documentation
omni.avreality.rain for the Python API documentation

Describing wetness

Wetness description in the scene

Wetness in the scene is to be described using a few parameters. The main ones affecting a properly configured scene are:

Enabled: Whether wetness support is enabled in the scene. Wetness is activated upon request as it adds some computation load to the scene.
Wetness: The amount of wetness in the scene, from full dry (equivalent to wetness being off) to fully wet.
Water albedo: The tint that standing water will apply on the underlying asset.
Water transparency: A much the underlying asset will be visible under standing water.
Accumulation scale: The amount of water present in areas that can accumulate water, from fully dry to max accumulation.

Those are expected to be changed at runtime depending on some weather conditions.

See Runtime wetness settings for details on how to change wetness state of the scene at runtime.

Some other properties are of interest when authoring an asset.

Porosity: Describe areas of the asset that are possibly absorbing water.
Water accumulation: Describes where standing water would accumulate in case of high precipitations.
Water albedo: How the accumulated water would tint the underlying asset in case of standing water, if the water is not fully transparent.
Water transparency: How transparent is the accumulated water. This will define how much the underlying asset is visible.

See Authoring wetness for details on how to enable assets for wetness.

Puddle placement

For drivable surface type of assets, this extension gives the ability to dynamically place puddles.

Puddles are configured using the following parameters:

Center: The center of the puddle.
Radius: The radius of the puddle.
Depth: THe maximum depth of the puddle at its center.

See Puddle placement for details on how to place puddles in the scene.

Note

Puddle shape can only be circular for now, with a depth that is maximum at the center and decreasing toward 0 at the circle bounds.

Scene preparation

At runtime, a properly authored scene needs to be prepared to handle wetness and puddle interactions.

Preparation for wetness and puddle placement

The scene needs to be properly setup to be able to react to wetness changes and to enable puddle placement.

C++

#include <omni/avreality/rain/WetnessController.h>
using omni::avreality::rain::WetnessController;
...
WetnessController::loadShaderParameters();

Python

from omni.avreality.rain import WetnessController
...
WetnessController.load_shaders_parameters()

The above sequences will populate the session layer so default MDL parameters, if those are not actually authored, are set on related prims.

Additional setup for puddle placement

Puddle placement at runtime requires an additional configuration step. Dynamic textures need to be bound to the shaders so those can be updated at runtime and be consumed by the renderer.

C++

#include <omni/avreality/rain/PuddleBaker.h>
using omni::avreality::rain::PuddleBaker;
...
std::vector<pxr::SdfPath, std::string> mapShaderPathsToAccumulationMapNames;
// Fill in the above.
PuddleBaker::assignShadersAccumulationMapTextureNames(mapShaderPathsToAccumulationMapNames);

Python

from pxr import Sdf
from omni.avreality.rain import PuddleBaker
...
mapShaderPathsToAccumulationMapNames: List[Tuple[Sdf.fPath, str]] = []
PuddleBaker.assign_shaders_accumulation_map_texture_names(mapShaderPathsToAccumulationMapNames)

Runtime wetness settings

Wetness can be controlled at runtime using the WetnessController class (C++ and Python). This controls the configuration of the complete scene.

Wetness support can be toggle on/off using the applyGlobalWetnessState (apply_global_wetness_state) call.
Wetness amount can be set using the applyGlobalWetness (apply_global_wetness) call. Ranging from 0 (dry) to 1 (wet).

Water accumulation can also be controller using the WetnessController.

The amount of accumulated water can updated using applyGlobalWaterAccumulationScale (apply_global_water_accumulation_scale) call.
The color of standing water and its transparency level can be changed using the applyGlobalWaterAlbedo (apply_global_water_albedo) and applyGlobalWaterTransparency (apply_global_water_transparency) calls.

C++

#include <omni/avreality/rain/WetnessController.h>
using omni::avreality::rain::WetnessController;
...
WetnessController wc;
wc.applyGlobalWetnessState(true); // Enables wetness.
wc.applyGlobalWetness(0.5f); // Half-way wetness.
wc.applyGlobalWaterAccumulationScale(0.5f); // Half-way accumulation

Python

from omni.avreality.rain import WetnessController
...
wc = WetnessController()
wc.apply_global_wetness_state(True) # Enable wetness
wc.apply_global_wetness(0.5) # Half-way wetness
wc.apply_global_water_accumulation_scale(0.5) #  Half-way accumulation

See omni::avreality::rain::WetnessController.

Authoring wetness

Assets need to be setup so they can properly react to scene wetness changes.

Props

Props can define those properties to help with wetness interpretation in the scene:

Porosity map, that describes how porous is the asset on. This ranges from 0 (impermeable) to 1 (highly absorbant). This will affect how the asset renders when the wetness increases.
Water accumulation map that describes regions of the asset where water would accumulate in case of high precipitations. This setting will affect how the asset renders when the Water accumulation scale increases.

Drivable surfaces

Drivable surface also provides a porosity map. Compared to props, the handling of accumulation of roads is two folds:

Road can exhibit an intrisic accumulation property, that would describe potholes, cracks and gutters. This akin to the Water accumulation map of the props, this property is baked and cannot be edited.
This leaves the actual Water accumulation map free. Puddle placement relies on this to give the ability to place puddles at runtime.

Puddle placement

To place puddles, the scene must have been prepared after loading (see Scene preparation). Once this is done, the following steps are to be applied:

Create a PuddleBaker instance.
Allocate one or more puddles using its acquirePuddle (acquire_puddle).
The puddles can then be updated using setPuddlePosition, setPuddleRadius and setPuddleDepth calls.
To remove a puddle, it needs to be released through releasePuddle.
To do the actual puddle baking, one need to call bake using the target texture name and its extent.

The texture extent, puddle radius and position must be expressed in the space coordinate space.

C++

#include <omni/avreality/rain/PuddleBaker.h>
using omni::avreality::rain::PuddleBaker;
...
unsigned int puddleCount = 2;
carb::Float2 positions[] = { { 5.0f, 10.0f }, { 10.0f, 5.0f } };
float radii[] = { 5.0f, 7.0f };
float depths[] = { 1.0f, 0.5f };

PuddleBaker::bake("my-dynamic-texture", carb::Float2(0.0f, 0.0f), carb::Float2(20.0f, 20.0f),
  gsl::span<const carb::Float2>(positions, puddleCount),
  gsl::span<const float>(radii, puddleCount),
  gsl::span<const float>(depths, puddleCount)); // gsl::span can be implicitely built with C++17.

Python

from omni.avreality.rain import PuddleBaker
...
puddleCount = 2
positions = [(5.0, 10.0), (10.0, 5.0)]
radii = [5.0, 7.0]
depths = [1.0, 0.5]

PuddleBaker.bake("my-dynamic-texture", (0.0, 0.0), (20.0, 20.0))