bbi¶

The Bifrost Basic Interface library provides a powerful API for creating and manipulating 3D content. Frequently used classes are available directly from the top level bbi module.

class World(world_name: str)¶

Bases: BaseWorld

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

class SatelliteWorld¶

Bases: BaseWorld

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

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

class Asset(node_id: str, asset_class: str | None = None, asset_name: str | None = None, position: Vector3 = Vector3.zero(), rotation: Vector3 = Vector3.zero(), scale: Vector3 = Vector3(1, 1, 1), randomize: bool = False)¶

Bases: Node, Animatable[AssetUpdateParam]

Asset class which holds the 3D model data and information.

If asset_name is provided, the specific asset will be spawned.
If asset_class is provided, a random asset from that class will be spawned. If randomize is set to True,

the asset will be randomized on every frame.

Parameters:

node_id (str) – The user defined unique ID.
asset_class (str, optional) – The name of the asset class.
asset_name (str, optional) – The name of the asset.
position (Vector3, optional) – The position of the asset. Defaults to Vector3.zero().
rotation (Vector3, optional) – The rotation of the asset. Defaults to Vector3.zero().
scale (Vector3, optional) – The scale of the asset. Defaults to Vector3(1, 1, 1).
randomize (bool, optional) – Randomize the asset on each frame, only applicable for asset_class. Defaults to False.

property size: Vector3¶

property centroid_offset: Vector3¶: The offset to add to the asset position to get the centroid of the asset.

property asset_name: str¶

set_transform(transform: Transform) → None¶

Set the transform of the instance. For efficiency, this method is preferred over setting individual transform components.

Parameters:: transform (Transform) – The transform.

is_static() → bool¶

Returns True if the Asset spawns a single static 3D model.

If is_static() returns False, then the asset is randomized and spawns random 3D models with a class defined by asset_class.

If asset_name is provided on creation, the Asset is considered static.

is_randomized() → bool¶

Returns True if the Asset spawns random 3D models with a defined class.

If is_randomized() returns False, then the asset is static and spawns a single 3D model defined by asset_name.

If asset_name is not provided on creation, the Asset is considered randomized.

get_collisions() → set[str]¶: Get the names of all assets that collide with the current asset.

attach_to(parent: Node, rule: TransformAttachmentRule = TransformAttachmentRule.KEEP_WORLD) → None¶

Attach the asset to another node inheriting its transform operations.

Parameters:

parent (Node) – The parent node to attach the asset to.
rule (TransformAttachmentRule, optional) – How to handle transforms and welding when attaching, defaults to TransformAttachmentRule.KEEP_WORLD.

attach_to_root() → None¶: Attach the asset to its root node.

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

Update the asset 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.

enable_wake(is_enabled: bool) → None¶

Enables or disables the wake effect on the asset.

Parameters:: is_enabled (bool) – Whether to enable or disable the wake effect.

set_collision_check(check: bool) → None¶

Whether the asset should be included in collision checks.

When enabled, this asset will be considered during collision detection with other assets being added or moved in the spatial index. When disabled, this asset will be ignored during such checks.

Parameters:: check (bool) – Whether to perform collision checks for this asset.

class BuoyantAsset(node_id: str, asset_class: str | None = None, asset_name: str | None = None, position: Vector3 = Vector3.zero(), rotation: Vector3 = Vector3.zero(), scale: Vector3 = Vector3(1, 1, 1), randomize: bool = False)¶

Bases: Asset, Animatable[BuoyantAssetUpdateParam]

Assets which floats on water and has a buoyant physics effect.

set_sinking_offset(sinking_offset: float) → None¶

Set the sinking offset for the buoyant asset.

Parameters:: sinking_offset (float) – The offset value (in meters) for the sinking effect.

set_buoyancy_damping(damping: float) → None¶

Set the buoyancy damping of the buoyant asset.

Parameters:: damping (float) – The rate at which rotation should chase buoyancy. A value of 1.0 means that the asset will be as buoyant as the ocean, and a value of 0.0 means that the asset will have no buoyancy at all.

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

Update the asset 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 SpawnZone(node_id: str, asset_names: list[str], quantity: int, geometry: Geometry | list[Geometry], asset_type: type[Asset] = Asset, yaw_range: tuple[float, float] = (0, 360), pitch_range: tuple[float, float] = (0, 0), roll_range: tuple[float, float] = (0, 0), asset_weights: list[float] | None = None, force_respawn: bool = False, contain_within: bool = True, jitter_z: tuple[float, float] = (0, 0), use_geom_rotation: bool = True)¶

