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. These can be set using the set_wake_properties method.

Example: configuring wake properties¶

world.env.ocean.set_wake_properties(
    wake_height=OceanWakeHeight.MEDIUM,
    wake_length=OceanWakeLength.MEDIUM,
    foam_intensity=OceanFoamIntensity.MODERATE,
    wake_sharpness=OceanWakeSharpness.NATURAL,
    speed_modifier=OceanWakeSpeed.MODERATE,
    sea_state_modifier=SeaState.CALM_RIPPLED
)

Parameter	Description
`wake_height`	Controls the height of the wake. Options: `EXTRA_SMALL`, `SMALL`, `MEDIUM`, `LARGE`, `EXTRA_LARGE`
`wake_length`	Controls how far the wake extends behind the vessel. Options: `EXTRA_SMALL`, `SMALL`, `MEDIUM`, `LARGE`, `EXTRA_LARGE`
`foam_intensity`	Controls the amount of white water in the wake. Options: `NONE`, `LITTLE`, `MODERATE`, `EXTREME`
`wake_sharpness`	Controls the detail level of the wake. Options: `SOFT`, `SMOOTH`, `NATURAL`, `CRISP`
`speed_modifier`	Adjust wake properties based on vessel speed. Higher speeds tend to increase wake effects, lower speeds tend to decrease them. Options: `STATIONARY` `SLOW` `MODERATE` `FAST`
`sea_state_modifier`	Adjust wake properties based on sea conditions. Higher sea states tend to increase wake effects, lower states tend to decrease them. Uses standard `SeaState` enum values.

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_properties(
    wake_height=OceanWakeHeight.MEDIUM,
    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.