devices

Capture devices represent the physical hardware (or driver/pipeline) that produces frame data. A device owns the underlying resources (USB handles, DepthAI pipelines, etc.) and can be powered on or off independently of any recording. Cameras, by contrast, are lightweight per-recording wrappers typically created from a capture device.

For example, the OAK-D capture device manages the DepthAI pipeline and hardware connection, while OakDRGBCamera and OakDDepthCamera are session-scoped readers created for each recording. The device may stay powered between recordings (e.g. for preview), but cameras are created fresh each time.

omgrab.devices.capture_device

Capture device abstraction.

A capture device represents the physical hardware (or driver/pipeline) that owns the underlying resources required to produce one or more camera streams. Devices can be powered on or off independently of any recording session. Cameras, by contrast, are lightweight per-recording wrappers typically created from a capture device, and are started/stopped each time the user begins and ends a recording.

PreviewUnavailableError

Bases: RuntimeError

Raised when preview is not available on a capture device.

This occurs when a device was not configured with a preview config, or does not support preview at all.

CaptureDevice

Bases: Protocol

A physical capture device that can be opened/closed and queried for health.

label property

Human-readable label for this device (e.g. 'oakd', 'left_wrist').

connected property

Whether the underlying device appears connected/healthy.

ready property

Whether the underlying device is ready to capture frames.

device_type property

Return a device type identifier, if available.

This is an opaque string whose meaning is defined by the concrete device implementation. For example, OAK-D devices report variants like 'oakd_pro_wide'. Returns None if the device has not been started, does not support type detection, or detection failed.

wait_until_ready(timeout=None)

Wait until the underlying device is ready to capture frames.

__enter__()

Acquire underlying resources needed for capture.

__exit__(exc_type, exc_value, traceback)

Release underlying resources needed for capture.

preview()

Start a lightweight preview pipeline.

Returns a context manager that runs a preview-only pipeline while active. The device must not be in recording mode (i.e. __enter__ must not be active). Implementations that do not support preview should raise RuntimeError.

omgrab.devices.oakd_capture_device

OAK-D capture device implementation.

The capture device represents the physical OAK-D hardware and owns the DepthAI pipeline lifecycle. It can be opened and closed independently of the cameras that read from its frame queues. Cameras are lightweight wrappers that represent a particular recording session; the device may outlive many camera instances across multiple recordings.

PipelineConfig(warmup_frames=10, startup_grace_s=3.0, shutdown_timeout_s=2.0) dataclass

Configuration for the OAK-D pipeline runner.

Attributes:

Name	Type	Description
warmup_frames	int	Number of initial frames to discard before marking the device as ready.
startup_grace_s	float	Grace period after pipeline start during which stale-frame detection is relaxed.
shutdown_timeout_s	float	Timeout for joining the capture thread during device shutdown.

OakDCaptureDevice(rgb_config, depth_config, max_queue_size=200, imu_rate_hz=0, preview_config=None, pipeline_config=_DEFAULT_PIPELINE_CONFIG)

Bases: CaptureDevice

OakD device used to populate two camera queues from one source.

Initialize the OakD device.

Parameters:

Name	Type	Description	Default
rgb_config	CameraConfig	Configuration for the RGB camera.	required
depth_config	CameraConfig	Configuration for the depth camera.	required
max_queue_size	int	Maximum queue size for frame/data buffers.	200
imu_rate_hz	int	IMU sampling rate in Hz. 0 to disable IMU.	0
preview_config	Optional[CameraConfig]	Optional configuration for the preview camera. If provided, enables the preview() context manager and get_preview_camera(). Uses a lightweight RGB-only pipeline.	None
pipeline_config	PipelineConfig	Configuration for the pipeline runner.	_DEFAULT_PIPELINE_CONFIG

label property

Human-readable label for this device.

connected property

Check if the OakD camera is connected.

ready property

Check if the OakD camera is ready.

rgb_queue property

Get the rgb queue.

depth_queue property

