oakutils.tools package

Submodules

oakutils.tools.depth module

Tools for working with depth images.

Functions

align_depth_to_rgb

Use to align a depth image to an RGB image.

quantize_colormap_depth_frame

Further quantize the depth image for nice visualization.

overlay_depth_frame

Overlay the depth map on top of the RGB image.

oakutils.tools.depth.align_depth_to_rgb(depth_image: ndarray, pixel_coords: ndarray, inverse_depth_intrinsic: ndarray, rgb_intrinsic: ndarray, depth_to_rgb_extrinsic: ndarray, rgb_width: int, rgb_height: int, depth_scale: float = 1000.0) → ndarray

Use to align a depth image to an RGB image.

Parameters:

  • depth_image (np.ndarray) – The depth image to align.

  • pixel_coords (np.ndarray) – The pixel coordinates of the depth image.

  • inverse_depth_intrinsic (np.ndarray) – The inverse depth intrinsic matrix.

  • rgb_intrinsic (np.ndarray) – The RGB intrinsic matrix.

  • depth_to_rgb_extrinsic (np.ndarray) – The depth to RGB extrinsic matrix.

  • rgb_width (int) – The width of the RGB image.

  • rgb_height (int) – The height of the RGB image.

  • depth_scale (float, optional) – Depth scaling factor. Defaults to 1000.0 to convert from millimeters to meters.

Returns:

The aligned depth image.

Return type:

np.ndarray

References

https://github.com/luxonis/depthai-experiments/blob/master/gen2-pointcloud/rgbd-pointcloud/utils.py

oakutils.tools.depth.overlay_depth_frame(rgb_frame: ndarray, depth_frame: ndarray, rgb_alpha: float = 0.5) → ndarray

Overlay the depth map on top of the RGB image.

Parameters:

  • rgb_frame (np.ndarray) – RGB image

  • depth_frame (np.ndarray) – Depth map image

  • rgb_alpha (float) – Alpha value for blending the RGB and depth map images

Returns:

Blended RGB and depth map image

Return type:

np.ndarray

References

https://github.com/luxonis/depthai-experiments/blob/master/gen2-pointcloud/rgbd-pointcloud/utils.py

oakutils.tools.depth.quantize_colormap_depth_frame(frame: ndarray, depth_scale_factor: float = 2.0, *, apply_colormap: bool | None = None) → ndarray

Further quantize the depth image for nice visualization.

Parameters:

  • frame (np.ndarray) – Depth map image

  • depth_scale_factor (float) – Scale factor to apply to the depth map before quantization

  • apply_colormap (bool) – Whether to apply a colormap to the depth map

Returns:

Quantized depth map image

Return type:

np.ndarray

References

https://github.com/luxonis/depthai-experiments/blob/master/gen2-pointcloud/rgbd-pointcloud/utils.py

oakutils.tools.display module

Module for creating and using displays for visualization.

Classes

DisplayManager

Used to display multiple camera streams at once.

Functions

get_resolution_area

Gets the area of the given resolution.

order_resolutions

Orders the given resolutions from smallest to largest.

get_smaller_size

Gets the smaller size of the two given sizes.

class oakutils.tools.display.DisplayManager(fps: int = 30, display_size: tuple[int, int] = (640, 480))

Bases: object

Used in the Camera class to display all the image streams.

callback(name: str) → Callable[[dai.ImgFrame], None]

Use to get a callback to be used with ImgFrame outputs.

The outputs come from queues from a depthai.Device. The callback will update the display with the given name based on the data from the ImgFrame.

Parameters:

name (str) – The name of the output queue to add the callback to.

Returns:

The callback to be used with the Camera class.

Return type:

Callable[[dai.ImgFrame], None]

property fps: int

Returns the fps of the display manager.

Returns:

The fps of the display manager

Return type:

int

set_transform(name: str, transform: Callable[[np.ndarray], np.ndarray]) → None

Use to set a transform for the given name.

A transform should take in an np.ndarray and return an np.ndarray.

Parameters:

  • name (str) – The name of the transform

  • transform (Callable[[np.ndarray], np.ndarray]) – The transform to set

stop() → None

Use to stop the display manager.

update(data: tuple[str, np.ndarray] | list[tuple[str, np.ndarray]], transform: Callable | None = None) → None

Use to update the display manager with the given data.

Parameters:

  • data (Union[Tuple[str, np.ndarray], list[str, np.ndarray]]) – The data to update the display with. Can be a single tuple or an list of tuples.

  • transform (Optional[Callable], optional) – A transform to call on each frame, by default None The transform should take in an np.ndarray and return an np.ndarray

oakutils.tools.display.get_resolution_area(resolution: tuple[int, int]) → int

Use to get the area of the given resolution.