Bases: Node, Animatable[SpawnZoneUpdateParam]

Random scattering of assets within a defined zone.

Parameters:

node_id (str) – The node ID of the zone.
asset_names (list[str]) – The names of the assets to spawn.
quantity (int) – The max number of objects to spawn. The final number of spawned assets might be less than this number if there are not enough valid spawn locations, most often due to collisions.
geometry (Geometry, list[Geometry]) – The geometry that defines the spawn zone.
asset_type (type[Asset], optional) – The type of asset to spawn. Defaults to Asset.
yaw_range (tuple[float, float], optional) – The yaw range for the assets. Defaults to (0, 360). If the geometry is a Spline, the yaw would be set to the tangent of the spline at the spawn position, unless use_geom_rotation is set to False.
roll_range (tuple[float, float], optional) – The roll range for the assets. Defaults to (0, 0). This has no effect on BuoyantAsset.
pitch_range (tuple[float, float], optional) – The pitch range for the assets. Defaults to (0, 0). If the geometry is a Spline, the pitch would be set to the normal of the spline at the spawn position. This has no effect on BuoyantAsset.
asset_weights (list[float], optional) – The distribution of assets when spawning. If not provided, all assets are equally likely to be spawned.
force_respawn (bool, optional) – Forcibly remove all existing assets and spawn new ones at each frame, even if the SpawnZone parameters have not changed. If SpawnZone parameters are changed, assets are always respawned regardless of the value of force_respawn. Defaults to False.
contain_within (bool, optional) – Make assets spawn contained entirely within the geometry (Polygon or Cuboid). If True, assets will not clip the edges of the boundary. If False, assets may extend beyond the boundary. Defaults to True.
jitter_z (tuple[float, float], optional) – The range of z-axis jitter applied to the assets after they are spawned. Defaults to (0, 0).
use_geom_rotation (bool, optional) – Whether to use the intrinsic rotation of the geometry (e.g. Spline). Defaults to True.

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.

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.

class Vector3(x: float = 0, y: float = 0, z: float = 0)¶

Bases: object

A 3D vector defined by x, y, and z values.

By convention, units for world space are in meters.

Parameters:

x (float, optional) – The x value. Defaults to 0.
y (float, optional) – The y value. Defaults to 0.
z (float, optional) – The z value. Defaults to 0.

static zero() → Vector3¶: Returns a zero vector Vector3(0, 0, 0).

static one() → Vector3¶

Returns a one vector Vector3(1, 1, 1).

This is useful for setting a default scale.

to_direction() → Vector3¶: Converts a rotation Vector3 (roll, pitch, yaw) to a directional unit Vector3.

to_rotation() → Vector3¶

Converts a directional Vector3 to a rotation Vector3 (roll, pitch, yaw).

Roll is always 0.

numpy() → ndarray¶: Returns the vector as a NumPy array of shape (3,).

magnitude() → float¶: Returns the magnitude of the vector.

normalized() → Vector3¶: Returns a new normalized vector.

cross(other: Vector3) → Vector3¶: Returns the cross product of two vectors.

dot(other: Vector3) → float¶: Returns the dot product of two vectors.

distance_to_point(other: Vector3) → float¶: Calculates the distance to another point.

distance_to_line_segment(start: Vector3, end: Vector3) → float¶: Calculates the shortest distance to a line segment defined by two points.

isclose(other: Vector3, rel_tol: float = 1.0e-5, abs_tol: float = 1.0e-8) → bool¶

Returns True if two vectors are element-wise equal within a tolerance.

The tolerance values are positive, typically very small numbers. The relative difference (rel_tol * abs(b)) and the absolute difference abs_tol are added together to compare against the absolute difference between a and b.

NaNs are treated as equal if they are in the same place and if equal_nan=True. Infs are treated as equal if they are in the same place and of the same sign in both arrays.

Parameters:

other (Vector3) – The other vector to compare.
rel_tol (float, optional) – The relative tolerance. Defaults to 1.e-5.
abs_tol (float, optional) – The absolute tolerance. Defaults to 1.e-8.

to_dict() → dict¶: Returns a dictionary representation of the vector for JSON serialization.

class Transform(position: Vector3 = Vector3.zero(), rotation: Vector3 = Vector3.zero(), scale: Vector3 = Vector3(1, 1, 1))¶

