Vision

Vision provides dependency-light camera geometry helpers for RGB-D observations and Cartesian/pixel alignment-error helpers for caller-owned correction loops.

Python

Camera geometry and position/pixel alignment-error helpers.

Types

class olo.vision.Pixel

Bases: object

Pixel coordinate, zero-based from the top-left of the image.

__init__(x, y)

Parameters:

• x (float)

• y (float)

Return type:

None

class olo.vision.BoundingBox

Bases: object

Half-open image bounding box with XYXY pixel coordinates.

__init__(minimum, maximum)

Parameters:

• minimum (Pixel)

• maximum (Pixel)

Return type:

None

property center: Pixel

Return the box centre pixel.

classmethod from_xywh(x, y, width, height)

Create a half-open bounding box from x, y, width, height.

Return type:

BoundingBox

Parameters:

• x (float)

• y (float)

• width (float)

• height (float)

classmethod from_xyxy(x_min, y_min, x_max, y_max)

Create a half-open bounding box from x_min, y_min, x_max, y_max.

Return type:

BoundingBox

Parameters:

• x_min (float)

• y_min (float)

• x_max (float)

• y_max (float)

property height: float

Return the box height in pixels.

to_xywh()

Return x, y, width, height.

Return type:

tuple[float, float, float, float]

to_xyxy()

Return x_min, y_min, x_max, y_max.

Return type:

tuple[float, float, float, float]

property width: float

Return the box width in pixels.

class olo.vision.CameraIntrinsics

Bases: object

Pinhole camera calibration parsed from sensor_msgs/CameraInfo.

__init__(width, height, fx, fy, cx, cy, frame_id='', stamp=None, distortion_model='', distortion=())

Parameters:

• width (int)

• height (int)

• fx (float)

• fy (float)

• cx (float)

• cy (float)

• frame_id (str)

• stamp (datetime | None)

• distortion_model (str)

• distortion (tuple[float, ...])

Return type:

None

class olo.vision.PointObservation

Bases: object

Stamped 3D point observation in the camera optical frame.

__init__(point, frame_id, pixel, depth_metres, stamp=None)

Parameters:

• point (Point)

• frame_id (str)

• pixel (Pixel)

• depth_metres (float)

• stamp (datetime | None)

Return type:

None

class olo.vision.AlignmentError

Bases: object

Image-space alignment error.

__init__(x_px, y_px, distance_px, converged)

Parameters:

• x_px (float)

• y_px (float)

• distance_px (float)

• converged (bool)

Return type:

None

class olo.vision.PositionError

Bases: object

Cartesian position error.

__init__(vector, distance, converged, frame_id='')

Parameters:

• vector (Vector)

• distance (float)

• converged (bool)

• frame_id (str)

Return type:

None

Camera geometry helpers

olo.vision.camera_info_to_intrinsics(message)

Parse a sensor_msgs/CameraInfo message into pinhole intrinsics.

Return type:

CameraIntrinsics

Parameters:

message (dict[str, Any])

olo.vision.sample_depth(image, pixel, *, window_size=1, min_depth_metres=None, max_depth_metres=None)

Sample a depth image at a pixel, optionally using a median window.

Return type:

float | None

Parameters:

• image (Image)

• pixel (Pixel)

• window_size (int)

• min_depth_metres (float | None)

• max_depth_metres (float | None)

olo.vision.sample_depth_region(image, region, *, aggregation='median', min_valid_pixels=1, min_depth_metres=None, max_depth_metres=None)

Sample a depth image region and aggregate valid depths in metres.

Return type:

float

Parameters:

• image (Image)

• region (BoundingBox | ndarray)

• aggregation (Literal['median', 'trimmed_mean'])

• min_valid_pixels (int)

• min_depth_metres (float | None)

• max_depth_metres (float | None)

olo.vision.sample_depth_point(depth_image, pixel, intrinsics, *, window_size=1, min_depth_metres=None, max_depth_metres=None)

Sample and deproject a depth point, preserving the depth image observation stamp.

Return type:

PointObservation | None

Parameters:

• depth_image (Image)

• pixel (Pixel)

• intrinsics (CameraIntrinsics)

• window_size (int)

• min_depth_metres (float | None)

• max_depth_metres (float | None)

olo.vision.deproject_pixel(pixel, depth_metres, intrinsics)

Deproject a pixel and depth into the ROS optical camera frame.

Return type:

Point

Parameters:

• pixel (Pixel)

• depth_metres (float)

• intrinsics (CameraIntrinsics)

olo.vision.deproject_point(pixel, depth_metres, intrinsics)

Deproject a pixel and scalar depth into the ROS optical camera frame.

Return type:

Point

Parameters:

• pixel (Pixel)

• depth_metres (float)

• intrinsics (CameraIntrinsics)

olo.vision.deproject(depth_image, pixel, intrinsics, *, window_size=1, min_depth_metres=None, max_depth_metres=None)

Sample and deproject a depth point, preserving frame metadata.

Return type:

PointObservation | None

Parameters:

• depth_image (Image)

• pixel (Pixel)

• intrinsics (CameraIntrinsics)

• window_size (int)

• min_depth_metres (float | None)

• max_depth_metres (float | None)

olo.vision.deproject_region(depth_image, region, intrinsics, *, aggregation='median', min_valid_pixels=1, min_depth_metres=None, max_depth_metres=None)

Deproject a depth region into an aggregated camera-frame observation.

Return type:

PointObservation

Parameters:

• depth_image (Image)

• region (BoundingBox | ndarray)

• intrinsics (CameraIntrinsics)

• aggregation (Literal['median', 'trimmed_mean'])

• min_valid_pixels (int)

• min_depth_metres (float | None)

• max_depth_metres (float | None)

olo.vision.deproject_to_frame(observation, *, frames, target_frame, timeout=5.0)

Transform a stamped point observation into a target frame.

Return type:

PointObservation

Parameters:

• observation (PointObservation)

• frames (FrameLookup)

• target_frame (str)

• timeout (float)

olo.vision.project_point(point, intrinsics)

Project a camera-frame point into pixel coordinates.

Return type:

Pixel

Parameters:

• point (Point)

• intrinsics (CameraIntrinsics)

olo.vision.project(point, intrinsics)

Project a camera-frame point into pixel coordinates.

Return type:

Pixel

Parameters:

• point (Point)

• intrinsics (CameraIntrinsics)

Control helpers

olo.vision.pixel_alignment_error(current, target, *, tolerance_px)

Return signed pixel error and convergence against a tolerance.

Return type:

AlignmentError

Parameters:

• current (Pixel)

• target (Pixel)

• tolerance_px (float)

olo.vision.position_error(current, target, *, tolerance_m)

Return Cartesian target - current error and convergence.

Return type:

PositionError

Parameters:

• current (Point | PointObservation)

• target (Point | PointObservation)

• tolerance_m (float)

TypeScript

Import from olo/vision:

Types

• Pixel Zero-based image pixel coordinate.

• BoundingBox Half-open image bounding box with XYXY pixel coordinates.

• CameraIntrinsics Pinhole camera calibration parsed from sensor_msgs/CameraInfo.

• PointObservation Stamped 3D point observation in an image-derived frame.

• AlignmentError Image-space alignment error.

• PositionError Cartesian position error.

Options

• SampleDepthOptions

• SampleDepthRegionOptions

Camera geometry helpers

• cameraInfoToIntrinsics

• sampleDepth

• sampleDepthRegion

• sampleDepthPoint

• deprojectPixel

• deprojectPoint

• deproject

• deprojectRegion

• deprojectToFrame

• projectPoint

• project

Control helpers

• pixelAlignmentError

• positionError