Parameters:

resolution (Tuple[int, int]) – The resolution to get the area of

Returns:

The area of the resolution

Return type:

int

oakutils.tools.display.get_smaller_size(size1: tuple[int, int], size2: tuple[int, int]) → tuple[int, int]

Use to get the smaller size of the two given sizes.

Parameters:

  • size1 (Tuple[int, int]) – The first size

  • size2 (Tuple[int, int]) – The second size

Returns:

The smaller size

Return type:

Tuple[int, int]

oakutils.tools.display.order_resolutions(resolutions: Iterable[tuple[int, int]], *, reverse: bool | None = None) → list[tuple[int, int]]

Use to order the given resolutions from smallest to largest.

Parameters:

  • resolutions (Iterable[Tuple[int, int]]) – The resolutions to order

  • reverse (Optional[bool], optional) – Whether or not to reverse the order, by default False If reverse is True, then it will order from largest to smallest.

Returns:

The ordered resolutions

Return type:

list[Tuple[int, int]]

oakutils.tools.parsing module

Module for converting between depthai types, tuples, and strings.

Functions

get_color_sensor_resolution_from_str

Use to convert a str to a SensorResolution.

get_tuple_from_color_sensor_resolution

Use to convert a SensorResolution to a tuple.

get_color_sensor_resolution_from_tuple

Use to convert a tuple to a SensorResolution.

get_color_sensor_info_from_str

Use to parse a resolution string into a tuple of (width, height, SensorResolution).

get_mono_sensor_resolution_from_str

Coverts a str to a SensorResolution.

get_mono_sensor_resolution_from_tuple

Use to convert a tuple to a SensorResolution.

get_tuple_from_mono_sensor_resolution

Use to convert a SensorResolution to a tuple.

get_mono_sensor_info_from_str

Use to parse a resolution string into a tuple of (width, height, SensorResolution).

get_median_filter_from_str

Use to convert a str to a MedianFilter.

oakutils.tools.parsing.get_color_sensor_info_from_str(resolution: str) → tuple[int, int, SensorResolution]

Use to parse a resolution string into a tuple of (width, height, SensorResolution).

Parameters:

resolution (str) – The resolution to parse

Returns:

The tuple of (width, height, SensorResolution)

Return type:

Tuple[int, int, dai.ColorCameraProperties.SensorResolution]

oakutils.tools.parsing.get_color_sensor_resolution_from_str(resolution: str) → SensorResolution

Use to convert a str to a SensorResolution.

Parameters:

resolution (str) – The resolution to convert

Returns:

The SensorResolution

Return type:

dai.ColorCameraProperties.SensorResolution

Raises:

ValueError – If the resolution is invalid

oakutils.tools.parsing.get_color_sensor_resolution_from_tuple(resolution: tuple[int, int]) → SensorResolution

Use to convert a tuple to a SensorResolution.

Parameters:

resolution (tuple[int, int]) – The resolution to convert

Returns:

The SensorResolution

Return type:

dai.ColorCameraProperties.SensorResolution

Raises:

ValueError – If the resolution is invalid

oakutils.tools.parsing.get_median_filter_from_str(filter_size: int | None) → MedianFilter

Use to convert a str to a MedianFilter.

Parameters:

filter_size (Optional[int]) – The filter size to convert

Returns:

The MedianFilter

Return type:

dai.StereoDepthProperties.MedianFilter

Raises:

ValueError – If the filter size is invalid

oakutils.tools.parsing.get_mono_sensor_info_from_str(resolution: str) → tuple[int, int, SensorResolution]

Use to parse a resolution string into a tuple of (width, height, SensorResolution).

Parameters:

resolution (str) – The resolution to parse

Returns:

The tuple of (width, height, SensorResolution)

Return type:

Tuple[int, int, dai.MonoCameraProperties.SensorResolution]

oakutils.tools.parsing.get_mono_sensor_resolution_from_str(resolution: str) → SensorResolution

Coverts a str to a SensorResolution.

Parameters:

resolution (str) – The resolution to convert

Returns:

The SensorResolution

Return type:

dai.MonoCameraProperties.SensorResolution

Raises:

ValueError – If the resolution is invalid

oakutils.tools.parsing.get_mono_sensor_resolution_from_tuple(resolution: tuple[int, int]) → SensorResolution

Use to convert a tuple to a SensorResolution.

Parameters:

resolution (tuple[int, int]) – The resolution to convert

Returns:

The SensorResolution

Return type:

dai.MonoCameraProperties.SensorResolution

Raises:

ValueError – If the resolution is invalid

oakutils.tools.parsing.get_tuple_from_color_sensor_resolution(resolution: SensorResolution) → tuple[int, int]

Use to convert a SensorResolution to a tuple.

