Change ocean parameters

For worlds with an Ocean, BBI allows you to vary the sea state (wave and swell) and color. These are accessible through world.env.ocean.

Note

Only the following worlds have an Ocean:

  • World("lake")

  • World("ocean")

  • World("port_city")

Change sea state and color

Ocean attributes can be set directly using the following methods:

Example: changing ocean parameters
# Set only sea state
world.env.ocean.set_sea_state(state=SeaState.ROUGH)

# Set only sea color
world.env.ocean.set_sea_color(color=SeaColor.MURKY)

Sea State

SeaState

bbi.SeaState.CALM_GLASSY

Wave height 0m (0")

bbi.SeaState.CALM_RIPPLED

Wave height 0m - 0.1m (0.0" - 3.9")

bbi.SeaState.SMOOTH

Wave height 0.1m - 0.5m (3.9"- 1'8")

bbi.SeaState.SLIGHT

Wave height 0.5m - 1.25m (1'8"- 4'1")

bbi.SeaState.MODERATE

Wave height 1.25m - 2.5m (4'1"- 8'2")

bbi.SeaState.ROUGH

Wave height 2.5m - 4m (8'2"- 13'1")

bbi.SeaState.VERY_ROUGH

Wave height 4m - 6m (13'1" - 20')

Sea color

SeaColor

We provide a few presets for sea color:

bbi.SeaColor.AZURE_BLUE

Azure blue color useful for open waters

bbi.SeaColor.DARK_BLUE

Dark blue color useful for open waters

bbi.SeaColor.MEDIUM_BLUE

Medium blue color useful for open waters

bbi.SeaColor.MURKY

Murky greenish color useful for dirty waters

bbi.SeaColor.MURKY_BROWN

Murky brown color useful for dirty waters

bbi.SeaColor.TURQUOISE

Turquoise color useful for shallow tropical waters

Animating ocean state

The ocean can be animated through scenario keyframes, allowing it to vary across frames.

Tip: Address SeaState using integers

The SeaState enum is represented as an integer. You can use these integers to set the sea state directly.

The following statements are equivalent:
world.env.ocean.set_sea_state(state=SeaState.ROUGH)
world.env.ocean.set_sea_state(state=SeaState(5))
Example: Make the ocean more turbulent over time
scenario = world.new_scenario(num_frames=10)

for i in range(scenario.num_frames):
    # Increase from SeaState 0 to 4
    scenario.set_keyframe(world.env.ocean, i, sea_state=SeaState(i//2))

Ocean wakes

Basic wake setup

Ocean wakes are enabled for all BuoyantAsset assets by default. The wake system allows for detailed control of how the water reacts to moving vessels. You can toggle wakes on and off using the vessel.set_wake_enabled(enabled=False) method. In order to get wakes to be characterized for a specific vessel, set the global_wake_target using world.env.ocean.set_global_wake_target(asset=vessel).

Example: configure wakes based on a vessel
vessel = BuoyantAsset(node_id="myvessel", asset_name="White Bumboat")
world.add(asset=vessel)
world.env.ocean.set_global_wake_target(asset=vessel)

Important

Only one vessel can be set as the global wake target. While all vessels will generate wakes, the wake effects will be optimized for the target vessel’s characteristics.

Wake duration

The OceanWakeDuration enum determines how long the system will interpolate before rendering to generate wake effects. By default, wakes will interpolate 5 seconds before rendering to generate the wake effects. This can be adjusted using set_wake_duration, but be cautious with longer durations as they will increase render times.

bbi.OceanWakeDuration.NONE

Wake disappears immediately

bbi.OceanWakeDuration.SHORT

Wake persists briefly (2 seconds)

bbi.OceanWakeDuration.MODERATE

Wake persists for medium duration (5 seconds)

bbi.OceanWakeDuration.LONG

Wake persists for extended period (30 seconds)

bbi.OceanWakeDuration.FULL_FRAME_DURATION

Wake persists for the entire frame duration

Example: setting wake duration
# Default duration (5 seconds)
world.env.ocean.set_wake_duration(duration=OceanWakeDuration.MODERATE)

# Full scenario duration (use cautiously)
world.env.ocean.set_wake_duration(duration=OceanWakeDuration.FULL_FRAME_DURATION)

Warning

Using FULL_FRAME_DURATION with long scenarios can significantly increase render times as the wake system will interpolate the entire duration before each frame.

Wake properties

The wake system provides multiple parameters that can be adjusted to achieve different visual effects. Each property can be set individually using dedicated methods.

Example: configuring wake properties individually
# Set wake height
world.env.ocean.set_wake_height(wake_height=OceanWakeHeight.MEDIUM)

# Set wake length
world.env.ocean.set_wake_length(wake_length=OceanWakeLength.MEDIUM)

# Set foam intensity
world.env.ocean.set_foam_intensity(foam_intensity=OceanFoamIntensity.MODERATE)

# Set churn strength
world.env.ocean.set_churn_strength(churn_strength=OceanChurnStrength.MODERATE)

# Set wake sharpness
world.env.ocean.set_wake_sharpness(wake_sharpness=OceanWakeSharpness.NATURAL)

Wake Height

OceanWakeHeight

bbi.OceanWakeHeight.EXTRA_SMALL

Very subtle wake waves, barely visible

bbi.OceanWakeHeight.SMALL

Low amplitude wake waves

bbi.OceanWakeHeight.MEDIUM

Moderate wake waves suitable for average vessels

bbi.OceanWakeHeight.LARGE

Tall wake waves for larger vessels

bbi.OceanWakeHeight.EXTRA_LARGE

Maximum wake wave height for very large vessels

Wake Length

OceanWakeLength

bbi.OceanWakeLength.EXTRA_SMALL

Very short wake trail

bbi.OceanWakeLength.SMALL

Short wake trail suitable for slow vessels

bbi.OceanWakeLength.MEDIUM

Medium length wake trail for average vessels

bbi.OceanWakeLength.LARGE

Long wake trail for fast vessels

bbi.OceanWakeLength.EXTRA_LARGE

Very long wake trail for high-speed vessels

Foam Intensity

OceanFoamIntensity

bbi.OceanFoamIntensity.NONE

No foam generation

bbi.OceanFoamIntensity.LITTLE

Light foam suitable for calm conditions

bbi.OceanFoamIntensity.MODERATE

Medium foam suitable for average conditions

bbi.OceanFoamIntensity.EXTREME

Heavy foam suitable for rough conditions

Churn Strength

OceanChurnStrength

bbi.OceanChurnStrength.NONE

No water churning

bbi.OceanChurnStrength.LITTLE

Slight water disturbance

bbi.OceanChurnStrength.MODERATE

Medium water churning suitable for most vessels

bbi.OceanChurnStrength.EXTREME

Maximum water churning for powerful vessels

Wake Sharpness

OceanWakeSharpness

bbi.OceanWakeSharpness.SOFT

Blurred, gentle wake patterns

bbi.OceanWakeSharpness.SMOOTH

Slightly defined wake patterns

bbi.OceanWakeSharpness.NATURAL

Well-defined, realistic wake patterns

bbi.OceanWakeSharpness.CRISP

Highly detailed, sharp wake patterns

Method

Description

set_wake_height()

Controls the height of the wake.

Takes OceanWakeHeight enum.

set_wake_length()

Controls how far the wake extends behind the vessel.

Takes OceanWakeLength enum.

set_foam_intensity()

Controls the amount of white water in the wake.

Takes OceanFoamIntensity enum.

set_churn_strength()

Controls the turbulence and mixing of water in the wake.

Takes OceanChurnStrength enum.

set_wake_sharpness()

Controls the detail level of the wake.

Takes OceanWakeSharpness enum.

Animating wakes

Wakes can be animated by moving the vessel through keyframes in a scenario. The wake system will automatically generate appropriate effects based on the vessel’s movement.

Example: creating an animation with wakes
# Setup the scene
world = World(name="Ocean")
world.env.ocean.set_sea_state(state=SeaState.CALM_GLASSY)
vessel = BuoyantAsset(node_id="myvessel", asset_name="White Bumboat")
world.add(asset=vessel)
world.env.ocean.set_global_wake_target(asset=vessel)

# Configure wake properties
world.env.ocean.set_wake_height(wake_height=OceanWakeHeight.MEDIUM)
world.env.ocean.set_foam_intensity(foam_intensity=OceanFoamIntensity.MODERATE)

# Create animation
frames = 5
scenario = world.new_scenario(num_frames=frames, total_seconds=10)
for i in range(frames):
    scenario.set_keyframe(
        target=vessel,
        frame=i,
        position=Vector3(i * 10, 0, 0),
        rotation=Vector3(0, 0, 0)
    )

scenario.preview_animation()

Note

Wake appearance can vary based on the vessel type, speed, and ocean conditions. Experimentation with different settings may be needed to achieve the desired visual effect.