Get the depth queue.

imu_queue property

Get the IMU data queue, or None if IMU is disabled.

imu_enabled property

Whether IMU data collection is enabled.

device_type property

Return the detected OAK-D device type as a string.

The device type is read from EEPROM during pipeline startup. Returns None if the device has not been started or if type detection failed.

Returns:

Type	Description
Optional[str]	One of the OakDDeviceType values (e.g. 'oakd_pro_wide'), or None.

wait_until_ready(timeout=None)

Wait until the OakD camera is ready to capture frames.

get_rgb_camera()

Get the RGB camera.

get_depth_camera()

Get the depth camera.

get_imu_source()

Get a data source for reading IMU data.

Returns:

Type	Description
QueueReaderSensor	QueueReaderSensor wrapping the IMU queue.

Raises:

Type	Description
RuntimeError	If IMU is not enabled.

get_preview_camera()

Get the preview RGB camera.

The returned camera reads from the preview queue and only produces frames while the preview() context manager is active.

Returns:

Type	Description
OakDRGBCamera	An OakDRGBCamera reading from the preview queue.

Raises:

Type	Description
RuntimeError	If preview_config was not provided at construction.

preview()

Context manager that runs a lightweight RGB-only preview pipeline.

The preview pipeline is mutually exclusive with the recording pipeline (__enter__). Starting preview while recording is active (or vice-versa) raises RuntimeError.

Yields:

Name	Type	Description
OakDCaptureDevice	OakDCaptureDevice	This device instance.

Raises:

Type	Description
PreviewUnavailableError	If preview_config was not provided.
RuntimeError	If the recording pipeline is already running.

__enter__()

Setup the oakd capture device.

__exit__(exc_type, exc_value, traceback)

Close the oakd capture device.

omgrab.devices.usb_capture_device

USB capture device.

USBCaptureDevice(config, usb_port_path, label, preview_config=None)

Bases: CaptureDevice

Capture device wrapping a single USB camera identified by USB port path.

Implements the CaptureDevice protocol. The camera is opened/closed per-recording by the capture thread (via the Camera context manager), not by this device's enter/exit.

Initialize the USB capture device.

Parameters:

Name	Type	Description	Default
config	CameraConfig	Camera configuration (fps, width, height).	required
usb_port_path	str	USB port path (e.g. '3-2') used to discover the /dev/videoN device via sysfs.	required
label	str	Human-readable label for logging (e.g. 'left_wrist').	required
preview_config	Optional[CameraConfig]	Optional camera configuration for preview mode. If not provided, preview() will raise PreviewUnavailableError.	None

label property

Human-readable label for this device.

connected property

Whether the USB camera is present and openable.

Resolves the USB port path to a /dev/videoN device via sysfs, then verifies the device node can actually be opened. A device may appear in sysfs even with a loose connection; the open check catches that.

ready property

USB cameras have no warmup; ready if connected.

device_type property

USB cameras do not have a device type.

wait_until_ready(timeout=None)

USB cameras are immediately ready.

get_camera()

Get the USB camera instance.

get_preview_camera()

Get the preview camera.

The returned camera reads from the preview queue and only produces frames while the preview() context manager is active.

Returns:

Type	Description
QueueReaderCamera[RGBFrame]	A QueueReaderCamera reading from the preview queue.

Raises:

Type	Description
PreviewUnavailableError	If preview_config was not provided.

__enter__()

No-op; the camera is opened by the capture thread.

__exit__(exc_type, exc_value, traceback)

No-op; the camera is closed by the capture thread.

preview()

Context manager that runs a preview capture loop.

Opens a separate USBCamera with the preview configuration and reads frames in a background thread, pushing them into a queue. The preview is mutually exclusive with recording.

Yields:

Name	Type	Description
USBCaptureDevice	USBCaptureDevice	This device instance.

Raises:

Type	Description
PreviewUnavailableError	If preview_config was not provided.
RuntimeError	If preview is already active.