bbi.utils

Collection of BBI related utility functions.

calculate_look_at_rotation(source_position: Vector3, target_position: Vector3) → Vector3

Calculate the rotation needed to look from one point towards another point.

Note

When turning to look at a point, only pitch and yaw are relevant. Roll is unnecessary and will be set to zero.

Parameters:

  • source_position (Vector3) – The position to look from

  • target_position (Vector3) – The position to look at

Returns:

The rotation in degrees (0, pitch, yaw)

Return type:

Vector3

plane_line_intersection(line_point: Vector3, line_direction: Vector3, plane_point: Vector3, plane_normal: Vector3) → Vector3 | None

Find the intersection point between a line and a plane.

A segment has two endpoints, a ray has one endpoint and extends infinitely in one direction, and a line extends infinitely in both directions.

Parameters:

  • line_point (Vector3) – A point on the line

  • line_direction (Vector3) – Direction vector of the line

  • plane_point (Vector3) – A point on the plane

  • plane_normal (Vector3) – Normal vector of the plane

See also

plane_ray_intersection(ray_start: Vector3, ray_direction: Vector3, plane_point: Vector3, plane_normal: Vector3) → Vector3 | None

Find the intersection point between a ray and a plane.

A segment has two endpoints, a ray has one endpoint and extends infinitely in one direction, and a line extends infinitely in both directions.

Parameters:

  • ray_start (Vector3) – Starting point of the ray

  • ray_direction (Vector3) – Direction vector of the ray

  • plane_point (Vector3) – A point on the plane

  • plane_normal (Vector3) – Normal vector of the plane

See also

plane_segment_intersection(segment_start: Vector3, segment_end: Vector3, plane_point: Vector3, plane_normal: Vector3) → Vector3 | None

Find the intersection point between a line segment and a plane.

A segment has two endpoints, a ray has one endpoint and extends infinitely in one direction, and a line extends infinitely in both directions.

Parameters:

  • segment_start (Vector3) – Starting point of the line segment

  • segment_end (Vector3) – Ending point of the line segment

  • plane_point (Vector3) – A point on the plane

  • plane_normal (Vector3) – Normal vector of the plane

See also

point_to_line_distance(point: Vector3, line_point: Vector3, line_direction: Vector3) → float

Find the shortest distance from a point to a line.

A segment has two endpoints, a ray has one endpoint and extends infinitely in one direction, and a line extends infinitely in both directions.

Parameters:

  • point (Vector3) – The point to measure distance from

  • line_point (Vector3) – Any point on the line

  • line_direction (Vector3) – Direction vector of the line

See also

point_to_ray_distance(point: Vector3, ray_start: Vector3, ray_direction: Vector3) → float

Find the shortest distance from a point to a ray.

A segment has two endpoints, a ray has one endpoint and extends infinitely in one direction, and a line extends infinitely in both directions.

Parameters:

  • point (Vector3) – The point to measure distance from

  • ray_start (Vector3) – Starting point of the ray

  • ray_direction (Vector3) – Direction vector of the ray

See also

point_to_segment_distance(point: Vector3, segment_start: Vector3, segment_end: Vector3) → float

Find the shortest distance from a point to a line segment.

A segment has two endpoints, a ray has one endpoint and extends infinitely in one direction, and a line extends infinitely in both directions.

Parameters:

  • point (Vector3) – The point to measure distance from

  • segment_start (Vector3) – First endpoint of the line segment

  • segment_end (Vector3) – Second endpoint of the line segment

See also

calculate_vfov(hfov: float, resolution: tuple[int, int]) → float

Calculate the vertical field of view in degrees.

Parameters:

  • hfov (float) – The horizontal field of view in degrees.

  • resolution (tuple[int, int]) – The resolution of the camera.

Returns:

The vertical field of view in degrees.

Return type:

float

camera_ground_footprint(min_distance: float, max_distance: float, cam_position: Vector3, cam_rotation: Vector3, hfov: float, vfov: float) → list[Vector3] | None

Calculate the polygon footprint of camera frustum on the ground plane.

Finds the visible area on the ground (z=0) within the camera’s field of view and distance constraints measured in the direction (yaw) the camera is facing at ground level.

Parameters:

  • min_distance (float) – Minimum distance in the direction the camera is facing

  • max_distance (float) – Maximum distance in the direction the camera is facing

  • cam_position (Vector3) – Camera position in world coordinates

  • cam_rotation (Vector3) – Camera rotation as (roll, pitch, yaw) in degrees

  • hfov (float) – Horizontal field of view in degrees

  • vfov (float) – Vertical field of view in degrees

Returns:

The polygon points forming the camera footprint on the ground plane.

None if the camera frustum does not intersect with the ground plane or if the distance constraints exceeds the frustum bounds.

Return type:

list[Vector3] | None

ray_direction_to_screen(direction: Vector3, cam_rotation: Vector3, hfov: float, vfov: float) → tuple[float, float] | None

Find where a camera ray direction projects onto the screen.

Given a camera ray direction in world space, calculates the corresponding screen space coordinates where that ray would intersect the screen.

Screen space coordinates (0-1 range): - (0.5, 0.5) = center - (0, 1) = bottom-left corner - (0, 0) = top-left corner - (1, 0) = top-right corner - (1, 1) = bottom-right corner

Parameters:

  • direction (Vector3) – Camera ray direction in world space. Should be a unit vector.

  • cam_rotation (Vector3) – Camera rotation (roll, pitch, yaw) in degrees.

  • hfov (float) – Horizontal field of view in degrees.

  • vfov (float) – Vertical field of view in degrees.

See also

Returns:

The screen space coordinates where the ray intersects the screen, or None if the ray is behind the camera or on the camera plane.

Return type:

tuple[float, float] | None

screen_to_ray_direction(screen_x: float, screen_y: float, cam_rotation: Vector3, hfov: float, vfov: float) → Vector3

Calculate the normalized camera ray direction in world space for a given screen space coordinate.

Given a screen space coordinate (x, y), compute the direction of the camera ray in world space that would project to that point on the screen.

Screen space coordinates (0-1 range): - (0.5, 0.5) = center - (0, 1) = bottom-left corner - (0, 0) = top-left corner - (1, 0) = top-right corner - (1, 1) = bottom-right corner

Parameters:

  • screen_x (float) – Horizontal screen coordinate (in range [0, 1]).

  • screen_y (float) – Vertical screen coordinate (in range [0, 1]).

  • cam_rotation (Vector3) – Camera rotation (roll, pitch, yaw) in degrees.

  • hfov (float) – Horizontal field of view in degrees.

  • vfov (float) – Vertical field of view in degrees.

See also

Returns:

The normalized camera ray direction in world space.

Return type:

Vector3