Bases: object

A transform in 3D space that represents position, rotation, and scale.

By convention, units for world space are in meters.

Parameters:

position (Vector3, optional) – The position. Defaults to Vector3.zero().
rotation (Vector3, optional) – The rotation. Defaults to Vector3.zero().
scale (Vector3, optional) – The scale. Defaults to Vector3(1, 1, 1).

right_to_left_handed_conversion = array([[ 0, 1, 0, 0], [ 1, 0, 0, 0], [ 0, 0, -1, 0], [ 0, 0, 0, 1]])¶

property position: Vector3¶

property rotation: Vector3¶

property scale: Vector3¶

property matrix: ndarray¶

apply_relative_transform(relative_transform: Transform) → Transform¶

Applies the relative transform to this transform.

Parameters:: relative_transform (Transform) – The relative transform.
Returns:: The transformed transform.
Return type:: Transform

transform_position(position: Vector3) → Vector3¶

Transforms a position vector by this transform accounting its scale.

Parameters:: position (Vector3) – The position to transform.
Returns:: The transformed position.
Return type:: Vector3

transform_rotation(relative_rotation: Vector3) → Vector3¶

Transforms a rotation vector by this transform.

Parameters:: relative_rotation (Vector3) – The rotation to transform.
Returns:: The transformed rotation.
Return type:: Vector3

transform_scale(relative_scale: Vector3) → Vector3¶

Transforms a scale vector by this transform.

Parameters:: relative_scale (Vector3) – The scale to transform.
Returns:: The transformed scale.
Return type:: Vector3

relative_to(reference: Transform) → Transform¶

Calculates the transform of this transform relative to another transform.

Parameters:

reference (Transform) – The reference transform against which the relative transformation is calculated.

Returns:

A new Transform object representing this transform relative to reference,: with calculated position, rotation, and scale.

Return type:

Transform

get_relative_position(other_position: Vector3) → Vector3¶

Calculates the relative position of other position relative to this transform.

Parameters:: other_position (Vector3) – The other position.
Returns:: The relative position.
Return type:: Vector3

get_relative_rotation(other_rotation: Vector3) → Vector3¶

Calculates the relative rotation of other rotation relative to this transform.

Parameters:: other_rotation (Vector3) – The other rotation.
Returns:: The relative rotation.
Return type:: Vector3

get_relative_scale(other_scale: Vector3) → Vector3¶

Calculates the relative scale of other scale relative to this transform.

Parameters:: other_scale (Vector3) – The other scale.
Returns:: The relative scale.
Return type:: Vector3

class Point(node_id: str, position: Vector3, rotation: Vector3 = Vector3.zero())¶

Bases: Geometry

A 3D point in space.

Parameters:

node_id (str) – The node ID of the point.
position (Vector3) – The position of the point.
rotation (Vector3, optional) – The rotation of the point. Defaults to Vector3(0, 0, 0).

uniform_random_points(n: int) → list[Vector3]¶: Return n uniformly random points within the geometry.

class Spline(node_id: str, points: list[Vector3], tangents: list[Vector3] | None = None)¶

Bases: Geometry

A curved spline constructed using a list of Vector3 positions, and optionally a list of Vector3 tangents.

Spline will pass through all points provided. A minimum of one point must be provided to construct a spline. If tangents are not provided, they are automatically calculated using the points.

Parameters:

node_id (str) – The node ID of the spline.
points (list[Vector3]) – The list of input positions in Vector3.
tangents (list[Vector3], optional) – The list of tangents at each point. Defaults to None.

property length: float¶: The length of the spline in meters.

get_position(t: float) → Vector3¶

Given a particular progress value, get the position along the spline.

Parameters:: t (float) – The time parameter in the range [0, 1].

get_rotation(t: float, look_ahead_value: float = 0.01) → Vector3¶

Given a particular progress value, get a rotation vector useful for aligning assets along the spline.

Parameters:

t (float) – The time parameter in the range [0, 1].
look_ahead_value (float, optional) – The amount to look ahead to calculate the rotation. Defaults to 0.01.

set_width(width: float) → None¶

Assign a width to the spline. The width would act as an obstacle, so that collision checks would factor in width distance from the spline. The spline must be added to the scene before calling this function.

Parameters:: width (float) – The width of the spline.

class Cuboid(node_id: str, origin: Vector3, size: Vector3, rotation: Vector3)¶

Bases: Geometry

A 3D cuboid defined by an origin and size.

