bbi.experimental¶

The experimental bbi is a fork of the main bbi code with some classes swapped out for experimental implementations. Experimental is meant for demo code only, NOT for WIP features. Eventually, everything in experimental should be either moved to the main bbi codebase or removed.

class World(world_name: str)¶

Bases: World

new_scenario(num_frames: int, total_seconds: float = 0.0) → Scenario¶

Creates a new scenario. Note that creating a new scenario will clear all previously set keyframes.

Parameters:

num_frames (int) – The number of frames in the scenario.
total_seconds (float) – The expected total duration of this scenario in seconds. This is used together with num_frames to calculate the delta time between frames. For example, if num_frames is 100 and total_seconds is 10, then the delta time between frames is 0.1 seconds. Set it to 0.0 to disable delta time calculation.

Returns:

A new scenario.

Return type:

Scenario

class SatelliteWorld¶

Bases: BaseWorld

new_scenario(num_frames: int, total_seconds: float = 0.0) → Scenario¶

Creates a new scenario. Note that creating a new scenario will clear all previously set keyframes.

Parameters:

num_frames (int) – The number of frames in the scenario.
total_seconds (float) – The expected total duration of this scenario in seconds. This is used together with num_frames to calculate the delta time between frames. For example, if num_frames is 100 and total_seconds is 10, then the delta time between frames is 0.1 seconds. Set it to 0.0 to disable delta time calculation.

Returns:

A new scenario.

Return type:

Scenario

property camera: SatelliteCamera¶: The default camera in the world.

property backplate: SatelliteBackplate¶: The backplate in the world.

class Scenario(world: BaseWorld, num_frames: int, total_seconds: float)¶

Bases: Scenario

set_metadata_keyframe(frame_id: int, key: str, value: Any)¶

get_metadata_at_frame(frame_id: int) → dict[str, Any]¶

class PlacementManager(world: BaseWorld, meters_per_cell: int = 50, grid_height: int = 15, grid_width: int = 15, grid_start: Vector3 = Vector3(0, 0, 0), diagonal_movement: int = DiagonalMovement.never, node_id: str | None = None)¶

Bases: object

set_diagonal_movement(diagonal_movement: int) → None¶

Set the diagonal movement type. - 1=always - 2=never - 3=if_at_most_one_obstacle - 4=only_when_no_obstacle

Parameters:: diagonal_movement (int) – The diagonal movement type.

show(show_internal_grid: bool = True) → None¶

Outline the placement area as a grid.

Parameters:: show_internal_grid (bool, optional) – Whether to show the internal grid lines. Defaults to True.

hide()¶: Hide the grid.

world_to_grid_index(world_position: Vector3, radius: float = 0) → list[tuple[int, int]]¶

Convert world coordinates to grid indices. If radius is provided, the function will return all grid indices within the radius of the world position.

Parameters:

world_position (Vector3) – World position to convert.
radius (float, optional) – Radius from position to calculate grid indices. Defaults to 0.

create_paths(max_paths: int) → list[Spline]¶

Randomly create paths, in the form of splines, within the grid. Old paths are deleted before creating new ones.

Parameters:: max_paths (int) – The maximum number of paths to create. The actual number of paths created may be less than this value.

add_path(path: Spline, path_radius: float = 0) → None¶

Add a path to PlacementManager defined area. Subsequent paths and assets will avoid this path.

Parameters:

path (Spline) – The path to add.
path_radius (float, optional) – The radius of the path in meters. All grid cells within radius of the path will be blocked.

scatter_static_assets(asset_names: list[str], num_assets: int, asset_length: int = 0, rotation_range: tuple[float, float] = (0, 360), asset_type: type[Asset] = BuoyantAsset) → list[Asset]¶

Randomly scatter static assets within the grid.

Parameters:

asset_class (str) – The asset class to sample assets from.
num_assets (int) – The number of assets to scatter.
asset_length (int, optional) – The length of the obstacles in meters. Defaults to 0.
rotation_range (tuple[float, float], optional) – The range of rotation in degrees. Defaults to (0, 360).
asset_type (type[Asset], optional) – The type of asset to spawn. Defaults to BuoyantAsset.

