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:
# 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¶
Wave height 0m (0") |
|
Wave height 0m - 0.1m (0.0" - 3.9") |
|
Wave height 0.1m - 0.5m (3.9"- 1'8") |
|
Wave height 0.5m - 1.25m (1'8"- 4'1") |
|
Wave height 1.25m - 2.5m (4'1"- 8'2") |
|
Wave height 2.5m - 4m (8'2"- 13'1") |
|
Wave height 4m - 6m (13'1" - 20') |
Sea color¶
We provide a few presets for sea color:
Azure blue color useful for open waters |
|
Dark blue color useful for open waters |
|
Medium blue color useful for open waters |
|
Murky greenish color useful for dirty waters |
|
Murky brown color useful for dirty waters |
|
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.
world.env.ocean.set_sea_state(state=SeaState.ROUGH)
world.env.ocean.set_sea_state(state=SeaState(5))
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)
.
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.
Wake disappears immediately |
|
Wake persists briefly (2 seconds) |
|
Wake persists for medium duration (5 seconds) |
|
Wake persists for extended period (30 seconds) |
|
Wake persists for the entire frame 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.
# 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¶
Very subtle wake waves, barely visible |
|
Low amplitude wake waves |
|
Moderate wake waves suitable for average vessels |
|
Tall wake waves for larger vessels |
|
Maximum wake wave height for very large vessels |
Wake Length¶
Very short wake trail |
|
Short wake trail suitable for slow vessels |
|
Medium length wake trail for average vessels |
|
Long wake trail for fast vessels |
|
Very long wake trail for high-speed vessels |
Foam Intensity¶
No foam generation |
|
Light foam suitable for calm conditions |
|
Medium foam suitable for average conditions |
|
Heavy foam suitable for rough conditions |
Churn Strength¶
No water churning |
|
Slight water disturbance |
|
Medium water churning suitable for most vessels |
|
Maximum water churning for powerful vessels |
Wake Sharpness¶
Blurred, gentle wake patterns |
|
Slightly defined wake patterns |
|
Well-defined, realistic wake patterns |
|
Highly detailed, sharp wake patterns |
Method |
Description |
---|---|
|
Controls the height of the wake. Takes |
|
Controls how far the wake extends behind the vessel. Takes |
|
Controls the amount of white water in the wake. Takes |
|
Controls the turbulence and mixing of water in the wake. Takes |
|
Controls the detail level of the wake. Takes |
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.
# 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.