Parameters:

resolution (dai.ColorCameraProperties.SensorResolution) – The resolution to convert

Returns:

The tuple of the resolution

Return type:

Tuple[int, int]

Raises:

ValueError – If the resolution is invalid

oakutils.tools.parsing.get_tuple_from_mono_sensor_resolution(resolution: SensorResolution) → tuple[int, int]

Use to convert a SensorResolution to a tuple.

Parameters:

resolution (dai.MonoCameraProperties.SensorResolution) – The resolution to convert

Returns:

The tuple of the resolution

Return type:

Tuple[int, int]

Raises:

ValueError – If the resolution is invalid

oakutils.tools.pixel module

Module for pixel coordinate tools.

Functions

homogenous_pixel_coord

Pixel in homogenous coordinate.

oakutils.tools.pixel.homogenous_pixel_coord(width: int, height: int) → ndarray

Pixel in homogenous coordinate.

Parameters:

  • width (int) – Location of pixel in image width.

  • height (int) – Location of pixel in image height.

Returns:

Pixel coordinate in homogenous coordinate. Pixel coordinate: [3, width * height]

Return type:

np.ndarray

References

https://github.com/luxonis/depthai-experiments/blob/master/gen2-pointcloud/rgbd-pointcloud/utils.py

oakutils.tools.spatial module

Module for tools related to calculating spatials locations.

Classes

HostSpatialsCalc

Class for calculating spatial coordinates on the host.

class oakutils.tools.spatial.HostSpatialsCalc(data: CalibrationData, delta: int = 5, thresh_low: int = 200, thresh_high: int = 30000)

Bases: object

Class for calculating spatial coordinates on the host.

References

https://github.com/luxonis/depthai-experiments/blob/master/gen2-calc-spatials-on-host/calc.py

calc_spatials(depth_data: dai.ImgFrame, roi: tuple[int, int] | tuple[int, int, int, int], averaging_method: Callable = <function mean>) → tuple[float, float, float, tuple[int, int]]

Use to compute spatial coordinates of the ROI.

Parameters:

  • depth_data (depthai.ImgFrame) – The depth frame and data.

  • roi (tuple of int) – The ROI to calculate the spatial coordinates for.

  • averaging_method (callable, optional) – The averaging method to use for calculating the depth. The default is np.mean.

Returns:

  • float – The x coordinate of the ROI centroid.

  • float – The y coordinate of the ROI centroid.

  • float – The z coordinate of the ROI centroid.

  • Tuple[int, int] – The centroid of the ROI.

Raises:

RuntimeError – If the initialization failed. Should never occur.

property delta: int

The delta parameter for the spatial coordinates calculation.

property thresh_high: int

The upper threshold for the spatial coordinates calculation.

property thresh_low: int

The lower threshold for the spatial coordinates calculation.

oakutils.tools.transform module

Helper functions for creating transformation matrices.

This module contains helper functions for creating transformation matrices. These matrices can be used to transform points from one coordinate system to another.

Functions

create_rotation

Use to create a rotation matrix from a rotation vector.

create_translation

Use to create a translation vector.

create_transform

Use to get transformation matrix from a rotation vector and translation vector.

oakutils.tools.transform.create_rotation(theta_x: float, theta_y: float, theta_z: float) → ndarray

Use to create a rotation matrix from a rotation vector.

Parameters:

  • theta_x (float) – The rotation angle around the x axis

  • theta_y (float) – The rotation angle around the y axis

  • theta_z (float) – The rotation angle around the z axis

Returns:

The rotation matrix

Return type:

np.ndarray

oakutils.tools.transform.create_transform(theta_x: float, theta_y: float, theta_z: float, delta_x: float, delta_y: float, delta_z: float) → ndarray

Use to get transformation matrix from a rotation vector and translation vector.

Parameters:

  • theta_x (float) – The rotation angle around the x axis

  • theta_y (float) – The rotation angle around the y axis

  • theta_z (float) – The rotation angle around the z axis

  • delta_x (float) – The translation along the x axis

  • delta_y (float) – The translation along the y axis

  • delta_z (float) – The translation along the z axis

Returns:

The transformation matrix

Return type:

np.ndarray

oakutils.tools.transform.create_translation(delta_x: float, delta_y: float, delta_z: float) → ndarray

Use to create a translation vector.

Parameters:

  • delta_x (float) – The translation along the x axis

  • delta_y (float) – The translation along the y axis

  • delta_z (float) – The translation along the z axis

Returns:

The translation vector

Return type:

np.ndarray

Module contents

Tools for working with the OAK devices.

Submodules

depth

Tools for working with depth images.

display

Tools for displaying frames.

parsing

Tools for switching between different formats.

pixel

Tools for working with pixels.

spatial

