oakutils package

Subpackages

Module contents

Package for Python utilities for the OpenCV AI Kit (OAK-D) and related hardware.

This package contains Python utilities for the OpenCV AI Kit (OAK-D) and related hardware. It is intended to be used with the Luxonis DepthAI API or SDK. Provides easy-to-use classes for working with the OAK-D and doing common tasks. Also provides easy methods for working with OpenCV and Open3D.

Submodules

aruco: Contains utilities for working with ArUco markers.
benchmark: Contains utilities for benchmarking characteristics of OAK devices.
blobs: Contains utilities for working with blobs.
calibration: Contains utilities for working with calibration.
core: Contains core utilities for working with the OAK-D.
filters: Contains utilities for working with filters.
nodes: Contains utilities for creating nodes.
optimizer: Contains utilities for optimizing pipelines.
point_clouds: Contains utilities for working with point clouds.
tools: Contains general tools and utilities.
vpu: Contains utilities for using the onboard VPU as a standalone processor.

Classes

ApiCamera: A lightweight class for creating custom pipelines using callbacks.
LegacyCamera: A class for using the color, mono, and imu sensors on the OAK-D.
Webcam: A class for reading frames from an OAK using the same interface as cv2.VideoCapture.
VPU: A class for using the onboard VPU as a standalone processor.

Functions

set_log_level: Set the log level for the oakutils package.
create_device: Create a DepthAI device object from a pipeline.

class oakutils.ApiCamera(color_size: tuple[int, int] = (1920, 1080), mono_size: tuple[int, int] = (640, 400), device_id: str | None = None, *, primary_mono_left: bool | None = None)

Bases: object

A lightweight class for creating custom pipelines using callbacks.

add_callback(name: str | Iterable[str], callback: Callable) → None

Use to add a callback to be run on the output queue with the given name.

Parameters:

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

add_device_call(call: Callable[[dai.DeviceBase], None]) → None

Use to add a device call to be run after the device is created.

Parameters:: call (Callable[[dai.Device], None]) – The call to add.
Raises:: RuntimeError – If the camera has already been started.

add_display(name: str) → None

Use to add a display callback for the given stream name.

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

property calibration: CalibrationData | ColorCalibrationData: Use to get the calibration data.

property displays: DisplayManager: Use to get the display manager.

property pcv: PCVisualizer | None

Use to get the point cloud visualizer.

If open3d is not installed, this will always return None.

Returns:: The point cloud visualizer.
Return type:: PointCloudVisualizer | None

property pipeline: dai.Pipeline

Use to get the pipeline. This is useful for adding custom nodes to the pipeline.

Raises:: RuntimeError – If the pipeline is accessed once the camera has been started.

start(*, blocking: bool | None = None) → None: Use to start the camera. To be done after all api calls are made.

stop() → None: Use to stop the camera.

class oakutils.VPU(device_id: str | None = None)

Bases: object

Class for using the onboard VPU as a standalone processor.

reconfigure(blob_path: str | Path, input_names: list[str] | None = None, model_data: YolomodelData | MobilenetData | None = None) → None

Use to reconfigure the VPU with a single new blob file.

Parameters:

blob_path (str | Path) – The path to the blob file.
input_names (list[str], optional) – The names of the input layers. Defaults to None.
model_data (YolomodelData | MobilenetData, optional) – The model data. Defaults to None. Can be used to set the YoloModelData or MobilenetData. If None, then a generic neural network will be created.

Reconfigure the VPU with multiple blob files.

Parameters:

blob_paths (Sequence[str | Path]) – The paths to the blob files.
input_names (Sequence[list[str] | None]) – The names of the input layers. Defaults to None. Should be filled in if a model has multiple inputs.
modeldata (Sequence[YolomodelData | MobilenetData | None]) – The model data. Defaults to None. Should be filled in if the model is a YOLO or Mobilenet model. If None, then a generic neural network will be created.

Use to run an inference on the VPU.

If the VPU was configured with multiple networks, then data must be a list of data. If the VPU was configured with a single network, then data can be a single np.ndarray or a list of np.ndarray if the network has multiple inputs. The return type will change based on whether the VPU was configured with multiple networks. If configured with a single network, then the return will be a single np.ndarray or dai.ImgDetections. If configured with multiple networks, then the return will be a list of np.ndarray or dai.ImgDetections.

Parameters:

data (np.ndarray | list[np.ndarray]) – The data to run an inference on.
safe (bool, optional) – If True, will evaluate the data before sending to the VPU. If False, will send data directly to the VPU. By default None, which will use safe mode.

Returns:

The result of the inference.

Return type:

dai.ADatatype | list[dai.ADatatype] | list[dai.ADatatype | list[dai.ADatatype]]

Raises:

RuntimeError – If the VPU thread is not set or alive. Will occur if not configured. If the VPU result is None.

stop() → None: Use to stop the VPU.

class oakutils.Webcam(resolution: tuple[int, int] = (1920, 1080), fps: int = 30, device_id: str | None = None)

Bases: object

A class for reading frames from an OAK using the same interface as cv2.VideoCapture.

property calibration: ColorCalibrationData

Returns the calibration info for the camera.

Returns:: The calibration info for the camera
Return type:: ColorCalibrationData

read() → tuple[bool, np.ndarray | None]

Read a frame from the camera.

Returns:: A tuple containing a boolean indicating if the frame was read successfully and the frame itself.
Return type:: tuple[bool, np.ndarray]

stop() → None: Stop the camera.

oakutils.create_device(pipeline: Pipeline, device_id: str | None = None, max_usb_speed: UsbSpeed | None = None) → DeviceBase

Create a DepthAI device object from a pipeline.

Parameters:

pipeline (dai.Pipeline) – The pipeline to use
device_id (str, optional) – The id of the device to use, by default None This can be a MXID, IP address, or USB port name. Examples: “14442C108144F1D000”, “192.168.1.44”, “3.3.3”
max_usb_speed (dai.UsbSpeed, optional) – The maximum USB speed to use, by default None Options are available in dai.UsbSpeed

Returns:

The DepthAI device object

Return type:

dai.Device

oakutils.set_log_level(level: str) → None

Set the log level for the oakutils package.

Parameters:: level (str) – The log level to set. One of “DEBUG”, “INFO”, “WARNING”, “ERROR”, “CRITICAL”.
Raises:: ValueError – If the level is not one of the allowed values.