clear_scattered_assets() → None¶: Clear all scattered assets from the grid.

remove_asset(asset: Asset) → None¶

Remove a specific asset from the grid.

Parameters:: asset (Asset) – The asset to remove.

class SpawnZoneV2(node_id: str, spawning_strategy: SpawningStrategy, quantity: int, max_attempts: int = 10, force_respawn: bool = False)¶

Bases: Node, Animatable[SpawnZoneV2UpdateParam]

Scattering of assets using a custom spawning strategy.

The spawning strategy must implement 2 methods: - asset_factory(): Returns a single Asset. The Asset can be a parent of other Assets. - placement_strategy(): Returns a Transform for positioning the returned Asset.

There are also 2 optional methods: - validation_strategy(asset) returns bool indicating if the placement is valid.

If not provided, it defaults to checking if the asset has collisions.

post_spawn_hook(asset) is called after the asset is spawned. Use this to configure properties of the asset.

Parameters:

node_id (str) – The node ID of the spawnzone.
spawning_strategy (SpawningStrategy) – The spawning strategy to use. Must implement asset_factory(), placement_strategy(), validation_strategy() and post_spawn_hook() methods.
quantity (int) – The max number of objects to spawn.
max_attempts (int, optional) – The maximum number of attempts to try and spawn an asset. Defaults to 10.
force_respawn (bool, optional) – Whether to forcibly remove all existing assets and spawn new ones at each frame. Defaults to False.

Example:

class MySpawningStrategy(SpawningStrategy):
    def __init__(self, polygon: Polygon):
        self.polygon = polygon

    def asset_factory(self) -> Asset:
        parent_asset = Asset(
            SpawningStrategy.NODE_ID_PLACEHOLDER,
            asset_name=...
        )
        child_asset = Asset(
            SpawningStrategy.NODE_ID_PLACEHOLDER,
            asset_name=...
        )
        child_asset.attach_to(parent_asset)
        return parent_asset

    def placement_strategy(self) -> Transform:
        position = self.polygon.uniform_random_points(1)[0]
        return Transform(
            position=position,
            rotation=Vector3.zero(),
            scale=Vector3.one()
        )

    def validation_strategy(self, asset: Asset) -> bool:
        all_nodes = [asset, *get_all_children(asset)]
        return not any(n.get_collisions() for n in all_nodes if isinstance(n, Asset))

    def post_spawn_hook(self, asset: Asset) -> None:
        asset.enable_wakes(True)

spawn_zone = SpawnZoneV2(
    node_id="my_spawn_zone",
    spawning_strategy=MySpawningStrategy(polygon=polygon),
    quantity=10
)

pre_execute(frame_id: int | None = None, frame_max: int | None = None, delta_seconds: float | None = None) → None¶

Removes spawned assets if respawning is needed. This is to ensure that the old assets are not present during collision checks, especially in the case where there are multiple SpawnZones and they overlap

Parameters:

frame_id (int | None, optional) – The frame ID. Defaults to None.
frame_max (int | None, optional) – Max frame count in the current loop. Defaults to None.
delta_seconds (float | None, optional) – The target real-time in seconds between frames. This is used to calculate physical displacement for certain assets. Defaults to None.

execute(frame_id: int | None = None, frame_max: int | None = None, delta_seconds: float | None = None) → None¶

Update the spawnzone state up to the specified frame.

Parameters:

frame_id (int | None, optional) – The frame ID. Defaults to None.
frame_max (int | None, optional) – Max frame count in the current loop. Defaults to None.
delta_seconds (float | None, optional) – The target real-time in seconds between frames. This is used to calculate physical displacement for certain assets. Defaults to None.

class SpawningStrategy¶

Bases: ABC

abstract asset_factory() → Asset¶

Factory method to create assets.

Perform all attachments here but only return a single parent asset.

abstract placement_strategy() → Transform¶: Strategy to determine the transform of the parent asset.

validation_strategy(asset: Asset) → bool¶

Strategy to validate if the assets can be spawned.

If not provided, it defaults to checking if the assets have collisions if any actors in the world.

post_spawn_hook(asset: Asset) → None¶

Hook to perform any post-spawn actions.

This is called after the asset is spawned.