Parameters:

node_id (str) – The node ID of the cuboid.
origin (Vector3) – The origin of the cuboid.
size (Vector3) – The size of the cuboid.

uniform_random_points(n: int) → list[Vector3]¶

Return n uniformly random points within the cuboid.

Parameters:: n (int) – The number of points to sample.

property min_x: float¶

property min_y: float¶

property min_z: float¶

property max_x: float¶

property max_y: float¶

property max_z: float¶

class Polygon(node_id: str, points: list[Vector3])¶

Bases: Geometry

A 3D polygon defined by a list of Vector3 points.

Parameters:

node_id (str) – The node ID of the polygon.
points (list[Vector3]) – The list of points that define the polygon.

property points: list[Vector3]¶

property is_simple: bool¶

property area: float¶

contains_point(point: Vector3) → bool¶: Check if a point is within the polygon.

uniform_random_points(n: int) → list[Vector3]¶: Sample n random points within the polygon.

intersection(other: Polygon) → Polygon | None¶

Returns the intersection of this polygon with another polygon.

Parameters:: other (Polygon) – The polygon to intersect with.

difference(other: Polygon) → list[Polygon] | None¶

Returns the difference of this polygon with another polygon.

Parameters:: other (Polygon) – The polygon to subtract from this polygon.

class SeaState(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: IntEnum

Based off WMO sea state codes.

CALM_GLASSY = 0¶: Wave height 0m (0”)

CALM_RIPPLED = 1¶: Wave height 0m - 0.1m (0.0” - 3.9”)

SMOOTH = 2¶: Wave height 0.1m - 0.5m (3.9”- 1’8”)

SLIGHT = 3¶: Wave height 0.5m - 1.25m (1’8”- 4’1”)

MODERATE = 4¶: Wave height 1.25m - 2.5m (4’1”- 8’2”)

ROUGH = 5¶: Wave height 2.5m - 4m (8’2”- 13’1”)

VERY_ROUGH = 6¶: Wave height 4m - 6m (13’1” - 20’)

class SeaColor(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: StrEnum

Water color presets

AZURE_BLUE = 'AzureBlue'¶: Azure blue color useful for open waters

MEDIUM_BLUE = 'MediumBlue'¶: Medium blue color useful for open waters

DARK_BLUE = 'DarkBlue'¶: Dark blue color useful for open waters

TURQUOISE = 'Turquoise'¶: Turquoise color useful for shallow tropical waters

MURKY = 'Murky'¶: Murky greenish color useful for dirty waters

MURKY_BROWN = 'MurkyBrown'¶: Murky brown color useful for dirty waters

pydantic model CameraProfile¶

Bases: BaseModel

field id: str [Required]¶

field lut_cube_base64: str = ''¶

field name: str [Required]¶

field post_processing_color_overrides: dict[str, Vector4] = {}¶

field post_processing_float_overrides: dict[str, float] = {}¶

field post_processing_int_overrides: dict[str, int] = {}¶

field ppv_components: list[LensAndFilmPostProcessingVolumeComponent] = [LensAndFilmPostProcessingVolumeComponent(world_component=<MapComponent.LENS_AND_FILM_POST_PROCESSING_VOLUME: 'LensAndFilmPostProcessingVolume'>, properties={'Enabled': 'false'})]¶

class ScreenDropletsPreset(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: StrEnum

NONE = 'None'¶: No droplets on the camera lens

LIGHT = 'Light'¶: Small droplets on the camera lens

MEDIUM = 'Medium'¶: Small running droplets on the camera lens

HEAVY = 'Heavy'¶: Large running droplets on the camera lens

class RenderMode(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: StrEnum

IN_EDITOR = 'in_editor'¶

OFFLINE = 'offline'¶

class Color(r: float = 0, g: float = 0, b: float = 0, a: float = 1)¶

Bases: object

A class describing color in RGBA channel values normalized between 0 and 1.

Parameters:

r (float, optional) – The RED value. Defaults to 0.
g (float, optional) – The GREEN value. Defaults to 0.
b (float, optional) – The BLUE value. Defaults to 0.
a (float, optional) – The ALPHA value. Defaults to 1.

static black() → Color¶: Returns black color Color(0, 0, 0, 1).

to_hsv() → tuple[float, float, float]¶

Converts the color to HSV values.

Returns:: The HSV values.
Return type:: tuple[float, float, float]

static from_vector_data(color: Vector4) → Color¶

Converts a Vector4 to Color.

Parameters:: vector (Vector4) – The Vector4 to convert.
Returns:: The converted Color.
Return type:: Color

static from_hsv(hue: float, saturation: float, value: float) → Color¶

Converts HSV values to a Color.

Parameters:

hue (float) – The hue value.
saturation (float) – The saturation value.
value (float) – The value.

Returns:

The converted Color.

Return type:

Color

class OceanWakeDuration(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: IntEnum

Controls how long the wake persists

NONE = 0¶: Wake disappears immediately

SHORT = 1¶: Wake persists briefly (2 seconds)

MODERATE = 2¶: Wake persists for medium duration (5 seconds)

LONG = 3¶: Wake persists for extended period (30 seconds)

FULL_FRAME_DURATION = 4¶: Wake persists for the entire frame duration

class OceanChurnStrength(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: IntEnum

Controls the turbulence and mixing of water in the wake

NONE = 0¶: No water churning

LITTLE = 1¶: Slight water disturbance

MODERATE = 2¶: Medium water churning suitable for most vessels

EXTREME = 3¶: Maximum water churning for powerful vessels

class OceanFoamIntensity(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: IntEnum

Controls the amount and intensity of foam in the wake

NONE = 0¶: No foam generation

LITTLE = 1¶: Light foam suitable for calm conditions

MODERATE = 2¶: Medium foam suitable for average conditions

EXTREME = 3¶: Heavy foam suitable for rough conditions

class OceanWakeHeight(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: IntEnum

Controls the height/amplitude of the wake waves

EXTRA_SMALL = 0¶: Very subtle wake waves, barely visible

SMALL = 1¶: Low amplitude wake waves

MEDIUM = 2¶: Moderate wake waves suitable for average vessels

LARGE = 3¶: Tall wake waves for larger vessels

EXTRA_LARGE = 4¶: Maximum wake wave height for very large vessels

class OceanWakeLength(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: IntEnum

Controls how far the wake extends behind the vessel

EXTRA_SMALL = 0¶: Very short wake trail

SMALL = 1¶: Short wake trail suitable for slow vessels

MEDIUM = 2¶: Medium length wake trail for average vessels

LARGE = 3¶: Long wake trail for fast vessels

EXTRA_LARGE = 4¶: Very long wake trail for high-speed vessels

class OceanWakeSharpness(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: IntEnum

Controls the detail level and definition of wake patterns

SOFT = 0¶: Blurred, gentle wake patterns

SMOOTH = 1¶: Slightly defined wake patterns

NATURAL = 2¶: Well-defined, realistic wake patterns

CRISP = 3¶: Highly detailed, sharp wake patterns

class OceanWakeSpeed(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: IntEnum

Controls how the vessel’s speed affects wake characteristics

STATIONARY = 0¶: For stationary or barely moving vessels

SLOW = 1¶: For vessels moving at low speed

MODERATE = 2¶: For vessels at cruising speed

FAST = 3¶: For vessels at high speed

class Ontology¶

Bases: object

Class to manage ontologies

classmethod list_ontologies() → list[str]¶: List all ontologies.

classmethod get_ontology(ontology_name: str) → dict¶

Get an ontology by name.

Parameters:: ontology_name (str) – Name of the ontology to get.

classmethod set_ontology(ontology_name: str, ontology_classes: dict, overwrite: bool = False) → None¶

Create an ontology by mapping category IDs to category names and asset names.

Parameters:

ontology_name (str) – Name of the ontology.
ontology_classes (dict) – Dictionary where each key is the category ID and each value is a dictionary of the name of the category and the asset names associated with the category.
overwrite (bool, optional) – Overwrite the ontology if it already exists. Defaults to False.

Example:

ontology_classes = {
    1: {
        "name": "category_1",
        "asset_names": ["asset_a", "asset_b"]
    },
    2: {
        "name": "category_2",
        "asset_names": ["asset_c", "asset_d"]
    }
}
Ontology.set_ontology(ontology_name="ontology", ontology_classes=ontology_classes, overwrite=True)

classmethod delete_ontology(ontology_name: str) → None¶

Delete an ontology.

Parameters:: ontology_name (str) – Name of the ontology to delete.

classmethod rename_ontology(ontology_name: str, new_ontology_name: str) → None¶

Rename an ontology. Ontology name must be unique.

Parameters:

ontology_name (str) – Name of the ontology to rename.
new_ontology_name (str) – New name of the ontology.