Tools for working with spatial coordinates.

transform

Tools for working with transforms.

Classes

HostSpatialsCalc

Class for calculating spatial coordinates on the host.

Functions

align_depth_to_rgb

Use to align a depth image to an RGB image.

get_color_sensor_resolution_from_tuple

Use to get the color sensor resolution from a tuple.

get_mono_sensor_resolution_from_tuple

Use to get the mono sensor resolution from a tuple.

get_tuple_from_color_sensor_resolution

Use to get a tuple from a color sensor resolution.

get_tuple_from_mono_sensor_resolution

Use to get a tuple from a mono sensor resolution.

class oakutils.tools.HostSpatialsCalc(data: CalibrationData, delta: int = 5, thresh_low: int = 200, thresh_high: int = 30000)

Bases: object

Class for calculating spatial coordinates on the host.

References

https://github.com/luxonis/depthai-experiments/blob/master/gen2-calc-spatials-on-host/calc.py

calc_spatials(depth_data: dai.ImgFrame, roi: tuple[int, int] | tuple[int, int, int, int], averaging_method: Callable = <function mean>) → tuple[float, float, float, tuple[int, int]]

Use to compute spatial coordinates of the ROI.

Parameters:

  • depth_data (depthai.ImgFrame) – The depth frame and data.

  • roi (tuple of int) – The ROI to calculate the spatial coordinates for.

  • averaging_method (callable, optional) – The averaging method to use for calculating the depth. The default is np.mean.

Returns:

  • float – The x coordinate of the ROI centroid.

  • float – The y coordinate of the ROI centroid.

  • float – The z coordinate of the ROI centroid.

  • Tuple[int, int] – The centroid of the ROI.

Raises:

RuntimeError – If the initialization failed. Should never occur.

property delta: int

The delta parameter for the spatial coordinates calculation.

property thresh_high: int

The upper threshold for the spatial coordinates calculation.

property thresh_low: int

The lower threshold for the spatial coordinates calculation.

oakutils.tools.align_depth_to_rgb(depth_image: ndarray, pixel_coords: ndarray, inverse_depth_intrinsic: ndarray, rgb_intrinsic: ndarray, depth_to_rgb_extrinsic: ndarray, rgb_width: int, rgb_height: int, depth_scale: float = 1000.0) → ndarray

Use to align a depth image to an RGB image.

Parameters:

  • depth_image (np.ndarray) – The depth image to align.

  • pixel_coords (np.ndarray) – The pixel coordinates of the depth image.

  • inverse_depth_intrinsic (np.ndarray) – The inverse depth intrinsic matrix.

  • rgb_intrinsic (np.ndarray) – The RGB intrinsic matrix.

  • depth_to_rgb_extrinsic (np.ndarray) – The depth to RGB extrinsic matrix.

  • rgb_width (int) – The width of the RGB image.

  • rgb_height (int) – The height of the RGB image.

  • depth_scale (float, optional) – Depth scaling factor. Defaults to 1000.0 to convert from millimeters to meters.

Returns:

The aligned depth image.

Return type:

np.ndarray

References

https://github.com/luxonis/depthai-experiments/blob/master/gen2-pointcloud/rgbd-pointcloud/utils.py

oakutils.tools.get_color_sensor_resolution_from_tuple(resolution: tuple[int, int]) → SensorResolution

Use to convert a tuple to a SensorResolution.

Parameters:

resolution (tuple[int, int]) – The resolution to convert

Returns:

The SensorResolution

Return type:

dai.ColorCameraProperties.SensorResolution

Raises:

ValueError – If the resolution is invalid

oakutils.tools.get_mono_sensor_resolution_from_tuple(resolution: tuple[int, int]) → SensorResolution

Use to convert a tuple to a SensorResolution.

Parameters:

resolution (tuple[int, int]) – The resolution to convert

Returns:

The SensorResolution

Return type:

dai.MonoCameraProperties.SensorResolution

Raises:

ValueError – If the resolution is invalid

oakutils.tools.get_tuple_from_color_sensor_resolution(resolution: SensorResolution) → tuple[int, int]

Use to convert a SensorResolution to a tuple.

Parameters:

resolution (dai.ColorCameraProperties.SensorResolution) – The resolution to convert

Returns:

The tuple of the resolution

Return type:

Tuple[int, int]

Raises:

ValueError – If the resolution is invalid

oakutils.tools.get_tuple_from_mono_sensor_resolution(resolution: SensorResolution) → tuple[int, int]

Use to convert a SensorResolution to a tuple.

Parameters:

resolution (dai.MonoCameraProperties.SensorResolution) – The resolution to convert

Returns:

The tuple of the resolution

Return type:

Tuple[int, int]

Raises:

ValueError – If the resolution is invalid