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.