Create time series scenarios

Note

Both this guide and Randomize scenarios use the concept of keyframes to achieve time series data and randomization repsectively.

When crafting time series scenarios, finer control over individual parameters is needed to achieve smooth transitions over frames.

Instead of varying the environment via presets, we’ll describe changes to individual parameters, including physical attributes like position, rotation, and weather attributes like sun_intensity, rain_intensity, and sea_state.

When creating dynamic scenes with many moving objects, writing code to manually control the position and rotation of each asset can be cumbersome. Instead, use a Scenario and its keyframes to manage changes to the parameters of assets and the world over time.

Here’s a simple example of how to describe a boat moving 25m along the x-axis over 5 seconds.

Animate a boat moving along the x-axis

from bbi import *

world = World("ocean")

boat = Asset(node_id="boat", asset_name="Strong Boy")
world.add(boat)

scenario = world.new_scenario(num_frames=25, total_duration=5)
for i in range(scenario.num_frames):
    scenario.set_keyframe(boat, frame=i, position=Vector3(i, 0, 0))

scenario.preview_animation()

Similarly, you can use set_keyframe on cameras, assets, and environment objects to describe changes over time.

What can be keyframed?

Keyframable objects	List of keyframable parameters
Cameras
Camera	fov, position, rotation
SatelliteCamera	ground_target, look_angle, azimuth
Assets
Asset and BuoyantAsset	position, rotation
SpawnZone	asset_names, asset_weights, force_respawn, geometry, quantity, yaw_range
Environment
Ocean	sea_state, sea_color
Time	time
Weather	cloud_coverage, fog_distance, fog_intensity, fog_max_opacity, rain_intensity, rain_screen_droplets, sky_atmosphere_contribution_color_scale, sun_azimuth, sun_elevation, sun_intensity

For details on values for weather and time parameters, see Change weather and lighting.

View all keyframable params

From the notebook, you can view the full list of keyframable parameters and their types for a Node:

View all keyframable parameters for a Node

boat.view_updatable_params()

>>> {'position': 'Vector3', 'rotation': 'Vector3', 'scale': 'Vector3'}

Controlling the FPS

Each scenario is defined by the number of images it contains (num_frames), over a specified number of real-life seconds (total_duration). For example, if we want a 5-second sequence with 25 frames (5 FPS), we set num_frames=25 and total_duration=5.

\[\text{FPS} = \frac{\text{num_frames}}{\text{total_duration}}\]

Using keyframes to describe change

Asset motion can be described in raw transforms, but using Geometry to drive motion can be more convenient and intuitive.

The above example in Place assets along paths shows how to use Splines to drive asset motion.

Creating a video or GIF

After rendering and downloading the frames, you may use tools like ffmpeg to turn rendered images to create a video or a GIF.

Create a video from rendered images

ffmpeg -framerate 5 -i RGB_default_camera_%d.png -c:v libx264 -pix_fmt yuv420p output.mp4