Hardware Package API Reference

Mindtrace Hardware Module

A comprehensive hardware abstraction layer providing unified access to cameras, PLCs, sensors, and other industrial hardware components with lazy imports to prevent cross-contamination between different backends.

Key Features

• Lazy import system to avoid loading all backends at startup
• Unified interface for different hardware types
• Async-first design for optimal performance
• Thread-safe operations across all components
• Comprehensive error handling and logging
• Configuration management system
• Mock backends for testing and development

Hardware Components

• CameraManager: Unified camera management (Basler, OpenCV)
• PLCManager: Unified PLC management (Allen-Bradley, Siemens, Modbus)
• SensorManager: Sensor data acquisition and monitoring (MQTT, HTTP, Serial)
• SensorManagerService: Service wrapper for SensorManager with MCP endpoints
• ActuatorManager: Actuator control and positioning (Future)

Design Philosophy

This module uses lazy imports to prevent SWIG warnings from pycomm3 appearing in camera tests, and to avoid loading heavy SDKs unless they are actually needed. Each manager is only imported when accessed.

Usage

Import managers only when needed

from mindtrace.hardware import CameraManager, PLCManager, SensorManager from mindtrace.hardware.services.sensors import SensorManagerService

Camera operations

async with CameraManager() as camera_manager: cameras = camera_manager.discover() camera = await camera_manager.open(cameras[0]) image = await camera.capture()

PLC operations

async with PLCManager() as plc_manager: await plc_manager.register_plc("PLC1", "AllenBradley", "192.168.1.100") await plc_manager.connect_plc("PLC1") values = await plc_manager.read_tag("PLC1", ["Tag1", "Tag2"])

Sensor operations (direct manager)

async with SensorManager() as sensor_manager: await sensor_manager.connect_sensor("temp1", "mqtt", config, "sensors/temp") data = await sensor_manager.read_sensor_data("temp1")

Sensor operations (service with MCP endpoints)

service = SensorManagerService() response = await service.connect_sensor(connection_request)

Configuration

All hardware components use the unified configuration system: - Environment variables with MINDTRACE_HW_ prefix - JSON configuration files - Programmatic configuration via dataclasses - Hierarchical configuration inheritance

Thread Safety

All hardware managers are thread-safe and can be used concurrently from multiple threads without interference.

cameras

Camera module for mindtrace hardware.

Provides unified camera management across different camera manufacturers with graceful SDK handling and comprehensive error management.

CameraBackend

CameraBackend(
    camera_name: Optional[str] = None,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
)

Bases: MindtraceABC

Abstract base class for all camera implementations.

This class defines the async interface that all camera backends must implement to ensure consistent behavior across different camera types and manufacturers. Uses async-first design consistent with PLC backends.

Attributes:

Name	Type	Description
camera_name		Unique identifier for the camera
camera_config_file		Path to camera configuration file
img_quality_enhancement		Whether image quality enhancement is enabled
retrieve_retry_count		Number of retries for image retrieval
camera	Optional[Any]	The initialized camera object (implementation-specific)
device_manager	Optional[Any]	Device manager object (implementation-specific)
initialized	bool	Camera initialization status

Implementation Guide

• Offload blocking SDK calls from async methods: Use asyncio.to_thread for simple cases or loop.run_in_executor with a per-instance single-thread executor when the SDK requires thread affinity.
• Thread affinity: Many vendor SDKs are safest when all calls originate from one OS thread. Prefer a dedicated single-thread executor created during initialize() and shut down in close() to serialize SDK access without blocking the event loop.
• Timeouts and cancellation: Prefer SDK-native timeouts where available. Otherwise, wrap awaited futures with asyncio.wait_for to bound runtime. Note that cancelling an await does not stop the underlying thread function; design idempotent/short tasks when possible.
• Event loop hygiene: Never call blocking functions (e.g., long SDK calls, time.sleep) directly in async methods. Replace sleeps with await asyncio.sleep or run blocking work in the executor.
• Sync helpers: Lightweight getters/setters that do not touch hardware may remain synchronous. If a "getter" calls into the SDK, route it through the executor to avoid blocking.
• Errors: Map SDK-specific exceptions to the domain exceptions in mindtrace.hardware.core.exceptions with clear, contextual messages.
• Cleanup: Ensure resources (device handles, executors, buffers) are released in close(). __aenter__/__aexit__ already call setup_camera/close for async contexts.

Initialize base camera with configuration integration.

Parameters:

Name	Type	Description	Default
camera_name	Optional[str]	Unique identifier for the camera (auto-generated if None)	None
camera_config	Optional[str]	Path to camera configuration file	None
img_quality_enhancement	Optional[bool]	Whether to apply image quality enhancement (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of retries for image retrieval (uses config default if None)	None

setup_camera async

setup_camera()

Common setup method for camera initialization.

This method provides a standardized setup pattern that can be used by all camera backends. It calls the abstract initialize() method and handles common initialization patterns.

Raises:

Type	Description
CameraNotFoundError	If camera cannot be found
CameraInitializationError	If camera initialization fails
CameraConnectionError	If camera connection fails

set_bandwidth_limit async

set_bandwidth_limit(limit_mbps: Optional[float])

Set GigE camera bandwidth limit in Mbps.

get_bandwidth_limit async

get_bandwidth_limit() -> float

Get current bandwidth limit.

set_packet_size async

set_packet_size(size: int)

Set GigE packet size for network optimization.

get_packet_size async

get_packet_size() -> int

Get current packet size.

set_inter_packet_delay async

set_inter_packet_delay(delay_ticks: int)

Set inter-packet delay for network traffic control.

get_inter_packet_delay async

get_inter_packet_delay() -> int

Get current inter-packet delay.

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Note

This is a runtime-configurable parameter that can be changed without reinitializing the camera.

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

backends

Camera backends for different manufacturers and types.

This module provides camera backend implementations for the Mindtrace hardware system. Each backend implements the CameraBackend interface for consistent camera operations.

Available Backends

• CameraBackend: Abstract base class defining the camera interface
• BaslerCameraBackend: Industrial cameras from Basler (when available)
• OpenCVCameraBackend: USB cameras and webcams via OpenCV (when available)
• GenICamCameraBackend: GenICam-compliant cameras via Harvesters (when available)

Usage: from mindtrace.hardware.cameras.backends import CameraBackend from mindtrace.hardware.cameras.backends.basler import BaslerCameraBackend from mindtrace.hardware.cameras.backends.opencv import OpenCVCameraBackend from mindtrace.hardware.cameras.backends.genicam import GenICamCameraBackend

Configuration

Camera backends integrate with the Mindtrace configuration system to provide consistent default values and settings across all camera types.

CameraBackend

CameraBackend(
    camera_name: Optional[str] = None,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
)

Bases: MindtraceABC

Abstract base class for all camera implementations.

This class defines the async interface that all camera backends must implement to ensure consistent behavior across different camera types and manufacturers. Uses async-first design consistent with PLC backends.

Attributes:

Name	Type	Description
camera_name		Unique identifier for the camera
camera_config_file		Path to camera configuration file
img_quality_enhancement		Whether image quality enhancement is enabled
retrieve_retry_count		Number of retries for image retrieval
camera	Optional[Any]	The initialized camera object (implementation-specific)
device_manager	Optional[Any]	Device manager object (implementation-specific)
initialized	bool	Camera initialization status

Implementation Guide

• Offload blocking SDK calls from async methods: Use asyncio.to_thread for simple cases or loop.run_in_executor with a per-instance single-thread executor when the SDK requires thread affinity.
• Thread affinity: Many vendor SDKs are safest when all calls originate from one OS thread. Prefer a dedicated single-thread executor created during initialize() and shut down in close() to serialize SDK access without blocking the event loop.
• Timeouts and cancellation: Prefer SDK-native timeouts where available. Otherwise, wrap awaited futures with asyncio.wait_for to bound runtime. Note that cancelling an await does not stop the underlying thread function; design idempotent/short tasks when possible.
• Event loop hygiene: Never call blocking functions (e.g., long SDK calls, time.sleep) directly in async methods. Replace sleeps with await asyncio.sleep or run blocking work in the executor.
• Sync helpers: Lightweight getters/setters that do not touch hardware may remain synchronous. If a "getter" calls into the SDK, route it through the executor to avoid blocking.
• Errors: Map SDK-specific exceptions to the domain exceptions in mindtrace.hardware.core.exceptions with clear, contextual messages.
• Cleanup: Ensure resources (device handles, executors, buffers) are released in close(). __aenter__/__aexit__ already call setup_camera/close for async contexts.

Initialize base camera with configuration integration.

Parameters:

Name	Type	Description	Default
camera_name	Optional[str]	Unique identifier for the camera (auto-generated if None)	None
camera_config	Optional[str]	Path to camera configuration file	None
img_quality_enhancement	Optional[bool]	Whether to apply image quality enhancement (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of retries for image retrieval (uses config default if None)	None

setup_camera async

setup_camera()

Common setup method for camera initialization.

This method provides a standardized setup pattern that can be used by all camera backends. It calls the abstract initialize() method and handles common initialization patterns.

Raises:

Type	Description
CameraNotFoundError	If camera cannot be found
CameraInitializationError	If camera initialization fails
CameraConnectionError	If camera connection fails

set_bandwidth_limit async

set_bandwidth_limit(limit_mbps: Optional[float])

Set GigE camera bandwidth limit in Mbps.

get_bandwidth_limit async

get_bandwidth_limit() -> float

Get current bandwidth limit.

set_packet_size async

set_packet_size(size: int)

Set GigE packet size for network optimization.

get_packet_size async

get_packet_size() -> int

Get current packet size.

set_inter_packet_delay async

set_inter_packet_delay(delay_ticks: int)

Set inter-packet delay for network traffic control.

get_inter_packet_delay async

get_inter_packet_delay() -> int

Get current inter-packet delay.

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Note

This is a runtime-configurable parameter that can be changed without reinitializing the camera.

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

basler

Basler Camera Backend

Provides support for Basler cameras via pypylon SDK with mock implementation for testing.

Components

• BaslerCameraBackend: Real Basler camera implementation (requires pypylon SDK)
• MockBaslerCameraBackend: Mock implementation for testing and development

Requirements

• Real cameras: pypylon SDK (Pylon SDK for Python)
• Mock cameras: No additional dependencies

Installation

1. Install Pylon SDK from Basler
2. pip install pypylon
3. Configure camera permissions (Linux may require udev rules)

Usage

from mindtrace.hardware.cameras.backends.basler import BaslerCameraBackend, MockBaslerCameraBackend

Real camera

if BASLER_AVAILABLE: camera = BaslerCameraBackend("camera_name") success, cam_obj, remote_obj = await camera.initialize() # Initialize first if success: image = await camera.capture() await camera.close()

Mock camera (always available)

mock_camera = MockBaslerCameraBackend("mock_cam_0") success, cam_obj, remote_obj = await mock_camera.initialize() # Initialize first if success: image = await mock_camera.capture() await mock_camera.close()

BaslerCameraBackend

BaslerCameraBackend(
    camera_name: str,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
    multicast_enabled: Optional[bool] = None,
    target_ips: Optional[List[str]] = None,
    multicast_group: Optional[str] = None,
    multicast_port: Optional[int] = None,
    **backend_kwargs
)

Bases: CameraBackend

Basler Camera Backend Implementation

This class provides a comprehensive implementation for Basler cameras using the pypylon SDK. It supports advanced camera features including trigger modes, exposure control, ROI settings, and image quality enhancement.

Features

• Full Basler camera support via pypylon SDK
• Hardware trigger and continuous capture modes
• ROI (Region of Interest) control
• Automatic exposure and gain control
• Image quality enhancement with CLAHE
• Configuration import/export functionality
• Robust error handling and connection management

Requirements

• pypylon SDK (Pylon SDK for Python)
• OpenCV for image processing
• Basler Pylon SDK installed on system

Installation

1. Install Basler Pylon SDK from manufacturer
2. pip install pypylon
3. Configure camera permissions (Linux may require udev rules)

Usage::

from mindtrace.hardware.cameras.backends.basler import BaslerCameraBackend

# Get available cameras
cameras = BaslerCameraBackend.get_available_cameras()

# Initialize camera
camera = BaslerCameraBackend("camera_name", img_quality_enhancement=True)
success, cam_obj, remote_obj = await camera.initialize()  # Initialize first

if success:
    # Configure and capture
    await camera.set_exposure(20000)
    await camera.set_triggermode("continuous")
    image = await camera.capture()
    await camera.close()

Configuration

All parameters are configurable via the hardware configuration system: - MINDTRACE_CAMERA_EXPOSURE_TIME: Default exposure time in microseconds - MINDTRACE_CAMERA_TRIGGER_MODE: Default trigger mode ("continuous" or "trigger") - MINDTRACE_CAMERA_IMAGE_QUALITY_ENHANCEMENT: Enable CLAHE enhancement - MINDTRACE_CAMERA_RETRIEVE_RETRY_COUNT: Number of capture retry attempts - MINDTRACE_CAMERA_BUFFER_COUNT: Number of frame buffers for streaming - MINDTRACE_CAMERA_TIMEOUT_MS: Capture timeout in milliseconds

Supported Camera Models

• All Basler USB3 cameras (acA, daA series)
• All Basler GigE cameras (acA, daA series)
• Both monochrome and color variants
• Various resolutions and frame rates

Error Handling

The class uses a comprehensive exception hierarchy for precise error reporting: - SDKNotAvailableError: pypylon SDK not installed - CameraNotFoundError: Camera not detected or accessible - CameraInitializationError: Failed to initialize camera - CameraConfigurationError: Invalid configuration parameters - CameraConnectionError: Connection issues - CameraCaptureError: Image acquisition failures - CameraTimeoutError: Operation timeout - HardwareOperationError: General hardware operation failures

Attributes:

Name	Type	Description
initialized	bool	Whether camera was successfully initialized
camera	Optional[Any]	Underlying pypylon camera object
triggermode		Current trigger mode ("continuous" or "trigger")
img_quality_enhancement		Current image enhancement setting
timeout_ms		Capture timeout in milliseconds
buffer_count		Number of frame buffers
converter		Image format converter for pypylon
retrieve_retry_count		Number of capture retry attempts
default_pixel_format		Default pixel format for image conversion
camera_config_path		Path to camera configuration file
grabbing_mode		Pylon grabbing strategy

Initialize Basler camera with configurable parameters.

Parameters:

Name	Type	Description	Default
camera_name	str	Camera identifier (serial number, IP, or user-defined name)	required
camera_config	Optional[str]	Path to Pylon Feature Stream (.pfs) file (optional)	None
img_quality_enhancement	Optional[bool]	Enable CLAHE image enhancement (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of capture retry attempts (uses config default if None)	None
multicast_enabled	Optional[bool]	Enable multicast streaming mode (uses config default if None)	None
target_ips	Optional[List[str]]	List of target IP addresses for multicast discovery (optional)	None
multicast_group	Optional[str]	Multicast group IP address (uses config default if None)	None
multicast_port	Optional[int]	Multicast port number (uses config default if None)	None
**backend_kwargs		Backend-specific parameters: - pixel_format: Default pixel format (uses config default if None) - buffer_count: Number of frame buffers (uses config default if None) - timeout_ms: Capture timeout in milliseconds (uses config default if None)	{}

Raises:

Type	Description
SDKNotAvailableError	If pypylon SDK is not available
CameraConfigurationError	If configuration is invalid
CameraInitializationError	If camera initialization fails

get_available_cameras staticmethod

get_available_cameras(
    include_details: bool = False, target_ips: Optional[List[str]] = None
) -> Union[List[str], Dict[str, Dict[str, str]]]

Get available Basler cameras.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return detailed information	False
target_ips	Optional[List[str]]	Optional list of IP addresses to specifically discover	None

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	List of camera names (user-defined names preferred, serial numbers as fallback) or dict with details

Raises:

Type	Description
SDKNotAvailableError	If Basler SDK is not available
HardwareOperationError	If camera discovery fails

discover_async async classmethod

discover_async(
    include_details: bool = False, target_ips: Optional[List[str]] = None
) -> Union[List[str], Dict[str, Dict[str, str]]]

Async wrapper for get_available_cameras() - runs discovery in threadpool.

Use this instead of get_available_cameras() when calling from async context to avoid blocking the event loop during camera enumeration.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return a dict of details per camera.	False
target_ips	Optional[List[str]]	Optional list of specific IP addresses to target.	None

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	Union[List[str], Dict[str, Dict[str, str]]]: List of camera names or dict of details.

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the camera connection.

This searches for the camera by name, serial number, or IP and establishes a connection if found. Uses multicast-aware discovery if enabled.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success status, camera object, None)

Raises:

Type	Description
CameraNotFoundError	If no cameras found or specified camera not found
CameraInitializationError	If camera initialization fails
CameraConnectionError	If camera connection fails

configure_streaming async

configure_streaming()

Configure multicast streaming settings for the camera.

This method sets up multicast parameters when multicast mode is enabled. It configures the camera using the StreamGrabber interface for multicast streaming.

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If multicast configuration fails
HardwareOperationError	If streaming configuration fails

get_image_quality_enhancement

get_image_quality_enhancement() -> bool

Get image quality enhancement setting.

set_image_quality_enhancement

set_image_quality_enhancement(value: bool)

Set image quality enhancement setting.

get_exposure_range async

get_exposure_range() -> List[Union[int, float]]

Get the supported exposure time range in microseconds.

Returns:

Type	Description
List[Union[int, float]]	List with [min_exposure, max_exposure] in microseconds

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If exposure range retrieval fails

get_exposure async

get_exposure() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If exposure retrieval fails

set_exposure async

set_exposure(exposure: Union[int, float])

Set the camera exposure time in microseconds.

Parameters:

Name	Type	Description	Default
exposure_value		Exposure time in microseconds	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraConfigurationError	If exposure value is out of range
HardwareOperationError	If exposure setting fails

get_triggermode async

get_triggermode() -> str

Get current trigger mode.

Returns:

Type	Description
str	"continuous" or "trigger"

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If trigger mode retrieval fails

set_triggermode async

set_triggermode(triggermode: str = 'continuous')

Set the camera's trigger mode for image acquisition.

Parameters:

Name	Type	Description	Default
triggermode	str	Trigger mode ("continuous" or "trigger")	'continuous'

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraConfigurationError	If trigger mode is invalid
HardwareOperationError	If trigger mode setting fails

capture async

capture() -> np.ndarray

Capture a single image from the camera.

In continuous mode, returns the latest available frame. In trigger mode, executes a software trigger and waits for the image.

Returns:

Type	Description
ndarray	Image array in BGR format

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraCaptureError	If image capture fails
CameraTimeoutError	If capture times out

check_connection async

check_connection() -> bool

Check if camera is connected and operational.

Returns:

Type	Description
bool	True if connected and operational, False otherwise

import_config async

import_config(config_path: str)

Import camera configuration from common JSON format.

Parameters:

Name	Type	Description	Default
config_path	str	Path to configuration file	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If configuration import fails

export_config async

export_config(config_path: str)

Export current camera configuration to common JSON format.

Parameters:

Name	Type	Description	Default
config_path	str	Path where to save configuration file	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If configuration export fails

set_ROI async

set_ROI(x: int, y: int, width: int, height: int)

Set the Region of Interest (ROI) for image acquisition.

Parameters:

Name	Type	Description	Default
x	int	X offset from sensor top-left	required
y	int	Y offset from sensor top-left	required
width	int	ROI width	required
height	int	ROI height	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If ROI parameters are invalid
HardwareOperationError	If ROI setting fails

get_ROI async

get_ROI() -> Dict[str, int]

Get current Region of Interest settings.

Returns:

Type	Description
Dict[str, int]	Dictionary with x, y, width, height

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If ROI retrieval fails

reset_ROI async

reset_ROI()

Reset ROI to maximum sensor area.

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If ROI reset fails

set_gain async

set_gain(gain: float)

Set the camera's gain value.

Parameters:

Name	Type	Description	Default
gain	float	Gain value (camera-specific range)	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If gain value is out of range
HardwareOperationError	If gain setting fails

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If gain retrieval fails

get_gain_range async

get_gain_range() -> List[Union[int, float]]

Get camera gain range.

Returns:

Type	Description
List[Union[int, float]]	List containing [min_gain, max_gain]

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If gain range retrieval fails

set_bandwidth_limit async

set_bandwidth_limit(limit_mbps: Optional[float])

Set GigE camera bandwidth limit in Mbps.

get_bandwidth_limit async

get_bandwidth_limit() -> float

Get current bandwidth limit in Mbps.

set_packet_size async

set_packet_size(size: int)

Set GigE packet size for network optimization.

get_packet_size async

get_packet_size() -> int

Get current packet size.

set_inter_packet_delay async

set_inter_packet_delay(delay_ticks: int)

Set inter-packet delay for network traffic control.

get_inter_packet_delay async

get_inter_packet_delay() -> int

Get current inter-packet delay.

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Raises:

Type	Description
ValueError	If timeout_ms is negative

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

get_wb_range async

get_wb_range() -> List[str]

Get available white balance modes.

Returns:

Type	Description
List[str]	List of available white balance modes (lowercase for API compatibility)

get_width_range async

get_width_range() -> List[int]

Get camera width range.

Returns:

Type	Description
List[int]	List containing [min_width, max_width]

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If width range retrieval fails

get_height_range async

get_height_range() -> List[int]

Get camera height range.

Returns:

Type	Description
List[int]	List containing [min_height, max_height]

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If height range retrieval fails

get_pixel_format_range async

get_pixel_format_range() -> List[str]

Get available pixel formats.

Returns:

Type	Description
List[str]	List of available pixel formats

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If pixel format range retrieval fails

get_current_pixel_format async

get_current_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If pixel format retrieval fails

set_pixel_format async

set_pixel_format(pixel_format: str)

Set pixel format.

Parameters:

Name	Type	Description	Default
pixel_format	str	Pixel format to set	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If pixel format is invalid
HardwareOperationError	If pixel format setting fails

get_wb async

get_wb() -> str

Get the current white balance auto setting.

Returns:

Type	Description
str	White balance auto setting ("off", "once", "continuous")

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If white balance retrieval fails

set_auto_wb_once async

set_auto_wb_once(value: str)

Set the white balance auto mode.

Parameters:

Name	Type	Description	Default
value	str	White balance mode ("off", "once", "continuous")	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If white balance mode is invalid
HardwareOperationError	If white balance setting fails

get_trigger_modes async

get_trigger_modes() -> List[str]

Get available trigger modes for Basler cameras.

Returns:

Type	Description
List[str]	List of available trigger modes based on GenICam TriggerMode and TriggerSource

get_bandwidth_limit_range async

get_bandwidth_limit_range() -> List[float]

Get bandwidth limit range for GigE cameras.

Returns:

Type	Description
List[float]	List containing [min_bandwidth, max_bandwidth] in Mbps

get_packet_size_range async

get_packet_size_range() -> List[int]

Get packet size range for GigE cameras.

Returns:

Type	Description
List[int]	List containing [min_packet_size, max_packet_size] in bytes

get_inter_packet_delay_range async

get_inter_packet_delay_range() -> List[int]

Get inter-packet delay range for GigE cameras.

Returns:

Type	Description
List[int]	List containing [min_delay, max_delay] in ticks

close async

close()

Close the camera and release resources.

Raises:

Type	Description
CameraConnectionError	If camera closure fails

MockBaslerCameraBackend

MockBaslerCameraBackend(
    camera_name: str,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
    **backend_kwargs
)

Bases: CameraBackend

Mock Basler Camera Backend Implementation

This class provides a mock implementation of the Basler camera backend for testing and development. It simulates Basler camera functionality without requiring actual hardware, with configurable behavior and error simulation.

Features

• Complete simulation of Basler camera API
• Configurable image generation with realistic patterns
• Error simulation for testing error handling
• Configuration import/export simulation
• Camera control features (exposure, ROI, trigger modes, etc.)
• Realistic timing and behavior simulation

Usage::

from mindtrace.hardware.cameras.backends.basler import MockBaslerCameraBackend

camera = MockBaslerCameraBackend("mock_camera_1")
await camera.set_exposure(20000)
image = await camera.capture()
await camera.close()

Error Simulation

Enable error simulation via environment variables: - MOCK_BASLER_FAIL_INIT: Simulate initialization failure - MOCK_BASLER_FAIL_CAPTURE: Simulate capture failure - MOCK_BASLER_TIMEOUT: Simulate timeout errors

Attributes:

Name	Type	Description
initialized		Whether camera was successfully initialized
camera_name		Name/identifier of the mock camera
triggermode		Current trigger mode ("continuous" or "trigger")
img_quality_enhancement		Current image enhancement setting
timeout_ms		Capture timeout in milliseconds
retrieve_retry_count		Number of capture retry attempts
exposure_time		Current exposure time in microseconds
gain		Current gain value
roi		Current region of interest settings
white_balance_mode		Current white balance mode
image_counter		Counter for generating unique images
fail_init		Whether to simulate initialization failure
fail_capture		Whether to simulate capture failure
simulate_timeout		Whether to simulate timeout errors

Initialize mock Basler camera.

Parameters:

Name	Type	Description	Default
camera_name	str	Camera identifier	required
camera_config	Optional[str]	Path to configuration file (simulated)	None
img_quality_enhancement	Optional[bool]	Enable image enhancement simulation (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of capture retry attempts (uses config default if None)	None
**backend_kwargs		Backend-specific parameters: - pixel_format: Pixel format (simulated) - buffer_count: Buffer count (simulated) - timeout_ms: Timeout in milliseconds - fast_mode: If True, skip all sleep delays for fast unit tests (default: False) - simulate_fail_init: If True, simulate initialization failure (overrides env) - simulate_fail_capture: If True, simulate capture failure (overrides env) - simulate_timeout: If True, simulate timeout on capture (overrides env) - simulate_cancel: If True, simulate asyncio cancellation during capture - synthetic_width: Override synthetic image width (int) - synthetic_height: Override synthetic image height (int) - synthetic_pattern: One of {"auto","gradient","checkerboard","circular","noise"} - synthetic_checker_size: Checker size (int) used when pattern is checkerboard - synthetic_overlay_text: If False, disables text overlays in synthetic images	{}

Raises:

Type	Description
CameraConfigurationError	If configuration is invalid
CameraInitializationError	If initialization fails (when simulated)

get_available_cameras staticmethod

get_available_cameras(
    include_details: bool = False,
) -> Union[List[str], Dict[str, Dict[str, str]]]

Get available mock Basler cameras.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return detailed information	False

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	List of mock camera names or dict with details

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the mock camera connection.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success status, mock camera object, None)

Raises:

Type	Description
CameraNotFoundError	If no cameras found or specified camera not found
CameraInitializationError	If initialization fails (when simulated)
CameraConnectionError	If camera connection fails

capture async

capture() -> np.ndarray

Capture a single image from the mock camera.

Returns:

Type	Description
ndarray	Captured BGR image array

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraCaptureError	If image capture fails
CameraTimeoutError	If capture times out

IsGrabbing

IsGrabbing() -> bool

Return whether the mock camera is currently in a grabbing state.

StartGrabbing

StartGrabbing(grabbing_mode: Optional[str] = None) -> None

Enter grabbing state, optionally updating grabbing mode.

Parameters:

Name	Type	Description	Default
grabbing_mode	Optional[str]	Optional grabbing mode string; if provided, updates current mode.	None

StopGrabbing

StopGrabbing() -> None

Exit grabbing state.

get_image_quality_enhancement

get_image_quality_enhancement() -> bool

Get image quality enhancement setting.

Returns:

Type	Description
bool	True if enhancement is enabled, otherwise False.

set_image_quality_enhancement

set_image_quality_enhancement(value: bool)

Set image quality enhancement setting.

Parameters:

Name	Type	Description	Default
value	bool	True to enable enhancement, False to disable.	required

get_exposure_range async

get_exposure_range() -> List[Union[int, float]]

Get the supported exposure time range in microseconds.

Returns:

Type	Description
List[Union[int, float]]	List with [min_exposure, max_exposure] in microseconds

get_exposure async

get_exposure() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time

set_exposure async

set_exposure(exposure: Union[int, float])

Set the camera exposure time in microseconds.

Parameters:

Name	Type	Description	Default
exposure	Union[int, float]	Exposure time in microseconds	required

Raises:

Type	Description
CameraConfigurationError	If exposure value is out of range

get_triggermode async

get_triggermode() -> str

Get current trigger mode.

Returns:

Type	Description
str	Current trigger mode

set_triggermode async

set_triggermode(triggermode: str = 'continuous')

Set trigger mode.

Parameters:

Name	Type	Description	Default
triggermode	str	Trigger mode ("continuous" or "trigger")	'continuous'

Raises:

Type	Description
CameraConfigurationError	If trigger mode is invalid

check_connection async

check_connection() -> bool

Check if mock camera is connected and operational.

Returns:

Type	Description
bool	True if connected and operational, False otherwise

import_config async

import_config(config_path: str)

Import camera configuration from common JSON format.

Parameters:

Name	Type	Description	Default
config_path	str	Path to configuration file	required

Raises:

Type	Description
CameraConfigurationError	If configuration file is not found or invalid

export_config async

export_config(config_path: str)

Export camera configuration to common JSON format.

Parameters:

Name	Type	Description	Default
config_path	str	Path to save configuration file	required

set_ROI async

set_ROI(x: int, y: int, width: int, height: int)

Set Region of Interest (ROI).

Parameters:

Name	Type	Description	Default
x	int	ROI x offset	required
y	int	ROI y offset	required
width	int	ROI width	required
height	int	ROI height	required

Raises:

Type	Description
CameraConfigurationError	If ROI parameters are invalid

get_ROI async

get_ROI() -> Dict[str, int]

Get current Region of Interest (ROI).

Returns:

Type	Description
Dict[str, int]	Dictionary with ROI parameters

reset_ROI async

reset_ROI()

Reset ROI to full sensor size.

set_gain async

set_gain(gain: Union[int, float])

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	Union[int, float]	Gain value	required

Raises:

Type	Description
CameraConfigurationError	If gain value is out of range

get_gain_range async

get_gain_range() -> List[Union[int, float]]

Get the supported gain range.

Returns:

Type	Description
List[Union[int, float]]	List with [min_gain, max_gain]

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

get_wb async

get_wb() -> str

Get current white balance mode.

Returns:

Type	Description
str	Current white balance mode

set_auto_wb_once async

set_auto_wb_once(value: str)

Set white balance mode.

Parameters:

Name	Type	Description	Default
value	str	White balance mode	required

get_wb_range async

get_wb_range() -> List[str]

Get available white balance modes.

Returns:

Type	Description
List[str]	List of available white balance modes (lowercase for API compatibility)

get_pixel_format_range async

get_pixel_format_range() -> List[str]

Get available pixel formats.

Returns:

Type	Description
List[str]	List of available pixel formats

get_current_pixel_format async

get_current_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format

set_pixel_format async

set_pixel_format(pixel_format: str)

Set pixel format.

Parameters:

Name	Type	Description	Default
pixel_format	str	Pixel format to set	required

Raises:

Type	Description
CameraConfigurationError	If pixel format is not supported

get_width_range async

get_width_range() -> List[int]

Get camera width range.

Returns:

Type	Description
List[int]	List containing [min_width, max_width]

get_height_range async

get_height_range() -> List[int]

Get camera height range.

Returns:

Type	Description
List[int]	List containing [min_height, max_height]

set_bandwidth_limit async

set_bandwidth_limit(limit_mbps: Optional[float])

Set GigE camera bandwidth limit in Mbps (simulated).

get_bandwidth_limit async

get_bandwidth_limit() -> float

Get current bandwidth limit (simulated).

set_packet_size async

set_packet_size(size: int)

Set GigE packet size for network optimization (simulated).

get_packet_size async

get_packet_size() -> int

Get current packet size (simulated).

set_inter_packet_delay async

set_inter_packet_delay(delay_ticks: int)

Set inter-packet delay for network traffic control (simulated).

get_inter_packet_delay async

get_inter_packet_delay() -> int

Get current inter-packet delay (simulated).

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Raises:

Type	Description
ValueError	If timeout_ms is negative

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

get_trigger_modes async

get_trigger_modes() -> List[str]

Get available trigger modes for mock Basler cameras.

get_bandwidth_limit_range async

get_bandwidth_limit_range() -> List[float]

Get bandwidth limit range for mock GigE cameras.

get_packet_size_range async

get_packet_size_range() -> List[int]

Get packet size range for mock GigE cameras.

get_inter_packet_delay_range async

get_inter_packet_delay_range() -> List[int]

Get inter-packet delay range for mock GigE cameras.

close async

close()

Close the mock camera and release resources.

basler_camera_backend

Basler Camera Backend Module

BaslerCameraBackend

BaslerCameraBackend(
    camera_name: str,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
    multicast_enabled: Optional[bool] = None,
    target_ips: Optional[List[str]] = None,
    multicast_group: Optional[str] = None,
    multicast_port: Optional[int] = None,
    **backend_kwargs
)

Bases: CameraBackend

Basler Camera Backend Implementation

This class provides a comprehensive implementation for Basler cameras using the pypylon SDK. It supports advanced camera features including trigger modes, exposure control, ROI settings, and image quality enhancement.

Features

• Full Basler camera support via pypylon SDK
• Hardware trigger and continuous capture modes
• ROI (Region of Interest) control
• Automatic exposure and gain control
• Image quality enhancement with CLAHE
• Configuration import/export functionality
• Robust error handling and connection management

Requirements

• pypylon SDK (Pylon SDK for Python)
• OpenCV for image processing
• Basler Pylon SDK installed on system

Installation

1. Install Basler Pylon SDK from manufacturer
2. pip install pypylon
3. Configure camera permissions (Linux may require udev rules)

Usage::

from mindtrace.hardware.cameras.backends.basler import BaslerCameraBackend

# Get available cameras
cameras = BaslerCameraBackend.get_available_cameras()

# Initialize camera
camera = BaslerCameraBackend("camera_name", img_quality_enhancement=True)
success, cam_obj, remote_obj = await camera.initialize()  # Initialize first

if success:
    # Configure and capture
    await camera.set_exposure(20000)
    await camera.set_triggermode("continuous")
    image = await camera.capture()
    await camera.close()

Configuration

All parameters are configurable via the hardware configuration system: - MINDTRACE_CAMERA_EXPOSURE_TIME: Default exposure time in microseconds - MINDTRACE_CAMERA_TRIGGER_MODE: Default trigger mode ("continuous" or "trigger") - MINDTRACE_CAMERA_IMAGE_QUALITY_ENHANCEMENT: Enable CLAHE enhancement - MINDTRACE_CAMERA_RETRIEVE_RETRY_COUNT: Number of capture retry attempts - MINDTRACE_CAMERA_BUFFER_COUNT: Number of frame buffers for streaming - MINDTRACE_CAMERA_TIMEOUT_MS: Capture timeout in milliseconds

Supported Camera Models

• All Basler USB3 cameras (acA, daA series)
• All Basler GigE cameras (acA, daA series)
• Both monochrome and color variants
• Various resolutions and frame rates

Error Handling

The class uses a comprehensive exception hierarchy for precise error reporting: - SDKNotAvailableError: pypylon SDK not installed - CameraNotFoundError: Camera not detected or accessible - CameraInitializationError: Failed to initialize camera - CameraConfigurationError: Invalid configuration parameters - CameraConnectionError: Connection issues - CameraCaptureError: Image acquisition failures - CameraTimeoutError: Operation timeout - HardwareOperationError: General hardware operation failures

Attributes:

Name	Type	Description
initialized	bool	Whether camera was successfully initialized
camera	Optional[Any]	Underlying pypylon camera object
triggermode		Current trigger mode ("continuous" or "trigger")
img_quality_enhancement		Current image enhancement setting
timeout_ms		Capture timeout in milliseconds
buffer_count		Number of frame buffers
converter		Image format converter for pypylon
retrieve_retry_count		Number of capture retry attempts
default_pixel_format		Default pixel format for image conversion
camera_config_path		Path to camera configuration file
grabbing_mode		Pylon grabbing strategy

Initialize Basler camera with configurable parameters.

Parameters:

Name	Type	Description	Default
camera_name	str	Camera identifier (serial number, IP, or user-defined name)	required
camera_config	Optional[str]	Path to Pylon Feature Stream (.pfs) file (optional)	None
img_quality_enhancement	Optional[bool]	Enable CLAHE image enhancement (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of capture retry attempts (uses config default if None)	None
multicast_enabled	Optional[bool]	Enable multicast streaming mode (uses config default if None)	None
target_ips	Optional[List[str]]	List of target IP addresses for multicast discovery (optional)	None
multicast_group	Optional[str]	Multicast group IP address (uses config default if None)	None
multicast_port	Optional[int]	Multicast port number (uses config default if None)	None
**backend_kwargs		Backend-specific parameters: - pixel_format: Default pixel format (uses config default if None) - buffer_count: Number of frame buffers (uses config default if None) - timeout_ms: Capture timeout in milliseconds (uses config default if None)	{}

Raises:

Type	Description
SDKNotAvailableError	If pypylon SDK is not available
CameraConfigurationError	If configuration is invalid
CameraInitializationError	If camera initialization fails

get_available_cameras staticmethod

get_available_cameras(
    include_details: bool = False, target_ips: Optional[List[str]] = None
) -> Union[List[str], Dict[str, Dict[str, str]]]

Get available Basler cameras.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return detailed information	False
target_ips	Optional[List[str]]	Optional list of IP addresses to specifically discover	None

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	List of camera names (user-defined names preferred, serial numbers as fallback) or dict with details

Raises:

Type	Description
SDKNotAvailableError	If Basler SDK is not available
HardwareOperationError	If camera discovery fails

discover_async async classmethod

discover_async(
    include_details: bool = False, target_ips: Optional[List[str]] = None
) -> Union[List[str], Dict[str, Dict[str, str]]]

Async wrapper for get_available_cameras() - runs discovery in threadpool.

Use this instead of get_available_cameras() when calling from async context to avoid blocking the event loop during camera enumeration.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return a dict of details per camera.	False
target_ips	Optional[List[str]]	Optional list of specific IP addresses to target.	None

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	Union[List[str], Dict[str, Dict[str, str]]]: List of camera names or dict of details.

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the camera connection.

This searches for the camera by name, serial number, or IP and establishes a connection if found. Uses multicast-aware discovery if enabled.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success status, camera object, None)

Raises:

Type	Description
CameraNotFoundError	If no cameras found or specified camera not found
CameraInitializationError	If camera initialization fails
CameraConnectionError	If camera connection fails

configure_streaming async

configure_streaming()

Configure multicast streaming settings for the camera.

This method sets up multicast parameters when multicast mode is enabled. It configures the camera using the StreamGrabber interface for multicast streaming.

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If multicast configuration fails
HardwareOperationError	If streaming configuration fails

get_image_quality_enhancement

get_image_quality_enhancement() -> bool

Get image quality enhancement setting.

set_image_quality_enhancement

set_image_quality_enhancement(value: bool)

Set image quality enhancement setting.

get_exposure_range async

get_exposure_range() -> List[Union[int, float]]

Get the supported exposure time range in microseconds.

Returns:

Type	Description
List[Union[int, float]]	List with [min_exposure, max_exposure] in microseconds

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If exposure range retrieval fails

get_exposure async

get_exposure() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If exposure retrieval fails

set_exposure async

set_exposure(exposure: Union[int, float])

Set the camera exposure time in microseconds.

Parameters:

Name	Type	Description	Default
exposure_value		Exposure time in microseconds	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraConfigurationError	If exposure value is out of range
HardwareOperationError	If exposure setting fails

get_triggermode async

get_triggermode() -> str

Get current trigger mode.

Returns:

Type	Description
str	"continuous" or "trigger"

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If trigger mode retrieval fails

set_triggermode async

set_triggermode(triggermode: str = 'continuous')

Set the camera's trigger mode for image acquisition.

Parameters:

Name	Type	Description	Default
triggermode	str	Trigger mode ("continuous" or "trigger")	'continuous'

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraConfigurationError	If trigger mode is invalid
HardwareOperationError	If trigger mode setting fails

capture async

capture() -> np.ndarray

Capture a single image from the camera.

In continuous mode, returns the latest available frame. In trigger mode, executes a software trigger and waits for the image.

Returns:

Type	Description
ndarray	Image array in BGR format

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraCaptureError	If image capture fails
CameraTimeoutError	If capture times out

check_connection async

check_connection() -> bool

Check if camera is connected and operational.

Returns:

Type	Description
bool	True if connected and operational, False otherwise

import_config async

import_config(config_path: str)

Import camera configuration from common JSON format.

Parameters:

Name	Type	Description	Default
config_path	str	Path to configuration file	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If configuration import fails

export_config async

export_config(config_path: str)

Export current camera configuration to common JSON format.

Parameters:

Name	Type	Description	Default
config_path	str	Path where to save configuration file	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If configuration export fails

set_ROI async

set_ROI(x: int, y: int, width: int, height: int)

Set the Region of Interest (ROI) for image acquisition.

Parameters:

Name	Type	Description	Default
x	int	X offset from sensor top-left	required
y	int	Y offset from sensor top-left	required
width	int	ROI width	required
height	int	ROI height	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If ROI parameters are invalid
HardwareOperationError	If ROI setting fails

get_ROI async

get_ROI() -> Dict[str, int]

Get current Region of Interest settings.

Returns:

Type	Description
Dict[str, int]	Dictionary with x, y, width, height

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If ROI retrieval fails

reset_ROI async

reset_ROI()

Reset ROI to maximum sensor area.

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If ROI reset fails

set_gain async

set_gain(gain: float)

Set the camera's gain value.

Parameters:

Name	Type	Description	Default
gain	float	Gain value (camera-specific range)	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If gain value is out of range
HardwareOperationError	If gain setting fails

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If gain retrieval fails

get_gain_range async

get_gain_range() -> List[Union[int, float]]

Get camera gain range.

Returns:

Type	Description
List[Union[int, float]]	List containing [min_gain, max_gain]

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If gain range retrieval fails

set_bandwidth_limit async

set_bandwidth_limit(limit_mbps: Optional[float])

Set GigE camera bandwidth limit in Mbps.

get_bandwidth_limit async

get_bandwidth_limit() -> float

Get current bandwidth limit in Mbps.

set_packet_size async

set_packet_size(size: int)

Set GigE packet size for network optimization.

get_packet_size async

get_packet_size() -> int

Get current packet size.

set_inter_packet_delay async

set_inter_packet_delay(delay_ticks: int)

Set inter-packet delay for network traffic control.

get_inter_packet_delay async

get_inter_packet_delay() -> int

Get current inter-packet delay.

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Raises:

Type	Description
ValueError	If timeout_ms is negative

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

get_wb_range async

get_wb_range() -> List[str]

Get available white balance modes.

Returns:

Type	Description
List[str]	List of available white balance modes (lowercase for API compatibility)

get_width_range async

get_width_range() -> List[int]

Get camera width range.

Returns:

Type	Description
List[int]	List containing [min_width, max_width]

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If width range retrieval fails

get_height_range async

get_height_range() -> List[int]

Get camera height range.

Returns:

Type	Description
List[int]	List containing [min_height, max_height]

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If height range retrieval fails

get_pixel_format_range async

get_pixel_format_range() -> List[str]

Get available pixel formats.

Returns:

Type	Description
List[str]	List of available pixel formats

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If pixel format range retrieval fails

get_current_pixel_format async

get_current_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If pixel format retrieval fails

set_pixel_format async

set_pixel_format(pixel_format: str)

Set pixel format.

Parameters:

Name	Type	Description	Default
pixel_format	str	Pixel format to set	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If pixel format is invalid
HardwareOperationError	If pixel format setting fails

get_wb async

get_wb() -> str

Get the current white balance auto setting.

Returns:

Type	Description
str	White balance auto setting ("off", "once", "continuous")

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If white balance retrieval fails

set_auto_wb_once async

set_auto_wb_once(value: str)

Set the white balance auto mode.

Parameters:

Name	Type	Description	Default
value	str	White balance mode ("off", "once", "continuous")	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If white balance mode is invalid
HardwareOperationError	If white balance setting fails

get_trigger_modes async

get_trigger_modes() -> List[str]

Get available trigger modes for Basler cameras.

Returns:

Type	Description
List[str]	List of available trigger modes based on GenICam TriggerMode and TriggerSource

get_bandwidth_limit_range async

get_bandwidth_limit_range() -> List[float]

Get bandwidth limit range for GigE cameras.

Returns:

Type	Description
List[float]	List containing [min_bandwidth, max_bandwidth] in Mbps

get_packet_size_range async

get_packet_size_range() -> List[int]

Get packet size range for GigE cameras.

Returns:

Type	Description
List[int]	List containing [min_packet_size, max_packet_size] in bytes

get_inter_packet_delay_range async

get_inter_packet_delay_range() -> List[int]

Get inter-packet delay range for GigE cameras.

Returns:

Type	Description
List[int]	List containing [min_delay, max_delay] in ticks

close async

close()

Close the camera and release resources.

Raises:

Type	Description
CameraConnectionError	If camera closure fails

mock_basler_camera_backend

Mock Basler Camera Backend Module

MockBaslerCameraBackend

MockBaslerCameraBackend(
    camera_name: str,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
    **backend_kwargs
)

Bases: CameraBackend

Mock Basler Camera Backend Implementation

This class provides a mock implementation of the Basler camera backend for testing and development. It simulates Basler camera functionality without requiring actual hardware, with configurable behavior and error simulation.

Features

• Complete simulation of Basler camera API
• Configurable image generation with realistic patterns
• Error simulation for testing error handling
• Configuration import/export simulation
• Camera control features (exposure, ROI, trigger modes, etc.)
• Realistic timing and behavior simulation

Usage::

from mindtrace.hardware.cameras.backends.basler import MockBaslerCameraBackend

camera = MockBaslerCameraBackend("mock_camera_1")
await camera.set_exposure(20000)
image = await camera.capture()
await camera.close()

Error Simulation

Enable error simulation via environment variables: - MOCK_BASLER_FAIL_INIT: Simulate initialization failure - MOCK_BASLER_FAIL_CAPTURE: Simulate capture failure - MOCK_BASLER_TIMEOUT: Simulate timeout errors

Attributes:

Name	Type	Description
initialized		Whether camera was successfully initialized
camera_name		Name/identifier of the mock camera
triggermode		Current trigger mode ("continuous" or "trigger")
img_quality_enhancement		Current image enhancement setting
timeout_ms		Capture timeout in milliseconds
retrieve_retry_count		Number of capture retry attempts
exposure_time		Current exposure time in microseconds
gain		Current gain value
roi		Current region of interest settings
white_balance_mode		Current white balance mode
image_counter		Counter for generating unique images
fail_init		Whether to simulate initialization failure
fail_capture		Whether to simulate capture failure
simulate_timeout		Whether to simulate timeout errors

Initialize mock Basler camera.

Parameters:

Name	Type	Description	Default
camera_name	str	Camera identifier	required
camera_config	Optional[str]	Path to configuration file (simulated)	None
img_quality_enhancement	Optional[bool]	Enable image enhancement simulation (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of capture retry attempts (uses config default if None)	None
**backend_kwargs		Backend-specific parameters: - pixel_format: Pixel format (simulated) - buffer_count: Buffer count (simulated) - timeout_ms: Timeout in milliseconds - fast_mode: If True, skip all sleep delays for fast unit tests (default: False) - simulate_fail_init: If True, simulate initialization failure (overrides env) - simulate_fail_capture: If True, simulate capture failure (overrides env) - simulate_timeout: If True, simulate timeout on capture (overrides env) - simulate_cancel: If True, simulate asyncio cancellation during capture - synthetic_width: Override synthetic image width (int) - synthetic_height: Override synthetic image height (int) - synthetic_pattern: One of {"auto","gradient","checkerboard","circular","noise"} - synthetic_checker_size: Checker size (int) used when pattern is checkerboard - synthetic_overlay_text: If False, disables text overlays in synthetic images	{}

Raises:

Type	Description
CameraConfigurationError	If configuration is invalid
CameraInitializationError	If initialization fails (when simulated)

get_available_cameras staticmethod

get_available_cameras(
    include_details: bool = False,
) -> Union[List[str], Dict[str, Dict[str, str]]]

Get available mock Basler cameras.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return detailed information	False

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	List of mock camera names or dict with details

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the mock camera connection.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success status, mock camera object, None)

Raises:

Type	Description
CameraNotFoundError	If no cameras found or specified camera not found
CameraInitializationError	If initialization fails (when simulated)
CameraConnectionError	If camera connection fails

capture async

capture() -> np.ndarray

Capture a single image from the mock camera.

Returns:

Type	Description
ndarray	Captured BGR image array

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraCaptureError	If image capture fails
CameraTimeoutError	If capture times out

IsGrabbing

IsGrabbing() -> bool

Return whether the mock camera is currently in a grabbing state.

StartGrabbing

StartGrabbing(grabbing_mode: Optional[str] = None) -> None

Enter grabbing state, optionally updating grabbing mode.

Parameters:

Name	Type	Description	Default
grabbing_mode	Optional[str]	Optional grabbing mode string; if provided, updates current mode.	None

StopGrabbing

StopGrabbing() -> None

Exit grabbing state.

get_image_quality_enhancement

get_image_quality_enhancement() -> bool

Get image quality enhancement setting.

Returns:

Type	Description
bool	True if enhancement is enabled, otherwise False.

set_image_quality_enhancement

set_image_quality_enhancement(value: bool)

Set image quality enhancement setting.

Parameters:

Name	Type	Description	Default
value	bool	True to enable enhancement, False to disable.	required

get_exposure_range async

get_exposure_range() -> List[Union[int, float]]

Get the supported exposure time range in microseconds.

Returns:

Type	Description
List[Union[int, float]]	List with [min_exposure, max_exposure] in microseconds

get_exposure async

get_exposure() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time

set_exposure async

set_exposure(exposure: Union[int, float])

Set the camera exposure time in microseconds.

Parameters:

Name	Type	Description	Default
exposure	Union[int, float]	Exposure time in microseconds	required

Raises:

Type	Description
CameraConfigurationError	If exposure value is out of range

get_triggermode async

get_triggermode() -> str

Get current trigger mode.

Returns:

Type	Description
str	Current trigger mode

set_triggermode async

set_triggermode(triggermode: str = 'continuous')

Set trigger mode.

Parameters:

Name	Type	Description	Default
triggermode	str	Trigger mode ("continuous" or "trigger")	'continuous'

Raises:

Type	Description
CameraConfigurationError	If trigger mode is invalid

check_connection async

check_connection() -> bool

Check if mock camera is connected and operational.

Returns:

Type	Description
bool	True if connected and operational, False otherwise

import_config async

import_config(config_path: str)

Import camera configuration from common JSON format.

Parameters:

Name	Type	Description	Default
config_path	str	Path to configuration file	required

Raises:

Type	Description
CameraConfigurationError	If configuration file is not found or invalid

export_config async

export_config(config_path: str)

Export camera configuration to common JSON format.

Parameters:

Name	Type	Description	Default
config_path	str	Path to save configuration file	required

set_ROI async

set_ROI(x: int, y: int, width: int, height: int)

Set Region of Interest (ROI).

Parameters:

Name	Type	Description	Default
x	int	ROI x offset	required
y	int	ROI y offset	required
width	int	ROI width	required
height	int	ROI height	required

Raises:

Type	Description
CameraConfigurationError	If ROI parameters are invalid

get_ROI async

get_ROI() -> Dict[str, int]

Get current Region of Interest (ROI).

Returns:

Type	Description
Dict[str, int]	Dictionary with ROI parameters

reset_ROI async

reset_ROI()

Reset ROI to full sensor size.

set_gain async

set_gain(gain: Union[int, float])

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	Union[int, float]	Gain value	required

Raises:

Type	Description
CameraConfigurationError	If gain value is out of range

get_gain_range async

get_gain_range() -> List[Union[int, float]]

Get the supported gain range.

Returns:

Type	Description
List[Union[int, float]]	List with [min_gain, max_gain]

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

get_wb async

get_wb() -> str

Get current white balance mode.

Returns:

Type	Description
str	Current white balance mode

set_auto_wb_once async

set_auto_wb_once(value: str)

Set white balance mode.

Parameters:

Name	Type	Description	Default
value	str	White balance mode	required

get_wb_range async

get_wb_range() -> List[str]

Get available white balance modes.

Returns:

Type	Description
List[str]	List of available white balance modes (lowercase for API compatibility)

get_pixel_format_range async

get_pixel_format_range() -> List[str]

Get available pixel formats.

Returns:

Type	Description
List[str]	List of available pixel formats

get_current_pixel_format async

get_current_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format

set_pixel_format async

set_pixel_format(pixel_format: str)

Set pixel format.

Parameters:

Name	Type	Description	Default
pixel_format	str	Pixel format to set	required

Raises:

Type	Description
CameraConfigurationError	If pixel format is not supported

get_width_range async

get_width_range() -> List[int]

Get camera width range.

Returns:

Type	Description
List[int]	List containing [min_width, max_width]

get_height_range async

get_height_range() -> List[int]

Get camera height range.

Returns:

Type	Description
List[int]	List containing [min_height, max_height]

set_bandwidth_limit async

set_bandwidth_limit(limit_mbps: Optional[float])

Set GigE camera bandwidth limit in Mbps (simulated).

get_bandwidth_limit async

get_bandwidth_limit() -> float

Get current bandwidth limit (simulated).

set_packet_size async

set_packet_size(size: int)

Set GigE packet size for network optimization (simulated).

get_packet_size async

get_packet_size() -> int

Get current packet size (simulated).

set_inter_packet_delay async

set_inter_packet_delay(delay_ticks: int)

Set inter-packet delay for network traffic control (simulated).

get_inter_packet_delay async

get_inter_packet_delay() -> int

Get current inter-packet delay (simulated).

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Raises:

Type	Description
ValueError	If timeout_ms is negative

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

get_trigger_modes async

get_trigger_modes() -> List[str]

Get available trigger modes for mock Basler cameras.

get_bandwidth_limit_range async

get_bandwidth_limit_range() -> List[float]

Get bandwidth limit range for mock GigE cameras.

get_packet_size_range async

get_packet_size_range() -> List[int]

Get packet size range for mock GigE cameras.

get_inter_packet_delay_range async

get_inter_packet_delay_range() -> List[int]

Get inter-packet delay range for mock GigE cameras.

close async

close()

Close the mock camera and release resources.

camera_backend

CameraBackend

CameraBackend(
    camera_name: Optional[str] = None,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
)

Bases: MindtraceABC

Abstract base class for all camera implementations.

This class defines the async interface that all camera backends must implement to ensure consistent behavior across different camera types and manufacturers. Uses async-first design consistent with PLC backends.

Attributes:

Name	Type	Description
camera_name		Unique identifier for the camera
camera_config_file		Path to camera configuration file
img_quality_enhancement		Whether image quality enhancement is enabled
retrieve_retry_count		Number of retries for image retrieval
camera	Optional[Any]	The initialized camera object (implementation-specific)
device_manager	Optional[Any]	Device manager object (implementation-specific)
initialized	bool	Camera initialization status

Implementation Guide

• Offload blocking SDK calls from async methods: Use asyncio.to_thread for simple cases or loop.run_in_executor with a per-instance single-thread executor when the SDK requires thread affinity.
• Thread affinity: Many vendor SDKs are safest when all calls originate from one OS thread. Prefer a dedicated single-thread executor created during initialize() and shut down in close() to serialize SDK access without blocking the event loop.
• Timeouts and cancellation: Prefer SDK-native timeouts where available. Otherwise, wrap awaited futures with asyncio.wait_for to bound runtime. Note that cancelling an await does not stop the underlying thread function; design idempotent/short tasks when possible.
• Event loop hygiene: Never call blocking functions (e.g., long SDK calls, time.sleep) directly in async methods. Replace sleeps with await asyncio.sleep or run blocking work in the executor.
• Sync helpers: Lightweight getters/setters that do not touch hardware may remain synchronous. If a "getter" calls into the SDK, route it through the executor to avoid blocking.
• Errors: Map SDK-specific exceptions to the domain exceptions in mindtrace.hardware.core.exceptions with clear, contextual messages.
• Cleanup: Ensure resources (device handles, executors, buffers) are released in close(). __aenter__/__aexit__ already call setup_camera/close for async contexts.

Initialize base camera with configuration integration.

Parameters:

Name	Type	Description	Default
camera_name	Optional[str]	Unique identifier for the camera (auto-generated if None)	None
camera_config	Optional[str]	Path to camera configuration file	None
img_quality_enhancement	Optional[bool]	Whether to apply image quality enhancement (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of retries for image retrieval (uses config default if None)	None

setup_camera async

setup_camera()

Common setup method for camera initialization.

This method provides a standardized setup pattern that can be used by all camera backends. It calls the abstract initialize() method and handles common initialization patterns.

Raises:

Type	Description
CameraNotFoundError	If camera cannot be found
CameraInitializationError	If camera initialization fails
CameraConnectionError	If camera connection fails

set_bandwidth_limit async

set_bandwidth_limit(limit_mbps: Optional[float])

Set GigE camera bandwidth limit in Mbps.

get_bandwidth_limit async

get_bandwidth_limit() -> float

Get current bandwidth limit.

set_packet_size async

set_packet_size(size: int)

Set GigE packet size for network optimization.

get_packet_size async

get_packet_size() -> int

Get current packet size.

set_inter_packet_delay async

set_inter_packet_delay(delay_ticks: int)

Set inter-packet delay for network traffic control.

get_inter_packet_delay async

get_inter_packet_delay() -> int

Get current inter-packet delay.

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Note

This is a runtime-configurable parameter that can be changed without reinitializing the camera.

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

genicam

GenICam Camera Backend Module

GenICamCameraBackend

GenICamCameraBackend(
    camera_name: str,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
    **backend_kwargs
)

Bases: CameraBackend

GenICam Camera Backend Implementation

This class provides a comprehensive implementation for GenICam-compliant cameras using the Harvesters library with Matrix Vision GenTL Producer. It supports advanced camera features including trigger modes, exposure control, ROI settings, and image quality enhancement.

Thread Safety

Uses a singleton Harvester instance shared across all backend instances to avoid GenTL device conflicts. Multiple cameras can be opened simultaneously using the same Harvester.

Features

• Full GenICam camera support via Harvesters
• Matrix Vision GenTL Producer integration
• Hardware trigger and continuous capture modes
• ROI (Region of Interest) control
• Automatic exposure and gain control
• Image quality enhancement with CLAHE
• Configuration import/export functionality
• Robust error handling and connection management
• Vendor-specific parameter handling (Keyence, Basler, etc.)

Requirements

• Harvesters library (pip install harvesters)
• Matrix Vision mvIMPACT Acquire SDK
• OpenCV for image processing
• GenTL Producer (.cti file) installed on system

Installation

1. Install Matrix Vision mvIMPACT Acquire SDK
2. pip install harvesters opencv-python numpy
3. Configure network interface for GigE cameras
4. Set GENICAM_CTI_PATH environment variable (optional)

Usage::

from mindtrace.hardware.cameras.backends.genicam import GenICamCameraBackend

# Get available cameras
cameras = GenICamCameraBackend.get_available_cameras()

# Initialize camera
camera = GenICamCameraBackend("device_serial", img_quality_enhancement=True)
success, cam_obj, remote_obj = await camera.initialize()

if success:
    # Configure and capture
    await camera.set_exposure(50000)
    await camera.set_triggermode("continuous")
    image = await camera.capture()
    await camera.close()

Configuration

All parameters are configurable via environment variables or the hardware configuration system: - GENICAM_CTI_PATH: Path to GenTL Producer (.cti file) - MINDTRACE_CAMERA_EXPOSURE_TIME: Default exposure time in microseconds - MINDTRACE_CAMERA_TRIGGER_MODE: Default trigger mode ("continuous" or "trigger") - MINDTRACE_CAMERA_IMAGE_QUALITY_ENHANCEMENT: Enable CLAHE enhancement - MINDTRACE_CAMERA_RETRIEVE_RETRY_COUNT: Number of capture retry attempts - MINDTRACE_CAMERA_TIMEOUT_MS: Capture timeout in milliseconds

Supported Camera Models

• Keyence VJ series cameras
• Basler GigE cameras (alternative to pypylon)
• Allied Vision cameras
• FLIR/Teledyne cameras
• Any GenICam-compliant camera with compatible GenTL Producer

Error Handling

The class uses a comprehensive exception hierarchy for precise error reporting: - SDKNotAvailableError: Harvesters library not installed - CameraNotFoundError: Camera not detected or accessible - CameraInitializationError: Failed to initialize camera - CameraConfigurationError: Invalid configuration parameters - CameraConnectionError: Connection issues - CameraCaptureError: Image acquisition failures - CameraTimeoutError: Operation timeout - HardwareOperationError: General hardware operation failures

Attributes:

Name	Type	Description
initialized	bool	Whether camera was successfully initialized
image_acquirer	Optional[Any]	Harvesters ImageAcquirer object
harvester	Optional[Harvester]	Harvesters Harvester object
triggermode		Current trigger mode ("continuous" or "trigger")
img_quality_enhancement		Current image enhancement setting
timeout_ms		Capture timeout in milliseconds
retrieve_retry_count		Number of capture retry attempts
device_info	Optional[Dict[str, Any]]	Camera device information from discovery
vendor_quirks	Dict[str, bool]	Vendor-specific parameter handling flags
cti_path		Path to GenTL Producer file

Initialize GenICam camera with configurable parameters.

Parameters:

Name	Type	Description	Default
camera_name	str	Camera identifier (serial number, device ID, or user-defined name)	required
camera_config	Optional[str]	Path to JSON configuration file (optional)	None
img_quality_enhancement	Optional[bool]	Enable CLAHE image enhancement (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of capture retry attempts (uses config default if None)	None
**backend_kwargs		Backend-specific parameters: - cti_path: Path to GenTL Producer file (auto-detected if None) - timeout_ms: Capture timeout in milliseconds (uses config default if None) - buffer_count: Number of frame buffers (uses config default if None)	{}

Raises:

Type	Description
SDKNotAvailableError	If Harvesters library is not available
CameraConfigurationError	If configuration is invalid
CameraInitializationError	If camera initialization fails

get_available_cameras staticmethod

get_available_cameras(
    include_details: bool = False,
) -> Union[List[str], Dict[str, Dict[str, str]]]

Get available GenICam cameras.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return detailed information	False

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	List of camera names (serial numbers or device IDs) or dict with details

Raises:

Type	Description
SDKNotAvailableError	If Harvesters library is not available
HardwareOperationError	If camera discovery fails

discover_async async classmethod

discover_async(
    include_details: bool = False,
) -> Union[List[str], Dict[str, Dict[str, str]]]

Async wrapper for get_available_cameras() - runs discovery in threadpool.

Use this instead of get_available_cameras() when calling from async context to avoid blocking the event loop during camera discovery.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return detailed camera information	False

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	List of camera names or dict with details (same as get_available_cameras)

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the camera connection.

This searches for the camera by name, serial number, or device ID and establishes a connection if found.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success status, image_acquirer object, device_info)

Raises:

Type	Description
CameraNotFoundError	If no cameras found or specified camera not found
CameraInitializationError	If camera initialization fails
CameraConnectionError	If camera connection fails

get_exposure_range async

get_exposure_range() -> List[Union[int, float]]

Get the supported exposure time range in microseconds.

Returns:

Type	Description
List[Union[int, float]]	List with [min_exposure, max_exposure] in microseconds

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If exposure range retrieval fails

get_exposure async

get_exposure() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If exposure retrieval fails

set_exposure async

set_exposure(exposure: Union[int, float])

Set the camera exposure time in microseconds.

Parameters:

Name	Type	Description	Default
exposure	Union[int, float]	Exposure time in microseconds	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraConfigurationError	If exposure value is out of range
HardwareOperationError	If exposure setting fails

get_current_pixel_format async

get_current_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format string (e.g., "Mono8", "RGB8", "BayerRG8")

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If pixel format retrieval fails

get_width_range async

get_width_range() -> List[int]

Get camera width range.

Returns:

Type	Description
List[int]	List containing [min_width, max_width]

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If width range retrieval fails

get_height_range async

get_height_range() -> List[int]

Get camera height range.

Returns:

Type	Description
List[int]	List containing [min_height, max_height]

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If height range retrieval fails

get_pixel_format_range async

get_pixel_format_range() -> List[str]

Get list of supported pixel formats.

Returns:

Type	Description
List[str]	List of supported pixel format strings

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If pixel format list retrieval fails

set_pixel_format async

set_pixel_format(pixel_format: str)

Set the camera pixel format.

Parameters:

Name	Type	Description	Default
pixel_format	str	Pixel format string (e.g., "Mono8", "RGB8")	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraConfigurationError	If pixel format is not supported
HardwareOperationError	If pixel format setting fails

get_triggermode async

get_triggermode() -> str

Get current trigger mode.

Returns:

Type	Description
str	"continuous" or "trigger"

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If trigger mode retrieval fails

set_triggermode async

set_triggermode(triggermode: str = 'continuous')

Set the camera's trigger mode for image acquisition.

Parameters:

Name	Type	Description	Default
triggermode	str	Trigger mode ("continuous" or "trigger")	'continuous'

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraConfigurationError	If trigger mode is invalid
HardwareOperationError	If trigger mode setting fails

capture async

capture() -> np.ndarray

Capture a single image from the camera.

In continuous mode, returns the latest available frame. In trigger mode, executes a software trigger and waits for the image.

Returns:

Type	Description
ndarray	Image array in BGR format

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraCaptureError	If image capture fails
CameraTimeoutError	If capture times out

check_connection async

check_connection() -> bool

Check if camera is connected and operational.

Returns:

Type	Description
bool	True if connected and operational, False otherwise

close async

close()

Close the camera and release resources.

Raises:

Type	Description
CameraConnectionError	If camera closure fails

get_gain_range async

get_gain_range() -> List[Union[int, float]]

Get camera gain range.

get_gain async

get_gain() -> float

Get current camera gain.

set_gain async

set_gain(gain: Union[int, float])

Set camera gain.

get_wb async

get_wb() -> str

Get current white balance mode using GenICam nodes.

Returns:

Type	Description
str	Current white balance mode string

Raises:

Type	Description
CameraConnectionError	If camera is not initialized

set_auto_wb_once async

set_auto_wb_once(value: str)

Execute automatic white balance once using GenICam nodes.

Parameters:

Name	Type	Description	Default
value	str	White balance mode ("auto", "once", "manual", "off")	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If white balance setting fails

get_wb_range async

get_wb_range() -> List[str]

Get available white balance modes using GenICam nodes.

Returns:

Type	Description
List[str]	List of available white balance mode strings

Raises:

Type	Description
CameraConnectionError	If camera is not initialized

import_config async

import_config(config_path: str)

Import camera configuration from JSON file.

Parameters:

Name	Type	Description	Default
config_path	str	Path to JSON configuration file	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If configuration file is invalid
HardwareOperationError	If configuration import fails

export_config async

export_config(config_path: str)

Export camera configuration to JSON file.

Parameters:

Name	Type	Description	Default
config_path	str	Path to save JSON configuration file	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If configuration export fails

set_ROI async

set_ROI(x: int, y: int, width: int, height: int)

Set Region of Interest using GenICam nodes.

Parameters:

Name	Type	Description	Default
x	int	Left offset	required
y	int	Top offset	required
width	int	Width of ROI	required
height	int	Height of ROI	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If ROI parameters are invalid
HardwareOperationError	If ROI setting fails

get_ROI async

get_ROI() -> Dict[str, int]

Get current ROI settings from GenICam nodes.

Returns:

Type	Description
Dict[str, int]	Dictionary with 'x', 'y', 'width', 'height' keys

Raises:

Type	Description
CameraConnectionError	If camera is not initialized

reset_ROI async

reset_ROI()

Reset ROI to maximum sensor area using GenICam nodes.

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If ROI reset fails

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Raises:

Type	Description
ValueError	If timeout_ms is negative

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

MockGenICamCameraBackend

MockGenICamCameraBackend(
    camera_name: str,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
    **backend_kwargs
)

Bases: CameraBackend

Mock GenICam Camera Backend Implementation

This class provides a mock implementation of the GenICam camera backend for testing and development. It simulates GenICam camera functionality without requiring actual hardware, Harvesters library, or GenTL Producer files.

Features

• Complete simulation of GenICam camera API
• Configurable image generation with realistic patterns
• Error simulation for testing error handling
• Configuration import/export simulation
• Camera control features (exposure, ROI, trigger modes, etc.)
• Vendor-specific quirks simulation (Keyence, Basler, etc.)
• Realistic timing and behavior simulation

Usage::

from mindtrace.hardware.cameras.backends.genicam import MockGenICamCameraBackend

camera = MockGenICamCameraBackend("mock_keyence_001", vendor="KEYENCE")
await camera.set_exposure(50000)
image = await camera.capture()
await camera.close()

Error Simulation

Enable error simulation via environment variables: - MOCK_GENICAM_FAIL_INIT: Simulate initialization failure - MOCK_GENICAM_FAIL_CAPTURE: Simulate capture failure - MOCK_GENICAM_TIMEOUT: Simulate timeout errors

Attributes:

Name	Type	Description
initialized	bool	Whether camera was successfully initialized
camera_name		Name/identifier of the mock camera
triggermode		Current trigger mode ("continuous" or "trigger")
img_quality_enhancement		Current image enhancement setting
timeout_ms		Capture timeout in milliseconds
retrieve_retry_count		Number of capture retry attempts
exposure_time		Current exposure time in microseconds
gain		Current gain value
roi		Current region of interest settings
vendor		Simulated camera vendor
model		Simulated camera model
serial_number		Simulated serial number
vendor_quirks		Vendor-specific parameter handling flags
image_counter		Counter for generating unique images
fail_init		Whether to simulate initialization failure
fail_capture		Whether to simulate capture failure
simulate_timeout		Whether to simulate timeout errors

Initialize mock GenICam camera.

Parameters:

Name	Type	Description	Default
camera_name	str	Camera identifier	required
camera_config	Optional[str]	Path to configuration file (simulated)	None
img_quality_enhancement	Optional[bool]	Enable image enhancement simulation (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of capture retry attempts (uses config default if None)	None
**backend_kwargs		Backend-specific parameters: - vendor: Simulated vendor ("KEYENCE", "BASLER", "FLIR", etc.) - model: Simulated model name - serial_number: Simulated serial number - cti_path: Simulated CTI path (ignored in mock) - timeout_ms: Timeout in milliseconds - buffer_count: Buffer count (simulated) - simulate_fail_init: If True, simulate initialization failure - simulate_fail_capture: If True, simulate capture failure - simulate_timeout: If True, simulate timeout on capture - synthetic_width: Override synthetic image width (int) - synthetic_height: Override synthetic image height (int) - synthetic_pattern: One of {"auto","gradient","checkerboard","circular","noise"} - synthetic_overlay_text: If False, disables text overlays in synthetic images	{}

Raises:

Type	Description
CameraConfigurationError	If configuration is invalid
CameraInitializationError	If initialization fails (when simulated)

get_available_cameras staticmethod

get_available_cameras(
    include_details: bool = False,
) -> Union[List[str], Dict[str, Dict[str, str]]]

Get available mock GenICam cameras.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return detailed information	False

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	List of camera names or dict with details

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the mock camera connection.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success status, mock camera object, device_info)

Raises:

Type	Description
CameraNotFoundError	If camera not found (when simulated)
CameraInitializationError	If initialization fails (when simulated)
CameraConnectionError	If connection fails (when simulated)

get_exposure_range async

get_exposure_range() -> List[Union[int, float]]

Get the simulated exposure time range in microseconds.

get_exposure async

get_exposure() -> float

Get current simulated exposure time in microseconds.

set_exposure async

set_exposure(exposure: Union[int, float])

Set the simulated camera exposure time in microseconds.

get_triggermode async

get_triggermode() -> str

Get current simulated trigger mode.

set_triggermode async

set_triggermode(triggermode: str = 'continuous')

Set the simulated camera's trigger mode.

capture async

capture() -> np.ndarray

Capture a simulated image from the mock camera.

check_connection async

check_connection() -> bool

Check if mock camera is connected and operational.

close async

close()

Close the mock camera and release simulated resources.

get_gain_range async

get_gain_range() -> List[Union[int, float]]

Get simulated camera gain range.

get_gain async

get_gain() -> float

Get current simulated camera gain.

set_gain async

set_gain(gain: Union[int, float])

Set simulated camera gain.

set_ROI async

set_ROI(x: int, y: int, width: int, height: int)

Set simulated Region of Interest.

get_ROI async

get_ROI() -> Dict[str, int]

Get current simulated ROI settings.

reset_ROI async

reset_ROI()

Reset simulated ROI to maximum sensor area.

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Raises:

Type	Description
ValueError	If timeout_ms is negative

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

import_config async

import_config(config_path: str)

Import simulated camera configuration from JSON file.

export_config async

export_config(config_path: str)

Export current simulated camera configuration to JSON file.

genicam_camera_backend

GenICam Camera Backend Module

GenICamCameraBackend

GenICamCameraBackend(
    camera_name: str,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
    **backend_kwargs
)

Bases: CameraBackend

GenICam Camera Backend Implementation

This class provides a comprehensive implementation for GenICam-compliant cameras using the Harvesters library with Matrix Vision GenTL Producer. It supports advanced camera features including trigger modes, exposure control, ROI settings, and image quality enhancement.

Thread Safety

Uses a singleton Harvester instance shared across all backend instances to avoid GenTL device conflicts. Multiple cameras can be opened simultaneously using the same Harvester.

Features

• Full GenICam camera support via Harvesters
• Matrix Vision GenTL Producer integration
• Hardware trigger and continuous capture modes
• ROI (Region of Interest) control
• Automatic exposure and gain control
• Image quality enhancement with CLAHE
• Configuration import/export functionality
• Robust error handling and connection management
• Vendor-specific parameter handling (Keyence, Basler, etc.)

Requirements

• Harvesters library (pip install harvesters)
• Matrix Vision mvIMPACT Acquire SDK
• OpenCV for image processing
• GenTL Producer (.cti file) installed on system

Installation

1. Install Matrix Vision mvIMPACT Acquire SDK
2. pip install harvesters opencv-python numpy
3. Configure network interface for GigE cameras
4. Set GENICAM_CTI_PATH environment variable (optional)

Usage::

from mindtrace.hardware.cameras.backends.genicam import GenICamCameraBackend

# Get available cameras
cameras = GenICamCameraBackend.get_available_cameras()

# Initialize camera
camera = GenICamCameraBackend("device_serial", img_quality_enhancement=True)
success, cam_obj, remote_obj = await camera.initialize()

if success:
    # Configure and capture
    await camera.set_exposure(50000)
    await camera.set_triggermode("continuous")
    image = await camera.capture()
    await camera.close()

Configuration

All parameters are configurable via environment variables or the hardware configuration system: - GENICAM_CTI_PATH: Path to GenTL Producer (.cti file) - MINDTRACE_CAMERA_EXPOSURE_TIME: Default exposure time in microseconds - MINDTRACE_CAMERA_TRIGGER_MODE: Default trigger mode ("continuous" or "trigger") - MINDTRACE_CAMERA_IMAGE_QUALITY_ENHANCEMENT: Enable CLAHE enhancement - MINDTRACE_CAMERA_RETRIEVE_RETRY_COUNT: Number of capture retry attempts - MINDTRACE_CAMERA_TIMEOUT_MS: Capture timeout in milliseconds

Supported Camera Models

• Keyence VJ series cameras
• Basler GigE cameras (alternative to pypylon)
• Allied Vision cameras
• FLIR/Teledyne cameras
• Any GenICam-compliant camera with compatible GenTL Producer

Error Handling

The class uses a comprehensive exception hierarchy for precise error reporting: - SDKNotAvailableError: Harvesters library not installed - CameraNotFoundError: Camera not detected or accessible - CameraInitializationError: Failed to initialize camera - CameraConfigurationError: Invalid configuration parameters - CameraConnectionError: Connection issues - CameraCaptureError: Image acquisition failures - CameraTimeoutError: Operation timeout - HardwareOperationError: General hardware operation failures

Attributes:

Name	Type	Description
initialized	bool	Whether camera was successfully initialized
image_acquirer	Optional[Any]	Harvesters ImageAcquirer object
harvester	Optional[Harvester]	Harvesters Harvester object
triggermode		Current trigger mode ("continuous" or "trigger")
img_quality_enhancement		Current image enhancement setting
timeout_ms		Capture timeout in milliseconds
retrieve_retry_count		Number of capture retry attempts
device_info	Optional[Dict[str, Any]]	Camera device information from discovery
vendor_quirks	Dict[str, bool]	Vendor-specific parameter handling flags
cti_path		Path to GenTL Producer file

Initialize GenICam camera with configurable parameters.

Parameters:

Name	Type	Description	Default
camera_name	str	Camera identifier (serial number, device ID, or user-defined name)	required
camera_config	Optional[str]	Path to JSON configuration file (optional)	None
img_quality_enhancement	Optional[bool]	Enable CLAHE image enhancement (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of capture retry attempts (uses config default if None)	None
**backend_kwargs		Backend-specific parameters: - cti_path: Path to GenTL Producer file (auto-detected if None) - timeout_ms: Capture timeout in milliseconds (uses config default if None) - buffer_count: Number of frame buffers (uses config default if None)	{}

Raises:

Type	Description
SDKNotAvailableError	If Harvesters library is not available
CameraConfigurationError	If configuration is invalid
CameraInitializationError	If camera initialization fails

get_available_cameras staticmethod

get_available_cameras(
    include_details: bool = False,
) -> Union[List[str], Dict[str, Dict[str, str]]]

Get available GenICam cameras.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return detailed information	False

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	List of camera names (serial numbers or device IDs) or dict with details

Raises:

Type	Description
SDKNotAvailableError	If Harvesters library is not available
HardwareOperationError	If camera discovery fails

discover_async async classmethod

discover_async(
    include_details: bool = False,
) -> Union[List[str], Dict[str, Dict[str, str]]]

Async wrapper for get_available_cameras() - runs discovery in threadpool.

Use this instead of get_available_cameras() when calling from async context to avoid blocking the event loop during camera discovery.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return detailed camera information	False

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	List of camera names or dict with details (same as get_available_cameras)

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the camera connection.

This searches for the camera by name, serial number, or device ID and establishes a connection if found.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success status, image_acquirer object, device_info)

Raises:

Type	Description
CameraNotFoundError	If no cameras found or specified camera not found
CameraInitializationError	If camera initialization fails
CameraConnectionError	If camera connection fails

get_exposure_range async

get_exposure_range() -> List[Union[int, float]]

Get the supported exposure time range in microseconds.

Returns:

Type	Description
List[Union[int, float]]	List with [min_exposure, max_exposure] in microseconds

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If exposure range retrieval fails

get_exposure async

get_exposure() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If exposure retrieval fails

set_exposure async

set_exposure(exposure: Union[int, float])

Set the camera exposure time in microseconds.

Parameters:

Name	Type	Description	Default
exposure	Union[int, float]	Exposure time in microseconds	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraConfigurationError	If exposure value is out of range
HardwareOperationError	If exposure setting fails

get_current_pixel_format async

get_current_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format string (e.g., "Mono8", "RGB8", "BayerRG8")

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If pixel format retrieval fails

get_width_range async

get_width_range() -> List[int]

Get camera width range.

Returns:

Type	Description
List[int]	List containing [min_width, max_width]

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If width range retrieval fails

get_height_range async

get_height_range() -> List[int]

Get camera height range.

Returns:

Type	Description
List[int]	List containing [min_height, max_height]

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If height range retrieval fails

get_pixel_format_range async

get_pixel_format_range() -> List[str]

Get list of supported pixel formats.

Returns:

Type	Description
List[str]	List of supported pixel format strings

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If pixel format list retrieval fails

set_pixel_format async

set_pixel_format(pixel_format: str)

Set the camera pixel format.

Parameters:

Name	Type	Description	Default
pixel_format	str	Pixel format string (e.g., "Mono8", "RGB8")	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraConfigurationError	If pixel format is not supported
HardwareOperationError	If pixel format setting fails

get_triggermode async

get_triggermode() -> str

Get current trigger mode.

Returns:

Type	Description
str	"continuous" or "trigger"

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
HardwareOperationError	If trigger mode retrieval fails

set_triggermode async

set_triggermode(triggermode: str = 'continuous')

Set the camera's trigger mode for image acquisition.

Parameters:

Name	Type	Description	Default
triggermode	str	Trigger mode ("continuous" or "trigger")	'continuous'

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraConfigurationError	If trigger mode is invalid
HardwareOperationError	If trigger mode setting fails

capture async

capture() -> np.ndarray

Capture a single image from the camera.

In continuous mode, returns the latest available frame. In trigger mode, executes a software trigger and waits for the image.

Returns:

Type	Description
ndarray	Image array in BGR format

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraCaptureError	If image capture fails
CameraTimeoutError	If capture times out

check_connection async

check_connection() -> bool

Check if camera is connected and operational.

Returns:

Type	Description
bool	True if connected and operational, False otherwise

close async

close()

Close the camera and release resources.

Raises:

Type	Description
CameraConnectionError	If camera closure fails

get_gain_range async

get_gain_range() -> List[Union[int, float]]

Get camera gain range.

get_gain async

get_gain() -> float

Get current camera gain.

set_gain async

set_gain(gain: Union[int, float])

Set camera gain.

get_wb async

get_wb() -> str

Get current white balance mode using GenICam nodes.

Returns:

Type	Description
str	Current white balance mode string

Raises:

Type	Description
CameraConnectionError	If camera is not initialized

set_auto_wb_once async

set_auto_wb_once(value: str)

Execute automatic white balance once using GenICam nodes.

Parameters:

Name	Type	Description	Default
value	str	White balance mode ("auto", "once", "manual", "off")	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If white balance setting fails

get_wb_range async

get_wb_range() -> List[str]

Get available white balance modes using GenICam nodes.

Returns:

Type	Description
List[str]	List of available white balance mode strings

Raises:

Type	Description
CameraConnectionError	If camera is not initialized

import_config async

import_config(config_path: str)

Import camera configuration from JSON file.

Parameters:

Name	Type	Description	Default
config_path	str	Path to JSON configuration file	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If configuration file is invalid
HardwareOperationError	If configuration import fails

export_config async

export_config(config_path: str)

Export camera configuration to JSON file.

Parameters:

Name	Type	Description	Default
config_path	str	Path to save JSON configuration file	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If configuration export fails

set_ROI async

set_ROI(x: int, y: int, width: int, height: int)

Set Region of Interest using GenICam nodes.

Parameters:

Name	Type	Description	Default
x	int	Left offset	required
y	int	Top offset	required
width	int	Width of ROI	required
height	int	Height of ROI	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If ROI parameters are invalid
HardwareOperationError	If ROI setting fails

get_ROI async

get_ROI() -> Dict[str, int]

Get current ROI settings from GenICam nodes.

Returns:

Type	Description
Dict[str, int]	Dictionary with 'x', 'y', 'width', 'height' keys

Raises:

Type	Description
CameraConnectionError	If camera is not initialized

reset_ROI async

reset_ROI()

Reset ROI to maximum sensor area using GenICam nodes.

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If ROI reset fails

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Raises:

Type	Description
ValueError	If timeout_ms is negative

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

mock_genicam_camera_backend

Mock GenICam Camera Backend Module

MockGenICamCameraBackend

MockGenICamCameraBackend(
    camera_name: str,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
    **backend_kwargs
)

Bases: CameraBackend

Mock GenICam Camera Backend Implementation

This class provides a mock implementation of the GenICam camera backend for testing and development. It simulates GenICam camera functionality without requiring actual hardware, Harvesters library, or GenTL Producer files.

Features

• Complete simulation of GenICam camera API
• Configurable image generation with realistic patterns
• Error simulation for testing error handling
• Configuration import/export simulation
• Camera control features (exposure, ROI, trigger modes, etc.)
• Vendor-specific quirks simulation (Keyence, Basler, etc.)
• Realistic timing and behavior simulation

Usage::

from mindtrace.hardware.cameras.backends.genicam import MockGenICamCameraBackend

camera = MockGenICamCameraBackend("mock_keyence_001", vendor="KEYENCE")
await camera.set_exposure(50000)
image = await camera.capture()
await camera.close()

Error Simulation

Enable error simulation via environment variables: - MOCK_GENICAM_FAIL_INIT: Simulate initialization failure - MOCK_GENICAM_FAIL_CAPTURE: Simulate capture failure - MOCK_GENICAM_TIMEOUT: Simulate timeout errors

Attributes:

Name	Type	Description
initialized	bool	Whether camera was successfully initialized
camera_name		Name/identifier of the mock camera
triggermode		Current trigger mode ("continuous" or "trigger")
img_quality_enhancement		Current image enhancement setting
timeout_ms		Capture timeout in milliseconds
retrieve_retry_count		Number of capture retry attempts
exposure_time		Current exposure time in microseconds
gain		Current gain value
roi		Current region of interest settings
vendor		Simulated camera vendor
model		Simulated camera model
serial_number		Simulated serial number
vendor_quirks		Vendor-specific parameter handling flags
image_counter		Counter for generating unique images
fail_init		Whether to simulate initialization failure
fail_capture		Whether to simulate capture failure
simulate_timeout		Whether to simulate timeout errors

Initialize mock GenICam camera.

Parameters:

Name	Type	Description	Default
camera_name	str	Camera identifier	required
camera_config	Optional[str]	Path to configuration file (simulated)	None
img_quality_enhancement	Optional[bool]	Enable image enhancement simulation (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of capture retry attempts (uses config default if None)	None
**backend_kwargs		Backend-specific parameters: - vendor: Simulated vendor ("KEYENCE", "BASLER", "FLIR", etc.) - model: Simulated model name - serial_number: Simulated serial number - cti_path: Simulated CTI path (ignored in mock) - timeout_ms: Timeout in milliseconds - buffer_count: Buffer count (simulated) - simulate_fail_init: If True, simulate initialization failure - simulate_fail_capture: If True, simulate capture failure - simulate_timeout: If True, simulate timeout on capture - synthetic_width: Override synthetic image width (int) - synthetic_height: Override synthetic image height (int) - synthetic_pattern: One of {"auto","gradient","checkerboard","circular","noise"} - synthetic_overlay_text: If False, disables text overlays in synthetic images	{}

Raises:

Type	Description
CameraConfigurationError	If configuration is invalid
CameraInitializationError	If initialization fails (when simulated)

get_available_cameras staticmethod

get_available_cameras(
    include_details: bool = False,
) -> Union[List[str], Dict[str, Dict[str, str]]]

Get available mock GenICam cameras.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return detailed information	False

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	List of camera names or dict with details

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the mock camera connection.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success status, mock camera object, device_info)

Raises:

Type	Description
CameraNotFoundError	If camera not found (when simulated)
CameraInitializationError	If initialization fails (when simulated)
CameraConnectionError	If connection fails (when simulated)

get_exposure_range async

get_exposure_range() -> List[Union[int, float]]

Get the simulated exposure time range in microseconds.

get_exposure async

get_exposure() -> float

Get current simulated exposure time in microseconds.

set_exposure async

set_exposure(exposure: Union[int, float])

Set the simulated camera exposure time in microseconds.

get_triggermode async

get_triggermode() -> str

Get current simulated trigger mode.

set_triggermode async

set_triggermode(triggermode: str = 'continuous')

Set the simulated camera's trigger mode.

capture async

capture() -> np.ndarray

Capture a simulated image from the mock camera.

check_connection async

check_connection() -> bool

Check if mock camera is connected and operational.

close async

close()

Close the mock camera and release simulated resources.

get_gain_range async

get_gain_range() -> List[Union[int, float]]

Get simulated camera gain range.

get_gain async

get_gain() -> float

Get current simulated camera gain.

set_gain async

set_gain(gain: Union[int, float])

Set simulated camera gain.

set_ROI async

set_ROI(x: int, y: int, width: int, height: int)

Set simulated Region of Interest.

get_ROI async

get_ROI() -> Dict[str, int]

Get current simulated ROI settings.

reset_ROI async

reset_ROI()

Reset simulated ROI to maximum sensor area.

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Raises:

Type	Description
ValueError	If timeout_ms is negative

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

import_config async

import_config(config_path: str)

Import simulated camera configuration from JSON file.

export_config async

export_config(config_path: str)

Export current simulated camera configuration to JSON file.

opencv

OpenCV Camera Backend

Provides support for USB cameras and webcams via OpenCV with comprehensive error handling.

Components

• OpenCVCameraBackend: OpenCV camera implementation (requires opencv-python)

Requirements

• opencv-python: For camera access and image processing
• numpy: For image array operations

Installation

pip install opencv-python numpy

Usage

from mindtrace.hardware.cameras.backends.opencv import OpenCVCameraBackend

USB camera (index 0)

if OPENCV_AVAILABLE: camera = OpenCVCameraBackend("0") success, cam_obj, remote_obj = await camera.initialize() # Initialize first if success: image = await camera.capture() await camera.close()

OpenCVCameraBackend

OpenCVCameraBackend(
    camera_name: str,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
    **backend_kwargs
)

Bases: CameraBackend

OpenCV camera implementation for USB cameras and webcams.

This backend provides a comprehensive interface to USB cameras, webcams, and other video capture devices using OpenCV's VideoCapture with robust error handling and resource management. It works across Windows, Linux, and macOS with platform-aware discovery.

Features

• USB camera and webcam support across Windows, Linux, and macOS
• Automatic camera discovery and enumeration
• Configurable resolution, frame rate, and exposure settings
• Optional image quality enhancement (CLAHE)
• Robust error handling with retries and bounded timeouts
• BGR to RGB conversion for consistency
• Thread-safe operations with per-instance serialization
• Platform-specific optimizations

Configuration

All parameters are configurable via the hardware configuration system: - MINDTRACE_CAMERA_OPENCV_DEFAULT_WIDTH: Default frame width (1280) - MINDTRACE_CAMERA_OPENCV_DEFAULT_HEIGHT: Default frame height (720) - MINDTRACE_CAMERA_OPENCV_DEFAULT_FPS: Default frame rate (30) - MINDTRACE_CAMERA_OPENCV_DEFAULT_EXPOSURE: Default exposure (-1 for auto) - MINDTRACE_CAMERA_OPENCV_MAX_CAMERA_INDEX: Maximum camera index to test (10) - MINDTRACE_CAMERA_IMAGE_QUALITY_ENHANCEMENT: Enable CLAHE enhancement - MINDTRACE_CAMERA_RETRIEVE_RETRY_COUNT: Number of capture retry attempts - MINDTRACE_CAMERA_TIMEOUT_MS: Capture timeout in milliseconds

Concurrency and serialization: - All OpenCV SDK calls are executed on a per-instance single-thread executor to maintain thread affinity. - A per-instance asyncio.Lock (_io_lock) serializes mutating operations to prevent concurrent set/read races. - Unlike Basler, OpenCV cameras do not have an explicit "grabbing" state; all operations use continuous mode.

Attributes:

Name	Type	Description
camera_index		Camera device index or path
cap	Optional[VideoCapture]	OpenCV VideoCapture object
initialized	bool	Camera initialization status
width	bool	Current frame width
height	bool	Current frame height
fps	bool	Current frame rate
exposure	bool	Current exposure setting
timeout_ms		Capture timeout in milliseconds

Example::

from mindtrace.hardware.cameras.backends.opencv import OpenCVCameraBackend

async def main():
    camera = OpenCVCameraBackend("0", width=1280, height=720)
    ok, cap, _ = await camera.initialize()
    if ok:
        image = await camera.capture()
        await camera.close()

Initialize OpenCV camera with configuration.

Parameters:

Name	Type	Description	Default
camera_name	str	Camera identifier (index number or device path)	required
camera_config	Optional[str]	Path to camera config file (not used for OpenCV)	None
img_quality_enhancement	Optional[bool]	Whether to apply image quality enhancement (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of times to retry capture (uses config default if None)	None
**backend_kwargs		Backend-specific parameters: - width: Frame width (uses config default if None) - height: Frame height (uses config default if None) - fps: Frame rate (uses config default if None) - exposure: Exposure value (uses config default if None) - timeout_ms: Capture timeout in milliseconds (uses config default if None)	{}

Raises:

Type	Description
SDKNotAvailableError	If OpenCV is not installed
CameraConfigurationError	If configuration is invalid
CameraInitializationError	If camera initialization fails

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the camera and establish connection.

Returns:

Type	Description
bool	Tuple[bool, Any, Any]: (success, camera_object, remote_control_object). For OpenCV
Any	cameras, both objects are the same VideoCapture instance.

Raises:

Type	Description
CameraNotFoundError	If camera cannot be opened
CameraInitializationError	If camera initialization fails
CameraConnectionError	If camera connection fails

get_available_cameras staticmethod

get_available_cameras(
    include_details: bool = False,
) -> Union[List[str], Dict[str, Dict[str, str]]]

Discover cameras with backend-aware probing.

• Linux: prefer CAP_V4L2 probing across indices
• Windows: try CAP_DSHOW then CAP_MSMF
• macOS: try CAP_AVFOUNDATION
• Fallback: default backend probing

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return a dict of details per camera.	False

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	Union[List[str], Dict[str, Dict[str, str]]]: List of camera names (e.g.,
Union[List[str], Dict[str, Dict[str, str]]]	["opencv_camera_0"]) or a dict of details when include_details=True.

discover_async async classmethod

discover_async(
    include_details: bool = False,
) -> Union[List[str], Dict[str, Dict[str, str]]]

Async wrapper for get_available_cameras() - runs discovery in threadpool.

Use this instead of get_available_cameras() when calling from async context to avoid blocking the event loop during camera enumeration.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return a dict of details per camera.	False

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	Union[List[str], Dict[str, Dict[str, str]]]: List of camera names or dict of details.

capture async

capture() -> np.ndarray

Capture an image from the camera.

Implements retry logic and proper error handling for robust image capture. Converts OpenCV's default BGR format to RGB for consistency.

Returns:

Type	Description
ndarray	np.ndarray: Captured image as an RGB numpy array.

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraCaptureError	If image capture fails
CameraTimeoutError	If capture times out

check_connection async

check_connection() -> bool

Check if camera connection is active and healthy.

Returns:

Type	Description
bool	True if camera is connected and responsive, False otherwise

close async

close()

Close camera connection and cleanup resources.

Properly releases the VideoCapture object and resets camera state.

Raises:

Type	Description
CameraConnectionError	If camera closure fails

is_exposure_control_supported async

is_exposure_control_supported() -> bool

Check if exposure control is actually supported for this camera. Tests both reading and setting exposure to verify true support. Returns: True if exposure control is supported, False otherwise

set_exposure async

set_exposure(exposure: Union[int, float])

Set camera exposure time.

Parameters:

Name	Type	Description	Default
exposure	Union[int, float]	Exposure value (OpenCV uses log scale, typically -13 to -1)	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If exposure value is invalid or unsupported
HardwareOperationError	If exposure setting fails

get_exposure async

get_exposure() -> float

Get current camera exposure time.

Returns:

Type	Description
float	Current exposure time value

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If exposure retrieval fails

get_exposure_range async

get_exposure_range() -> Optional[List[Union[int, float]]]

Get camera exposure time range.

Returns:

Type	Description
Optional[List[Union[int, float]]]	List containing [min_exposure, max_exposure] in OpenCV log scale, or None if exposure control not supported

get_width_range async

get_width_range() -> List[int]

Get supported width range.

Returns:

Type	Description
List[int]	List containing [min_width, max_width]

get_height_range async

get_height_range() -> List[int]

Get supported height range.

Returns:

Type	Description
List[int]	List containing [min_height, max_height]

get_gain_range async

get_gain_range() -> List[Union[int, float]]

Get the supported gain range.

Returns:

Type	Description
List[Union[int, float]]	List with [min_gain, max_gain]

set_gain async

set_gain(gain: Union[int, float])

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	Union[int, float]	Gain value	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If gain value is out of range or setting fails

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

set_ROI async

set_ROI(x: int, y: int, width: int, height: int)

Set Region of Interest (ROI).

Note: OpenCV cameras typically don't support hardware ROI; implement in software if needed.

Parameters:

Name	Type	Description	Default
x	int	ROI x offset	required
y	int	ROI y offset	required
width	int	ROI width	required
height	int	ROI height	required

Raises:

Type	Description
NotImplementedError	ROI is not supported by the OpenCV backend

get_ROI async

get_ROI() -> Dict[str, int]

Get current Region of Interest (ROI).

Returns:

Type	Description
Dict[str, int]	Dictionary with full frame dimensions (ROI not supported)

reset_ROI async

reset_ROI()

Reset ROI to full sensor size.

Raises:

Type	Description
NotImplementedError	ROI reset is not supported by the OpenCV backend

get_wb async

get_wb() -> str

Get current white balance mode.

Returns:

Type	Description
str	Current white balance mode ("auto" or "manual")

set_auto_wb_once async

set_auto_wb_once(value: str)

Set white balance mode.

Parameters:

Name	Type	Description	Default
value	str	White balance mode ("auto", "manual", "off")	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If value is invalid
HardwareOperationError	If the operation fails

get_wb_range async

get_wb_range() -> List[str]

Get available white balance modes.

Returns:

Type	Description
List[str]	List of available white balance modes

get_pixel_format_range async

get_pixel_format_range() -> List[str]

Get available pixel formats.

Returns:

Type	Description
List[str]	List of available pixel formats (OpenCV always uses BGR internally)

get_current_pixel_format async

get_current_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format (always BGR8 for OpenCV, converted to RGB8 in capture)

set_pixel_format async

set_pixel_format(pixel_format: str)

Set pixel format.

Parameters:

Name	Type	Description	Default
pixel_format	str	Pixel format to set	required

Raises:

Type	Description
CameraConfigurationError	If pixel format is not supported

get_triggermode async

get_triggermode() -> str

Get trigger mode (always continuous for USB cameras).

Returns:

Type	Description
str	"continuous" (USB cameras only support continuous mode)

set_triggermode async

set_triggermode(triggermode: str = 'continuous')

Set trigger mode.

USB cameras only support continuous mode.

Parameters:

Name	Type	Description	Default
triggermode	str	Trigger mode ("continuous" only)	'continuous'

Raises:

Type	Description
CameraConfigurationError	If trigger mode is not supported

get_image_quality_enhancement

get_image_quality_enhancement() -> bool

Get image quality enhancement status.

set_image_quality_enhancement

set_image_quality_enhancement(img_quality_enhancement: bool)

Set image quality enhancement.

Parameters:

Name	Type	Description	Default
img_quality_enhancement	bool	Whether to enable image quality enhancement	required

Raises:

Type	Description
HardwareOperationError	If setting cannot be applied

export_config async

export_config(config_path: str)

Export current camera configuration to common JSON format.

Parameters:

Name	Type	Description	Default
config_path	str	Path to save configuration file	required

Raises:

Type	Description
CameraConnectionError	If camera is not connected
CameraConfigurationError	If configuration export fails

import_config async

import_config(config_path: str)

Import camera configuration from common JSON format.

Parameters:

Name	Type	Description	Default
config_path	str	Path to configuration file	required

Raises:

Type	Description
CameraConnectionError	If camera is not connected
CameraConfigurationError	If configuration import fails

get_bandwidth_limit async

get_bandwidth_limit() -> float

Bandwidth limiting not applicable for OpenCV cameras.

get_packet_size async

get_packet_size() -> int

Packet size not applicable for OpenCV cameras.

get_inter_packet_delay async

get_inter_packet_delay() -> int

Inter-packet delay not applicable for OpenCV cameras.

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Raises:

Type	Description
ValueError	If timeout_ms is negative

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

get_trigger_modes async

get_trigger_modes() -> List[str]

Get available trigger modes for OpenCV cameras.

Returns:

Type	Description
List[str]	List of available trigger modes (OpenCV only supports continuous)

opencv_camera_backend

OpenCV camera backend module.

OpenCVCameraBackend

OpenCVCameraBackend(
    camera_name: str,
    camera_config: Optional[str] = None,
    img_quality_enhancement: Optional[bool] = None,
    retrieve_retry_count: Optional[int] = None,
    **backend_kwargs
)

Bases: CameraBackend

OpenCV camera implementation for USB cameras and webcams.

This backend provides a comprehensive interface to USB cameras, webcams, and other video capture devices using OpenCV's VideoCapture with robust error handling and resource management. It works across Windows, Linux, and macOS with platform-aware discovery.

Features

• USB camera and webcam support across Windows, Linux, and macOS
• Automatic camera discovery and enumeration
• Configurable resolution, frame rate, and exposure settings
• Optional image quality enhancement (CLAHE)
• Robust error handling with retries and bounded timeouts
• BGR to RGB conversion for consistency
• Thread-safe operations with per-instance serialization
• Platform-specific optimizations

Configuration

All parameters are configurable via the hardware configuration system: - MINDTRACE_CAMERA_OPENCV_DEFAULT_WIDTH: Default frame width (1280) - MINDTRACE_CAMERA_OPENCV_DEFAULT_HEIGHT: Default frame height (720) - MINDTRACE_CAMERA_OPENCV_DEFAULT_FPS: Default frame rate (30) - MINDTRACE_CAMERA_OPENCV_DEFAULT_EXPOSURE: Default exposure (-1 for auto) - MINDTRACE_CAMERA_OPENCV_MAX_CAMERA_INDEX: Maximum camera index to test (10) - MINDTRACE_CAMERA_IMAGE_QUALITY_ENHANCEMENT: Enable CLAHE enhancement - MINDTRACE_CAMERA_RETRIEVE_RETRY_COUNT: Number of capture retry attempts - MINDTRACE_CAMERA_TIMEOUT_MS: Capture timeout in milliseconds

Concurrency and serialization: - All OpenCV SDK calls are executed on a per-instance single-thread executor to maintain thread affinity. - A per-instance asyncio.Lock (_io_lock) serializes mutating operations to prevent concurrent set/read races. - Unlike Basler, OpenCV cameras do not have an explicit "grabbing" state; all operations use continuous mode.

Attributes:

Name	Type	Description
camera_index		Camera device index or path
cap	Optional[VideoCapture]	OpenCV VideoCapture object
initialized	bool	Camera initialization status
width	bool	Current frame width
height	bool	Current frame height
fps	bool	Current frame rate
exposure	bool	Current exposure setting
timeout_ms		Capture timeout in milliseconds

Example::

from mindtrace.hardware.cameras.backends.opencv import OpenCVCameraBackend

async def main():
    camera = OpenCVCameraBackend("0", width=1280, height=720)
    ok, cap, _ = await camera.initialize()
    if ok:
        image = await camera.capture()
        await camera.close()

Initialize OpenCV camera with configuration.

Parameters:

Name	Type	Description	Default
camera_name	str	Camera identifier (index number or device path)	required
camera_config	Optional[str]	Path to camera config file (not used for OpenCV)	None
img_quality_enhancement	Optional[bool]	Whether to apply image quality enhancement (uses config default if None)	None
retrieve_retry_count	Optional[int]	Number of times to retry capture (uses config default if None)	None
**backend_kwargs		Backend-specific parameters: - width: Frame width (uses config default if None) - height: Frame height (uses config default if None) - fps: Frame rate (uses config default if None) - exposure: Exposure value (uses config default if None) - timeout_ms: Capture timeout in milliseconds (uses config default if None)	{}

Raises:

Type	Description
SDKNotAvailableError	If OpenCV is not installed
CameraConfigurationError	If configuration is invalid
CameraInitializationError	If camera initialization fails

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the camera and establish connection.

Returns:

Type	Description
bool	Tuple[bool, Any, Any]: (success, camera_object, remote_control_object). For OpenCV
Any	cameras, both objects are the same VideoCapture instance.

Raises:

Type	Description
CameraNotFoundError	If camera cannot be opened
CameraInitializationError	If camera initialization fails
CameraConnectionError	If camera connection fails

get_available_cameras staticmethod

get_available_cameras(
    include_details: bool = False,
) -> Union[List[str], Dict[str, Dict[str, str]]]

Discover cameras with backend-aware probing.

• Linux: prefer CAP_V4L2 probing across indices
• Windows: try CAP_DSHOW then CAP_MSMF
• macOS: try CAP_AVFOUNDATION
• Fallback: default backend probing

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return a dict of details per camera.	False

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	Union[List[str], Dict[str, Dict[str, str]]]: List of camera names (e.g.,
Union[List[str], Dict[str, Dict[str, str]]]	["opencv_camera_0"]) or a dict of details when include_details=True.

discover_async async classmethod

discover_async(
    include_details: bool = False,
) -> Union[List[str], Dict[str, Dict[str, str]]]

Async wrapper for get_available_cameras() - runs discovery in threadpool.

Use this instead of get_available_cameras() when calling from async context to avoid blocking the event loop during camera enumeration.

Parameters:

Name	Type	Description	Default
include_details	bool	If True, return a dict of details per camera.	False

Returns:

Type	Description
Union[List[str], Dict[str, Dict[str, str]]]	Union[List[str], Dict[str, Dict[str, str]]]: List of camera names or dict of details.

capture async

capture() -> np.ndarray

Capture an image from the camera.

Implements retry logic and proper error handling for robust image capture. Converts OpenCV's default BGR format to RGB for consistency.

Returns:

Type	Description
ndarray	np.ndarray: Captured image as an RGB numpy array.

Raises:

Type	Description
CameraConnectionError	If camera is not initialized or accessible
CameraCaptureError	If image capture fails
CameraTimeoutError	If capture times out

check_connection async

check_connection() -> bool

Check if camera connection is active and healthy.

Returns:

Type	Description
bool	True if camera is connected and responsive, False otherwise

close async

close()

Close camera connection and cleanup resources.

Properly releases the VideoCapture object and resets camera state.

Raises:

Type	Description
CameraConnectionError	If camera closure fails

is_exposure_control_supported async

is_exposure_control_supported() -> bool

Check if exposure control is actually supported for this camera. Tests both reading and setting exposure to verify true support. Returns: True if exposure control is supported, False otherwise

set_exposure async

set_exposure(exposure: Union[int, float])

Set camera exposure time.

Parameters:

Name	Type	Description	Default
exposure	Union[int, float]	Exposure value (OpenCV uses log scale, typically -13 to -1)	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If exposure value is invalid or unsupported
HardwareOperationError	If exposure setting fails

get_exposure async

get_exposure() -> float

Get current camera exposure time.

Returns:

Type	Description
float	Current exposure time value

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
HardwareOperationError	If exposure retrieval fails

get_exposure_range async

get_exposure_range() -> Optional[List[Union[int, float]]]

Get camera exposure time range.

Returns:

Type	Description
Optional[List[Union[int, float]]]	List containing [min_exposure, max_exposure] in OpenCV log scale, or None if exposure control not supported

get_width_range async

get_width_range() -> List[int]

Get supported width range.

Returns:

Type	Description
List[int]	List containing [min_width, max_width]

get_height_range async

get_height_range() -> List[int]

Get supported height range.

Returns:

Type	Description
List[int]	List containing [min_height, max_height]

get_gain_range async

get_gain_range() -> List[Union[int, float]]

Get the supported gain range.

Returns:

Type	Description
List[Union[int, float]]	List with [min_gain, max_gain]

set_gain async

set_gain(gain: Union[int, float])

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	Union[int, float]	Gain value	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If gain value is out of range or setting fails

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

set_ROI async

set_ROI(x: int, y: int, width: int, height: int)

Set Region of Interest (ROI).

Note: OpenCV cameras typically don't support hardware ROI; implement in software if needed.

Parameters:

Name	Type	Description	Default
x	int	ROI x offset	required
y	int	ROI y offset	required
width	int	ROI width	required
height	int	ROI height	required

Raises:

Type	Description
NotImplementedError	ROI is not supported by the OpenCV backend

get_ROI async

get_ROI() -> Dict[str, int]

Get current Region of Interest (ROI).

Returns:

Type	Description
Dict[str, int]	Dictionary with full frame dimensions (ROI not supported)

reset_ROI async

reset_ROI()

Reset ROI to full sensor size.

Raises:

Type	Description
NotImplementedError	ROI reset is not supported by the OpenCV backend

get_wb async

get_wb() -> str

Get current white balance mode.

Returns:

Type	Description
str	Current white balance mode ("auto" or "manual")

set_auto_wb_once async

set_auto_wb_once(value: str)

Set white balance mode.

Parameters:

Name	Type	Description	Default
value	str	White balance mode ("auto", "manual", "off")	required

Raises:

Type	Description
CameraConnectionError	If camera is not initialized
CameraConfigurationError	If value is invalid
HardwareOperationError	If the operation fails

get_wb_range async

get_wb_range() -> List[str]

Get available white balance modes.

Returns:

Type	Description
List[str]	List of available white balance modes

get_pixel_format_range async

get_pixel_format_range() -> List[str]

Get available pixel formats.

Returns:

Type	Description
List[str]	List of available pixel formats (OpenCV always uses BGR internally)

get_current_pixel_format async

get_current_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format (always BGR8 for OpenCV, converted to RGB8 in capture)

set_pixel_format async

set_pixel_format(pixel_format: str)

Set pixel format.

Parameters:

Name	Type	Description	Default
pixel_format	str	Pixel format to set	required

Raises:

Type	Description
CameraConfigurationError	If pixel format is not supported

get_triggermode async

get_triggermode() -> str

Get trigger mode (always continuous for USB cameras).

Returns:

Type	Description
str	"continuous" (USB cameras only support continuous mode)

set_triggermode async

set_triggermode(triggermode: str = 'continuous')

Set trigger mode.

USB cameras only support continuous mode.

Parameters:

Name	Type	Description	Default
triggermode	str	Trigger mode ("continuous" only)	'continuous'

Raises:

Type	Description
CameraConfigurationError	If trigger mode is not supported

get_image_quality_enhancement

get_image_quality_enhancement() -> bool

Get image quality enhancement status.

set_image_quality_enhancement

set_image_quality_enhancement(img_quality_enhancement: bool)

Set image quality enhancement.

Parameters:

Name	Type	Description	Default
img_quality_enhancement	bool	Whether to enable image quality enhancement	required

Raises:

Type	Description
HardwareOperationError	If setting cannot be applied

export_config async

export_config(config_path: str)

Export current camera configuration to common JSON format.

Parameters:

Name	Type	Description	Default
config_path	str	Path to save configuration file	required

Raises:

Type	Description
CameraConnectionError	If camera is not connected
CameraConfigurationError	If configuration export fails

import_config async

import_config(config_path: str)

Import camera configuration from common JSON format.

Parameters:

Name	Type	Description	Default
config_path	str	Path to configuration file	required

Raises:

Type	Description
CameraConnectionError	If camera is not connected
CameraConfigurationError	If configuration import fails

get_bandwidth_limit async

get_bandwidth_limit() -> float

Bandwidth limiting not applicable for OpenCV cameras.

get_packet_size async

get_packet_size() -> int

Packet size not applicable for OpenCV cameras.

get_inter_packet_delay async

get_inter_packet_delay() -> int

Inter-packet delay not applicable for OpenCV cameras.

set_capture_timeout async

set_capture_timeout(timeout_ms: int)

Set capture timeout in milliseconds.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Timeout value in milliseconds	required

Raises:

Type	Description
ValueError	If timeout_ms is negative

get_capture_timeout async

get_capture_timeout() -> int

Get current capture timeout in milliseconds.

Returns:

Type	Description
int	Current timeout value in milliseconds

get_trigger_modes async

get_trigger_modes() -> List[str]

Get available trigger modes for OpenCV cameras.

Returns:

Type	Description
List[str]	List of available trigger modes (OpenCV only supports continuous)

homography

Homography-based planar measurement system.

This module provides homography calibration and measurement capabilities for converting pixel-space object detections to real-world metric dimensions on planar surfaces.

Features

• Automatic checkerboard calibration
• Manual point correspondence calibration
• RANSAC-based robust homography estimation
• Multi-unit measurement support (mm, cm, m, in, ft)
• Batch processing for multiple objects
• Framework-integrated logging and configuration

Typical Usage::

from mindtrace.hardware import HomographyCalibrator, HomographyMeasurer

# One-time calibration
calibrator = HomographyCalibrator()
calibration = calibrator.calibrate_checkerboard(
    image=checkerboard_image,
    board_size=(12, 12),
    square_size=25.0,
    world_unit="mm"
)
calibration.save("camera_calibration.json")

# Repeated measurement
measurer = HomographyMeasurer(calibration)
detections = yolo.detect(frame)
measurements = measurer.measure_bounding_boxes(detections, target_unit="cm")

for measured in measurements:
    print(f"Size: {measured.width_world:.1f} × {measured.height_world:.1f} cm")

HomographyCalibrator

HomographyCalibrator(**kwargs)

Bases: Mindtrace

Calibrates planar homography for pixel-to-world coordinate mapping.

Establishes a homography matrix H that maps planar world coordinates (X, Y, Z=0) in metric units to image pixel coordinates (u, v). Supports both automatic checkerboard-based calibration and manual point correspondence calibration.

The homography enables real-world measurements from camera images for objects lying on a known planar surface (e.g., overhead cameras, objects on tables/floors).

Features

• Automatic checkerboard pattern detection and calibration
• Manual point correspondence calibration
• RANSAC-based robust homography estimation
• Sub-pixel corner refinement for improved accuracy
• Lens distortion correction support
• Camera intrinsics estimation from FOV

Typical Workflow

1. Place calibration target (checkerboard) on measurement plane
2. Capture image with known world coordinates
3. Calibrate to obtain homography matrix
4. Use calibration for repeated measurements

Usage::

from mindtrace.hardware import HomographyCalibrator

# Automatic checkerboard calibration
calibrator = HomographyCalibrator()
calibration = calibrator.calibrate_checkerboard(
    image=checkerboard_image,
    board_size=(12, 12),     # Inner corners
    square_width=25.0,       # mm width per square
    square_height=25.0,      # mm height per square
    world_unit="mm"
)

# Manual point correspondence calibration
calibration = calibrator.calibrate_from_correspondences(
    world_points=[(0, 0), (300, 0), (300, 200), (0, 200)],  # mm
    image_points=[(100, 50), (500, 50), (500, 400), (100, 400)],  # pixels
    world_unit="mm"
)

# Save for later use
calibration.save("camera_calibration.json")

Configuration

All parameters can be configured via hardware config: - ransac_threshold: RANSAC reprojection error threshold (default: 3.0 pixels) - refine_corners: Enable sub-pixel corner refinement (default: True) - corner_refinement_window: Refinement window size (default: 11) - min_correspondences: Minimum points needed (default: 4) - default_world_unit: Default measurement unit (default: "mm")

Limitations

• Only works for planar surfaces (Z=0 assumption)
• Requires camera to remain fixed after calibration
• Accuracy degrades with severe viewing angles

Initialize homography calibrator.

Parameters:

Name	Type	Description	Default
**kwargs		Additional arguments passed to Mindtrace base class	{}

estimate_intrinsics_from_fov

estimate_intrinsics_from_fov(
    image_size: Tuple[int, int],
    fov_horizontal_deg: float,
    fov_vertical_deg: float,
    principal_point: Optional[Tuple[float, float]] = None,
) -> np.ndarray

Estimate camera intrinsics matrix from field-of-view parameters.

Computes a simple pinhole camera model intrinsics matrix (K) from the camera's horizontal and vertical field of view angles and image dimensions. Useful when full camera calibration is not available.

Parameters:

Name	Type	Description	Default
image_size	Tuple[int, int]	Image dimensions as (width, height) in pixels	required
fov_horizontal_deg	float	Horizontal field of view in degrees	required
fov_vertical_deg	float	Vertical field of view in degrees	required
principal_point	Optional[Tuple[float, float]]	Optional (cx, cy) principal point in pixels. Defaults to image center if not provided.	None

Returns:

Type	Description
ndarray	3x3 camera intrinsics matrix K

Example::

K = calibrator.estimate_intrinsics_from_fov(
    image_size=(1920, 1080),
    fov_horizontal_deg=70.0,
    fov_vertical_deg=45.0
)

calibrate_from_correspondences

calibrate_from_correspondences(
    world_points: ndarray,
    image_points: ndarray,
    world_unit: Optional[str] = None,
    camera_matrix: Optional[ndarray] = None,
    dist_coeffs: Optional[ndarray] = None,
) -> CalibrationData

Compute homography from known point correspondences.

Establishes the homography matrix H given known world coordinates (on Z=0 plane) and their corresponding image pixel coordinates. Uses RANSAC for robust estimation in the presence of outliers.

Parameters:

Name	Type	Description	Default
world_points	ndarray	Nx2 array of world coordinates in metric units (X, Y on Z=0 plane)	required
image_points	ndarray	Nx2 array of corresponding image coordinates in pixels (u, v)	required
world_unit	Optional[str]	Unit of world coordinates (e.g., 'mm', 'cm', 'm'). Uses config default if None.	None
camera_matrix	Optional[ndarray]	Optional 3x3 camera intrinsics matrix for undistortion	None
dist_coeffs	Optional[ndarray]	Optional distortion coefficients for undistortion	None

Returns:

Type	Description
CalibrationData	CalibrationData containing homography matrix and metadata

Raises:

Type	Description
CameraConfigurationError	If inputs are invalid (wrong shape, too few points)
HardwareOperationError	If homography estimation fails

Example::

# Four corner correspondences (world in mm, image in pixels)
world_pts = np.array([[0, 0], [300, 0], [300, 200], [0, 200]])
image_pts = np.array([[100, 50], [500, 50], [500, 400], [100, 400]])

calibration = calibrator.calibrate_from_correspondences(
    world_points=world_pts,
    image_points=image_pts,
    world_unit="mm"
)

calibrate_checkerboard

calibrate_checkerboard(
    image: Union[Image, ndarray],
    board_size: Optional[Tuple[int, int]] = None,
    square_size: Optional[float] = None,
    world_unit: Optional[str] = None,
    camera_matrix: Optional[ndarray] = None,
    dist_coeffs: Optional[ndarray] = None,
    refine_corners: Optional[bool] = None,
) -> CalibrationData

Automatic calibration from checkerboard pattern detection.

Detects a checkerboard calibration pattern in the image, extracts corner correspondences, and computes the homography matrix. The checkerboard is assumed to lie on the Z=0 plane with known square dimensions.

Parameters:

Name	Type	Description	Default
image	Union[Image, ndarray]	PIL Image or BGR numpy array containing checkerboard pattern	required
board_size	Optional[Tuple[int, int]]	Number of inner corners as (columns, rows). Uses config default if None. For a standard 8x8 checkerboard, use (7, 7).	None
square_size	Optional[float]	Physical size of one checkerboard square in world units. Uses config default if None.	None
world_unit	Optional[str]	Unit of square_size (e.g., 'mm', 'cm', 'm'). Uses config default if None.	None
camera_matrix	Optional[ndarray]	Optional 3x3 camera intrinsics matrix for undistortion	None
dist_coeffs	Optional[ndarray]	Optional distortion coefficients for undistortion	None
refine_corners	Optional[bool]	Enable sub-pixel corner refinement. Uses config default if None.	None

Returns:

Type	Description
CalibrationData	CalibrationData containing homography matrix and metadata

Raises:

Type	Description
CameraConfigurationError	If image format is unsupported
HardwareOperationError	If checkerboard detection fails

Example::

# Use config defaults for standard calibration board
calibration = calibrator.calibrate_checkerboard(image=checkerboard_image)

# Or override specific parameters
calibration = calibrator.calibrate_checkerboard(
    image=checkerboard_image,
    board_size=(9, 6),         # Custom board size
    square_size=30.0,          # Custom square size
    world_unit="mm"
)

Notes

• board_size is the number of INNER corners, not squares
• A standard 8x8 checkerboard has 7x7 inner corners
• Ensure good lighting and focus for accurate detection
• Checkerboard should fill significant portion of image
• If using a standard calibration board, configure dimensions via: MINDTRACE_HW_HOMOGRAPHY_CHECKERBOARD_COLS MINDTRACE_HW_HOMOGRAPHY_CHECKERBOARD_ROWS MINDTRACE_HW_HOMOGRAPHY_CHECKERBOARD_SQUARE

calibrate_checkerboard_multi_view

calibrate_checkerboard_multi_view(
    images: list[Union[Image, ndarray]],
    positions: list[Tuple[float, float]],
    board_size: Optional[Tuple[int, int]] = None,
    square_width: Optional[float] = None,
    square_height: Optional[float] = None,
    world_unit: Optional[str] = None,
    camera_matrix: Optional[ndarray] = None,
    dist_coeffs: Optional[ndarray] = None,
    refine_corners: Optional[bool] = None,
) -> CalibrationData

Calibrate from multiple checkerboard positions on the same plane.

Combines corner detections from multiple images where the checkerboard is placed at different positions on the measurement plane. This provides better calibration coverage over large areas without requiring an oversized calibration target.

Ideal for calibrating long surfaces (e.g., metallic bars, conveyor belts) using a standard-sized checkerboard moved to multiple positions.

Parameters:

Name	Type	Description	Default
images	list[Union[Image, ndarray]]	List of images, each containing the checkerboard at a different position	required
positions	list[Tuple[float, float]]	List of (x_offset, y_offset) tuples in world units specifying the checkerboard's origin position in each image. The first position is typically (0, 0), and subsequent positions indicate how far the checkerboard was moved.	required
board_size	Optional[Tuple[int, int]]	Number of inner corners as (columns, rows). Uses config default if None.	None
square_width	Optional[float]	Physical width of one checkerboard square in world units. Uses config default if None.	None
square_height	Optional[float]	Physical height of one checkerboard square in world units. Uses config default if None.	None
world_unit	Optional[str]	Unit of positions and square_width/height. Uses config default if None.	None
camera_matrix	Optional[ndarray]	Optional 3x3 camera intrinsics matrix for undistortion	None
dist_coeffs	Optional[ndarray]	Optional distortion coefficients for undistortion	None
refine_corners	Optional[bool]	Enable sub-pixel corner refinement. Uses config default if None.	None

Returns:

Type	Description
CalibrationData	CalibrationData containing homography matrix computed from all positions

Raises:

Type	Description
CameraConfigurationError	If inputs are invalid or inconsistent
HardwareOperationError	If checkerboard detection fails in any image

Example::

# Calibrate a 2-meter long bar using 3 checkerboard positions
images = [image1, image2, image3]
positions = [
    (0, 0),      # Start of bar
    (1000, 0),   # Middle (1000mm from start)
    (2000, 0)    # End (2000mm from start)
]

calibration = calibrator.calibrate_checkerboard_multi_view(
    images=images,
    positions=positions,
    board_size=(12, 12),
    square_width=25.0,    # 25mm wide squares
    square_height=25.0,   # 25mm tall squares
    world_unit="mm"
)

Notes

• All images must show the same plane (Z=0)
• Positions specify where the checkerboard origin (top-left corner) is located
• Use more positions for better coverage of large measurement areas
• Typical usage: 3-5 positions for long surfaces
• RANSAC automatically handles slight inaccuracies in position measurements

CalibrationData dataclass

CalibrationData(
    H: ndarray,
    camera_matrix: Optional[ndarray] = None,
    dist_coeffs: Optional[ndarray] = None,
    world_unit: str = "mm",
    plane_normal_camera: Optional[ndarray] = None,
)

Immutable container for homography calibration data.

Holds the homography matrix and optional camera intrinsics derived or provided during calibration. The homography maps world plane coordinates (Z=0) in metric units to image pixel coordinates.

Attributes:

Name	Type	Description
H	ndarray	3x3 homography matrix from world plane (Z=0) to image pixels
camera_matrix	Optional[ndarray]	3x3 camera intrinsics matrix (K) if known or estimated
dist_coeffs	Optional[ndarray]	Lens distortion coefficients if available
world_unit	str	Unit used for world coordinates (e.g., 'mm', 'cm', 'm', 'in', 'ft')
plane_normal_camera	Optional[ndarray]	Optional 3D normal of the plane in camera frame if recovered

save

save(filepath: str) -> None

Save calibration data to JSON file.

Parameters:

Name	Type	Description	Default
filepath	str	Path to save the calibration data	required

Note

NumPy arrays are converted to lists for JSON serialization.

load classmethod

load(filepath: str) -> CalibrationData

Load calibration data from JSON file.

Parameters:

Name	Type	Description	Default
filepath	str	Path to the calibration data file	required

Returns:

Type	Description
CalibrationData	CalibrationData instance loaded from file

Raises:

Type	Description
FileNotFoundError	If the file doesn't exist
ValueError	If the file format is invalid

MeasuredBox dataclass

MeasuredBox(
    corners_world: ndarray,
    width_world: float,
    height_world: float,
    area_world: float,
    unit: str,
)

Immutable container for metric-space measurement of a bounding box.

Stores the result of projecting a pixel-space bounding box to world coordinates on a planar surface using homography inversion. Contains the projected corner points and computed physical dimensions.

Attributes:

Name	Type	Description
corners_world	ndarray	4x2 array of corner coordinates in world units (top-left, top-right, bottom-right, bottom-left)
width_world	float	Width in world units (distance between top-left and top-right)
height_world	float	Height in world units (distance between top-left and bottom-left)
area_world	float	Area in square world units (computed via shoelace formula)
unit	str	Unit of measurement (e.g., 'mm', 'cm', 'm', 'in', 'ft')

to_dict

to_dict() -> dict

Convert measurement to dictionary.

Returns:

Type	Description
dict	Dictionary representation with corners as list

HomographyMeasurer

HomographyMeasurer(calibration: CalibrationData, **kwargs)

Bases: Mindtrace

Measures physical dimensions of objects using planar homography.

Projects pixel-space bounding boxes from object detection to real-world metric coordinates on a planar surface using a pre-calibrated homography matrix. Enables accurate physical size measurements from camera images.

The measurer uses the inverse homography (H⁻¹) to map image pixels back to world coordinates, then computes Euclidean distances and polygon areas for size measurements.

Features

• Pixel-to-world coordinate projection
• Bounding box dimension measurement (width, height, area)
• Multi-unit support with automatic conversion
• Batch processing for multiple detections
• Pre-computed inverse homography for performance

Typical Workflow

1. Calibrate camera view to obtain HomographyCalibrator.calibrate_*()
2. Create measurer with calibration data
3. Detect objects with vision model (YOLO, etc.)
4. Measure physical dimensions from bounding boxes
5. Apply size-based filtering or quality control

Usage::

from mindtrace.hardware import HomographyCalibrator, HomographyMeasurer
from mindtrace.core.types import BoundingBox

# One-time calibration
calibrator = HomographyCalibrator()
calibration = calibrator.calibrate_checkerboard(
    image=checkerboard_image,
    board_size=(12, 12),
    square_size=25.0,
    world_unit="mm"
)

# Create measurer (reuse for all measurements)
measurer = HomographyMeasurer(calibration)

# Measure objects from detection results
detections = yolo.detect(frame)  # List[BoundingBox]
measurements = measurer.measure_bounding_boxes(detections, target_unit="cm")

for measured in measurements:
    print(f"Width: {measured.width_world:.2f} cm")
    print(f"Height: {measured.height_world:.2f} cm")
    print(f"Area: {measured.area_world:.2f} cm²")

    # Size-based filtering
    if measured.width_world > 10.0:
        reject_oversized_part(measured)

Configuration

• Supported units: mm, cm, m, in, ft (configurable via hardware config)
• Default world unit: Inherited from calibration data

Limitations

• Only works for planar surfaces (Z=0 assumption)
• Accuracy depends on calibration quality and viewing angle
• Assumes objects lie flat on the calibrated plane
• Camera must remain fixed after calibration

Initialize homography measurer with calibration data.

Parameters:

Name	Type	Description	Default
calibration	CalibrationData	CalibrationData from HomographyCalibrator	required
**kwargs		Additional arguments passed to Mindtrace base class	{}

Raises:

Type	Description
CameraConfigurationError	If homography matrix is invalid

pixels_to_world

pixels_to_world(points_px: ndarray) -> np.ndarray

Project pixel coordinates to world plane coordinates.

Maps Nx2 pixel coordinates to world plane coordinates using the inverse homography matrix H⁻¹. This is the core projection operation for all measurement functionality.

Parameters:

Name	Type	Description	Default
points_px	ndarray	Nx2 array of pixel coordinates (u, v)	required

Returns:

Type	Description
ndarray	Nx2 array of world coordinates (X, Y) in calibration world unit

Raises:

Type	Description
CameraConfigurationError	If input array has wrong shape

Example::

# Project single point
world_point = measurer.pixels_to_world(np.array([[320, 240]]))

# Project multiple points
pixel_corners = np.array([[100, 50], [500, 50], [500, 400], [100, 400]])
world_corners = measurer.pixels_to_world(pixel_corners)

measure_bounding_box

measure_bounding_box(
    box: BoundingBox, target_unit: Optional[str] = None
) -> MeasuredBox

Measure physical dimensions of a bounding box on the calibrated plane.

Projects the four corners of a pixel-space bounding box to world coordinates, then computes width, height, and area in the specified unit.

Parameters:

Name	Type	Description	Default
box	BoundingBox	BoundingBox from object detection (x, y, width, height in pixels)	required
target_unit	Optional[str]	Unit for output measurements (e.g., 'cm', 'm'). Uses calibration unit if None.	None

Returns:

Type	Description
MeasuredBox	MeasuredBox with physical dimensions and corner coordinates

Example::

# From object detection
detection = BoundingBox(x=100, y=50, width=400, height=350)
measured = measurer.measure_bounding_box(detection, target_unit="cm")

print(f"Object is {measured.width_world:.1f} × {measured.height_world:.1f} cm")
print(f"Area: {measured.area_world:.1f} cm²")

measure_bounding_boxes

measure_bounding_boxes(
    boxes: Sequence[BoundingBox], target_unit: Optional[str] = None
) -> List[MeasuredBox]

Measure physical dimensions of multiple bounding boxes.

Batch processing of multiple object detections. More efficient than calling measure_bounding_box() in a loop.

Parameters:

Name	Type	Description	Default
boxes	Sequence[BoundingBox]	Sequence of BoundingBox objects from object detection	required
target_unit	Optional[str]	Unit for output measurements. Uses calibration unit if None.	None

Returns:

Type	Description
List[MeasuredBox]	List of MeasuredBox objects with physical dimensions

Example::

# Batch measurement from multiple detections
detections = yolo.detect(frame)  # List[BoundingBox]
measurements = measurer.measure_bounding_boxes(detections, target_unit="cm")

# Size-based filtering
large_objects = [m for m in measurements if m.width_world > 15.0]

# Quality control
for measured in measurements:
    if not (10.0 <= measured.width_world <= 20.0):
        reject_part(measured)

measure_distance

measure_distance(
    point1: Union[Tuple[float, float], ndarray],
    point2: Union[Tuple[float, float], ndarray],
    target_unit: Optional[str] = None,
) -> Tuple[float, str]

Measure Euclidean distance between two points on the calibrated plane.

Converts pixel coordinates to world coordinates and computes the distance. Useful for measuring gaps, spacing, or verifying known distances.

Parameters:

Name	Type	Description	Default
point1	Union[Tuple[float, float], ndarray]	First point as (x, y) pixel coordinates	required
point2	Union[Tuple[float, float], ndarray]	Second point as (x, y) pixel coordinates	required
target_unit	Optional[str]	Unit for output distance. Uses calibration unit if None.	None

Returns:

Type	Description
Tuple[float, str]	Tuple of (distance, unit)

Raises:

Type	Description
ValueError	If target_unit is not supported

Example::

# Measure distance between two detected points
point1 = (150, 200)  # pixels
point2 = (350, 200)  # pixels
distance, unit = measurer.measure_distance(point1, point2, target_unit="mm")
print(f"Distance: {distance:.2f} {unit}")

# Verify calibration accuracy
known_distance_mm = 100.0
measured_distance, _ = measurer.measure_distance(ref_point1, ref_point2, "mm")
error_percent = abs(measured_distance - known_distance_mm) / known_distance_mm * 100
print(f"Calibration error: {error_percent:.2f}%")

calibrator

Homography calibration for planar surface measurement.

This module provides calibration methods for establishing the relationship between image pixel coordinates and real-world metric coordinates on a planar surface.

HomographyCalibrator

HomographyCalibrator(**kwargs)

Bases: Mindtrace

Calibrates planar homography for pixel-to-world coordinate mapping.

Establishes a homography matrix H that maps planar world coordinates (X, Y, Z=0) in metric units to image pixel coordinates (u, v). Supports both automatic checkerboard-based calibration and manual point correspondence calibration.

The homography enables real-world measurements from camera images for objects lying on a known planar surface (e.g., overhead cameras, objects on tables/floors).

Features

• Automatic checkerboard pattern detection and calibration
• Manual point correspondence calibration
• RANSAC-based robust homography estimation
• Sub-pixel corner refinement for improved accuracy
• Lens distortion correction support
• Camera intrinsics estimation from FOV

Typical Workflow

1. Place calibration target (checkerboard) on measurement plane
2. Capture image with known world coordinates
3. Calibrate to obtain homography matrix
4. Use calibration for repeated measurements

Usage::

from mindtrace.hardware import HomographyCalibrator

# Automatic checkerboard calibration
calibrator = HomographyCalibrator()
calibration = calibrator.calibrate_checkerboard(
    image=checkerboard_image,
    board_size=(12, 12),     # Inner corners
    square_width=25.0,       # mm width per square
    square_height=25.0,      # mm height per square
    world_unit="mm"
)

# Manual point correspondence calibration
calibration = calibrator.calibrate_from_correspondences(
    world_points=[(0, 0), (300, 0), (300, 200), (0, 200)],  # mm
    image_points=[(100, 50), (500, 50), (500, 400), (100, 400)],  # pixels
    world_unit="mm"
)

# Save for later use
calibration.save("camera_calibration.json")

Configuration

All parameters can be configured via hardware config: - ransac_threshold: RANSAC reprojection error threshold (default: 3.0 pixels) - refine_corners: Enable sub-pixel corner refinement (default: True) - corner_refinement_window: Refinement window size (default: 11) - min_correspondences: Minimum points needed (default: 4) - default_world_unit: Default measurement unit (default: "mm")

Limitations

• Only works for planar surfaces (Z=0 assumption)
• Requires camera to remain fixed after calibration
• Accuracy degrades with severe viewing angles

Initialize homography calibrator.

Parameters:

Name	Type	Description	Default
**kwargs		Additional arguments passed to Mindtrace base class	{}

estimate_intrinsics_from_fov

estimate_intrinsics_from_fov(
    image_size: Tuple[int, int],
    fov_horizontal_deg: float,
    fov_vertical_deg: float,
    principal_point: Optional[Tuple[float, float]] = None,
) -> np.ndarray

Estimate camera intrinsics matrix from field-of-view parameters.

Computes a simple pinhole camera model intrinsics matrix (K) from the camera's horizontal and vertical field of view angles and image dimensions. Useful when full camera calibration is not available.

Parameters:

Name	Type	Description	Default
image_size	Tuple[int, int]	Image dimensions as (width, height) in pixels	required
fov_horizontal_deg	float	Horizontal field of view in degrees	required
fov_vertical_deg	float	Vertical field of view in degrees	required
principal_point	Optional[Tuple[float, float]]	Optional (cx, cy) principal point in pixels. Defaults to image center if not provided.	None

Returns:

Type	Description
ndarray	3x3 camera intrinsics matrix K

Example::

K = calibrator.estimate_intrinsics_from_fov(
    image_size=(1920, 1080),
    fov_horizontal_deg=70.0,
    fov_vertical_deg=45.0
)

calibrate_from_correspondences

calibrate_from_correspondences(
    world_points: ndarray,
    image_points: ndarray,
    world_unit: Optional[str] = None,
    camera_matrix: Optional[ndarray] = None,
    dist_coeffs: Optional[ndarray] = None,
) -> CalibrationData

Compute homography from known point correspondences.

Establishes the homography matrix H given known world coordinates (on Z=0 plane) and their corresponding image pixel coordinates. Uses RANSAC for robust estimation in the presence of outliers.

Parameters:

Name	Type	Description	Default
world_points	ndarray	Nx2 array of world coordinates in metric units (X, Y on Z=0 plane)	required
image_points	ndarray	Nx2 array of corresponding image coordinates in pixels (u, v)	required
world_unit	Optional[str]	Unit of world coordinates (e.g., 'mm', 'cm', 'm'). Uses config default if None.	None
camera_matrix	Optional[ndarray]	Optional 3x3 camera intrinsics matrix for undistortion	None
dist_coeffs	Optional[ndarray]	Optional distortion coefficients for undistortion	None

Returns:

Type	Description
CalibrationData	CalibrationData containing homography matrix and metadata

Raises:

Type	Description
CameraConfigurationError	If inputs are invalid (wrong shape, too few points)
HardwareOperationError	If homography estimation fails

Example::

# Four corner correspondences (world in mm, image in pixels)
world_pts = np.array([[0, 0], [300, 0], [300, 200], [0, 200]])
image_pts = np.array([[100, 50], [500, 50], [500, 400], [100, 400]])

calibration = calibrator.calibrate_from_correspondences(
    world_points=world_pts,
    image_points=image_pts,
    world_unit="mm"
)

calibrate_checkerboard

calibrate_checkerboard(
    image: Union[Image, ndarray],
    board_size: Optional[Tuple[int, int]] = None,
    square_size: Optional[float] = None,
    world_unit: Optional[str] = None,
    camera_matrix: Optional[ndarray] = None,
    dist_coeffs: Optional[ndarray] = None,
    refine_corners: Optional[bool] = None,
) -> CalibrationData

Automatic calibration from checkerboard pattern detection.

Detects a checkerboard calibration pattern in the image, extracts corner correspondences, and computes the homography matrix. The checkerboard is assumed to lie on the Z=0 plane with known square dimensions.

Parameters:

Name	Type	Description	Default
image	Union[Image, ndarray]	PIL Image or BGR numpy array containing checkerboard pattern	required
board_size	Optional[Tuple[int, int]]	Number of inner corners as (columns, rows). Uses config default if None. For a standard 8x8 checkerboard, use (7, 7).	None
square_size	Optional[float]	Physical size of one checkerboard square in world units. Uses config default if None.	None
world_unit	Optional[str]	Unit of square_size (e.g., 'mm', 'cm', 'm'). Uses config default if None.	None
camera_matrix	Optional[ndarray]	Optional 3x3 camera intrinsics matrix for undistortion	None
dist_coeffs	Optional[ndarray]	Optional distortion coefficients for undistortion	None
refine_corners	Optional[bool]	Enable sub-pixel corner refinement. Uses config default if None.	None

Returns:

Type	Description
CalibrationData	CalibrationData containing homography matrix and metadata

Raises:

Type	Description
CameraConfigurationError	If image format is unsupported
HardwareOperationError	If checkerboard detection fails

Example::

# Use config defaults for standard calibration board
calibration = calibrator.calibrate_checkerboard(image=checkerboard_image)

# Or override specific parameters
calibration = calibrator.calibrate_checkerboard(
    image=checkerboard_image,
    board_size=(9, 6),         # Custom board size
    square_size=30.0,          # Custom square size
    world_unit="mm"
)

Notes

• board_size is the number of INNER corners, not squares
• A standard 8x8 checkerboard has 7x7 inner corners
• Ensure good lighting and focus for accurate detection
• Checkerboard should fill significant portion of image
• If using a standard calibration board, configure dimensions via: MINDTRACE_HW_HOMOGRAPHY_CHECKERBOARD_COLS MINDTRACE_HW_HOMOGRAPHY_CHECKERBOARD_ROWS MINDTRACE_HW_HOMOGRAPHY_CHECKERBOARD_SQUARE

calibrate_checkerboard_multi_view

calibrate_checkerboard_multi_view(
    images: list[Union[Image, ndarray]],
    positions: list[Tuple[float, float]],
    board_size: Optional[Tuple[int, int]] = None,
    square_width: Optional[float] = None,
    square_height: Optional[float] = None,
    world_unit: Optional[str] = None,
    camera_matrix: Optional[ndarray] = None,
    dist_coeffs: Optional[ndarray] = None,
    refine_corners: Optional[bool] = None,
) -> CalibrationData

Calibrate from multiple checkerboard positions on the same plane.

Combines corner detections from multiple images where the checkerboard is placed at different positions on the measurement plane. This provides better calibration coverage over large areas without requiring an oversized calibration target.

Ideal for calibrating long surfaces (e.g., metallic bars, conveyor belts) using a standard-sized checkerboard moved to multiple positions.

Parameters:

Name	Type	Description	Default
images	list[Union[Image, ndarray]]	List of images, each containing the checkerboard at a different position	required
positions	list[Tuple[float, float]]	List of (x_offset, y_offset) tuples in world units specifying the checkerboard's origin position in each image. The first position is typically (0, 0), and subsequent positions indicate how far the checkerboard was moved.	required
board_size	Optional[Tuple[int, int]]	Number of inner corners as (columns, rows). Uses config default if None.	None
square_width	Optional[float]	Physical width of one checkerboard square in world units. Uses config default if None.	None
square_height	Optional[float]	Physical height of one checkerboard square in world units. Uses config default if None.	None
world_unit	Optional[str]	Unit of positions and square_width/height. Uses config default if None.	None
camera_matrix	Optional[ndarray]	Optional 3x3 camera intrinsics matrix for undistortion	None
dist_coeffs	Optional[ndarray]	Optional distortion coefficients for undistortion	None
refine_corners	Optional[bool]	Enable sub-pixel corner refinement. Uses config default if None.	None

Returns:

Type	Description
CalibrationData	CalibrationData containing homography matrix computed from all positions

Raises:

Type	Description
CameraConfigurationError	If inputs are invalid or inconsistent
HardwareOperationError	If checkerboard detection fails in any image

Example::

# Calibrate a 2-meter long bar using 3 checkerboard positions
images = [image1, image2, image3]
positions = [
    (0, 0),      # Start of bar
    (1000, 0),   # Middle (1000mm from start)
    (2000, 0)    # End (2000mm from start)
]

calibration = calibrator.calibrate_checkerboard_multi_view(
    images=images,
    positions=positions,
    board_size=(12, 12),
    square_width=25.0,    # 25mm wide squares
    square_height=25.0,   # 25mm tall squares
    world_unit="mm"
)

Notes

• All images must show the same plane (Z=0)
• Positions specify where the checkerboard origin (top-left corner) is located
• Use more positions for better coverage of large measurement areas
• Typical usage: 3-5 positions for long surfaces
• RANSAC automatically handles slight inaccuracies in position measurements

data

Data structures for homography calibration and measurement.

This module defines immutable data containers for homography-based measurement operations.

CalibrationData dataclass

CalibrationData(
    H: ndarray,
    camera_matrix: Optional[ndarray] = None,
    dist_coeffs: Optional[ndarray] = None,
    world_unit: str = "mm",
    plane_normal_camera: Optional[ndarray] = None,
)

Immutable container for homography calibration data.

Holds the homography matrix and optional camera intrinsics derived or provided during calibration. The homography maps world plane coordinates (Z=0) in metric units to image pixel coordinates.

Attributes:

Name	Type	Description
H	ndarray	3x3 homography matrix from world plane (Z=0) to image pixels
camera_matrix	Optional[ndarray]	3x3 camera intrinsics matrix (K) if known or estimated
dist_coeffs	Optional[ndarray]	Lens distortion coefficients if available
world_unit	str	Unit used for world coordinates (e.g., 'mm', 'cm', 'm', 'in', 'ft')
plane_normal_camera	Optional[ndarray]	Optional 3D normal of the plane in camera frame if recovered

save

save(filepath: str) -> None

Save calibration data to JSON file.

Parameters:

Name	Type	Description	Default
filepath	str	Path to save the calibration data	required

Note

NumPy arrays are converted to lists for JSON serialization.

load classmethod

load(filepath: str) -> CalibrationData

Load calibration data from JSON file.

Parameters:

Name	Type	Description	Default
filepath	str	Path to the calibration data file	required

Returns:

Type	Description
CalibrationData	CalibrationData instance loaded from file

Raises:

Type	Description
FileNotFoundError	If the file doesn't exist
ValueError	If the file format is invalid

MeasuredBox dataclass

MeasuredBox(
    corners_world: ndarray,
    width_world: float,
    height_world: float,
    area_world: float,
    unit: str,
)

Immutable container for metric-space measurement of a bounding box.

Stores the result of projecting a pixel-space bounding box to world coordinates on a planar surface using homography inversion. Contains the projected corner points and computed physical dimensions.

Attributes:

Name	Type	Description
corners_world	ndarray	4x2 array of corner coordinates in world units (top-left, top-right, bottom-right, bottom-left)
width_world	float	Width in world units (distance between top-left and top-right)
height_world	float	Height in world units (distance between top-left and bottom-left)
area_world	float	Area in square world units (computed via shoelace formula)
unit	str	Unit of measurement (e.g., 'mm', 'cm', 'm', 'in', 'ft')

to_dict

to_dict() -> dict

Convert measurement to dictionary.

Returns:

Type	Description
dict	Dictionary representation with corners as list

measurer

Homography-based measurement for planar objects.

This module provides measurement operations that project pixel-space bounding boxes to real-world metric coordinates using calibrated homography transformations.

HomographyMeasurer

HomographyMeasurer(calibration: CalibrationData, **kwargs)

Bases: Mindtrace

Measures physical dimensions of objects using planar homography.

Projects pixel-space bounding boxes from object detection to real-world metric coordinates on a planar surface using a pre-calibrated homography matrix. Enables accurate physical size measurements from camera images.

The measurer uses the inverse homography (H⁻¹) to map image pixels back to world coordinates, then computes Euclidean distances and polygon areas for size measurements.

Features

• Pixel-to-world coordinate projection
• Bounding box dimension measurement (width, height, area)
• Multi-unit support with automatic conversion
• Batch processing for multiple detections
• Pre-computed inverse homography for performance

Typical Workflow

1. Calibrate camera view to obtain HomographyCalibrator.calibrate_*()
2. Create measurer with calibration data
3. Detect objects with vision model (YOLO, etc.)
4. Measure physical dimensions from bounding boxes
5. Apply size-based filtering or quality control

Usage::

from mindtrace.hardware import HomographyCalibrator, HomographyMeasurer
from mindtrace.core.types import BoundingBox

# One-time calibration
calibrator = HomographyCalibrator()
calibration = calibrator.calibrate_checkerboard(
    image=checkerboard_image,
    board_size=(12, 12),
    square_size=25.0,
    world_unit="mm"
)

# Create measurer (reuse for all measurements)
measurer = HomographyMeasurer(calibration)

# Measure objects from detection results
detections = yolo.detect(frame)  # List[BoundingBox]
measurements = measurer.measure_bounding_boxes(detections, target_unit="cm")

for measured in measurements:
    print(f"Width: {measured.width_world:.2f} cm")
    print(f"Height: {measured.height_world:.2f} cm")
    print(f"Area: {measured.area_world:.2f} cm²")

    # Size-based filtering
    if measured.width_world > 10.0:
        reject_oversized_part(measured)

Configuration

• Supported units: mm, cm, m, in, ft (configurable via hardware config)
• Default world unit: Inherited from calibration data

Limitations

• Only works for planar surfaces (Z=0 assumption)
• Accuracy depends on calibration quality and viewing angle
• Assumes objects lie flat on the calibrated plane
• Camera must remain fixed after calibration

Initialize homography measurer with calibration data.

Parameters:

Name	Type	Description	Default
calibration	CalibrationData	CalibrationData from HomographyCalibrator	required
**kwargs		Additional arguments passed to Mindtrace base class	{}

Raises:

Type	Description
CameraConfigurationError	If homography matrix is invalid

pixels_to_world

pixels_to_world(points_px: ndarray) -> np.ndarray

Project pixel coordinates to world plane coordinates.

Maps Nx2 pixel coordinates to world plane coordinates using the inverse homography matrix H⁻¹. This is the core projection operation for all measurement functionality.

Parameters:

Name	Type	Description	Default
points_px	ndarray	Nx2 array of pixel coordinates (u, v)	required

Returns:

Type	Description
ndarray	Nx2 array of world coordinates (X, Y) in calibration world unit

Raises:

Type	Description
CameraConfigurationError	If input array has wrong shape

Example::

# Project single point
world_point = measurer.pixels_to_world(np.array([[320, 240]]))

# Project multiple points
pixel_corners = np.array([[100, 50], [500, 50], [500, 400], [100, 400]])
world_corners = measurer.pixels_to_world(pixel_corners)

measure_bounding_box

measure_bounding_box(
    box: BoundingBox, target_unit: Optional[str] = None
) -> MeasuredBox

Measure physical dimensions of a bounding box on the calibrated plane.

Projects the four corners of a pixel-space bounding box to world coordinates, then computes width, height, and area in the specified unit.

Parameters:

Name	Type	Description	Default
box	BoundingBox	BoundingBox from object detection (x, y, width, height in pixels)	required
target_unit	Optional[str]	Unit for output measurements (e.g., 'cm', 'm'). Uses calibration unit if None.	None

Returns:

Type	Description
MeasuredBox	MeasuredBox with physical dimensions and corner coordinates

Example::

# From object detection
detection = BoundingBox(x=100, y=50, width=400, height=350)
measured = measurer.measure_bounding_box(detection, target_unit="cm")

print(f"Object is {measured.width_world:.1f} × {measured.height_world:.1f} cm")
print(f"Area: {measured.area_world:.1f} cm²")

measure_bounding_boxes

measure_bounding_boxes(
    boxes: Sequence[BoundingBox], target_unit: Optional[str] = None
) -> List[MeasuredBox]

Measure physical dimensions of multiple bounding boxes.

Batch processing of multiple object detections. More efficient than calling measure_bounding_box() in a loop.

Parameters:

Name	Type	Description	Default
boxes	Sequence[BoundingBox]	Sequence of BoundingBox objects from object detection	required
target_unit	Optional[str]	Unit for output measurements. Uses calibration unit if None.	None

Returns:

Type	Description
List[MeasuredBox]	List of MeasuredBox objects with physical dimensions

Example::

# Batch measurement from multiple detections
detections = yolo.detect(frame)  # List[BoundingBox]
measurements = measurer.measure_bounding_boxes(detections, target_unit="cm")

# Size-based filtering
large_objects = [m for m in measurements if m.width_world > 15.0]

# Quality control
for measured in measurements:
    if not (10.0 <= measured.width_world <= 20.0):
        reject_part(measured)

measure_distance

measure_distance(
    point1: Union[Tuple[float, float], ndarray],
    point2: Union[Tuple[float, float], ndarray],
    target_unit: Optional[str] = None,
) -> Tuple[float, str]

Measure Euclidean distance between two points on the calibrated plane.

Converts pixel coordinates to world coordinates and computes the distance. Useful for measuring gaps, spacing, or verifying known distances.

Parameters:

Name	Type	Description	Default
point1	Union[Tuple[float, float], ndarray]	First point as (x, y) pixel coordinates	required
point2	Union[Tuple[float, float], ndarray]	Second point as (x, y) pixel coordinates	required
target_unit	Optional[str]	Unit for output distance. Uses calibration unit if None.	None

Returns:

Type	Description
Tuple[float, str]	Tuple of (distance, unit)

Raises:

Type	Description
ValueError	If target_unit is not supported

Example::

# Measure distance between two detected points
point1 = (150, 200)  # pixels
point2 = (350, 200)  # pixels
distance, unit = measurer.measure_distance(point1, point2, target_unit="mm")
print(f"Distance: {distance:.2f} {unit}")

# Verify calibration accuracy
known_distance_mm = 100.0
measured_distance, _ = measurer.measure_distance(ref_point1, ref_point2, "mm")
error_percent = abs(measured_distance - known_distance_mm) / known_distance_mm * 100
print(f"Calibration error: {error_percent:.2f}%")

setup

Camera Setup Module

This module provides setup scripts for various camera SDKs and utilities for configuring camera hardware in the Mindtrace system.

Available CLI commands (after package installation): mindtrace-camera-setup install # Install all camera SDKs mindtrace-camera-setup uninstall # Uninstall all camera SDKs mindtrace-camera-basler install # Install Basler Pylon SDK mindtrace-camera-basler uninstall # Uninstall Basler Pylon SDK mindtrace-camera-genicam install # Install GenICam CTI files mindtrace-camera-genicam uninstall # Uninstall GenICam SDK mindtrace-camera-genicam verify # Verify GenICam installation

Each setup script uses Typer for CLI and can be run independently.

PylonSDKInstaller

PylonSDKInstaller(package_path: Optional[str] = None)

Bases: Mindtrace

Basler Pylon SDK installer with guided wizard.

This class provides an interactive installation wizard that guides users through downloading and installing the Basler Pylon SDK from the official Basler website.

Initialize the Pylon SDK installer.

Parameters:

Name	Type	Description	Default
package_path	Optional[str]	Optional path to pre-downloaded package file	None

install

install() -> bool

Install the Pylon SDK using interactive wizard or pre-downloaded package.

Returns:

Type	Description
bool	True if installation successful, False otherwise

uninstall

uninstall() -> bool

Uninstall the Pylon SDK.

Returns:

Type	Description
bool	True if uninstallation successful, False otherwise

CameraSystemSetup

CameraSystemSetup()

Bases: Mindtrace

Unified camera system setup and configuration manager.

This class handles the installation and configuration of all camera SDKs and related network settings for the Mindtrace hardware system.

Initialize the camera system setup manager.

install_all_sdks

install_all_sdks(release_version: str = 'v1.0-stable') -> bool

Install all camera SDKs.

Parameters:

Name	Type	Description	Default
release_version	str	SDK release version to install	'v1.0-stable'

Returns:

Type	Description
bool	True if all installations successful, False otherwise

uninstall_all_sdks

uninstall_all_sdks() -> bool

Uninstall all camera SDKs.

Returns:

Type	Description
bool	True if all uninstallations successful, False otherwise

configure_firewall

configure_firewall(ip_range: Optional[str] = None) -> bool

Configure firewall rules to allow camera communication.

This method configures platform-specific firewall rules to allow communication with GigE Vision cameras on the specified IP range.

Parameters:

Name	Type	Description	Default
ip_range	Optional[str]	IP range to allow (uses config default if None)	None

Returns:

Type	Description
bool	True if firewall configuration successful, False otherwise

GenICamCTIInstaller

GenICamCTIInstaller(release_version: str = 'latest')

Bases: Mindtrace

Matrix Vision GenICam CTI installer and manager.

This class handles the download, installation, and uninstallation of the Matrix Vision Impact Acquire SDK and GenTL Producer across different platforms.

Initialize the GenICam CTI installer.

Parameters:

Name	Type	Description	Default
release_version	str	SDK release version to download	'latest'

get_cti_path

get_cti_path() -> str

Get the expected CTI file path for the current platform.

Returns:

Type	Description
str	Path to the CTI file for the current platform

verify_installation

verify_installation() -> bool

Verify that the CTI file is properly installed.

Returns:

Type	Description
bool	True if CTI file exists and is accessible, False otherwise

install

install() -> bool

Install the Matrix Vision Impact Acquire SDK for the current platform.

Returns:

Type	Description
bool	True if installation successful, False otherwise

uninstall

uninstall() -> bool

Uninstall the Impact Acquire SDK.

Returns:

Type	Description
bool	True if uninstallation successful, False otherwise

configure_firewall_helper

configure_firewall_helper(ip_range: Optional[str] = None) -> bool

Configure firewall rules to allow camera communication.

This function provides a simple interface to configure firewall rules for camera network communication. It works on both Windows and Linux.

Parameters:

Name	Type	Description	Default
ip_range	Optional[str]	IP range to allow (uses config default if None)	None

Returns:

Type	Description
bool	True if firewall configuration successful, False otherwise

setup_basler

Basler Pylon SDK Setup Script

This script provides a guided installation wizard for the Basler Pylon SDK for both Linux and Windows systems. The Pylon SDK provides tools like Pylon Viewer and IP Configurator for camera management.

Note: pypylon (the Python package) is self-contained for camera operations. This SDK installation is only needed for the GUI tools.

Features: - Interactive guided wizard with browser integration - Platform-specific installation instructions - Support for pre-downloaded packages (--package flag) - Comprehensive logging and error handling - Uninstallation support

Usage

python setup_basler.py # Interactive wizard python setup_basler.py --package /path/to/file # Use pre-downloaded file python setup_basler.py --uninstall # Uninstall SDK mindtrace-camera-basler-install # Console script (install) mindtrace-camera-basler-uninstall # Console script (uninstall)

PylonSDKInstaller

PylonSDKInstaller(package_path: Optional[str] = None)

Bases: Mindtrace

Basler Pylon SDK installer with guided wizard.

This class provides an interactive installation wizard that guides users through downloading and installing the Basler Pylon SDK from the official Basler website.

Initialize the Pylon SDK installer.

Parameters:

Name	Type	Description	Default
package_path	Optional[str]	Optional path to pre-downloaded package file	None

install

install() -> bool

Install the Pylon SDK using interactive wizard or pre-downloaded package.

Returns:

Type	Description
bool	True if installation successful, False otherwise

uninstall

uninstall() -> bool

Uninstall the Pylon SDK.

Returns:

Type	Description
bool	True if uninstallation successful, False otherwise

install

install(
    package: Optional[Path] = typer.Option(
        None,
        "--package",
        "-p",
        help="Path to pre-downloaded Pylon SDK package file",
        exists=True,
        dir_okay=False,
    ),
    verbose: bool = typer.Option(
        False, "--verbose", "-v", help="Enable verbose logging"
    ),
) -> None

Install the Basler Pylon SDK using an interactive wizard.

The wizard will guide you through downloading and installing the SDK from Basler's official website where you'll accept their EULA.

For CI/automation, use --package to provide a pre-downloaded file.

uninstall

uninstall(
    verbose: bool = typer.Option(
        False, "--verbose", "-v", help="Enable verbose logging"
    )
) -> None

Uninstall the Basler Pylon SDK.

main

main() -> None

Main entry point for the script.

setup_cameras

Camera Setup and Configuration Script

This script provides a unified interface for installing and configuring all camera SDKs and related network settings for the Mindtrace hardware system. It combines Basler SDK installation with firewall configuration for camera network communication.

Features: - Combined installation of all camera SDKs (Basler Pylon, Matrix Vision GenICam CTI) - Firewall configuration for camera network communication - Cross-platform support (Windows, Linux, and macOS) - Individual SDK uninstallation support - Comprehensive logging and error handling - Configurable IP range and firewall settings - Integration with Mindtrace configuration system

Configuration

The script uses the Mindtrace hardware configuration system for default values. Settings can be customized via:

1. Environment Variables:
2. MINDTRACE_HW_NETWORK_CAMERA_IP_RANGE: IP range for firewall rules (default: 192.168.50.0/24)

3. MINDTRACE_HW_NETWORK_FIREWALL_RULE_NAME: Name for firewall rules (default: "Allow Camera Network")

4. Configuration File (hardware_config.json): { "network": { "camera_ip_range": "192.168.50.0/24", "firewall_rule_name": "Allow Camera Network" } }

5. Command Line Arguments (highest priority)

Usage

python setup_cameras.py # Install all SDKs python setup_cameras.py --uninstall # Uninstall all SDKs python setup_cameras.py --configure-firewall # Configure firewall only python setup_cameras.py --ip-range 10.0.0.0/24 # Use custom IP range mindtrace-setup-cameras # Console script

Network Configuration

The script configures firewall rules to allow camera communication on the specified IP range. This is essential for GigE Vision cameras that communicate over Ethernet. The default IP range (192.168.50.0/24) follows industrial camera networking standards.

CameraSystemSetup

CameraSystemSetup()

Bases: Mindtrace

Unified camera system setup and configuration manager.

This class handles the installation and configuration of all camera SDKs and related network settings for the Mindtrace hardware system.

Initialize the camera system setup manager.

install_all_sdks

install_all_sdks(release_version: str = 'v1.0-stable') -> bool

Install all camera SDKs.

Parameters:

Name	Type	Description	Default
release_version	str	SDK release version to install	'v1.0-stable'

Returns:

Type	Description
bool	True if all installations successful, False otherwise

uninstall_all_sdks

uninstall_all_sdks() -> bool

Uninstall all camera SDKs.

Returns:

Type	Description
bool	True if all uninstallations successful, False otherwise

configure_firewall

configure_firewall(ip_range: Optional[str] = None) -> bool

Configure firewall rules to allow camera communication.

This method configures platform-specific firewall rules to allow communication with GigE Vision cameras on the specified IP range.

Parameters:

Name	Type	Description	Default
ip_range	Optional[str]	IP range to allow (uses config default if None)	None

Returns:

Type	Description
bool	True if firewall configuration successful, False otherwise

configure_firewall_helper

configure_firewall_helper(ip_range: Optional[str] = None) -> bool

Configure firewall rules to allow camera communication.

This function provides a simple interface to configure firewall rules for camera network communication. It works on both Windows and Linux.

Parameters:

Name	Type	Description	Default
ip_range	Optional[str]	IP range to allow (uses config default if None)	None

Returns:

Type	Description
bool	True if firewall configuration successful, False otherwise

install

install(
    version: str = typer.Option(
        "v1.0-stable", "--version", help="SDK release version to install"
    ),
    ip_range: Optional[str] = typer.Option(
        None,
        "--ip-range",
        help="IP range to allow in firewall (uses config default if not specified)",
    ),
    verbose: bool = typer.Option(
        False, "--verbose", "-v", help="Enable verbose logging"
    ),
) -> None

Install all camera SDKs and configure firewall.

Installs Basler Pylon SDK and Matrix Vision GenICam CTI files, then configures firewall rules for GigE Vision camera communication.

uninstall

uninstall(
    verbose: bool = typer.Option(
        False, "--verbose", "-v", help="Enable verbose logging"
    )
) -> None

Uninstall all camera SDKs.

configure_firewall

configure_firewall(
    ip_range: Optional[str] = typer.Option(
        None,
        "--ip-range",
        help="IP range to allow in firewall (uses config default if not specified)",
    ),
    verbose: bool = typer.Option(
        False, "--verbose", "-v", help="Enable verbose logging"
    ),
) -> None

Configure firewall rules for camera network communication.

Configures platform-specific firewall rules to allow GigE Vision camera communication on the specified IP range.

Windows: Uses netsh advfirewall commands Linux: Uses UFW (Uncomplicated Firewall)

main

main() -> None

Main entry point for the camera setup script.

setup_genicam

Matrix Vision GenICam CTI Setup Script

This script automates the download and installation of the Matrix Vision Impact Acquire SDK and GenTL Producer (CTI files) for Linux, Windows, and macOS. The CTI files are required for GenICam camera communication via Harvesters.

Features: - Automatic SDK download from Matrix Vision or GitHub releases - Platform-specific installation (Linux .deb/.tar.gz, Windows .exe, macOS .dmg/.pkg) - CTI file detection and verification - Administrative privilege handling - Comprehensive logging and error handling - Uninstallation support - Harvesters CTI path configuration

CTI File Locations: - Linux: /opt/ImpactAcquire/lib/x86_64/mvGenTLProducer.cti - Windows: C:\Program Files\MATRIX VISION\mvIMPACT Acquire\bin\x64\mvGenTLProducer.cti - macOS: /Applications/mvIMPACT_Acquire.app/Contents/Libraries/x86_64/mvGenTLProducer.cti

Usage

python setup_genicam.py # Install CTI files python setup_genicam.py --uninstall # Uninstall SDK python setup_genicam.py --verify # Verify CTI installation mindtrace-camera-genicam-install # Console script (install) mindtrace-camera-genicam-uninstall # Console script (uninstall) mindtrace-camera-genicam-verify # Console script (verify)

GenICamCTIInstaller

GenICamCTIInstaller(release_version: str = 'latest')

Bases: Mindtrace

Matrix Vision GenICam CTI installer and manager.

This class handles the download, installation, and uninstallation of the Matrix Vision Impact Acquire SDK and GenTL Producer across different platforms.

Initialize the GenICam CTI installer.

Parameters:

Name	Type	Description	Default
release_version	str	SDK release version to download	'latest'

get_cti_path

get_cti_path() -> str

Get the expected CTI file path for the current platform.

Returns:

Type	Description
str	Path to the CTI file for the current platform

verify_installation

verify_installation() -> bool

Verify that the CTI file is properly installed.

Returns:

Type	Description
bool	True if CTI file exists and is accessible, False otherwise

install

install() -> bool

Install the Matrix Vision Impact Acquire SDK for the current platform.

Returns:

Type	Description
bool	True if installation successful, False otherwise

uninstall

uninstall() -> bool

Uninstall the Impact Acquire SDK.

Returns:

Type	Description
bool	True if uninstallation successful, False otherwise

install_genicam_cti

install_genicam_cti(release_version: str = 'latest') -> bool

Install the Matrix Vision GenICam CTI files.

Parameters:

Name	Type	Description	Default
release_version	str	SDK release version to install	'latest'

Returns:

Type	Description
bool	True if installation successful, False otherwise

uninstall_genicam_cti

uninstall_genicam_cti() -> bool

Uninstall the Matrix Vision Impact Acquire SDK.

Returns:

Type	Description
bool	True if uninstallation successful, False otherwise

verify_genicam_cti

verify_genicam_cti() -> bool

Verify the Matrix Vision CTI installation.

Returns:

Type	Description
bool	True if CTI files are properly installed, False otherwise

install

install(
    version: str = typer.Option(
        "latest", "--version", help="SDK release version to install"
    ),
    verbose: bool = typer.Option(
        False, "--verbose", "-v", help="Enable verbose logging"
    ),
) -> None

Install the Matrix Vision Impact Acquire SDK and CTI files.

Downloads and installs the SDK from the official Balluff/Matrix Vision servers. The CTI files are required for GenICam camera communication via Harvesters.

uninstall

uninstall(
    verbose: bool = typer.Option(
        False, "--verbose", "-v", help="Enable verbose logging"
    )
) -> None

Uninstall the Matrix Vision Impact Acquire SDK.

verify

verify(
    verbose: bool = typer.Option(
        False, "--verbose", "-v", help="Enable verbose logging"
    )
) -> None

Verify that CTI files are properly installed.

main

main() -> None

Main entry point for the script.

cli

Mindtrace Hardware CLI - Command-line interface for hardware management.

commands

CLI command modules.

status_command

status_command()

Show status of all hardware services.

camera

Camera service commands.

start

start(
    api_host: Annotated[
        str,
        Option(--api - host, help="API service host", envvar=CAMERA_API_HOST),
    ] = "localhost",
    api_port: Annotated[
        int,
        Option(--api - port, help="API service port", envvar=CAMERA_API_PORT),
    ] = 8002,
    include_mocks: Annotated[
        bool, Option(--include - mocks, help="Include mock cameras")
    ] = False,
    open_docs: Annotated[
        bool, Option(--open - docs, help="Open API documentation in browser")
    ] = False,
)

Start camera API service (headless).

stop

stop()

Stop camera API service.

status

status()

Show camera API service status.

logs

logs()

View camera API service logs.

plc

PLC service commands.

start

start(
    api_host: Annotated[
        str, Option(--api - host, help="API service host", envvar=PLC_API_HOST)
    ] = "localhost",
    api_port: Annotated[
        int, Option(--api - port, help="API service port", envvar=PLC_API_PORT)
    ] = 8003,
)

Start PLC API service.

stop

stop()

Stop PLC API service.

status

status()

Show PLC service status.

logs

logs()

View PLC service logs.

status

Status command for all hardware services.

status_command

status_command()

Show status of all hardware services.

stereo

Stereo camera service commands.

start

start(
    api_host: Annotated[
        str,
        Option(
            --api - host,
            help="Stereo Camera API service host",
            envvar=STEREO_CAMERA_API_HOST,
        ),
    ] = "localhost",
    api_port: Annotated[
        int,
        Option(
            --api - port,
            help="Stereo Camera API service port",
            envvar=STEREO_CAMERA_API_PORT,
        ),
    ] = 8004,
    open_docs: Annotated[
        bool, Option(--open - docs, help="Open API documentation in browser")
    ] = False,
)

Start stereo camera API service.

stop

stop()

Stop stereo camera API service.

status

status()

Show stereo camera service status.

logs

logs()

View stereo camera service logs.

core

Core CLI functionality.

ProcessManager

ProcessManager()

Manages hardware service processes.

Initialize process manager.

load_pids

load_pids()

Load saved PIDs from file.

save_pids

save_pids()

Save PIDs to file.

start_camera_api

start_camera_api(
    host: str = None, port: int = None, include_mocks: bool = False
) -> subprocess.Popen

Launch camera API service.

Parameters:

Name	Type	Description	Default
host	str	Host to bind the service to (default: CAMERA_API_HOST env var or 'localhost')	None
port	int	Port to run the service on (default: CAMERA_API_PORT env var or 8002)	None
include_mocks	bool	Include mock cameras in discovery	False

Returns:

Type	Description
Popen	The subprocess handle

start_plc_api

start_plc_api(host: str = None, port: int = None) -> subprocess.Popen

Launch PLC API service.

Parameters:

Name	Type	Description	Default
host	str	Host to bind the service to (default: PLC_API_HOST env var or 'localhost')	None
port	int	Port to run the service on (default: PLC_API_PORT env var or 8003)	None

Returns:

Type	Description
Popen	The subprocess handle

start_stereo_camera_api

start_stereo_camera_api(host: str = None, port: int = None) -> subprocess.Popen

Launch Stereo Camera API service.

Parameters:

Name	Type	Description	Default
host	str	Host to bind the service to (default: STEREO_CAMERA_API_HOST env var or 'localhost')	None
port	int	Port to run the service on (default: STEREO_CAMERA_API_PORT env var or 8004)	None

Returns:

Type	Description
Popen	The subprocess handle

stop_service

stop_service(service_name: str) -> bool

Stop a service by name.

Parameters:

Name	Type	Description	Default
service_name	str	Name of the service to stop	required

Returns:

Type	Description
bool	True if stopped successfully

stop_all

stop_all()

Stop all running services.

get_status

get_status() -> Dict[str, Any]

Get status of all services.

Returns:

Type	Description
Dict[str, Any]	Dictionary with service status information

is_service_running

is_service_running(service_name: str) -> bool

Check if a specific service is running.

Parameters:

Name	Type	Description	Default
service_name	str	Name of the service	required

Returns:

Type	Description
bool	True if the service is running

setup_logger

setup_logger(
    name: str = "mindtrace-hw-cli",
    log_file: Optional[Path] = None,
    verbose: bool = False,
) -> logging.Logger

Set up logger for the CLI.

Parameters:

Name	Type	Description	Default
name	str	Logger name	'mindtrace-hw-cli'
log_file	Optional[Path]	Optional log file path	None
verbose	bool	Enable verbose logging	False

Returns:

Type	Description
Logger	Configured logger instance

logger

Logging configuration for the CLI using Rich.

RichLogger

RichLogger(console: Optional[Console] = None)

Logger that uses Rich Console for professional output.

Initialize RichLogger.

Parameters:

Name	Type	Description	Default
console	Optional[Console]	Optional Rich Console instance. Creates new one if not provided.	None

info

info(message: str)

Log info message.

Parameters:

Name	Type	Description	Default
message	str	Message to log	required

success

success(message: str)

Log success message.

Parameters:

Name	Type	Description	Default
message	str	Success message to log	required

warning

warning(message: str)

Log warning message.

Parameters:

Name	Type	Description	Default
message	str	Warning message to log	required

error

error(message: str)

Log error message.

Parameters:

Name	Type	Description	Default
message	str	Error message to log	required

progress

progress(message: str)

Log progress message.

Parameters:

Name	Type	Description	Default
message	str	Progress message to log	required

setup_logger

setup_logger(
    name: str = "mindtrace-hw-cli",
    log_file: Optional[Path] = None,
    verbose: bool = False,
) -> logging.Logger

Set up logger for the CLI.

Parameters:

Name	Type	Description	Default
name	str	Logger name	'mindtrace-hw-cli'
log_file	Optional[Path]	Optional log file path	None
verbose	bool	Enable verbose logging	False

Returns:

Type	Description
Logger	Configured logger instance

process_manager

Process management for hardware services.

ProcessManager

ProcessManager()

Manages hardware service processes.

Initialize process manager.

load_pids

load_pids()

Load saved PIDs from file.

save_pids

save_pids()

Save PIDs to file.

start_camera_api

start_camera_api(
    host: str = None, port: int = None, include_mocks: bool = False
) -> subprocess.Popen

Launch camera API service.

Parameters:

Name	Type	Description	Default
host	str	Host to bind the service to (default: CAMERA_API_HOST env var or 'localhost')	None
port	int	Port to run the service on (default: CAMERA_API_PORT env var or 8002)	None
include_mocks	bool	Include mock cameras in discovery	False

Returns:

Type	Description
Popen	The subprocess handle

start_plc_api

start_plc_api(host: str = None, port: int = None) -> subprocess.Popen

Launch PLC API service.

Parameters:

Name	Type	Description	Default
host	str	Host to bind the service to (default: PLC_API_HOST env var or 'localhost')	None
port	int	Port to run the service on (default: PLC_API_PORT env var or 8003)	None

Returns:

Type	Description
Popen	The subprocess handle

start_stereo_camera_api

start_stereo_camera_api(host: str = None, port: int = None) -> subprocess.Popen

Launch Stereo Camera API service.

Parameters:

Name	Type	Description	Default
host	str	Host to bind the service to (default: STEREO_CAMERA_API_HOST env var or 'localhost')	None
port	int	Port to run the service on (default: STEREO_CAMERA_API_PORT env var or 8004)	None

Returns:

Type	Description
Popen	The subprocess handle

stop_service

stop_service(service_name: str) -> bool

Stop a service by name.

Parameters:

Name	Type	Description	Default
service_name	str	Name of the service to stop	required

Returns:

Type	Description
bool	True if stopped successfully

stop_all

stop_all()

Stop all running services.

get_status

get_status() -> Dict[str, Any]

Get status of all services.

Returns:

Type	Description
Dict[str, Any]	Dictionary with service status information

is_service_running

is_service_running(service_name: str) -> bool

Check if a specific service is running.

Parameters:

Name	Type	Description	Default
service_name	str	Name of the service	required

Returns:

Type	Description
bool	True if the service is running

utils

CLI utility functions.

format_status

format_status(status: Dict[str, Any]) -> None

Format and display service status.

Parameters:

Name	Type	Description	Default
status	Dict[str, Any]	Status dictionary from ProcessManager	required

print_table

print_table(data: List[Dict[str, Any]], headers: Optional[List[str]] = None)

Print data as a formatted table.

Parameters:

Name	Type	Description	Default
data	List[Dict[str, Any]]	List of dictionaries to display	required
headers	Optional[List[str]]	Optional header names	None

display

Display utilities for CLI output using Rich.

format_status

format_status(status: Dict[str, Any]) -> None

Format and display service status.

Parameters:

Name	Type	Description	Default
status	Dict[str, Any]	Status dictionary from ProcessManager	required

print_table

print_table(data: List[Dict[str, Any]], headers: Optional[List[str]] = None)

Print data as a formatted table.

Parameters:

Name	Type	Description	Default
data	List[Dict[str, Any]]	List of dictionaries to display	required
headers	Optional[List[str]]	Optional header names	None

print_service_box

print_service_box(title: str, services: Dict[str, Dict[str, Any]])

Print services in a nice panel format.

Parameters:

Name	Type	Description	Default
title	str	Panel title	required
services	Dict[str, Dict[str, Any]]	Service information dictionary	required

show_banner

show_banner()

Display the CLI banner.

print_list

print_list(items: List[str], title: Optional[str] = None, style: str = 'white')

Print a list of items.

Parameters:

Name	Type	Description	Default
items	List[str]	List of strings to display	required
title	Optional[str]	Optional title for the list	None
style	str	Rich style for items	'white'

plcs

PLC module for Mindtrace hardware system.

Provides unified interface for managing PLCs from different manufacturers with support for discovery, registration, and batch operations.

PLCManager

PLCManager()

Bases: Mindtrace

Unified PLC management system for industrial automation.

This manager provides a comprehensive interface for managing PLCs from different manufacturers with support for discovery, registration, connection management, and batch tag operations. It handles multiple PLC backends transparently and provides thread-safe operations with proper error handling.

The manager supports: - Automatic PLC discovery across multiple backends - Dynamic PLC registration and connection management - Batch tag read/write operations for optimal performance - Connection monitoring and automatic reconnection - Comprehensive error handling and logging - Thread-safe operations with proper resource management

Supported PLC Types: - Allen-Bradley: ControlLogix, CompactLogix, MicroLogix PLCs - Siemens: S7-300, S7-400, S7-1200, S7-1500 PLCs (Future) - Modbus: Modbus TCP/RTU devices (Future) - Mock PLCs: For testing and development

Attributes:

Name	Type	Description
plcs	Dict[str, BasePLC]	Dictionary mapping PLC names to PLC instances
config		Hardware configuration manager instance
logger		Centralized logger for PLC operations

Example

Basic usage

async with PLCManager() as manager: # Discover available PLCs discovered = await manager.discover_plcs()

# Register and connect to a PLC
await manager.register_plc("PLC1", "AllenBradley", "192.168.1.100")
await manager.connect_plc("PLC1")

# Read and write tags
values = await manager.read_tag("PLC1", ["Temperature", "Pressure"])
await manager.write_tag("PLC1", [("Setpoint", 75.0)])

Batch operations

async with PLCManager() as manager: # Register multiple PLCs await manager.register_plc("PLC1", "AllenBradley", "192.168.1.100") await manager.register_plc("PLC2", "AllenBradley", "192.168.1.101")

# Batch read from multiple PLCs
read_requests = [
    ("PLC1", ["Temperature", "Pressure"]),
    ("PLC2", ["Speed", "Position"])
]
results = await manager.read_tags_batch(read_requests)

Initialize the PLC manager.

discover_plcs async

discover_plcs() -> Dict[str, List[str]]

Discover available PLCs from all enabled backends.

Returns:

Type	Description
Dict[str, List[str]]	Dictionary mapping backend names to lists of discovered PLCs

register_plc async

register_plc(
    plc_name: str,
    backend: str,
    ip_address: str,
    plc_type: Optional[str] = None,
    **kwargs
) -> bool

Register a PLC with the manager.

Parameters:

Name	Type	Description	Default
plc_name	str	Unique identifier for the PLC	required
backend	str	Backend type ("AllenBradley", "Siemens", "Modbus")	required
ip_address	str	IP address of the PLC	required
plc_type	Optional[str]	Specific PLC type (backend-dependent)	None
**kwargs		Additional backend-specific parameters	{}

Returns:

Type	Description
bool	True if registration successful, False otherwise

unregister_plc async

unregister_plc(plc_name: str) -> bool

Unregister a PLC from the manager.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC to unregister	required

Returns:

Type	Description
bool	True if unregistration successful, False otherwise

connect_plc async

connect_plc(plc_name: str) -> bool

Connect to a specific PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC to connect	required

Returns:

Type	Description
bool	True if connection successful, False otherwise

disconnect_plc async

disconnect_plc(plc_name: str) -> bool

Disconnect from a specific PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC to disconnect	required

Returns:

Type	Description
bool	True if disconnection successful, False otherwise

connect_all_plcs async

connect_all_plcs() -> Dict[str, bool]

Connect to all registered PLCs.

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping PLC names to connection success status

disconnect_all_plcs async

disconnect_all_plcs() -> Dict[str, bool]

Disconnect from all registered PLCs.

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping PLC names to disconnection success status

read_tag async

read_tag(plc_name: str, tags: Union[str, List[str]]) -> Dict[str, Any]

Read tags from a specific PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC	required
tags	Union[str, List[str]]	Single tag name or list of tag names	required

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping tag names to their values

write_tag async

write_tag(
    plc_name: str, tags: Union[Tuple[str, Any], List[Tuple[str, Any]]]
) -> Dict[str, bool]

Write tags to a specific PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC	required
tags	Union[Tuple[str, Any], List[Tuple[str, Any]]]	Single (tag_name, value) tuple or list of tuples	required

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping tag names to write success status

read_tags_batch async

read_tags_batch(
    requests: List[Tuple[str, Union[str, List[str]]]],
) -> Dict[str, Dict[str, Any]]

Read tags from multiple PLCs in batch.

Parameters:

Name	Type	Description	Default
requests	List[Tuple[str, Union[str, List[str]]]]	List of (plc_name, tags) tuples	required

Returns:

Type	Description
Dict[str, Dict[str, Any]]	Dictionary mapping PLC names to their tag read results

write_tags_batch async

write_tags_batch(
    requests: List[Tuple[str, Union[Tuple[str, Any], List[Tuple[str, Any]]]]],
) -> Dict[str, Dict[str, bool]]

Write tags to multiple PLCs in batch.

Parameters:

Name	Type	Description	Default
requests	List[Tuple[str, Union[Tuple[str, Any], List[Tuple[str, Any]]]]]	List of (plc_name, tags) tuples	required

Returns:

Type	Description
Dict[str, Dict[str, bool]]	Dictionary mapping PLC names to their tag write results

get_plc_status async

get_plc_status(plc_name: str) -> Dict[str, Any]

Get status information for a specific PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC	required

Returns:

Type	Description
Dict[str, Any]	Dictionary with PLC status information

get_all_plc_status async

get_all_plc_status() -> Dict[str, Dict[str, Any]]

Get status information for all registered PLCs.

Returns:

Type	Description
Dict[str, Dict[str, Any]]	Dictionary mapping PLC names to their status information

get_plc_tags async

get_plc_tags(plc_name: str) -> List[str]

Get list of available tags for a specific PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC	required

Returns:

Type	Description
List[str]	List of available tag names

get_registered_plcs

get_registered_plcs() -> List[str]

Get list of registered PLC names.

Returns:

Type	Description
List[str]	List of registered PLC names

get_backend_info

get_backend_info() -> Dict[str, Dict[str, Any]]

Get information about available PLC backends.

Returns:

Type	Description
Dict[str, Dict[str, Any]]	Dictionary mapping backend names to their information

cleanup async

cleanup()

Clean up all PLC connections and resources.

backends

PLC backends for different manufacturers and protocols.

This module contains implementations for various PLC types including Allen Bradley, Siemens, Modbus, and other industrial protocols.

allen_bradley

Allen Bradley PLC Backend.

Implements PLC communication for Allen Bradley PLCs using the pycomm3 library.

AllenBradleyPLC

AllenBradleyPLC(
    plc_name: str,
    ip_address: str,
    plc_type: Optional[str] = None,
    plc_config_file: Optional[str] = None,
    connection_timeout: Optional[float] = None,
    read_timeout: Optional[float] = None,
    write_timeout: Optional[float] = None,
    retry_count: Optional[int] = None,
    retry_delay: Optional[float] = None,
)

Bases: BasePLC

Allen Bradley PLC implementation using pycomm3.

Supports multiple PLC types and Ethernet/IP devices: - ControlLogix, CompactLogix, Micro800 (LogixDriver) - SLC500, MicroLogix (SLCDriver) - Generic Ethernet/IP devices (CIPDriver)

Attributes:

Name	Type	Description
plc		pycomm3 driver instance (LogixDriver, SLCDriver, or CIPDriver)
driver_type		Type of driver being used
plc_type		Type of PLC (auto-detected or specified)
_tags_cache	Optional[List[str]]	Cached list of available tags
_cache_timestamp	float	Timestamp of last tag cache update
_cache_ttl	float	Time-to-live for tag cache in seconds

Initialize Allen Bradley PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Unique identifier for the PLC	required
ip_address	str	IP address of the PLC	required
plc_type	Optional[str]	PLC type ('logix', 'slc', 'cip', or 'auto' for auto-detection)	None
plc_config_file	Optional[str]	Path to PLC configuration file	None
connection_timeout	Optional[float]	Connection timeout in seconds	None
read_timeout	Optional[float]	Tag read timeout in seconds	None
write_timeout	Optional[float]	Tag write timeout in seconds	None
retry_count	Optional[int]	Number of retry attempts	None
retry_delay	Optional[float]	Delay between retries in seconds	None

Raises:

Type	Description
SDKNotAvailableError	If pycomm3 is not installed

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the Allen Bradley PLC connection.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success, plc_object, device_manager)

connect async

connect() -> bool

Establish connection to the Allen Bradley PLC.

Returns:

Type	Description
bool	True if connection successful, False otherwise

disconnect async

disconnect() -> bool

Disconnect from the Allen Bradley PLC.

Returns:

Type	Description
bool	True if disconnection successful, False otherwise

is_connected async

is_connected() -> bool

Check if Allen Bradley PLC is currently connected.

Returns:

Type	Description
bool	True if connected, False otherwise

read_tag async

read_tag(tags: Union[str, List[str]]) -> Dict[str, Any]

Read values from Allen Bradley PLC tags.

Parameters:

Name	Type	Description	Default
tags	Union[str, List[str]]	Single tag name or list of tag names	required

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping tag names to their values

Raises:

Type	Description
PLCTagReadError	If tag reading fails

write_tag async

write_tag(
    tags: Union[Tuple[str, Any], List[Tuple[str, Any]]],
) -> Dict[str, bool]

Write values to Allen Bradley PLC tags.

Parameters:

Name	Type	Description	Default
tags	Union[Tuple[str, Any], List[Tuple[str, Any]]]	Single (tag_name, value) tuple or list of tuples	required

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping tag names to write success status

Raises:

Type	Description
PLCTagWriteError	If tag writing fails

get_all_tags async

get_all_tags() -> List[str]

Get list of all available tags on the Allen Bradley PLC.

Returns:

Type	Description
List[str]	List of tag names

get_tag_info async

get_tag_info(tag_name: str) -> Dict[str, Any]

Get detailed information about a specific tag.

Parameters:

Name	Type	Description	Default
tag_name	str	Name of the tag	required

Returns:

Type	Description
Dict[str, Any]	Dictionary with tag information (type, description, etc.)

get_plc_info async

get_plc_info() -> Dict[str, Any]

Get detailed information about the connected PLC using proper pycomm3 methods.

Returns:

Type	Description
Dict[str, Any]	Dictionary with PLC information

get_available_plcs staticmethod

get_available_plcs() -> List[str]

Discover available Allen Bradley PLCs using proper pycomm3 discovery methods.

Returns:

Type	Description
List[str]	List of PLC identifiers in format "AllenBradley:IP:Type"

discover_async async classmethod

discover_async() -> List[str]

Async wrapper for get_available_plcs() - runs discovery in threadpool.

Use this instead of get_available_plcs() when calling from async context to avoid blocking the event loop during PLC network discovery.

Returns:

Type	Description
List[str]	List[str]: List of discovered PLC IP addresses.

get_backend_info staticmethod

get_backend_info() -> Dict[str, Any]

Get information about the Allen Bradley PLC backend.

Returns:

Type	Description
Dict[str, Any]	Dictionary with backend information

MockAllenBradleyPLC

MockAllenBradleyPLC(
    plc_name: str,
    ip_address: str,
    plc_type: Optional[str] = None,
    plc_config_file: Optional[str] = None,
    connection_timeout: Optional[float] = None,
    read_timeout: Optional[float] = None,
    write_timeout: Optional[float] = None,
    retry_count: Optional[int] = None,
    retry_delay: Optional[float] = None,
)

Bases: BasePLC

Mock implementation of Allen Bradley PLC for testing and development.

This class provides a complete simulation of the Allen Bradley PLC API without requiring actual hardware. It simulates all three driver types and provides realistic tag behavior for comprehensive testing.

Attributes:

Name	Type	Description
plc_name		User-defined PLC identifier
ip_address		Simulated IP address
plc_type		PLC type ("logix", "slc", "cip", or "auto")
driver_type		Detected/simulated driver type
_is_connected		Connection status simulation
_tag_values	Dict[str, Any]	Simulated tag values storage
_tag_types	Dict[str, str]	Tag type mapping for different driver types
_cache_ttl		Tag cache time-to-live
_tags_cache	Optional[List[str]]	Cached list of available tags
_cache_timestamp	float	Timestamp of last cache update

Initialize mock Allen Bradley PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Unique identifier for the PLC	required
ip_address	str	Simulated IP address	required
plc_type	Optional[str]	PLC type ('logix', 'slc', 'cip', or 'auto' for auto-detection)	None
plc_config_file	Optional[str]	Path to configuration file (simulated)	None
connection_timeout	Optional[float]	Connection timeout in seconds	None
read_timeout	Optional[float]	Tag read timeout in seconds	None
write_timeout	Optional[float]	Tag write timeout in seconds	None
retry_count	Optional[int]	Number of retry attempts	None
retry_delay	Optional[float]	Delay between retries in seconds	None

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the mock Allen Bradley PLC connection.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success, mock_plc_object, mock_device_manager)

connect async

connect() -> bool

Simulate connection to the Allen Bradley PLC.

Returns:

Type	Description
bool	True if connection successful, False otherwise

disconnect async

disconnect() -> bool

Simulate disconnection from the Allen Bradley PLC.

Returns:

Type	Description
bool	True if disconnection successful, False otherwise

is_connected async

is_connected() -> bool

Check if mock Allen Bradley PLC is currently connected.

Returns:

Type	Description
bool	True if connected, False otherwise

read_tag async

read_tag(tags: Union[str, List[str]]) -> Dict[str, Any]

Simulate reading values from Allen Bradley PLC tags.

Parameters:

Name	Type	Description	Default
tags	Union[str, List[str]]	Single tag name or list of tag names	required

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping tag names to their values

write_tag async

write_tag(
    tags: Union[Tuple[str, Any], List[Tuple[str, Any]]],
) -> Dict[str, bool]

Simulate writing values to Allen Bradley PLC tags.

Parameters:

Name	Type	Description	Default
tags	Union[Tuple[str, Any], List[Tuple[str, Any]]]	Single (tag_name, value) tuple or list of tuples	required

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping tag names to write success status

get_all_tags async

get_all_tags() -> List[str]

Get list of all available mock tags.

Returns:

Type	Description
List[str]	List of tag names

get_tag_info async

get_tag_info(tag_name: str) -> Dict[str, Any]

Get detailed information about a mock tag.

Parameters:

Name	Type	Description	Default
tag_name	str	Name of the tag	required

Returns:

Type	Description
Dict[str, Any]	Dictionary with tag information

get_plc_info async

get_plc_info() -> Dict[str, Any]

Get detailed information about the mock PLC.

Returns:

Type	Description
Dict[str, Any]	Dictionary with PLC information

get_available_plcs staticmethod

get_available_plcs() -> List[str]

Discover available mock Allen Bradley PLCs.

Returns:

Type	Description
List[str]	List of PLC identifiers in format "AllenBradley:IP:Type"

get_backend_info staticmethod

get_backend_info() -> Dict[str, Any]

Get information about the mock Allen Bradley PLC backend.

Returns:

Type	Description
Dict[str, Any]	Dictionary with backend information

allen_bradley_plc

Allen Bradley PLC implementation using pycomm3.

Provides communication interface for Allen Bradley PLCs and other Ethernet/IP devices using CIPDriver, LogixDriver, and SLCDriver from pycomm3 library.

AllenBradleyPLC

AllenBradleyPLC(
    plc_name: str,
    ip_address: str,
    plc_type: Optional[str] = None,
    plc_config_file: Optional[str] = None,
    connection_timeout: Optional[float] = None,
    read_timeout: Optional[float] = None,
    write_timeout: Optional[float] = None,
    retry_count: Optional[int] = None,
    retry_delay: Optional[float] = None,
)

Bases: BasePLC

Allen Bradley PLC implementation using pycomm3.

Supports multiple PLC types and Ethernet/IP devices: - ControlLogix, CompactLogix, Micro800 (LogixDriver) - SLC500, MicroLogix (SLCDriver) - Generic Ethernet/IP devices (CIPDriver)

Attributes:

Name	Type	Description
plc		pycomm3 driver instance (LogixDriver, SLCDriver, or CIPDriver)
driver_type		Type of driver being used
plc_type		Type of PLC (auto-detected or specified)
_tags_cache	Optional[List[str]]	Cached list of available tags
_cache_timestamp	float	Timestamp of last tag cache update
_cache_ttl	float	Time-to-live for tag cache in seconds

Initialize Allen Bradley PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Unique identifier for the PLC	required
ip_address	str	IP address of the PLC	required
plc_type	Optional[str]	PLC type ('logix', 'slc', 'cip', or 'auto' for auto-detection)	None
plc_config_file	Optional[str]	Path to PLC configuration file	None
connection_timeout	Optional[float]	Connection timeout in seconds	None
read_timeout	Optional[float]	Tag read timeout in seconds	None
write_timeout	Optional[float]	Tag write timeout in seconds	None
retry_count	Optional[int]	Number of retry attempts	None
retry_delay	Optional[float]	Delay between retries in seconds	None

Raises:

Type	Description
SDKNotAvailableError	If pycomm3 is not installed

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the Allen Bradley PLC connection.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success, plc_object, device_manager)

connect async

connect() -> bool

Establish connection to the Allen Bradley PLC.

Returns:

Type	Description
bool	True if connection successful, False otherwise

disconnect async

disconnect() -> bool

Disconnect from the Allen Bradley PLC.

Returns:

Type	Description
bool	True if disconnection successful, False otherwise

is_connected async

is_connected() -> bool

Check if Allen Bradley PLC is currently connected.

Returns:

Type	Description
bool	True if connected, False otherwise

read_tag async

read_tag(tags: Union[str, List[str]]) -> Dict[str, Any]

Read values from Allen Bradley PLC tags.

Parameters:

Name	Type	Description	Default
tags	Union[str, List[str]]	Single tag name or list of tag names	required

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping tag names to their values

Raises:

Type	Description
PLCTagReadError	If tag reading fails

write_tag async

write_tag(
    tags: Union[Tuple[str, Any], List[Tuple[str, Any]]],
) -> Dict[str, bool]

Write values to Allen Bradley PLC tags.

Parameters:

Name	Type	Description	Default
tags	Union[Tuple[str, Any], List[Tuple[str, Any]]]	Single (tag_name, value) tuple or list of tuples	required

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping tag names to write success status

Raises:

Type	Description
PLCTagWriteError	If tag writing fails

get_all_tags async

get_all_tags() -> List[str]

Get list of all available tags on the Allen Bradley PLC.

Returns:

Type	Description
List[str]	List of tag names

get_tag_info async

get_tag_info(tag_name: str) -> Dict[str, Any]

Get detailed information about a specific tag.

Parameters:

Name	Type	Description	Default
tag_name	str	Name of the tag	required

Returns:

Type	Description
Dict[str, Any]	Dictionary with tag information (type, description, etc.)

get_plc_info async

get_plc_info() -> Dict[str, Any]

Get detailed information about the connected PLC using proper pycomm3 methods.

Returns:

Type	Description
Dict[str, Any]	Dictionary with PLC information

get_available_plcs staticmethod

get_available_plcs() -> List[str]

Discover available Allen Bradley PLCs using proper pycomm3 discovery methods.

Returns:

Type	Description
List[str]	List of PLC identifiers in format "AllenBradley:IP:Type"

discover_async async classmethod

discover_async() -> List[str]

Async wrapper for get_available_plcs() - runs discovery in threadpool.

Use this instead of get_available_plcs() when calling from async context to avoid blocking the event loop during PLC network discovery.

Returns:

Type	Description
List[str]	List[str]: List of discovered PLC IP addresses.

get_backend_info staticmethod

get_backend_info() -> Dict[str, Any]

Get information about the Allen Bradley PLC backend.

Returns:

Type	Description
Dict[str, Any]	Dictionary with backend information

mock_allen_bradley

Mock Allen Bradley PLC Implementation

This module provides a mock implementation of Allen Bradley PLCs for testing and development without requiring actual hardware or the pycomm3 SDK.

Features

• Complete simulation of all three driver types (Logix, SLC, CIP)
• Realistic tag data generation and management
• Configurable number of mock PLCs
• Error simulation capabilities for testing
• No hardware dependencies

Components

• MockAllenBradleyPLC: Mock PLC implementation

Usage

from mindtrace.hardware.plcs.backends.allen_bradley import MockAllenBradleyPLC

Initialize mock PLC

plc = MockAllenBradleyPLC("TestPLC", "192.168.1.100", plc_type="logix")

Use exactly like real PLC

await plc.connect() tags = await plc.read_tag(["Motor1_Speed", "Conveyor_Status"]) await plc.write_tag([("Pump1_Command", True)]) await plc.disconnect()

MockAllenBradleyPLC

MockAllenBradleyPLC(
    plc_name: str,
    ip_address: str,
    plc_type: Optional[str] = None,
    plc_config_file: Optional[str] = None,
    connection_timeout: Optional[float] = None,
    read_timeout: Optional[float] = None,
    write_timeout: Optional[float] = None,
    retry_count: Optional[int] = None,
    retry_delay: Optional[float] = None,
)

Bases: BasePLC

Mock implementation of Allen Bradley PLC for testing and development.

This class provides a complete simulation of the Allen Bradley PLC API without requiring actual hardware. It simulates all three driver types and provides realistic tag behavior for comprehensive testing.

Attributes:

Name	Type	Description
plc_name		User-defined PLC identifier
ip_address		Simulated IP address
plc_type		PLC type ("logix", "slc", "cip", or "auto")
driver_type		Detected/simulated driver type
_is_connected		Connection status simulation
_tag_values	Dict[str, Any]	Simulated tag values storage
_tag_types	Dict[str, str]	Tag type mapping for different driver types
_cache_ttl		Tag cache time-to-live
_tags_cache	Optional[List[str]]	Cached list of available tags
_cache_timestamp	float	Timestamp of last cache update

Initialize mock Allen Bradley PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Unique identifier for the PLC	required
ip_address	str	Simulated IP address	required
plc_type	Optional[str]	PLC type ('logix', 'slc', 'cip', or 'auto' for auto-detection)	None
plc_config_file	Optional[str]	Path to configuration file (simulated)	None
connection_timeout	Optional[float]	Connection timeout in seconds	None
read_timeout	Optional[float]	Tag read timeout in seconds	None
write_timeout	Optional[float]	Tag write timeout in seconds	None
retry_count	Optional[int]	Number of retry attempts	None
retry_delay	Optional[float]	Delay between retries in seconds	None

initialize async

initialize() -> Tuple[bool, Any, Any]

Initialize the mock Allen Bradley PLC connection.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success, mock_plc_object, mock_device_manager)

connect async

connect() -> bool

Simulate connection to the Allen Bradley PLC.

Returns:

Type	Description
bool	True if connection successful, False otherwise

disconnect async

disconnect() -> bool

Simulate disconnection from the Allen Bradley PLC.

Returns:

Type	Description
bool	True if disconnection successful, False otherwise

is_connected async

is_connected() -> bool

Check if mock Allen Bradley PLC is currently connected.

Returns:

Type	Description
bool	True if connected, False otherwise

read_tag async

read_tag(tags: Union[str, List[str]]) -> Dict[str, Any]

Simulate reading values from Allen Bradley PLC tags.

Parameters:

Name	Type	Description	Default
tags	Union[str, List[str]]	Single tag name or list of tag names	required

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping tag names to their values

write_tag async

write_tag(
    tags: Union[Tuple[str, Any], List[Tuple[str, Any]]],
) -> Dict[str, bool]

Simulate writing values to Allen Bradley PLC tags.

Parameters:

Name	Type	Description	Default
tags	Union[Tuple[str, Any], List[Tuple[str, Any]]]	Single (tag_name, value) tuple or list of tuples	required

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping tag names to write success status

get_all_tags async

get_all_tags() -> List[str]

Get list of all available mock tags.

Returns:

Type	Description
List[str]	List of tag names

get_tag_info async

get_tag_info(tag_name: str) -> Dict[str, Any]

Get detailed information about a mock tag.

Parameters:

Name	Type	Description	Default
tag_name	str	Name of the tag	required

Returns:

Type	Description
Dict[str, Any]	Dictionary with tag information

get_plc_info async

get_plc_info() -> Dict[str, Any]

Get detailed information about the mock PLC.

Returns:

Type	Description
Dict[str, Any]	Dictionary with PLC information

get_available_plcs staticmethod

get_available_plcs() -> List[str]

Discover available mock Allen Bradley PLCs.

Returns:

Type	Description
List[str]	List of PLC identifiers in format "AllenBradley:IP:Type"

get_backend_info staticmethod

get_backend_info() -> Dict[str, Any]

Get information about the mock Allen Bradley PLC backend.

Returns:

Type	Description
Dict[str, Any]	Dictionary with backend information

base

Abstract base classes for PLC implementations.

This module defines the interface that all PLC backends must implement, providing a consistent API for PLC operations across different manufacturers and communication protocols.

Features

• Abstract base class with comprehensive async PLC interface
• Consistent async pattern matching camera backends
• Type-safe method signatures with full type hints
• Configuration system integration
• Resource management and cleanup
• Default implementations for optional features
• Standardized constructor signature across all backends
• Retry logic with exponential backoff
• Connection management and monitoring

Usage

This is an abstract base class and cannot be instantiated directly. PLC backends should inherit from BasePLC and implement all abstract methods.

Example

class MyPLCBackend(BasePLC): async def initialize(self) -> Tuple[bool, Any, Any]: # Implementation here pass

async def connect(self) -> bool:
    # Implementation here
    pass

async def read_tag(self, tags: Union[str, List[str]]) -> Dict[str, Any]:
    # Implementation here
    pass

# ... implement other abstract methods

Backend Requirements

All PLC backends must implement the following abstract methods: - initialize(): Establish initial connection and setup - connect(): Connect to the PLC - disconnect(): Disconnect from the PLC - is_connected(): Check connection status - read_tag(): Read tag values from PLC - write_tag(): Write tag values to PLC - get_all_tags(): List all available tags - get_tag_info(): Get detailed tag information - get_available_plcs(): Static method for PLC discovery - get_backend_info(): Static method for backend information

Error Handling

Backends should raise appropriate exceptions from the PLC exception hierarchy: - PLCError: Base exception for all PLC-related errors - PLCNotFoundError: PLC not found during discovery - PLCConnectionError: Connection establishment or maintenance failures - PLCInitializationError: PLC initialization failures - PLCCommunicationError: Communication protocol errors - PLCTagError: Tag-related operation errors - PLCTimeoutError: Operation timeout errors - PLCConfigurationError: Configuration-related errors

BasePLC

BasePLC(
    plc_name: str,
    ip_address: str,
    plc_config_file: Optional[str] = None,
    connection_timeout: Optional[float] = None,
    read_timeout: Optional[float] = None,
    write_timeout: Optional[float] = None,
    retry_count: Optional[int] = None,
    retry_delay: Optional[float] = None,
)

Bases: MindtraceABC

Abstract base class for PLC implementations.

This class defines the interface that all PLC backends must implement to ensure consistent behavior across different manufacturers and protocols.

Attributes:

Name	Type	Description
plc_name		Unique identifier for the PLC instance
plc_config_file		Path to PLC-specific configuration file
ip_address		IP address of the PLC
connection_timeout		Connection timeout in seconds
read_timeout		Tag read timeout in seconds
write_timeout		Tag write timeout in seconds
retry_count		Number of retry attempts for operations
retry_delay		Delay between retry attempts in seconds
plc		The underlying PLC connection object
device_manager		Device-specific manager instance
initialized		Whether the PLC has been initialized

Initialize the PLC instance.

Parameters:

Name	Type	Description	Default
plc_name	str	Unique identifier for the PLC	required
ip_address	str	IP address of the PLC	required
plc_config_file	Optional[str]	Path to PLC configuration file	None
connection_timeout	Optional[float]	Connection timeout in seconds	None
read_timeout	Optional[float]	Tag read timeout in seconds	None
write_timeout	Optional[float]	Tag write timeout in seconds	None
retry_count	Optional[int]	Number of retry attempts	None
retry_delay	Optional[float]	Delay between retries in seconds	None

initialize abstractmethod async

initialize() -> Tuple[bool, Any, Any]

Initialize the PLC connection.

Returns:

Type	Description
Tuple[bool, Any, Any]	Tuple of (success, plc_object, device_manager)

connect abstractmethod async

connect() -> bool

Establish connection to the PLC.

Returns:

Type	Description
bool	True if connection successful, False otherwise

disconnect abstractmethod async

disconnect() -> bool

Disconnect from the PLC.

Returns:

Type	Description
bool	True if disconnection successful, False otherwise

is_connected abstractmethod async

is_connected() -> bool

Check if PLC is currently connected.

Returns:

Type	Description
bool	True if connected, False otherwise

read_tag abstractmethod async

read_tag(tags: Union[str, List[str]]) -> Dict[str, Any]

Read values from PLC tags.

Parameters:

Name	Type	Description	Default
tags	Union[str, List[str]]	Single tag name or list of tag names	required

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping tag names to their values

write_tag abstractmethod async

write_tag(
    tags: Union[Tuple[str, Any], List[Tuple[str, Any]]],
) -> Dict[str, bool]

Write values to PLC tags.

Parameters:

Name	Type	Description	Default
tags	Union[Tuple[str, Any], List[Tuple[str, Any]]]	Single (tag_name, value) tuple or list of tuples	required

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping tag names to write success status

get_all_tags abstractmethod async

get_all_tags() -> List[str]

Get list of all available tags on the PLC.

Returns:

Type	Description
List[str]	List of tag names

get_tag_info abstractmethod async

get_tag_info(tag_name: str) -> Dict[str, Any]

Get detailed information about a specific tag.

Parameters:

Name	Type	Description	Default
tag_name	str	Name of the tag	required

Returns:

Type	Description
Dict[str, Any]	Dictionary with tag information (type, description, etc.)

get_available_plcs abstractmethod staticmethod

get_available_plcs() -> List[str]

Discover available PLCs for this backend.

Returns:

Type	Description
List[str]	List of PLC identifiers in format "Backend:Identifier"

get_backend_info abstractmethod staticmethod

get_backend_info() -> Dict[str, Any]

Get information about this PLC backend.

Returns:

Type	Description
Dict[str, Any]	Dictionary with backend information

reconnect async

reconnect() -> bool

Attempt to reconnect to the PLC.

Returns:

Type	Description
bool	True if reconnection successful, False otherwise

read_tag_with_retry async

read_tag_with_retry(tags: Union[str, List[str]]) -> Dict[str, Any]

Read tags with retry mechanism.

Parameters:

Name	Type	Description	Default
tags	Union[str, List[str]]	Single tag name or list of tag names	required

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping tag names to their values

Raises:

Type	Description
PLCTagError	If all retry attempts fail

write_tag_with_retry async

write_tag_with_retry(
    tags: Union[Tuple[str, Any], List[Tuple[str, Any]]],
) -> Dict[str, bool]

Write tags with retry mechanism.

Parameters:

Name	Type	Description	Default
tags	Union[Tuple[str, Any], List[Tuple[str, Any]]]	Single (tag_name, value) tuple or list of tuples	required

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping tag names to write success status

Raises:

Type	Description
PLCTagError	If all retry attempts fail

plc_manager

Modern PLC Manager for Mindtrace Hardware System

A comprehensive PLC management system that provides unified access to multiple PLC backends with async operations, proper resource management, and batch processing capabilities.

Key Features

• Automatic PLC discovery and registration
• Unified interface for different PLC manufacturers
• Async operations with proper error handling
• Batch tag read/write operations
• Connection management and monitoring
• Thread-safe operations with proper locking
• Comprehensive configuration management
• Integrated logging and status reporting

Supported Backends

• Allen-Bradley: ControlLogix, CompactLogix PLCs (pycomm3)
• Siemens: S7-300, S7-400, S7-1200, S7-1500 PLCs (python-snap7)
• Modbus: Modbus TCP/RTU devices (pymodbus)
• Mock backends for testing and development

Requirements

• pycomm3: Allen-Bradley PLC communication
• python-snap7: Siemens PLC communication
• pymodbus: Modbus device communication
• asyncio: Async operations support

Installation

pip install pycomm3 python-snap7 pymodbus

Usage

Simple usage with discovery

async with PLCManager() as manager: plcs = await manager.discover_plcs() await manager.register_plc("PLC1", "AllenBradley", "192.168.1.100") await manager.connect_plc("PLC1")

# Read tags
values = await manager.read_tag("PLC1", ["Tag1", "Tag2"])

# Write tags
await manager.write_tag("PLC1", [("Tag1", 100), ("Tag2", 200)])

Batch operations

async with PLCManager() as manager: # Register multiple PLCs await manager.register_plc("PLC1", "AllenBradley", "192.168.1.100") await manager.register_plc("PLC2", "Siemens", "192.168.1.101")

# Connect all PLCs
results = await manager.connect_all_plcs()

# Batch read from multiple PLCs
read_requests = [
    ("PLC1", ["Temperature", "Pressure"]),
    ("PLC2", ["Speed", "Position"])
]
values = await manager.read_tags_batch(read_requests)

Configuration

All parameters are configurable via the hardware configuration system: - MINDTRACE_HW_PLC_AUTO_DISCOVERY: Enable automatic PLC discovery - MINDTRACE_HW_PLC_CONNECTION_TIMEOUT: Connection timeout in seconds - MINDTRACE_HW_PLC_READ_TIMEOUT: Tag read timeout in seconds - MINDTRACE_HW_PLC_WRITE_TIMEOUT: Tag write timeout in seconds - MINDTRACE_HW_PLC_RETRY_COUNT: Number of retry attempts - MINDTRACE_HW_PLC_MAX_CONCURRENT_CONNECTIONS: Maximum concurrent connections - MINDTRACE_HW_PLC_ALLEN_BRADLEY_ENABLED: Enable Allen-Bradley backend - MINDTRACE_HW_PLC_SIEMENS_ENABLED: Enable Siemens backend - MINDTRACE_HW_PLC_MODBUS_ENABLED: Enable Modbus backend

Error Handling

The module uses a comprehensive exception hierarchy for precise error reporting: - PLCError: Base exception for all PLC-related errors - PLCNotFoundError: PLC not found during discovery or registration - PLCConnectionError: Connection establishment or maintenance failures - PLCInitializationError: PLC initialization failures - PLCCommunicationError: Communication protocol errors - PLCTagError: Tag-related operation errors - PLCTagReadError: Tag read operation failures - PLCTagWriteError: Tag write operation failures - HardwareOperationError: General hardware operation failures

Thread Safety

All PLC operations are thread-safe. Multiple PLCs can be operated simultaneously from different threads without interference.

Performance Notes

• PLC discovery may take several seconds depending on network size
• Batch operations are more efficient than individual tag operations
• Connection pooling is used for optimal performance
• Consider PLC-specific optimizations for production use

PLCManager

PLCManager()

Bases: Mindtrace

Unified PLC management system for industrial automation.

This manager provides a comprehensive interface for managing PLCs from different manufacturers with support for discovery, registration, connection management, and batch tag operations. It handles multiple PLC backends transparently and provides thread-safe operations with proper error handling.

The manager supports: - Automatic PLC discovery across multiple backends - Dynamic PLC registration and connection management - Batch tag read/write operations for optimal performance - Connection monitoring and automatic reconnection - Comprehensive error handling and logging - Thread-safe operations with proper resource management

Supported PLC Types: - Allen-Bradley: ControlLogix, CompactLogix, MicroLogix PLCs - Siemens: S7-300, S7-400, S7-1200, S7-1500 PLCs (Future) - Modbus: Modbus TCP/RTU devices (Future) - Mock PLCs: For testing and development

Attributes:

Name	Type	Description
plcs	Dict[str, BasePLC]	Dictionary mapping PLC names to PLC instances
config		Hardware configuration manager instance
logger		Centralized logger for PLC operations

Example

Basic usage

async with PLCManager() as manager: # Discover available PLCs discovered = await manager.discover_plcs()

# Register and connect to a PLC
await manager.register_plc("PLC1", "AllenBradley", "192.168.1.100")
await manager.connect_plc("PLC1")

# Read and write tags
values = await manager.read_tag("PLC1", ["Temperature", "Pressure"])
await manager.write_tag("PLC1", [("Setpoint", 75.0)])

Batch operations

async with PLCManager() as manager: # Register multiple PLCs await manager.register_plc("PLC1", "AllenBradley", "192.168.1.100") await manager.register_plc("PLC2", "AllenBradley", "192.168.1.101")

# Batch read from multiple PLCs
read_requests = [
    ("PLC1", ["Temperature", "Pressure"]),
    ("PLC2", ["Speed", "Position"])
]
results = await manager.read_tags_batch(read_requests)

Initialize the PLC manager.

discover_plcs async

discover_plcs() -> Dict[str, List[str]]

Discover available PLCs from all enabled backends.

Returns:

Type	Description
Dict[str, List[str]]	Dictionary mapping backend names to lists of discovered PLCs

register_plc async

register_plc(
    plc_name: str,
    backend: str,
    ip_address: str,
    plc_type: Optional[str] = None,
    **kwargs
) -> bool

Register a PLC with the manager.

Parameters:

Name	Type	Description	Default
plc_name	str	Unique identifier for the PLC	required
backend	str	Backend type ("AllenBradley", "Siemens", "Modbus")	required
ip_address	str	IP address of the PLC	required
plc_type	Optional[str]	Specific PLC type (backend-dependent)	None
**kwargs		Additional backend-specific parameters	{}

Returns:

Type	Description
bool	True if registration successful, False otherwise

unregister_plc async

unregister_plc(plc_name: str) -> bool

Unregister a PLC from the manager.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC to unregister	required

Returns:

Type	Description
bool	True if unregistration successful, False otherwise

connect_plc async

connect_plc(plc_name: str) -> bool

Connect to a specific PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC to connect	required

Returns:

Type	Description
bool	True if connection successful, False otherwise

disconnect_plc async

disconnect_plc(plc_name: str) -> bool

Disconnect from a specific PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC to disconnect	required

Returns:

Type	Description
bool	True if disconnection successful, False otherwise

connect_all_plcs async

connect_all_plcs() -> Dict[str, bool]

Connect to all registered PLCs.

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping PLC names to connection success status

disconnect_all_plcs async

disconnect_all_plcs() -> Dict[str, bool]

Disconnect from all registered PLCs.

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping PLC names to disconnection success status

read_tag async

read_tag(plc_name: str, tags: Union[str, List[str]]) -> Dict[str, Any]

Read tags from a specific PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC	required
tags	Union[str, List[str]]	Single tag name or list of tag names	required

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping tag names to their values

write_tag async

write_tag(
    plc_name: str, tags: Union[Tuple[str, Any], List[Tuple[str, Any]]]
) -> Dict[str, bool]

Write tags to a specific PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC	required
tags	Union[Tuple[str, Any], List[Tuple[str, Any]]]	Single (tag_name, value) tuple or list of tuples	required

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping tag names to write success status

read_tags_batch async

read_tags_batch(
    requests: List[Tuple[str, Union[str, List[str]]]],
) -> Dict[str, Dict[str, Any]]

Read tags from multiple PLCs in batch.

Parameters:

Name	Type	Description	Default
requests	List[Tuple[str, Union[str, List[str]]]]	List of (plc_name, tags) tuples	required

Returns:

Type	Description
Dict[str, Dict[str, Any]]	Dictionary mapping PLC names to their tag read results

write_tags_batch async

write_tags_batch(
    requests: List[Tuple[str, Union[Tuple[str, Any], List[Tuple[str, Any]]]]],
) -> Dict[str, Dict[str, bool]]

Write tags to multiple PLCs in batch.

Parameters:

Name	Type	Description	Default
requests	List[Tuple[str, Union[Tuple[str, Any], List[Tuple[str, Any]]]]]	List of (plc_name, tags) tuples	required

Returns:

Type	Description
Dict[str, Dict[str, bool]]	Dictionary mapping PLC names to their tag write results

get_plc_status async

get_plc_status(plc_name: str) -> Dict[str, Any]

Get status information for a specific PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC	required

Returns:

Type	Description
Dict[str, Any]	Dictionary with PLC status information

get_all_plc_status async

get_all_plc_status() -> Dict[str, Dict[str, Any]]

Get status information for all registered PLCs.

Returns:

Type	Description
Dict[str, Dict[str, Any]]	Dictionary mapping PLC names to their status information

get_plc_tags async

get_plc_tags(plc_name: str) -> List[str]

Get list of available tags for a specific PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Name of the PLC	required

Returns:

Type	Description
List[str]	List of available tag names

get_registered_plcs

get_registered_plcs() -> List[str]

Get list of registered PLC names.

Returns:

Type	Description
List[str]	List of registered PLC names

get_backend_info

get_backend_info() -> Dict[str, Dict[str, Any]]

Get information about available PLC backends.

Returns:

Type	Description
Dict[str, Dict[str, Any]]	Dictionary mapping backend names to their information

cleanup async

cleanup()

Clean up all PLC connections and resources.

sensors

MindTrace Hardware Sensor System.

A unified sensor system that abstracts different communication backends (MQTT, HTTP, Serial, Modbus) behind a simple AsyncSensor interface.

SensorBackend

Bases: ABC

Abstract base class for all sensor backends.

This interface abstracts different communication patterns: - MQTT: Push-based (subscribe to topics, cache messages) - HTTP: Pull-based (make requests on-demand) - Serial: Pull-based (send commands, read responses) - Modbus: Pull-based (read registers)

connect abstractmethod async

connect() -> None

Establish connection to the backend.

Raises:

Type	Description
ConnectionError	If connection fails

disconnect abstractmethod async

disconnect() -> None

Close connection to the backend.

Should be safe to call multiple times.

read_data abstractmethod async

read_data(address: str) -> Optional[Dict[str, Any]]

Read sensor data from the specified address.

For different backends, 'address' means: - MQTT: topic name (returns cached message) - HTTP: endpoint path (makes GET request) - Serial: sensor command (send command, read response) - Modbus: register address (read holding registers)

Parameters:

Name	Type	Description	Default
address	str	Backend-specific address/identifier	required

Returns:

Type	Description
Optional[Dict[str, Any]]	Dictionary with sensor data, or None if no data available

Raises:

Type	Description
ConnectionError	If backend not connected
TimeoutError	If read operation times out
ValueError	If address is invalid

is_connected abstractmethod

is_connected() -> bool

Check if backend is currently connected.

Returns:

Type	Description
bool	True if connected, False otherwise

HTTPSensorBackend

HTTPSensorBackend(
    base_url: str,
    auth_token: Optional[str] = None,
    timeout: float = 30.0,
    **kwargs
)

Bases: SensorBackend

HTTP backend for sensor communication (placeholder).

This backend will connect to REST APIs and make HTTP GET requests to read sensor data. It implements a pull-based pattern where we request data on-demand.

Future implementation will: - Make HTTP GET requests to base_url + endpoint - Handle authentication headers - Parse JSON responses - Implement timeout and retry logic

Initialize HTTP backend.

Parameters:

Name	Type	Description	Default
base_url	str	Base URL for HTTP requests (e.g., "http://api.sensors.com")	required
auth_token	Optional[str]	Optional authentication token	None
timeout	float	Request timeout in seconds	30.0
**kwargs		Additional HTTP client parameters	{}

connect async

connect() -> None

Establish HTTP client connection.

Raises:

Type	Description
NotImplementedError	HTTP backend not yet implemented

disconnect async

disconnect() -> None

Close HTTP client connection.

read_data async

read_data(address: str) -> Optional[Dict[str, Any]]

Read sensor data via HTTP GET request.

Parameters:

Name	Type	Description	Default
address	str	Endpoint path (e.g., "/sensors/temperature/current")	required

Returns:

Type	Description
Optional[Dict[str, Any]]	JSON response data, or None if request fails

Raises:

Type	Description
NotImplementedError	HTTP backend not yet implemented

is_connected

is_connected() -> bool

Check if HTTP client is ready.

Returns:

Type	Description
bool	Always False until implementation is complete

MQTTSensorBackend

MQTTSensorBackend(
    broker_url: str,
    identifier: Optional[str] = None,
    username: Optional[str] = None,
    password: Optional[str] = None,
    keepalive: int = 60,
    **kwargs
)

Bases: SensorBackend

MQTT backend for sensor communication.

This backend connects to an MQTT broker and subscribes to topics. Messages are cached when received, and read_data() returns the latest cached message.

This implements a push-based pattern where data comes to us, unlike HTTP/Serial which are pull-based where we request data on-demand.

Initialize MQTT backend.

Parameters:

Name	Type	Description	Default
broker_url	str	MQTT broker URL (e.g., "mqtt://localhost:1883")	required
identifier	Optional[str]	MQTT client identifier (auto-generated if None)	None
username	Optional[str]	MQTT username (optional)	None
password	Optional[str]	MQTT password (optional)	None
keepalive	int	MQTT keepalive interval in seconds	60
**kwargs		Additional MQTT client parameters	{}

connect async

connect() -> None

Connect to MQTT broker.

Raises:

Type	Description
ConnectionError	If connection to broker fails

disconnect async

disconnect() -> None

Disconnect from MQTT broker.

read_data async

read_data(address: str) -> Optional[Dict[str, Any]]

Read cached data from MQTT topic.

For MQTT, the address is the topic name. If we haven't subscribed to this topic yet, we'll subscribe and wait briefly for a message.

Parameters:

Name	Type	Description	Default
address	str	MQTT topic name	required

Returns:

Type	Description
Optional[Dict[str, Any]]	Latest cached message for the topic, or None if no data available

Raises:

Type	Description
ConnectionError	If not connected to broker
ValueError	If topic name is invalid

is_connected

is_connected() -> bool

Check if connected to MQTT broker.

Returns:

Type	Description
bool	True if connected, False otherwise

SerialSensorBackend

SerialSensorBackend(
    port: str, baudrate: int = 9600, timeout: float = 5.0, **kwargs
)

Bases: SensorBackend

Serial backend for sensor communication (placeholder).

This backend will connect to sensors via serial/USB ports and send commands to read sensor data. It implements a pull-based pattern where we send commands and read responses on-demand.

Future implementation will: - Connect to serial ports (e.g., /dev/ttyUSB0, COM3) - Send sensor commands and read responses - Parse sensor data (JSON, CSV, or custom formats) - Handle timeouts and communication errors

Initialize Serial backend.

Parameters:

Name	Type	Description	Default
port	str	Serial port path (e.g., "/dev/ttyUSB0" or "COM3")	required
baudrate	int	Serial communication baudrate	9600
timeout	float	Communication timeout in seconds	5.0
**kwargs		Additional serial parameters (parity, stopbits, etc.)	{}

connect async

connect() -> None

Open serial port connection.

Raises:

Type	Description
NotImplementedError	Serial backend not yet implemented

disconnect async

disconnect() -> None

Close serial port connection.

read_data async

read_data(address: str) -> Optional[Dict[str, Any]]

Send command to sensor and read response.

Parameters:

Name	Type	Description	Default
address	str	Sensor command (e.g., "READ_TEMP", "GET_HUMIDITY")	required

Returns:

Type	Description
Optional[Dict[str, Any]]	Parsed sensor response data, or None if command fails

Raises:

Type	Description
NotImplementedError	Serial backend not yet implemented

is_connected

is_connected() -> bool

Check if serial port is open.

Returns:

Type	Description
bool	Always False until implementation is complete

SensorManager

SensorManager()

Simple manager for multiple sensors.

This manager provides basic functionality: - Register sensors with different backends - Remove sensors by ID - Read from all sensors in parallel

The manager keeps sensors in a registry and delegates operations to them.

Initialize sensor manager.

sensor_count property

sensor_count: int

Get number of registered sensors.

register_sensor

register_sensor(
    sensor_id: str,
    backend_type: str,
    connection_params: Dict[str, Any],
    address: str,
) -> AsyncSensor

Register a new sensor with the manager.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required
backend_type	str	Type of backend ("mqtt", "http", "serial")	required
connection_params	Dict[str, Any]	Backend-specific connection parameters	required
address	str	Backend-specific address (topic, endpoint, command)	required

Returns:

Type	Description
AsyncSensor	The created AsyncSensor instance

Raises:

Type	Description
ValueError	If sensor_id already exists or parameters are invalid

Examples:

Register MQTT sensor

sensor = manager.register_sensor( "temp001", "mqtt", {"broker_url": "mqtt://localhost:1883"}, "sensors/temperature" )

Register HTTP sensor

sensor = manager.register_sensor( "temp002", "http", {"base_url": "http://api.sensors.com"}, "/sensors/temperature" )

remove_sensor

remove_sensor(sensor_id: str) -> None

Remove a sensor from the manager.

Parameters:

Name	Type	Description	Default
sensor_id	str	ID of sensor to remove	required

Raises:

Type	Description
ValueError	If sensor_id doesn't exist

get_sensor

get_sensor(sensor_id: str) -> Optional[AsyncSensor]

Get a sensor by ID.

Parameters:

Name	Type	Description	Default
sensor_id	str	ID of sensor to get	required

Returns:

Type	Description
Optional[AsyncSensor]	AsyncSensor instance or None if not found

list_sensors

list_sensors() -> List[str]

Get list of all registered sensor IDs.

Returns:

Type	Description
List[str]	List of sensor IDs

connect_all async

connect_all() -> Dict[str, bool]

Connect all registered sensors.

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping sensor IDs to connection success (True/False)

disconnect_all async

disconnect_all() -> None

Disconnect all registered sensors.

read_all async

read_all() -> Dict[str, Dict[str, Any]]

Read data from all registered sensors.

Returns:

Type	Description
Dict[str, Dict[str, Any]]	Dictionary mapping sensor IDs to their data (or error info)

Examples:

{ "temp001": {"temperature": 23.5, "unit": "C"}, "temp002": {"error": "Not connected"}, "humid001": {"humidity": 65.2, "unit": "%"} }

AsyncSensor

AsyncSensor(sensor_id: str, backend: SensorBackend, address: str)

Unified async sensor interface.

This class provides a simple, consistent API for reading sensor data regardless of the underlying communication backend (MQTT, HTTP, Serial, etc.).

The sensor abstracts different communication patterns: - MQTT: Push-based (messages are cached when received) - HTTP: Pull-based (requests made on-demand) - Serial: Pull-based (commands sent on-demand)

All backends are hidden behind the same connect/disconnect/read interface.

Initialize AsyncSensor with a backend.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for this sensor	required
backend	SensorBackend	Backend implementation (MQTT, HTTP, Serial, etc.)	required
address	str	Backend-specific address (topic, endpoint, command, etc.)	required

Raises:

Type	Description
ValueError	If sensor_id or address is empty
TypeError	If backend is not a SensorBackend instance

sensor_id property

sensor_id: str

Get the sensor ID.

is_connected property

is_connected: bool

Check if sensor backend is connected.

Returns:

Type	Description
bool	True if backend is connected, False otherwise

connect async

connect() -> None

Connect the sensor backend.

This establishes the connection to the underlying communication system (MQTT broker, HTTP server, serial port, etc.).

Raises:

Type	Description
ConnectionError	If connection fails

disconnect async

disconnect() -> None

Disconnect the sensor backend.

This closes the connection to the underlying communication system. Safe to call multiple times.

read async

read() -> Optional[Dict[str, Any]]

Read sensor data.

This method abstracts different communication patterns: - MQTT: Returns cached message from topic - HTTP: Makes GET request to endpoint - Serial: Sends command and reads response

Returns:

Type	Description
Optional[Dict[str, Any]]	Dictionary with sensor data, or None if no data available

Raises:

Type	Description
ConnectionError	If backend is not connected
TimeoutError	If read operation times out
ValueError	If address is invalid

SensorSimulator

SensorSimulator(
    simulator_id: str, backend: SensorSimulatorBackend, address: str
)

Unified sensor simulator interface.

This class provides a simple, consistent API for publishing sensor data regardless of the underlying communication backend (MQTT, HTTP, Serial, etc.).

The simulator abstracts different communication patterns: - MQTT: Publish messages to topics - HTTP: POST data to REST endpoints - Serial: Send data/commands to serial devices

All backends are hidden behind the same connect/disconnect/publish interface. This is perfect for integration testing and sensor data simulation.

Initialize SensorSimulator with a backend.

Parameters:

Name	Type	Description	Default
simulator_id	str	Unique identifier for this simulator	required
backend	SensorSimulatorBackend	Backend implementation (MQTT, HTTP, Serial, etc.)	required
address	str	Backend-specific address (topic, endpoint, command, etc.)	required

Raises:

Type	Description
ValueError	If simulator_id or address is empty
TypeError	If backend is not a SensorSimulatorBackend instance

simulator_id property

simulator_id: str

Get the simulator ID.

is_connected property

is_connected: bool

Check if simulator backend is connected.

Returns:

Type	Description
bool	True if backend is connected, False otherwise

connect async

connect() -> None

Connect the simulator backend.

This establishes the connection to the underlying communication system (MQTT broker, HTTP server, serial port, etc.).

Raises:

Type	Description
ConnectionError	If connection fails

disconnect async

disconnect() -> None

Disconnect the simulator backend.

This closes the connection to the underlying communication system. Safe to call multiple times.

publish async

publish(data: Union[Dict[str, Any], Any]) -> None

Publish sensor data.

This method abstracts different communication patterns: - MQTT: Publishes message to topic - HTTP: Makes POST request to endpoint - Serial: Sends data to serial port

Parameters:

Name	Type	Description	Default
data	Union[Dict[str, Any], Any]	Data to publish (dict, primitive, or complex object)	required

Raises:

Type	Description
ConnectionError	If backend is not connected
TimeoutError	If publish operation times out
ValueError	If address is invalid or data cannot be serialized

SensorSimulatorBackend

Bases: ABC

Abstract base class for all sensor simulator backends.

This interface abstracts different communication patterns for publishing: - MQTT: Publish messages to topics - HTTP: POST data to endpoints - Serial: Send data/commands to serial ports - Modbus: Write to registers

connect abstractmethod async

connect() -> None

Establish connection to the backend.

Raises:

Type	Description
ConnectionError	If connection fails

disconnect abstractmethod async

disconnect() -> None

Close connection to the backend.

Should be safe to call multiple times.

publish_data abstractmethod async

publish_data(address: str, data: Union[Dict[str, Any], Any]) -> None

Publish sensor data to the specified address.

For different backends, 'address' means: - MQTT: topic name to publish to - HTTP: endpoint path to POST to - Serial: sensor command or data format - Modbus: register address to write to

Parameters:

Name	Type	Description	Default
address	str	Backend-specific address/identifier	required
data	Union[Dict[str, Any], Any]	Data to publish (dict, primitive, or complex object)	required

Raises:

Type	Description
ConnectionError	If backend not connected
TimeoutError	If publish operation times out
ValueError	If address is invalid or data cannot be serialized

is_connected abstractmethod

is_connected() -> bool

Check if backend is currently connected.

Returns:

Type	Description
bool	True if connected, False otherwise

HTTPSensorSimulator

HTTPSensorSimulator(
    base_url: str,
    auth_token: Optional[str] = None,
    timeout: float = 30.0,
    **kwargs
)

Bases: SensorSimulatorBackend

HTTP backend for sensor simulation (placeholder).

This backend will connect to REST APIs and make HTTP POST requests to publish sensor data. It implements a push-based pattern where we send data to endpoints.

Future implementation will: - Make HTTP POST requests to base_url + endpoint - Handle authentication headers - Send JSON payloads - Implement timeout and retry logic

Initialize HTTP simulator backend.

Parameters:

Name	Type	Description	Default
base_url	str	Base URL for HTTP requests (e.g., "http://api.sensors.com")	required
auth_token	Optional[str]	Optional authentication token	None
timeout	float	Request timeout in seconds	30.0
**kwargs		Additional HTTP client parameters	{}

connect async

connect() -> None

Establish HTTP client connection.

Raises:

Type	Description
NotImplementedError	HTTP simulator not yet implemented

disconnect async

disconnect() -> None

Close HTTP client connection.

publish_data async

publish_data(address: str, data: Union[Dict[str, Any], Any]) -> None

Publish sensor data via HTTP POST request.

Parameters:

Name	Type	Description	Default
address	str	Endpoint path (e.g., "/sensors/temperature/data")	required
data	Union[Dict[str, Any], Any]	Data to publish (will be JSON-encoded)	required

Raises:

Type	Description
NotImplementedError	HTTP simulator not yet implemented

is_connected

is_connected() -> bool

Check if HTTP client is ready.

Returns:

Type	Description
bool	Always False until implementation is complete

MQTTSensorSimulator

MQTTSensorSimulator(
    broker_url: str,
    identifier: Optional[str] = None,
    username: Optional[str] = None,
    password: Optional[str] = None,
    keepalive: int = 60,
    **kwargs
)

Bases: SensorSimulatorBackend

MQTT backend for sensor simulation.

This backend connects to an MQTT broker and publishes sensor data to topics. It's designed for testing and integration scenarios where you need to simulate sensor data streams that can be consumed by AsyncSensor instances.

Initialize MQTT simulator backend.

Parameters:

Name	Type	Description	Default
broker_url	str	MQTT broker URL (e.g., "mqtt://localhost:1883")	required
identifier	Optional[str]	MQTT client identifier (auto-generated if None)	None
username	Optional[str]	MQTT username (optional)	None
password	Optional[str]	MQTT password (optional)	None
keepalive	int	MQTT keepalive interval in seconds	60
**kwargs		Additional MQTT client parameters	{}

connect async

connect() -> None

Connect to MQTT broker.

Raises:

Type	Description
ConnectionError	If connection to broker fails

disconnect async

disconnect() -> None

Disconnect from MQTT broker.

publish_data async

publish_data(address: str, data: Union[Dict[str, Any], Any]) -> None

Publish sensor data to MQTT topic.

Parameters:

Name	Type	Description	Default
address	str	MQTT topic name to publish to	required
data	Union[Dict[str, Any], Any]	Data to publish (will be JSON-encoded if dict/list)	required

Raises:

Type	Description
ConnectionError	If not connected to broker
ValueError	If topic name is invalid
TimeoutError	If publish operation times out

is_connected

is_connected() -> bool

Check if connected to MQTT broker.

Returns:

Type	Description
bool	True if connected, False otherwise

SerialSensorSimulator

SerialSensorSimulator(
    port: str, baudrate: int = 9600, timeout: float = 5.0, **kwargs
)

Bases: SensorSimulatorBackend

Serial backend for sensor simulation (placeholder).

This backend will connect to serial/USB ports and send sensor data commands. It implements a push-based pattern where we send sensor data to simulate physical sensor devices.

Future implementation will: - Connect to serial ports (e.g., /dev/ttyUSB0, COM3) - Send sensor data in various formats (JSON, CSV, custom protocols) - Simulate sensor response patterns and timing - Handle communication protocols and handshaking

Initialize Serial simulator backend.

Parameters:

Name	Type	Description	Default
port	str	Serial port path (e.g., "/dev/ttyUSB0" or "COM3")	required
baudrate	int	Serial communication baudrate	9600
timeout	float	Communication timeout in seconds	5.0
**kwargs		Additional serial parameters (parity, stopbits, etc.)	{}

connect async

connect() -> None

Open serial port connection.

Raises:

Type	Description
NotImplementedError	Serial simulator not yet implemented

disconnect async

disconnect() -> None

Close serial port connection.

publish_data async

publish_data(address: str, data: Union[Dict[str, Any], Any]) -> None

Send sensor data via serial port.

Parameters:

Name	Type	Description	Default
address	str	Command type or data format identifier (e.g., "TEMP_DATA", "JSON_FORMAT")	required
data	Union[Dict[str, Any], Any]	Data to send (will be formatted according to address)	required

Raises:

Type	Description
NotImplementedError	Serial simulator not yet implemented

is_connected

is_connected() -> bool

Check if serial port is open.

Returns:

Type	Description
bool	Always False until implementation is complete

create_backend

create_backend(backend_type: str, **params) -> SensorBackend

Create a sensor backend of the specified type.

Parameters:

Name	Type	Description	Default
backend_type	str	Type of backend ("mqtt", "http", "serial")	required
**params		Backend-specific parameters	{}

Returns:

Type	Description
SensorBackend	Instantiated backend

Raises:

Type	Description
ValueError	If backend_type is unknown
TypeError	If required parameters are missing

Examples:

MQTT backend

mqtt_backend = create_backend("mqtt", broker_url="mqtt://localhost:1883")

HTTP backend

http_backend = create_backend("http", base_url="http://api.sensors.com")

Serial backend

serial_backend = create_backend("serial", port="/dev/ttyUSB0", baudrate=9600)

create_simulator_backend

create_simulator_backend(backend_type: str, **params) -> SensorSimulatorBackend

Create a sensor simulator backend of the specified type.

Parameters:

Name	Type	Description	Default
backend_type	str	Type of backend ("mqtt", "http", "serial")	required
**params		Backend-specific parameters	{}

Returns:

Type	Description
SensorSimulatorBackend	Instantiated simulator backend

Raises:

Type	Description
ValueError	If backend_type is unknown
TypeError	If required parameters are missing

Examples:

MQTT simulator backend

mqtt_sim = create_simulator_backend("mqtt", broker_url="mqtt://localhost:1883")

HTTP simulator backend

http_sim = create_simulator_backend("http", base_url="http://api.sensors.com")

Serial simulator backend

serial_sim = create_simulator_backend("serial", port="/dev/ttyUSB0", baudrate=9600)

backends

Sensor backends package.

base

Base sensor backend interface.

This module defines the abstract interface that all sensor backends must implement.

SensorBackend

Bases: ABC

Abstract base class for all sensor backends.

This interface abstracts different communication patterns: - MQTT: Push-based (subscribe to topics, cache messages) - HTTP: Pull-based (make requests on-demand) - Serial: Pull-based (send commands, read responses) - Modbus: Pull-based (read registers)

connect abstractmethod async

connect() -> None

Establish connection to the backend.

Raises:

Type	Description
ConnectionError	If connection fails

disconnect abstractmethod async

disconnect() -> None

Close connection to the backend.

Should be safe to call multiple times.

read_data abstractmethod async

read_data(address: str) -> Optional[Dict[str, Any]]

Read sensor data from the specified address.

For different backends, 'address' means: - MQTT: topic name (returns cached message) - HTTP: endpoint path (makes GET request) - Serial: sensor command (send command, read response) - Modbus: register address (read holding registers)

Parameters:

Name	Type	Description	Default
address	str	Backend-specific address/identifier	required

Returns:

Type	Description
Optional[Dict[str, Any]]	Dictionary with sensor data, or None if no data available

Raises:

Type	Description
ConnectionError	If backend not connected
TimeoutError	If read operation times out
ValueError	If address is invalid

is_connected abstractmethod

is_connected() -> bool

Check if backend is currently connected.

Returns:

Type	Description
bool	True if connected, False otherwise

http

HTTP sensor backend implementation (placeholder).

This module will implement the SensorBackend interface for HTTP/REST API communication. Currently this is a placeholder that raises NotImplementedError.

HTTPSensorBackend

HTTPSensorBackend(
    base_url: str,
    auth_token: Optional[str] = None,
    timeout: float = 30.0,
    **kwargs
)

Bases: SensorBackend

HTTP backend for sensor communication (placeholder).

This backend will connect to REST APIs and make HTTP GET requests to read sensor data. It implements a pull-based pattern where we request data on-demand.

Future implementation will: - Make HTTP GET requests to base_url + endpoint - Handle authentication headers - Parse JSON responses - Implement timeout and retry logic

Initialize HTTP backend.

Parameters:

Name	Type	Description	Default
base_url	str	Base URL for HTTP requests (e.g., "http://api.sensors.com")	required
auth_token	Optional[str]	Optional authentication token	None
timeout	float	Request timeout in seconds	30.0
**kwargs		Additional HTTP client parameters	{}

connect async

connect() -> None

Establish HTTP client connection.

Raises:

Type	Description
NotImplementedError	HTTP backend not yet implemented

disconnect async

disconnect() -> None

Close HTTP client connection.

read_data async

read_data(address: str) -> Optional[Dict[str, Any]]

Read sensor data via HTTP GET request.

Parameters:

Name	Type	Description	Default
address	str	Endpoint path (e.g., "/sensors/temperature/current")	required

Returns:

Type	Description
Optional[Dict[str, Any]]	JSON response data, or None if request fails

Raises:

Type	Description
NotImplementedError	HTTP backend not yet implemented

is_connected

is_connected() -> bool

Check if HTTP client is ready.

Returns:

Type	Description
bool	Always False until implementation is complete

mqtt

MQTT sensor backend implementation.

This module implements the SensorBackend interface for MQTT communication. It uses a push-based model where messages are cached when received.

MQTTSensorBackend

MQTTSensorBackend(
    broker_url: str,
    identifier: Optional[str] = None,
    username: Optional[str] = None,
    password: Optional[str] = None,
    keepalive: int = 60,
    **kwargs
)

Bases: SensorBackend

MQTT backend for sensor communication.

This backend connects to an MQTT broker and subscribes to topics. Messages are cached when received, and read_data() returns the latest cached message.

This implements a push-based pattern where data comes to us, unlike HTTP/Serial which are pull-based where we request data on-demand.

Initialize MQTT backend.

Parameters:

Name	Type	Description	Default
broker_url	str	MQTT broker URL (e.g., "mqtt://localhost:1883")	required
identifier	Optional[str]	MQTT client identifier (auto-generated if None)	None
username	Optional[str]	MQTT username (optional)	None
password	Optional[str]	MQTT password (optional)	None
keepalive	int	MQTT keepalive interval in seconds	60
**kwargs		Additional MQTT client parameters	{}

connect async

connect() -> None

Connect to MQTT broker.

Raises:

Type	Description
ConnectionError	If connection to broker fails

disconnect async

disconnect() -> None

Disconnect from MQTT broker.

read_data async

read_data(address: str) -> Optional[Dict[str, Any]]

Read cached data from MQTT topic.

For MQTT, the address is the topic name. If we haven't subscribed to this topic yet, we'll subscribe and wait briefly for a message.

Parameters:

Name	Type	Description	Default
address	str	MQTT topic name	required

Returns:

Type	Description
Optional[Dict[str, Any]]	Latest cached message for the topic, or None if no data available

Raises:

Type	Description
ConnectionError	If not connected to broker
ValueError	If topic name is invalid

is_connected

is_connected() -> bool

Check if connected to MQTT broker.

Returns:

Type	Description
bool	True if connected, False otherwise

serial

Serial sensor backend implementation (placeholder).

This module will implement the SensorBackend interface for serial/USB communication. Currently this is a placeholder that raises NotImplementedError.

SerialSensorBackend

SerialSensorBackend(
    port: str, baudrate: int = 9600, timeout: float = 5.0, **kwargs
)

Bases: SensorBackend

Serial backend for sensor communication (placeholder).

This backend will connect to sensors via serial/USB ports and send commands to read sensor data. It implements a pull-based pattern where we send commands and read responses on-demand.

Future implementation will: - Connect to serial ports (e.g., /dev/ttyUSB0, COM3) - Send sensor commands and read responses - Parse sensor data (JSON, CSV, or custom formats) - Handle timeouts and communication errors

Initialize Serial backend.

Parameters:

Name	Type	Description	Default
port	str	Serial port path (e.g., "/dev/ttyUSB0" or "COM3")	required
baudrate	int	Serial communication baudrate	9600
timeout	float	Communication timeout in seconds	5.0
**kwargs		Additional serial parameters (parity, stopbits, etc.)	{}

connect async

connect() -> None

Open serial port connection.

Raises:

Type	Description
NotImplementedError	Serial backend not yet implemented

disconnect async

disconnect() -> None

Close serial port connection.

read_data async

read_data(address: str) -> Optional[Dict[str, Any]]

Send command to sensor and read response.

Parameters:

Name	Type	Description	Default
address	str	Sensor command (e.g., "READ_TEMP", "GET_HUMIDITY")	required

Returns:

Type	Description
Optional[Dict[str, Any]]	Parsed sensor response data, or None if command fails

Raises:

Type	Description
NotImplementedError	Serial backend not yet implemented

is_connected

is_connected() -> bool

Check if serial port is open.

Returns:

Type	Description
bool	Always False until implementation is complete

core

Sensor core package.

factory

Backend factory for creating sensor backends and simulators.

This module provides factory functions to create different types of sensor backends and simulator backends based on type strings and parameters.

create_backend

create_backend(backend_type: str, **params) -> SensorBackend

Create a sensor backend of the specified type.

Parameters:

Name	Type	Description	Default
backend_type	str	Type of backend ("mqtt", "http", "serial")	required
**params		Backend-specific parameters	{}

Returns:

Type	Description
SensorBackend	Instantiated backend

Raises:

Type	Description
ValueError	If backend_type is unknown
TypeError	If required parameters are missing

Examples:

MQTT backend

mqtt_backend = create_backend("mqtt", broker_url="mqtt://localhost:1883")

HTTP backend

http_backend = create_backend("http", base_url="http://api.sensors.com")

Serial backend

serial_backend = create_backend("serial", port="/dev/ttyUSB0", baudrate=9600)

register_backend

register_backend(backend_type: str, backend_class: type) -> None

Register a custom backend type.

Parameters:

Name	Type	Description	Default
backend_type	str	Name for the backend type	required
backend_class	type	Backend class that implements SensorBackend	required

Raises:

Type	Description
TypeError	If backend_class doesn't inherit from SensorBackend

get_available_backends

get_available_backends() -> Dict[str, type]

Get all available backend types.

Returns:

Type	Description
Dict[str, type]	Dictionary mapping backend names to classes

create_simulator_backend

create_simulator_backend(backend_type: str, **params) -> SensorSimulatorBackend

Create a sensor simulator backend of the specified type.

Parameters:

Name	Type	Description	Default
backend_type	str	Type of backend ("mqtt", "http", "serial")	required
**params		Backend-specific parameters	{}

Returns:

Type	Description
SensorSimulatorBackend	Instantiated simulator backend

Raises:

Type	Description
ValueError	If backend_type is unknown
TypeError	If required parameters are missing

Examples:

MQTT simulator backend

mqtt_sim = create_simulator_backend("mqtt", broker_url="mqtt://localhost:1883")

HTTP simulator backend

http_sim = create_simulator_backend("http", base_url="http://api.sensors.com")

Serial simulator backend

serial_sim = create_simulator_backend("serial", port="/dev/ttyUSB0", baudrate=9600)

register_simulator_backend

register_simulator_backend(backend_type: str, backend_class: type) -> None

Register a custom simulator backend type.

Parameters:

Name	Type	Description	Default
backend_type	str	Name for the backend type	required
backend_class	type	Backend class that implements SensorSimulatorBackend	required

Raises:

Type	Description
TypeError	If backend_class doesn't inherit from SensorSimulatorBackend

get_available_simulator_backends

get_available_simulator_backends() -> Dict[str, type]

Get all available simulator backend types.

Returns:

Type	Description
Dict[str, type]	Dictionary mapping simulator backend names to classes

manager

Simple sensor manager implementation.

This module implements a minimal SensorManager that can register/remove sensors and perform bulk read operations across multiple sensors.

SensorManager

SensorManager()

Simple manager for multiple sensors.

This manager provides basic functionality: - Register sensors with different backends - Remove sensors by ID - Read from all sensors in parallel

The manager keeps sensors in a registry and delegates operations to them.

Initialize sensor manager.

sensor_count property

sensor_count: int

Get number of registered sensors.

register_sensor

register_sensor(
    sensor_id: str,
    backend_type: str,
    connection_params: Dict[str, Any],
    address: str,
) -> AsyncSensor

Register a new sensor with the manager.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required
backend_type	str	Type of backend ("mqtt", "http", "serial")	required
connection_params	Dict[str, Any]	Backend-specific connection parameters	required
address	str	Backend-specific address (topic, endpoint, command)	required

Returns:

Type	Description
AsyncSensor	The created AsyncSensor instance

Raises:

Type	Description
ValueError	If sensor_id already exists or parameters are invalid

Examples:

Register MQTT sensor

sensor = manager.register_sensor( "temp001", "mqtt", {"broker_url": "mqtt://localhost:1883"}, "sensors/temperature" )

Register HTTP sensor

sensor = manager.register_sensor( "temp002", "http", {"base_url": "http://api.sensors.com"}, "/sensors/temperature" )

remove_sensor

remove_sensor(sensor_id: str) -> None

Remove a sensor from the manager.

Parameters:

Name	Type	Description	Default
sensor_id	str	ID of sensor to remove	required

Raises:

Type	Description
ValueError	If sensor_id doesn't exist

get_sensor

get_sensor(sensor_id: str) -> Optional[AsyncSensor]

Get a sensor by ID.

Parameters:

Name	Type	Description	Default
sensor_id	str	ID of sensor to get	required

Returns:

Type	Description
Optional[AsyncSensor]	AsyncSensor instance or None if not found

list_sensors

list_sensors() -> List[str]

Get list of all registered sensor IDs.

Returns:

Type	Description
List[str]	List of sensor IDs

connect_all async

connect_all() -> Dict[str, bool]

Connect all registered sensors.

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping sensor IDs to connection success (True/False)

disconnect_all async

disconnect_all() -> None

Disconnect all registered sensors.

read_all async

read_all() -> Dict[str, Dict[str, Any]]

Read data from all registered sensors.

Returns:

Type	Description
Dict[str, Dict[str, Any]]	Dictionary mapping sensor IDs to their data (or error info)

Examples:

{ "temp001": {"temperature": 23.5, "unit": "C"}, "temp002": {"error": "Not connected"}, "humid001": {"humidity": 65.2, "unit": "%"} }

sensor

Unified AsyncSensor class.

This module implements the main AsyncSensor class that provides a simple, unified interface for all sensor backends (MQTT, HTTP, Serial, etc.).

AsyncSensor

AsyncSensor(sensor_id: str, backend: SensorBackend, address: str)

Unified async sensor interface.

This class provides a simple, consistent API for reading sensor data regardless of the underlying communication backend (MQTT, HTTP, Serial, etc.).

The sensor abstracts different communication patterns: - MQTT: Push-based (messages are cached when received) - HTTP: Pull-based (requests made on-demand) - Serial: Pull-based (commands sent on-demand)

All backends are hidden behind the same connect/disconnect/read interface.

Initialize AsyncSensor with a backend.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for this sensor	required
backend	SensorBackend	Backend implementation (MQTT, HTTP, Serial, etc.)	required
address	str	Backend-specific address (topic, endpoint, command, etc.)	required

Raises:

Type	Description
ValueError	If sensor_id or address is empty
TypeError	If backend is not a SensorBackend instance

sensor_id property

sensor_id: str

Get the sensor ID.

is_connected property

is_connected: bool

Check if sensor backend is connected.

Returns:

Type	Description
bool	True if backend is connected, False otherwise

connect async

connect() -> None

Connect the sensor backend.

This establishes the connection to the underlying communication system (MQTT broker, HTTP server, serial port, etc.).

Raises:

Type	Description
ConnectionError	If connection fails

disconnect async

disconnect() -> None

Disconnect the sensor backend.

This closes the connection to the underlying communication system. Safe to call multiple times.

read async

read() -> Optional[Dict[str, Any]]

Read sensor data.

This method abstracts different communication patterns: - MQTT: Returns cached message from topic - HTTP: Makes GET request to endpoint - Serial: Sends command and reads response

Returns:

Type	Description
Optional[Dict[str, Any]]	Dictionary with sensor data, or None if no data available

Raises:

Type	Description
ConnectionError	If backend is not connected
TimeoutError	If read operation times out
ValueError	If address is invalid

simulator

SensorSimulator class for publishing sensor data.

This module implements the main SensorSimulator class that provides a simple, unified interface for publishing sensor data to all simulator backends (MQTT, HTTP, Serial, etc.).

SensorSimulator

SensorSimulator(
    simulator_id: str, backend: SensorSimulatorBackend, address: str
)

Unified sensor simulator interface.

This class provides a simple, consistent API for publishing sensor data regardless of the underlying communication backend (MQTT, HTTP, Serial, etc.).

The simulator abstracts different communication patterns: - MQTT: Publish messages to topics - HTTP: POST data to REST endpoints - Serial: Send data/commands to serial devices

All backends are hidden behind the same connect/disconnect/publish interface. This is perfect for integration testing and sensor data simulation.

Initialize SensorSimulator with a backend.

Parameters:

Name	Type	Description	Default
simulator_id	str	Unique identifier for this simulator	required
backend	SensorSimulatorBackend	Backend implementation (MQTT, HTTP, Serial, etc.)	required
address	str	Backend-specific address (topic, endpoint, command, etc.)	required

Raises:

Type	Description
ValueError	If simulator_id or address is empty
TypeError	If backend is not a SensorSimulatorBackend instance

simulator_id property

simulator_id: str

Get the simulator ID.

is_connected property

is_connected: bool

Check if simulator backend is connected.

Returns:

Type	Description
bool	True if backend is connected, False otherwise

connect async

connect() -> None

Connect the simulator backend.

This establishes the connection to the underlying communication system (MQTT broker, HTTP server, serial port, etc.).

Raises:

Type	Description
ConnectionError	If connection fails

disconnect async

disconnect() -> None

Disconnect the simulator backend.

This closes the connection to the underlying communication system. Safe to call multiple times.

publish async

publish(data: Union[Dict[str, Any], Any]) -> None

Publish sensor data.

This method abstracts different communication patterns: - MQTT: Publishes message to topic - HTTP: Makes POST request to endpoint - Serial: Sends data to serial port

Parameters:

Name	Type	Description	Default
data	Union[Dict[str, Any], Any]	Data to publish (dict, primitive, or complex object)	required

Raises:

Type	Description
ConnectionError	If backend is not connected
TimeoutError	If publish operation times out
ValueError	If address is invalid or data cannot be serialized

simulators

Sensor simulators for testing and integration purposes.

This module provides SensorSimulator implementations that can publish data to various backends (MQTT, HTTP, Serial) for testing AsyncSensor functionality.

SensorSimulatorBackend

Bases: ABC

Abstract base class for all sensor simulator backends.

This interface abstracts different communication patterns for publishing: - MQTT: Publish messages to topics - HTTP: POST data to endpoints - Serial: Send data/commands to serial ports - Modbus: Write to registers

connect abstractmethod async

connect() -> None

Establish connection to the backend.

Raises:

Type	Description
ConnectionError	If connection fails

disconnect abstractmethod async

disconnect() -> None

Close connection to the backend.

Should be safe to call multiple times.

publish_data abstractmethod async

publish_data(address: str, data: Union[Dict[str, Any], Any]) -> None

Publish sensor data to the specified address.

For different backends, 'address' means: - MQTT: topic name to publish to - HTTP: endpoint path to POST to - Serial: sensor command or data format - Modbus: register address to write to

Parameters:

Name	Type	Description	Default
address	str	Backend-specific address/identifier	required
data	Union[Dict[str, Any], Any]	Data to publish (dict, primitive, or complex object)	required

Raises:

Type	Description
ConnectionError	If backend not connected
TimeoutError	If publish operation times out
ValueError	If address is invalid or data cannot be serialized

is_connected abstractmethod

is_connected() -> bool

Check if backend is currently connected.

Returns:

Type	Description
bool	True if connected, False otherwise

HTTPSensorSimulator

HTTPSensorSimulator(
    base_url: str,
    auth_token: Optional[str] = None,
    timeout: float = 30.0,
    **kwargs
)

Bases: SensorSimulatorBackend

HTTP backend for sensor simulation (placeholder).

This backend will connect to REST APIs and make HTTP POST requests to publish sensor data. It implements a push-based pattern where we send data to endpoints.

Future implementation will: - Make HTTP POST requests to base_url + endpoint - Handle authentication headers - Send JSON payloads - Implement timeout and retry logic

Initialize HTTP simulator backend.

Parameters:

Name	Type	Description	Default
base_url	str	Base URL for HTTP requests (e.g., "http://api.sensors.com")	required
auth_token	Optional[str]	Optional authentication token	None
timeout	float	Request timeout in seconds	30.0
**kwargs		Additional HTTP client parameters	{}

connect async

connect() -> None

Establish HTTP client connection.

Raises:

Type	Description
NotImplementedError	HTTP simulator not yet implemented

disconnect async

disconnect() -> None

Close HTTP client connection.

publish_data async

publish_data(address: str, data: Union[Dict[str, Any], Any]) -> None

Publish sensor data via HTTP POST request.

Parameters:

Name	Type	Description	Default
address	str	Endpoint path (e.g., "/sensors/temperature/data")	required
data	Union[Dict[str, Any], Any]	Data to publish (will be JSON-encoded)	required

Raises:

Type	Description
NotImplementedError	HTTP simulator not yet implemented

is_connected

is_connected() -> bool

Check if HTTP client is ready.

Returns:

Type	Description
bool	Always False until implementation is complete

MQTTSensorSimulator

MQTTSensorSimulator(
    broker_url: str,
    identifier: Optional[str] = None,
    username: Optional[str] = None,
    password: Optional[str] = None,
    keepalive: int = 60,
    **kwargs
)

Bases: SensorSimulatorBackend

MQTT backend for sensor simulation.

This backend connects to an MQTT broker and publishes sensor data to topics. It's designed for testing and integration scenarios where you need to simulate sensor data streams that can be consumed by AsyncSensor instances.

Initialize MQTT simulator backend.

Parameters:

Name	Type	Description	Default
broker_url	str	MQTT broker URL (e.g., "mqtt://localhost:1883")	required
identifier	Optional[str]	MQTT client identifier (auto-generated if None)	None
username	Optional[str]	MQTT username (optional)	None
password	Optional[str]	MQTT password (optional)	None
keepalive	int	MQTT keepalive interval in seconds	60
**kwargs		Additional MQTT client parameters	{}

connect async

connect() -> None

Connect to MQTT broker.

Raises:

Type	Description
ConnectionError	If connection to broker fails

disconnect async

disconnect() -> None

Disconnect from MQTT broker.

publish_data async

publish_data(address: str, data: Union[Dict[str, Any], Any]) -> None

Publish sensor data to MQTT topic.

Parameters:

Name	Type	Description	Default
address	str	MQTT topic name to publish to	required
data	Union[Dict[str, Any], Any]	Data to publish (will be JSON-encoded if dict/list)	required

Raises:

Type	Description
ConnectionError	If not connected to broker
ValueError	If topic name is invalid
TimeoutError	If publish operation times out

is_connected

is_connected() -> bool

Check if connected to MQTT broker.

Returns:

Type	Description
bool	True if connected, False otherwise

SerialSensorSimulator

SerialSensorSimulator(
    port: str, baudrate: int = 9600, timeout: float = 5.0, **kwargs
)

Bases: SensorSimulatorBackend

Serial backend for sensor simulation (placeholder).

This backend will connect to serial/USB ports and send sensor data commands. It implements a push-based pattern where we send sensor data to simulate physical sensor devices.

Future implementation will: - Connect to serial ports (e.g., /dev/ttyUSB0, COM3) - Send sensor data in various formats (JSON, CSV, custom protocols) - Simulate sensor response patterns and timing - Handle communication protocols and handshaking

Initialize Serial simulator backend.

Parameters:

Name	Type	Description	Default
port	str	Serial port path (e.g., "/dev/ttyUSB0" or "COM3")	required
baudrate	int	Serial communication baudrate	9600
timeout	float	Communication timeout in seconds	5.0
**kwargs		Additional serial parameters (parity, stopbits, etc.)	{}

connect async

connect() -> None

Open serial port connection.

Raises:

Type	Description
NotImplementedError	Serial simulator not yet implemented

disconnect async

disconnect() -> None

Close serial port connection.

publish_data async

publish_data(address: str, data: Union[Dict[str, Any], Any]) -> None

Send sensor data via serial port.

Parameters:

Name	Type	Description	Default
address	str	Command type or data format identifier (e.g., "TEMP_DATA", "JSON_FORMAT")	required
data	Union[Dict[str, Any], Any]	Data to send (will be formatted according to address)	required

Raises:

Type	Description
NotImplementedError	Serial simulator not yet implemented

is_connected

is_connected() -> bool

Check if serial port is open.

Returns:

Type	Description
bool	Always False until implementation is complete

base

Base sensor simulator backend interface.

This module defines the abstract interface that all sensor simulator backends must implement.

SensorSimulatorBackend

Bases: ABC

Abstract base class for all sensor simulator backends.

This interface abstracts different communication patterns for publishing: - MQTT: Publish messages to topics - HTTP: POST data to endpoints - Serial: Send data/commands to serial ports - Modbus: Write to registers

connect abstractmethod async

connect() -> None

Establish connection to the backend.

Raises:

Type	Description
ConnectionError	If connection fails

disconnect abstractmethod async

disconnect() -> None

Close connection to the backend.

Should be safe to call multiple times.

publish_data abstractmethod async

publish_data(address: str, data: Union[Dict[str, Any], Any]) -> None

Publish sensor data to the specified address.

For different backends, 'address' means: - MQTT: topic name to publish to - HTTP: endpoint path to POST to - Serial: sensor command or data format - Modbus: register address to write to

Parameters:

Name	Type	Description	Default
address	str	Backend-specific address/identifier	required
data	Union[Dict[str, Any], Any]	Data to publish (dict, primitive, or complex object)	required

Raises:

Type	Description
ConnectionError	If backend not connected
TimeoutError	If publish operation times out
ValueError	If address is invalid or data cannot be serialized

is_connected abstractmethod

is_connected() -> bool

Check if backend is currently connected.

Returns:

Type	Description
bool	True if connected, False otherwise

http

HTTP sensor simulator backend implementation (placeholder).

This module will implement the SensorSimulatorBackend interface for HTTP/REST API communication. Currently this is a placeholder that raises NotImplementedError.

HTTPSensorSimulator

HTTPSensorSimulator(
    base_url: str,
    auth_token: Optional[str] = None,
    timeout: float = 30.0,
    **kwargs
)

Bases: SensorSimulatorBackend

HTTP backend for sensor simulation (placeholder).

This backend will connect to REST APIs and make HTTP POST requests to publish sensor data. It implements a push-based pattern where we send data to endpoints.

Future implementation will: - Make HTTP POST requests to base_url + endpoint - Handle authentication headers - Send JSON payloads - Implement timeout and retry logic

Initialize HTTP simulator backend.

Parameters:

Name	Type	Description	Default
base_url	str	Base URL for HTTP requests (e.g., "http://api.sensors.com")	required
auth_token	Optional[str]	Optional authentication token	None
timeout	float	Request timeout in seconds	30.0
**kwargs		Additional HTTP client parameters	{}

connect async

connect() -> None

Establish HTTP client connection.

Raises:

Type	Description
NotImplementedError	HTTP simulator not yet implemented

disconnect async

disconnect() -> None

Close HTTP client connection.

publish_data async

publish_data(address: str, data: Union[Dict[str, Any], Any]) -> None

Publish sensor data via HTTP POST request.

Parameters:

Name	Type	Description	Default
address	str	Endpoint path (e.g., "/sensors/temperature/data")	required
data	Union[Dict[str, Any], Any]	Data to publish (will be JSON-encoded)	required

Raises:

Type	Description
NotImplementedError	HTTP simulator not yet implemented

is_connected

is_connected() -> bool

Check if HTTP client is ready.

Returns:

Type	Description
bool	Always False until implementation is complete

mqtt

MQTT sensor simulator backend implementation.

This module implements the SensorSimulatorBackend interface for MQTT communication. It publishes sensor data to MQTT topics for testing and integration purposes.

MQTTSensorSimulator

MQTTSensorSimulator(
    broker_url: str,
    identifier: Optional[str] = None,
    username: Optional[str] = None,
    password: Optional[str] = None,
    keepalive: int = 60,
    **kwargs
)

Bases: SensorSimulatorBackend

MQTT backend for sensor simulation.

This backend connects to an MQTT broker and publishes sensor data to topics. It's designed for testing and integration scenarios where you need to simulate sensor data streams that can be consumed by AsyncSensor instances.

Initialize MQTT simulator backend.

Parameters:

Name	Type	Description	Default
broker_url	str	MQTT broker URL (e.g., "mqtt://localhost:1883")	required
identifier	Optional[str]	MQTT client identifier (auto-generated if None)	None
username	Optional[str]	MQTT username (optional)	None
password	Optional[str]	MQTT password (optional)	None
keepalive	int	MQTT keepalive interval in seconds	60
**kwargs		Additional MQTT client parameters	{}

connect async

connect() -> None

Connect to MQTT broker.

Raises:

Type	Description
ConnectionError	If connection to broker fails

disconnect async

disconnect() -> None

Disconnect from MQTT broker.

publish_data async

publish_data(address: str, data: Union[Dict[str, Any], Any]) -> None

Publish sensor data to MQTT topic.

Parameters:

Name	Type	Description	Default
address	str	MQTT topic name to publish to	required
data	Union[Dict[str, Any], Any]	Data to publish (will be JSON-encoded if dict/list)	required

Raises:

Type	Description
ConnectionError	If not connected to broker
ValueError	If topic name is invalid
TimeoutError	If publish operation times out

is_connected

is_connected() -> bool

Check if connected to MQTT broker.

Returns:

Type	Description
bool	True if connected, False otherwise

serial

Serial sensor simulator backend implementation (placeholder).

This module will implement the SensorSimulatorBackend interface for serial/USB communication. Currently this is a placeholder that raises NotImplementedError.

SerialSensorSimulator

SerialSensorSimulator(
    port: str, baudrate: int = 9600, timeout: float = 5.0, **kwargs
)

Bases: SensorSimulatorBackend

Serial backend for sensor simulation (placeholder).

This backend will connect to serial/USB ports and send sensor data commands. It implements a push-based pattern where we send sensor data to simulate physical sensor devices.

Future implementation will: - Connect to serial ports (e.g., /dev/ttyUSB0, COM3) - Send sensor data in various formats (JSON, CSV, custom protocols) - Simulate sensor response patterns and timing - Handle communication protocols and handshaking

Initialize Serial simulator backend.

Parameters:

Name	Type	Description	Default
port	str	Serial port path (e.g., "/dev/ttyUSB0" or "COM3")	required
baudrate	int	Serial communication baudrate	9600
timeout	float	Communication timeout in seconds	5.0
**kwargs		Additional serial parameters (parity, stopbits, etc.)	{}

connect async

connect() -> None

Open serial port connection.

Raises:

Type	Description
NotImplementedError	Serial simulator not yet implemented

disconnect async

disconnect() -> None

Close serial port connection.

publish_data async

publish_data(address: str, data: Union[Dict[str, Any], Any]) -> None

Send sensor data via serial port.

Parameters:

Name	Type	Description	Default
address	str	Command type or data format identifier (e.g., "TEMP_DATA", "JSON_FORMAT")	required
data	Union[Dict[str, Any], Any]	Data to send (will be formatted according to address)	required

Raises:

Type	Description
NotImplementedError	Serial simulator not yet implemented

is_connected

is_connected() -> bool

Check if serial port is open.

Returns:

Type	Description
bool	Always False until implementation is complete

services

Hardware API modules - lazy imports for independent service operation.

cameras

CameraManagerService - Service-based camera management API.

CameraManagerConnectionManager

CameraManagerConnectionManager(
    url: Url | None = None,
    server_id: UUID | None = None,
    server_pid_file: str | None = None,
)

Bases: ConnectionManager

Connection Manager for CameraManagerService.

Provides strongly-typed methods for all camera management operations, making it easy to use the service programmatically from other applications.

get async

get(endpoint: str, http_timeout: float = 60.0) -> Dict[str, Any]

Make GET request to service endpoint.

post async

post(
    endpoint: str, data: Dict[str, Any] = None, http_timeout: float = 60.0
) -> Dict[str, Any]

Make POST request to service endpoint.

discover_backends async

discover_backends() -> List[str]

Discover available camera backends.

Returns:

Type	Description
List[str]	List of available backend names

get_backend_info async

get_backend_info() -> Dict[str, Any]

Get detailed information about all backends.

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping backend names to their information

discover_cameras async

discover_cameras(backend: Optional[str] = None) -> List[str]

Discover available cameras from all or specific backends.

Parameters:

Name	Type	Description	Default
backend	Optional[str]	Optional backend name to filter by	None

Returns:

Type	Description
List[str]	List of camera names in format 'Backend:device_name'

open_camera async

open_camera(camera: str, test_connection: bool = True) -> bool

Open a single camera.

Parameters:

Name	Type	Description	Default
camera	str	Camera name in format 'Backend:device_name'	required
test_connection	bool	Test connection after opening	True

Returns:

Type	Description
bool	True if successful

open_cameras_batch async

open_cameras_batch(
    cameras: List[str], test_connection: bool = True
) -> Dict[str, Any]

Open multiple cameras in batch.

Parameters:

Name	Type	Description	Default
cameras	List[str]	List of camera names	required
test_connection	bool	Test connection after opening	True

Returns:

Type	Description
Dict[str, Any]	Batch operation results

close_camera async

close_camera(camera: str) -> bool

Close a specific camera.

Parameters:

Name	Type	Description	Default
camera	str	Camera name to close	required

Returns:

Type	Description
bool	True if successful

close_cameras_batch async

close_cameras_batch(cameras: List[str]) -> Dict[str, Any]

Close multiple cameras in batch.

Parameters:

Name	Type	Description	Default
cameras	List[str]	List of camera names to close	required

Returns:

Type	Description
Dict[str, Any]	Batch operation results

close_all_cameras async

close_all_cameras() -> bool

Close all active cameras.

Returns:

Type	Description
bool	True if successful

get_active_cameras async

get_active_cameras() -> List[str]

Get list of currently active cameras.

Returns:

Type	Description
List[str]	List of active camera names

get_camera_status async

get_camera_status(camera: str) -> Dict[str, Any]

Get camera status information.

Parameters:

Name	Type	Description	Default
camera	str	Camera name to query	required

Returns:

Type	Description
Dict[str, Any]	Camera status information

get_camera_info async

get_camera_info(camera: str) -> Dict[str, Any]

Get detailed camera information.

Parameters:

Name	Type	Description	Default
camera	str	Camera name to query	required

Returns:

Type	Description
Dict[str, Any]	Camera information

get_camera_capabilities async

get_camera_capabilities(camera: str) -> Dict[str, Any]

Get camera capabilities information.

Parameters:

Name	Type	Description	Default
camera	str	Camera name to query	required

Returns:

Type	Description
Dict[str, Any]	Camera capabilities

get_system_diagnostics async

get_system_diagnostics() -> Dict[str, Any]

Get system diagnostics information.

Returns:

Type	Description
Dict[str, Any]	System diagnostics data

configure_camera async

configure_camera(camera: str, properties: Dict[str, Any]) -> bool

Configure camera parameters.

Parameters:

Name	Type	Description	Default
camera	str	Camera name to configure	required
properties	Dict[str, Any]	Configuration properties	required

Returns:

Type	Description
bool	True if successful

configure_cameras_batch async

configure_cameras_batch(
    configurations: Dict[str, Dict[str, Any]],
) -> Dict[str, Any]

Configure multiple cameras in batch.

Parameters:

Name	Type	Description	Default
configurations	Dict[str, Dict[str, Any]]	Dictionary mapping camera names to their configurations	required

Returns:

Type	Description
Dict[str, Any]	Batch operation results

get_camera_configuration async

get_camera_configuration(camera: str) -> Dict[str, Any]

Get current camera configuration.

Parameters:

Name	Type	Description	Default
camera	str	Camera name to query	required

Returns:

Type	Description
Dict[str, Any]	Current camera configuration

import_camera_config async

import_camera_config(camera: str, config_path: str) -> Dict[str, Any]

Import camera configuration from file.

Parameters:

Name	Type	Description	Default
camera	str	Camera name	required
config_path	str	Path to configuration file	required

Returns:

Type	Description
Dict[str, Any]	Import operation result

export_camera_config async

export_camera_config(camera: str, config_path: str) -> Dict[str, Any]

Export camera configuration to file.

Parameters:

Name	Type	Description	Default
camera	str	Camera name	required
config_path	str	Path to save configuration file	required

Returns:

Type	Description
Dict[str, Any]	Export operation result

capture_image async

capture_image(
    camera: str, save_path: Optional[str] = None, output_format: str = "pil"
) -> Dict[str, Any]

Capture a single image.

Parameters:

Name	Type	Description	Default
camera	str	Camera name	required
save_path	Optional[str]	Optional path to save image	None
output_format	str	Output format for returned image ("numpy" or "pil")	'pil'

Returns:

Type	Description
Dict[str, Any]	Capture result

capture_images_batch async

capture_images_batch(
    cameras: List[str], output_format: str = "pil"
) -> Dict[str, Any]

Capture images from multiple cameras.

Parameters:

Name	Type	Description	Default
cameras	List[str]	List of camera names	required
output_format	str	Output format for returned images ("numpy" or "pil")	'pil'

Returns:

Type	Description
Dict[str, Any]	Batch capture results

capture_hdr_image async

capture_hdr_image(
    camera: str,
    save_path_pattern: Optional[str] = None,
    exposure_levels: int = 3,
    exposure_multiplier: float = 2.0,
    return_images: bool = True,
    output_format: str = "pil",
) -> Dict[str, Any]

Capture HDR image sequence.

Parameters:

Name	Type	Description	Default
camera	str	Camera name	required
save_path_pattern	Optional[str]	Path pattern with {exposure} placeholder	None
exposure_levels	int	Number of exposure levels	3
exposure_multiplier	float	Multiplier between exposures	2.0
return_images	bool	Return captured images	True
output_format	str	Output format for returned images ("numpy" or "pil")	'pil'

Returns:

Type	Description
Dict[str, Any]	HDR capture result

capture_hdr_images_batch async

capture_hdr_images_batch(
    cameras: List[str],
    save_path_pattern: Optional[str] = None,
    exposure_levels: int = 3,
    exposure_multiplier: float = 2.0,
    return_images: bool = True,
    output_format: str = "pil",
) -> Dict[str, Any]

Capture HDR images from multiple cameras.

Parameters:

Name	Type	Description	Default
cameras	List[str]	List of camera names	required
save_path_pattern	Optional[str]	Path pattern with {exposure} placeholder	None
exposure_levels	int	Number of exposure levels	3
exposure_multiplier	float	Multiplier between exposures	2.0
return_images	bool	Return captured images	True
output_format	str	Output format for returned images ("numpy" or "pil")	'pil'

Returns:

Type	Description
Dict[str, Any]	Batch HDR capture results

get_bandwidth_settings async

get_bandwidth_settings() -> Dict[str, Any]

Get current bandwidth settings.

Returns:

Type	Description
Dict[str, Any]	Bandwidth settings

set_bandwidth_limit async

set_bandwidth_limit(max_concurrent_captures: int) -> bool

Set maximum concurrent capture limit.

Parameters:

Name	Type	Description	Default
max_concurrent_captures	int	Maximum concurrent captures	required

Returns:

Type	Description
bool	True if successful

get_network_diagnostics async

get_network_diagnostics() -> Dict[str, Any]

Get network diagnostics information.

Returns:

Type	Description
Dict[str, Any]	Network diagnostics data

CameraManagerService

CameraManagerService(include_mocks: bool = False, **kwargs)

Bases: Service

Camera Management Service.

Provides comprehensive camera management functionality through a Service-based architecture with MCP tool integration and async camera operations.

Initialize CameraManagerService.

Parameters:

Name	Type	Description	Default
include_mocks	bool	Include mock cameras in discovery	False
**kwargs		Additional Service initialization parameters	{}

shutdown_cleanup async

shutdown_cleanup()

Cleanup camera manager on shutdown.

discover_backends async

discover_backends() -> BackendsResponse

Discover available camera backends.

get_backend_info async

get_backend_info() -> BackendInfoResponse

Get detailed information about all backends.

discover_cameras async

discover_cameras(request: BackendFilterRequest) -> ListResponse

Discover available cameras from all or specific backends.

open_camera async

open_camera(request: CameraOpenRequest) -> BoolResponse

Open a single camera with exposure validation.

open_cameras_batch async

open_cameras_batch(request: CameraOpenBatchRequest) -> BatchOperationResponse

Open multiple cameras in batch.

close_camera async

close_camera(request: CameraCloseRequest) -> BoolResponse

Close a specific camera.

close_cameras_batch async

close_cameras_batch(request: CameraCloseBatchRequest) -> BatchOperationResponse

Close multiple cameras in batch.

close_all_cameras async

close_all_cameras() -> BoolResponse

Close all active cameras.

get_active_cameras async

get_active_cameras() -> ActiveCamerasResponse

Get list of currently active cameras.

get_camera_status async

get_camera_status(request: CameraQueryRequest) -> CameraStatusResponse

Get camera status information.

get_camera_info async

get_camera_info(request: CameraQueryRequest) -> CameraInfoResponse

Get detailed camera information.

get_camera_capabilities async

get_camera_capabilities(
    request: CameraQueryRequest,
) -> CameraCapabilitiesResponse

Get camera capabilities information.

configure_camera async

configure_camera(request: CameraConfigureRequest) -> BoolResponse

Configure camera parameters.

configure_cameras_batch async

configure_cameras_batch(
    request: CameraConfigureBatchRequest,
) -> BatchOperationResponse

Configure multiple cameras in batch.

get_camera_configuration async

get_camera_configuration(
    request: CameraQueryRequest,
) -> CameraConfigurationResponse

Get current camera configuration.

import_camera_config async

import_camera_config(request: ConfigFileImportRequest) -> ConfigFileResponse

Import camera configuration from file.

export_camera_config async

export_camera_config(request: ConfigFileExportRequest) -> ConfigFileResponse

Export camera configuration to file.

capture_image async

capture_image(request: CaptureImageRequest) -> CaptureResponse

Capture a single image with timeout protection.

capture_images_batch async

capture_images_batch(request: CaptureBatchRequest) -> BatchCaptureResponse

Capture images from multiple cameras.

capture_hdr_image async

capture_hdr_image(request: CaptureHDRRequest) -> HDRCaptureResponse

Capture HDR image sequence.

capture_hdr_images_batch async

capture_hdr_images_batch(
    request: CaptureHDRBatchRequest,
) -> BatchHDRCaptureResponse

Capture HDR images from multiple cameras.

get_network_diagnostics async

get_network_diagnostics() -> NetworkDiagnosticsResponse

Get network diagnostics information.

get_performance_settings async

get_performance_settings(
    request: CameraPerformanceSettingsRequest = None,
) -> CameraPerformanceSettingsResponse

Get current camera performance settings.

Returns global settings (timeout, retries, concurrent captures) and optionally per-camera GigE settings (packet_size, inter_packet_delay, bandwidth_limit) if camera is specified.

set_performance_settings async

set_performance_settings(
    request: CameraPerformanceSettingsRequest,
) -> BoolResponse

Update camera performance settings.

Updates global settings (timeout, retries, concurrent captures) and optionally per-camera GigE settings (packet_size, inter_packet_delay, bandwidth_limit) if camera is specified.

start_stream async

start_stream(request: StreamStartRequest) -> StreamInfoResponse

Start camera stream with resilient state management.

stop_stream

stop_stream(request: StreamStopRequest) -> BoolResponse

Stop camera stream with resilient state management.

get_stream_status async

get_stream_status(request: StreamStatusRequest) -> StreamStatusResponse

Get camera stream status with resilient state management.

get_active_streams

get_active_streams() -> ActiveStreamsResponse

Get list of cameras with active streams.

stop_all_streams

stop_all_streams() -> BoolResponse

Stop all active camera streams.

serve_camera_stream async

serve_camera_stream(camera_name: str)

Serve MJPEG video stream for a specific camera.

calibrate_homography_checkerboard async

calibrate_homography_checkerboard(
    request: HomographyCalibrateCheckerboardRequest,
) -> HomographyCalibrationResponse

Calibrate homography using checkerboard pattern detection.

calibrate_homography_correspondences

calibrate_homography_correspondences(
    request: HomographyCalibrateCorrespondencesRequest,
) -> HomographyCalibrationResponse

Calibrate homography from known point correspondences.

calibrate_homography_multi_view

calibrate_homography_multi_view(
    request: HomographyCalibrateMultiViewRequest,
) -> HomographyCalibrationResponse

Calibrate homography from multiple checkerboard positions on the same plane.

Ideal for calibrating long surfaces (metallic bars, conveyor belts) using a standard checkerboard moved to multiple positions.

measure_homography_box

measure_homography_box(
    request: HomographyMeasureBoundingBoxRequest,
) -> HomographyMeasurementResponse

Measure bounding box dimensions using homography calibration.

measure_homography_batch

measure_homography_batch(
    request: HomographyMeasureBatchRequest,
) -> HomographyBatchMeasurementResponse

Unified batch measurement for bounding boxes and/or point-pair distances.

measure_homography_distance

measure_homography_distance(
    request: HomographyMeasureDistanceRequest,
) -> HomographyDistanceResponse

Measure distance between two points using homography calibration.

health_check async

health_check() -> HealthCheckResponse

Health check endpoint for container healthcheck.

get_system_diagnostics async

get_system_diagnostics() -> SystemDiagnosticsResponse

Get system diagnostics information.

connection_manager

Connection Manager for CameraManagerService.

Provides a strongly-typed client interface for programmatic access to camera management operations.

CameraManagerConnectionManager

CameraManagerConnectionManager(
    url: Url | None = None,
    server_id: UUID | None = None,
    server_pid_file: str | None = None,
)

Bases: ConnectionManager

Connection Manager for CameraManagerService.

Provides strongly-typed methods for all camera management operations, making it easy to use the service programmatically from other applications.

get async

get(endpoint: str, http_timeout: float = 60.0) -> Dict[str, Any]

Make GET request to service endpoint.

post async

post(
    endpoint: str, data: Dict[str, Any] = None, http_timeout: float = 60.0
) -> Dict[str, Any]

Make POST request to service endpoint.

discover_backends async

discover_backends() -> List[str]

Discover available camera backends.

Returns:

Type	Description
List[str]	List of available backend names

get_backend_info async

get_backend_info() -> Dict[str, Any]

Get detailed information about all backends.

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping backend names to their information

discover_cameras async

discover_cameras(backend: Optional[str] = None) -> List[str]

Discover available cameras from all or specific backends.

Parameters:

Name	Type	Description	Default
backend	Optional[str]	Optional backend name to filter by	None

Returns:

Type	Description
List[str]	List of camera names in format 'Backend:device_name'

open_camera async

open_camera(camera: str, test_connection: bool = True) -> bool

Open a single camera.

Parameters:

Name	Type	Description	Default
camera	str	Camera name in format 'Backend:device_name'	required
test_connection	bool	Test connection after opening	True

Returns:

Type	Description
bool	True if successful

open_cameras_batch async

open_cameras_batch(
    cameras: List[str], test_connection: bool = True
) -> Dict[str, Any]

Open multiple cameras in batch.

Parameters:

Name	Type	Description	Default
cameras	List[str]	List of camera names	required
test_connection	bool	Test connection after opening	True

Returns:

Type	Description
Dict[str, Any]	Batch operation results

close_camera async

close_camera(camera: str) -> bool

Close a specific camera.

Parameters:

Name	Type	Description	Default
camera	str	Camera name to close	required

Returns:

Type	Description
bool	True if successful

close_cameras_batch async

close_cameras_batch(cameras: List[str]) -> Dict[str, Any]

Close multiple cameras in batch.

Parameters:

Name	Type	Description	Default
cameras	List[str]	List of camera names to close	required

Returns:

Type	Description
Dict[str, Any]	Batch operation results

close_all_cameras async

close_all_cameras() -> bool

Close all active cameras.

Returns:

Type	Description
bool	True if successful

get_active_cameras async

get_active_cameras() -> List[str]

Get list of currently active cameras.

Returns:

Type	Description
List[str]	List of active camera names

get_camera_status async

get_camera_status(camera: str) -> Dict[str, Any]

Get camera status information.

Parameters:

Name	Type	Description	Default
camera	str	Camera name to query	required

Returns:

Type	Description
Dict[str, Any]	Camera status information

get_camera_info async

get_camera_info(camera: str) -> Dict[str, Any]

Get detailed camera information.

Parameters:

Name	Type	Description	Default
camera	str	Camera name to query	required

Returns:

Type	Description
Dict[str, Any]	Camera information

get_camera_capabilities async

get_camera_capabilities(camera: str) -> Dict[str, Any]

Get camera capabilities information.

Parameters:

Name	Type	Description	Default
camera	str	Camera name to query	required

Returns:

Type	Description
Dict[str, Any]	Camera capabilities

get_system_diagnostics async

get_system_diagnostics() -> Dict[str, Any]

Get system diagnostics information.

Returns:

Type	Description
Dict[str, Any]	System diagnostics data

configure_camera async

configure_camera(camera: str, properties: Dict[str, Any]) -> bool

Configure camera parameters.

Parameters:

Name	Type	Description	Default
camera	str	Camera name to configure	required
properties	Dict[str, Any]	Configuration properties	required

Returns:

Type	Description
bool	True if successful

configure_cameras_batch async

configure_cameras_batch(
    configurations: Dict[str, Dict[str, Any]],
) -> Dict[str, Any]

Configure multiple cameras in batch.

Parameters:

Name	Type	Description	Default
configurations	Dict[str, Dict[str, Any]]	Dictionary mapping camera names to their configurations	required

Returns:

Type	Description
Dict[str, Any]	Batch operation results

get_camera_configuration async

get_camera_configuration(camera: str) -> Dict[str, Any]

Get current camera configuration.

Parameters:

Name	Type	Description	Default
camera	str	Camera name to query	required

Returns:

Type	Description
Dict[str, Any]	Current camera configuration

import_camera_config async

import_camera_config(camera: str, config_path: str) -> Dict[str, Any]

Import camera configuration from file.

Parameters:

Name	Type	Description	Default
camera	str	Camera name	required
config_path	str	Path to configuration file	required

Returns:

Type	Description
Dict[str, Any]	Import operation result

export_camera_config async

export_camera_config(camera: str, config_path: str) -> Dict[str, Any]

Export camera configuration to file.

Parameters:

Name	Type	Description	Default
camera	str	Camera name	required
config_path	str	Path to save configuration file	required

Returns:

Type	Description
Dict[str, Any]	Export operation result

capture_image async

capture_image(
    camera: str, save_path: Optional[str] = None, output_format: str = "pil"
) -> Dict[str, Any]

Capture a single image.

Parameters:

Name	Type	Description	Default
camera	str	Camera name	required
save_path	Optional[str]	Optional path to save image	None
output_format	str	Output format for returned image ("numpy" or "pil")	'pil'

Returns:

Type	Description
Dict[str, Any]	Capture result

capture_images_batch async

capture_images_batch(
    cameras: List[str], output_format: str = "pil"
) -> Dict[str, Any]

Capture images from multiple cameras.

Parameters:

Name	Type	Description	Default
cameras	List[str]	List of camera names	required
output_format	str	Output format for returned images ("numpy" or "pil")	'pil'

Returns:

Type	Description
Dict[str, Any]	Batch capture results

capture_hdr_image async

capture_hdr_image(
    camera: str,
    save_path_pattern: Optional[str] = None,
    exposure_levels: int = 3,
    exposure_multiplier: float = 2.0,
    return_images: bool = True,
    output_format: str = "pil",
) -> Dict[str, Any]

Capture HDR image sequence.

Parameters:

Name	Type	Description	Default
camera	str	Camera name	required
save_path_pattern	Optional[str]	Path pattern with {exposure} placeholder	None
exposure_levels	int	Number of exposure levels	3
exposure_multiplier	float	Multiplier between exposures	2.0
return_images	bool	Return captured images	True
output_format	str	Output format for returned images ("numpy" or "pil")	'pil'

Returns:

Type	Description
Dict[str, Any]	HDR capture result

capture_hdr_images_batch async

capture_hdr_images_batch(
    cameras: List[str],
    save_path_pattern: Optional[str] = None,
    exposure_levels: int = 3,
    exposure_multiplier: float = 2.0,
    return_images: bool = True,
    output_format: str = "pil",
) -> Dict[str, Any]

Capture HDR images from multiple cameras.

Parameters:

Name	Type	Description	Default
cameras	List[str]	List of camera names	required
save_path_pattern	Optional[str]	Path pattern with {exposure} placeholder	None
exposure_levels	int	Number of exposure levels	3
exposure_multiplier	float	Multiplier between exposures	2.0
return_images	bool	Return captured images	True
output_format	str	Output format for returned images ("numpy" or "pil")	'pil'

Returns:

Type	Description
Dict[str, Any]	Batch HDR capture results

get_bandwidth_settings async

get_bandwidth_settings() -> Dict[str, Any]

Get current bandwidth settings.

Returns:

Type	Description
Dict[str, Any]	Bandwidth settings

set_bandwidth_limit async

set_bandwidth_limit(max_concurrent_captures: int) -> bool

Set maximum concurrent capture limit.

Parameters:

Name	Type	Description	Default
max_concurrent_captures	int	Maximum concurrent captures	required

Returns:

Type	Description
bool	True if successful

get_network_diagnostics async

get_network_diagnostics() -> Dict[str, Any]

Get network diagnostics information.

Returns:

Type	Description
Dict[str, Any]	Network diagnostics data

launcher

Camera API service launcher.

main

main()

Main launcher function.

models

Models for CameraManagerService API.

BackendFilterRequest

Bases: BaseModel

Request model for backend filtering.

BandwidthLimitCameraRequest

Bases: BaseModel

Request model for setting camera bandwidth limit.

BandwidthLimitRequest

Bases: BaseModel

Request model for setting bandwidth limit.

CameraCloseBatchRequest

Bases: BaseModel

Request model for batch camera closing.

CameraCloseRequest

Bases: BaseModel

Request model for closing a camera.

CameraConfigureBatchRequest

Bases: BaseModel

Request model for batch camera configuration.

validate_configurations classmethod

validate_configurations(
    v: Union[Dict[str, Dict[str, Any]], List[Dict[str, Any]]],
) -> Dict[str, Dict[str, Any]]

Convert list format to dict format.

CameraConfigureRequest

Bases: BaseModel

Request model for camera configuration.

CameraOpenBatchRequest

Bases: BaseModel

Request model for batch camera opening.

CameraOpenRequest

Bases: BaseModel

Request model for opening a camera.

CameraPerformanceSettingsRequest

Bases: BaseModel

Request model for updating camera performance settings.

Global settings (always applicable): - timeout_ms, retrieve_retry_count, max_concurrent_captures

Per-camera GigE settings (requires camera field, only for GigE cameras): - packet_size, inter_packet_delay, bandwidth_limit_mbps

CameraQueryRequest

Bases: BaseModel

Request model for camera query operations.

CaptureBatchRequest

Bases: BaseModel

Request model for batch image capture.

validate_output_format classmethod

validate_output_format(v: str) -> str

Validate output format is supported.

CaptureHDRBatchRequest

Bases: BaseModel

Request model for batch HDR image capture.

validate_exposure_levels classmethod

validate_exposure_levels(v: Union[int, List[float]]) -> Union[int, List[float]]

Validate exposure levels.

validate_output_format classmethod

validate_output_format(v: str) -> str

Validate output format is supported.

CaptureHDRRequest

Bases: BaseModel

Request model for HDR image capture.

validate_exposure_levels classmethod

validate_exposure_levels(v: Union[int, List[float]]) -> Union[int, List[float]]

Validate exposure levels.

validate_output_format classmethod

validate_output_format(v: str) -> str

Validate output format is supported.

CaptureImageRequest

Bases: BaseModel

Request model for single image capture.

validate_output_format classmethod

validate_output_format(v: str) -> str

Validate output format is supported.

ConfigFileExportRequest

Bases: BaseModel

Request model for configuration file export.

ConfigFileImportRequest

Bases: BaseModel

Request model for configuration file import.

ExposureRequest

Bases: BaseModel

Request model for exposure setting.

GainRequest

Bases: BaseModel

Request model for gain setting.

HomographyCalibrateCheckerboardRequest

Bases: BaseModel

Request model for checkerboard-based homography calibration.

HomographyCalibrateCorrespondencesRequest

Bases: BaseModel

Request model for manual point correspondence calibration.

validate_points classmethod

validate_points(v: List[List[float]]) -> List[List[float]]

Validate point arrays.

HomographyCalibrateMultiViewRequest

Bases: BaseModel

Request model for multi-view checkerboard calibration.

Note: Checkerboard parameters (board_size, square_size, world_unit) are configured in HomographySettings (see config.py), not passed per-request.

validate_positions classmethod

validate_positions(v: List[Dict[str, float]]) -> List[Dict[str, float]]

Validate position format.

validate_lengths_match

validate_lengths_match()

Ensure number of images matches number of positions.

HomographyMeasureBatchRequest

Bases: BaseModel

Unified request model for batch measurements (bounding boxes and/or point-pair distances).

validate_boxes classmethod

validate_boxes(
    v: Optional[List[Dict[str, int]]],
) -> Optional[List[Dict[str, int]]]

Validate bounding boxes.

validate_point_pairs classmethod

validate_point_pairs(
    v: Optional[List[List[List[float]]]],
) -> Optional[List[List[List[float]]]]

Validate point pairs.

validate_at_least_one

validate_at_least_one()

Ensure at least one measurement type is provided.

HomographyMeasureBoundingBoxRequest

Bases: BaseModel

Request model for measuring a single bounding box.

HomographyMeasureDistanceRequest

Bases: BaseModel

Request model for measuring distance between two points.

ImageEnhancementRequest

Bases: BaseModel

Request model for image enhancement setting.

InterPacketDelayRequest

Bases: BaseModel

Request model for setting inter-packet delay.

PacketSizeRequest

Bases: BaseModel

Request model for setting camera packet size.

PixelFormatRequest

Bases: BaseModel

Request model for pixel format setting.

ROIRequest

Bases: BaseModel

Request model for ROI (Region of Interest) setting.

StreamStartRequest

Bases: BaseModel

Request model for starting camera stream.

StreamStatusRequest

Bases: BaseModel

Request model for getting stream status.

StreamStopRequest

Bases: BaseModel

Request model for stopping camera stream.

TriggerModeRequest

Bases: BaseModel

Request model for trigger mode setting.

WhiteBalanceRequest

Bases: BaseModel

Request model for white balance setting.

ActiveCamerasResponse

Bases: BaseResponse

Response model for active cameras list.

ActiveStreamsResponse

Bases: BaseResponse

Response model for active streams list.

BackendInfo

Bases: BaseModel

Backend information model.

BackendInfoResponse

Bases: BaseResponse

Response model for detailed backend information.

BackendsResponse

Bases: BaseResponse

Response model for backend listing.

BandwidthSettings

Bases: BaseModel

Bandwidth settings model.

BandwidthSettingsResponse

Bases: BaseResponse

Response model for bandwidth settings.

BaseResponse

Bases: BaseModel

Base response model for all API endpoints.

BatchCaptureResponse

Bases: BaseResponse

Response model for batch capture operations.

BatchHDRCaptureResponse

Bases: BaseResponse

Response model for batch HDR capture.

BatchOperationResponse

Bases: BaseResponse

Response model for batch operations.

BatchOperationResult

Bases: BaseModel

Batch operation result model.

BoolResponse

Bases: BaseResponse

Response model for boolean operations.

CameraCapabilities

Bases: BaseModel

Camera capabilities model.

CameraCapabilitiesResponse

Bases: BaseResponse

Response model for camera capabilities.

CameraConfiguration

Bases: BaseModel

Camera configuration model.

CameraConfigurationResponse

Bases: BaseResponse

Response model for camera configuration.

CameraInfo

Bases: BaseModel

Camera information model.

CameraInfoResponse

Bases: BaseResponse

Response model for camera information.

CameraPerformanceSettings

Bases: BaseModel

Camera performance and retry settings model.

Global settings: - timeout_ms, retrieve_retry_count, max_concurrent_captures

Per-camera GigE settings (None if not applicable or not queried): - packet_size, inter_packet_delay, bandwidth_limit_mbps

CameraPerformanceSettingsResponse

Bases: BaseResponse

Response model for camera performance settings.

CameraStatus

Bases: BaseModel

Camera status model.

CameraStatusResponse

Bases: BaseResponse

Response model for camera status.

CaptureResponse

Bases: BaseResponse

Response model for single image capture.

CaptureResult

Bases: BaseModel

Capture result model.

ConfigFileOperationResult

Bases: BaseModel

Configuration file operation result.

ConfigFileResponse

Bases: BaseResponse

Response model for configuration file operations.

DictResponse

Bases: BaseResponse

Response model for dictionary data.

ErrorDetail

Bases: BaseModel

Error detail model.

ErrorResponse

Bases: BaseResponse

Response model for error conditions.

FloatResponse

Bases: BaseResponse

Response model for float values.

HDRCaptureResponse

Bases: BaseResponse

Response model for HDR capture.

HDRCaptureResult

Bases: BaseModel

HDR capture result model.

HealthCheckResponse

Bases: BaseModel

Health check response model.

HomographyBatchMeasurementData

Bases: BaseModel

Batch measurement data containing both box and distance measurements.

HomographyBatchMeasurementResponse

Bases: BaseResponse

Response model for unified batch homography measurements.

HomographyCalibrationResponse

Bases: BaseResponse

Response model for homography calibration.

HomographyCalibrationResult

Bases: BaseModel

Homography calibration result model.

HomographyDistanceResponse

Bases: BaseResponse

Response model for distance measurement.

HomographyDistanceResult

Bases: BaseModel

Homography distance measurement result model.

HomographyMeasurementResponse

Bases: BaseResponse

Response model for single homography measurement.

HomographyMeasurementResult

Bases: BaseModel

Homography measurement result model.

IntResponse

Bases: BaseResponse

Response model for integer values.

ListResponse

Bases: BaseResponse

Response model for list data.

NetworkDiagnostics

Bases: BaseModel

Network diagnostics model.

NetworkDiagnosticsResponse

Bases: BaseResponse

Response model for network diagnostics.

ParameterRange

Bases: BaseModel

Parameter range model.

RangeResponse

Bases: BaseResponse

Response model for parameter ranges.

StreamInfo

Bases: BaseModel

Stream information model.

StreamInfoResponse

Bases: BaseResponse

Response model for stream information.

StreamStatus

Bases: BaseModel

Stream status model.

StreamStatusResponse

Bases: BaseResponse

Response model for stream status.

StringResponse

Bases: BaseResponse

Response model for string values.

SystemDiagnostics

Bases: BaseModel

System diagnostics model.

SystemDiagnosticsResponse

Bases: BaseResponse

Response model for system diagnostics.

requests

Request models for CameraManagerService.

Contains all Pydantic models for API requests, ensuring proper input validation and documentation for all camera operations.

BackendFilterRequest

Bases: BaseModel

Request model for backend filtering.

CameraOpenRequest

Bases: BaseModel

Request model for opening a camera.

CameraOpenBatchRequest

Bases: BaseModel

Request model for batch camera opening.

CameraCloseRequest

Bases: BaseModel

Request model for closing a camera.

CameraCloseBatchRequest

Bases: BaseModel

Request model for batch camera closing.

CameraConfigureRequest

Bases: BaseModel

Request model for camera configuration.

CameraConfigureBatchRequest

Bases: BaseModel

Request model for batch camera configuration.

validate_configurations classmethod

validate_configurations(
    v: Union[Dict[str, Dict[str, Any]], List[Dict[str, Any]]],
) -> Dict[str, Dict[str, Any]]

Convert list format to dict format.

CameraQueryRequest

Bases: BaseModel

Request model for camera query operations.

ConfigFileImportRequest

Bases: BaseModel

Request model for configuration file import.

ConfigFileExportRequest

Bases: BaseModel

Request model for configuration file export.

CaptureImageRequest

Bases: BaseModel

Request model for single image capture.

validate_output_format classmethod

validate_output_format(v: str) -> str

Validate output format is supported.

CaptureBatchRequest

Bases: BaseModel

Request model for batch image capture.

validate_output_format classmethod

validate_output_format(v: str) -> str

Validate output format is supported.

CaptureHDRRequest

Bases: BaseModel

Request model for HDR image capture.

validate_exposure_levels classmethod

validate_exposure_levels(v: Union[int, List[float]]) -> Union[int, List[float]]

Validate exposure levels.

validate_output_format classmethod

validate_output_format(v: str) -> str

Validate output format is supported.

CaptureHDRBatchRequest

Bases: BaseModel

Request model for batch HDR image capture.

validate_exposure_levels classmethod

validate_exposure_levels(v: Union[int, List[float]]) -> Union[int, List[float]]

Validate exposure levels.

validate_output_format classmethod

validate_output_format(v: str) -> str

Validate output format is supported.

BandwidthLimitRequest

Bases: BaseModel

Request model for setting bandwidth limit.

CameraPerformanceSettingsRequest

Bases: BaseModel

Request model for updating camera performance settings.

Global settings (always applicable): - timeout_ms, retrieve_retry_count, max_concurrent_captures

Per-camera GigE settings (requires camera field, only for GigE cameras): - packet_size, inter_packet_delay, bandwidth_limit_mbps

ExposureRequest

Bases: BaseModel

Request model for exposure setting.

GainRequest

Bases: BaseModel

Request model for gain setting.

ROIRequest

Bases: BaseModel

Request model for ROI (Region of Interest) setting.

TriggerModeRequest

Bases: BaseModel

Request model for trigger mode setting.

PixelFormatRequest

Bases: BaseModel

Request model for pixel format setting.

WhiteBalanceRequest

Bases: BaseModel

Request model for white balance setting.

ImageEnhancementRequest

Bases: BaseModel

Request model for image enhancement setting.

BandwidthLimitCameraRequest

Bases: BaseModel

Request model for setting camera bandwidth limit.

PacketSizeRequest

Bases: BaseModel

Request model for setting camera packet size.

InterPacketDelayRequest

Bases: BaseModel

Request model for setting inter-packet delay.

StreamStartRequest

Bases: BaseModel

Request model for starting camera stream.

StreamStopRequest

Bases: BaseModel

Request model for stopping camera stream.

StreamStatusRequest

Bases: BaseModel

Request model for getting stream status.

HomographyCalibrateCheckerboardRequest

Bases: BaseModel

Request model for checkerboard-based homography calibration.

HomographyCalibrateCorrespondencesRequest

Bases: BaseModel

Request model for manual point correspondence calibration.

validate_points classmethod

validate_points(v: List[List[float]]) -> List[List[float]]

Validate point arrays.

HomographyMeasureBoundingBoxRequest

Bases: BaseModel

Request model for measuring a single bounding box.

HomographyMeasureBatchRequest

Bases: BaseModel

Unified request model for batch measurements (bounding boxes and/or point-pair distances).

validate_boxes classmethod

validate_boxes(
    v: Optional[List[Dict[str, int]]],
) -> Optional[List[Dict[str, int]]]

Validate bounding boxes.

validate_point_pairs classmethod

validate_point_pairs(
    v: Optional[List[List[List[float]]]],
) -> Optional[List[List[List[float]]]]

Validate point pairs.

validate_at_least_one

validate_at_least_one()

Ensure at least one measurement type is provided.

HomographyMeasureDistanceRequest

Bases: BaseModel

Request model for measuring distance between two points.

HomographyCalibrateMultiViewRequest

Bases: BaseModel

Request model for multi-view checkerboard calibration.

Note: Checkerboard parameters (board_size, square_size, world_unit) are configured in HomographySettings (see config.py), not passed per-request.

validate_positions classmethod

validate_positions(v: List[Dict[str, float]]) -> List[Dict[str, float]]

Validate position format.

validate_lengths_match

validate_lengths_match()

Ensure number of images matches number of positions.

responses

Response models for CameraManagerService.

Contains all Pydantic models for API responses, ensuring consistent response formatting across all camera management endpoints.

BaseResponse

Bases: BaseModel

Base response model for all API endpoints.

BoolResponse

Bases: BaseResponse

Response model for boolean operations.

StringResponse

Bases: BaseResponse

Response model for string values.

IntResponse

Bases: BaseResponse

Response model for integer values.

FloatResponse

Bases: BaseResponse

Response model for float values.

ListResponse

Bases: BaseResponse

Response model for list data.

DictResponse

Bases: BaseResponse

Response model for dictionary data.

BackendInfo

Bases: BaseModel

Backend information model.

BackendsResponse

Bases: BaseResponse

Response model for backend listing.

BackendInfoResponse

Bases: BaseResponse

Response model for detailed backend information.

CameraInfo

Bases: BaseModel

Camera information model.

CameraStatus

Bases: BaseModel

Camera status model.

CameraCapabilities

Bases: BaseModel

Camera capabilities model.

CameraConfiguration

Bases: BaseModel

Camera configuration model.

CameraInfoResponse

Bases: BaseResponse

Response model for camera information.

CameraStatusResponse

Bases: BaseResponse

Response model for camera status.

CameraCapabilitiesResponse

Bases: BaseResponse

Response model for camera capabilities.

CameraConfigurationResponse

Bases: BaseResponse

Response model for camera configuration.

ActiveCamerasResponse

Bases: BaseResponse

Response model for active cameras list.

CaptureResult

Bases: BaseModel

Capture result model.

CaptureResponse

Bases: BaseResponse

Response model for single image capture.

BatchCaptureResponse

Bases: BaseResponse

Response model for batch capture operations.

HDRCaptureResult

Bases: BaseModel

HDR capture result model.

HDRCaptureResponse

Bases: BaseResponse

Response model for HDR capture.

BatchHDRCaptureResponse

Bases: BaseResponse

Response model for batch HDR capture.

SystemDiagnostics

Bases: BaseModel

System diagnostics model.

SystemDiagnosticsResponse

Bases: BaseResponse

Response model for system diagnostics.

BandwidthSettings

Bases: BaseModel

Bandwidth settings model.

BandwidthSettingsResponse

Bases: BaseResponse

Response model for bandwidth settings.

CameraPerformanceSettings

Bases: BaseModel

Camera performance and retry settings model.

Global settings: - timeout_ms, retrieve_retry_count, max_concurrent_captures

Per-camera GigE settings (None if not applicable or not queried): - packet_size, inter_packet_delay, bandwidth_limit_mbps

CameraPerformanceSettingsResponse

Bases: BaseResponse

Response model for camera performance settings.

NetworkDiagnostics

Bases: BaseModel

Network diagnostics model.

NetworkDiagnosticsResponse

Bases: BaseResponse

Response model for network diagnostics.

BatchOperationResult

Bases: BaseModel

Batch operation result model.

BatchOperationResponse

Bases: BaseResponse

Response model for batch operations.

ErrorDetail

Bases: BaseModel

Error detail model.

ErrorResponse

Bases: BaseResponse

Response model for error conditions.

ParameterRange

Bases: BaseModel

Parameter range model.

RangeResponse

Bases: BaseResponse

Response model for parameter ranges.

ConfigFileOperationResult

Bases: BaseModel

Configuration file operation result.

ConfigFileResponse

Bases: BaseResponse

Response model for configuration file operations.

StreamInfo

Bases: BaseModel

Stream information model.

StreamStatus

Bases: BaseModel

Stream status model.

StreamInfoResponse

Bases: BaseResponse

Response model for stream information.

StreamStatusResponse

Bases: BaseResponse

Response model for stream status.

ActiveStreamsResponse

Bases: BaseResponse

Response model for active streams list.

HomographyCalibrationResult

Bases: BaseModel

Homography calibration result model.

HomographyCalibrationResponse

Bases: BaseResponse

Response model for homography calibration.

HomographyMeasurementResult

Bases: BaseModel

Homography measurement result model.

HomographyMeasurementResponse

Bases: BaseResponse

Response model for single homography measurement.

HomographyDistanceResult

Bases: BaseModel

Homography distance measurement result model.

HomographyDistanceResponse

Bases: BaseResponse

Response model for distance measurement.

HomographyBatchMeasurementData

Bases: BaseModel

Batch measurement data containing both box and distance measurements.

HomographyBatchMeasurementResponse

Bases: BaseResponse

Response model for unified batch homography measurements.

HealthCheckResponse

Bases: BaseModel

Health check response model.

schemas

TaskSchemas for CameraManagerService endpoints.

backend_schemas

Backend and Discovery TaskSchemas.

capture_schemas

Image Capture TaskSchemas.

config_schemas

Camera Configuration TaskSchemas.

health_schemas

Health check TaskSchema.

homography_schemas

Homography Calibration & Measurement TaskSchemas.

info_schemas

Camera Status and Information TaskSchemas.

lifecycle_schemas

Camera Lifecycle TaskSchemas.

network_schemas

Network and Performance TaskSchemas.

stream_schemas

Streaming TaskSchemas.

service

CameraManagerService - Service-based API for camera management.

This service wraps AsyncCameraManager functionality in a Service-based architecture with comprehensive MCP tool integration and typed client access.

CameraManagerService

CameraManagerService(include_mocks: bool = False, **kwargs)

Bases: Service

Camera Management Service.

Provides comprehensive camera management functionality through a Service-based architecture with MCP tool integration and async camera operations.

Initialize CameraManagerService.

Parameters:

Name	Type	Description	Default
include_mocks	bool	Include mock cameras in discovery	False
**kwargs		Additional Service initialization parameters	{}

shutdown_cleanup async

shutdown_cleanup()

Cleanup camera manager on shutdown.

discover_backends async

discover_backends() -> BackendsResponse

Discover available camera backends.

get_backend_info async

get_backend_info() -> BackendInfoResponse

Get detailed information about all backends.

discover_cameras async

discover_cameras(request: BackendFilterRequest) -> ListResponse

Discover available cameras from all or specific backends.

open_camera async

open_camera(request: CameraOpenRequest) -> BoolResponse

Open a single camera with exposure validation.

open_cameras_batch async

open_cameras_batch(request: CameraOpenBatchRequest) -> BatchOperationResponse

Open multiple cameras in batch.

close_camera async

close_camera(request: CameraCloseRequest) -> BoolResponse

Close a specific camera.

close_cameras_batch async

close_cameras_batch(request: CameraCloseBatchRequest) -> BatchOperationResponse

Close multiple cameras in batch.

close_all_cameras async

close_all_cameras() -> BoolResponse

Close all active cameras.

get_active_cameras async

get_active_cameras() -> ActiveCamerasResponse

Get list of currently active cameras.

get_camera_status async

get_camera_status(request: CameraQueryRequest) -> CameraStatusResponse

Get camera status information.

get_camera_info async

get_camera_info(request: CameraQueryRequest) -> CameraInfoResponse

Get detailed camera information.

get_camera_capabilities async

get_camera_capabilities(
    request: CameraQueryRequest,
) -> CameraCapabilitiesResponse

Get camera capabilities information.

configure_camera async

configure_camera(request: CameraConfigureRequest) -> BoolResponse

Configure camera parameters.

configure_cameras_batch async

configure_cameras_batch(
    request: CameraConfigureBatchRequest,
) -> BatchOperationResponse

Configure multiple cameras in batch.

get_camera_configuration async

get_camera_configuration(
    request: CameraQueryRequest,
) -> CameraConfigurationResponse

Get current camera configuration.

import_camera_config async

import_camera_config(request: ConfigFileImportRequest) -> ConfigFileResponse

Import camera configuration from file.

export_camera_config async

export_camera_config(request: ConfigFileExportRequest) -> ConfigFileResponse

Export camera configuration to file.

capture_image async

capture_image(request: CaptureImageRequest) -> CaptureResponse

Capture a single image with timeout protection.

capture_images_batch async

capture_images_batch(request: CaptureBatchRequest) -> BatchCaptureResponse

Capture images from multiple cameras.

capture_hdr_image async

capture_hdr_image(request: CaptureHDRRequest) -> HDRCaptureResponse

Capture HDR image sequence.

capture_hdr_images_batch async

capture_hdr_images_batch(
    request: CaptureHDRBatchRequest,
) -> BatchHDRCaptureResponse

Capture HDR images from multiple cameras.

get_network_diagnostics async

get_network_diagnostics() -> NetworkDiagnosticsResponse

Get network diagnostics information.

get_performance_settings async

get_performance_settings(
    request: CameraPerformanceSettingsRequest = None,
) -> CameraPerformanceSettingsResponse

Get current camera performance settings.

Returns global settings (timeout, retries, concurrent captures) and optionally per-camera GigE settings (packet_size, inter_packet_delay, bandwidth_limit) if camera is specified.

set_performance_settings async

set_performance_settings(
    request: CameraPerformanceSettingsRequest,
) -> BoolResponse

Update camera performance settings.

Updates global settings (timeout, retries, concurrent captures) and optionally per-camera GigE settings (packet_size, inter_packet_delay, bandwidth_limit) if camera is specified.

start_stream async

start_stream(request: StreamStartRequest) -> StreamInfoResponse

Start camera stream with resilient state management.

stop_stream

stop_stream(request: StreamStopRequest) -> BoolResponse

Stop camera stream with resilient state management.

get_stream_status async

get_stream_status(request: StreamStatusRequest) -> StreamStatusResponse

Get camera stream status with resilient state management.

get_active_streams

get_active_streams() -> ActiveStreamsResponse

Get list of cameras with active streams.

stop_all_streams

stop_all_streams() -> BoolResponse

Stop all active camera streams.

serve_camera_stream async

serve_camera_stream(camera_name: str)

Serve MJPEG video stream for a specific camera.

calibrate_homography_checkerboard async

calibrate_homography_checkerboard(
    request: HomographyCalibrateCheckerboardRequest,
) -> HomographyCalibrationResponse

Calibrate homography using checkerboard pattern detection.

calibrate_homography_correspondences

calibrate_homography_correspondences(
    request: HomographyCalibrateCorrespondencesRequest,
) -> HomographyCalibrationResponse

Calibrate homography from known point correspondences.

calibrate_homography_multi_view

calibrate_homography_multi_view(
    request: HomographyCalibrateMultiViewRequest,
) -> HomographyCalibrationResponse

Calibrate homography from multiple checkerboard positions on the same plane.

Ideal for calibrating long surfaces (metallic bars, conveyor belts) using a standard checkerboard moved to multiple positions.

measure_homography_box

measure_homography_box(
    request: HomographyMeasureBoundingBoxRequest,
) -> HomographyMeasurementResponse

Measure bounding box dimensions using homography calibration.

measure_homography_batch

measure_homography_batch(
    request: HomographyMeasureBatchRequest,
) -> HomographyBatchMeasurementResponse

Unified batch measurement for bounding boxes and/or point-pair distances.

measure_homography_distance

measure_homography_distance(
    request: HomographyMeasureDistanceRequest,
) -> HomographyDistanceResponse

Measure distance between two points using homography calibration.

health_check async

health_check() -> HealthCheckResponse

Health check endpoint for container healthcheck.

get_system_diagnostics async

get_system_diagnostics() -> SystemDiagnosticsResponse

Get system diagnostics information.

plcs

PLC API Service - REST API for PLC management and control.

PLCManagerConnectionManager

PLCManagerConnectionManager(
    url: Url | None = None,
    server_id: UUID | None = None,
    server_pid_file: str | None = None,
)

Bases: ConnectionManager

Connection Manager for PLCManagerService.

Provides strongly-typed methods for all PLC management operations, making it easy to use the service programmatically from other applications.

get async

get(endpoint: str, http_timeout: float = 60.0) -> Dict[str, Any]

Make GET request to service endpoint.

post async

post(
    endpoint: str, data: Dict[str, Any] = None, http_timeout: float = 60.0
) -> Dict[str, Any]

Make POST request to service endpoint.

discover_backends async

discover_backends() -> List[str]

Discover available PLC backends.

Returns:

Type	Description
List[str]	List of available backend names

get_backend_info async

get_backend_info() -> Dict[str, Any]

Get detailed information about all backends.

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping backend names to their information

discover_plcs async

discover_plcs(backend: Optional[str] = None) -> List[str]

Discover available PLCs from all or specific backends.

Parameters:

Name	Type	Description	Default
backend	Optional[str]	Optional backend name to filter by	None

Returns:

Type	Description
List[str]	List of PLC identifiers

connect_plc async

connect_plc(
    plc_name: str,
    backend: str,
    ip_address: str,
    plc_type: Optional[str] = None,
    connection_timeout: Optional[float] = None,
    read_timeout: Optional[float] = None,
    write_timeout: Optional[float] = None,
    retry_count: Optional[int] = None,
    retry_delay: Optional[float] = None,
) -> bool

Connect to a PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Unique identifier for the PLC	required
backend	str	Backend type (AllenBradley, Siemens, Modbus)	required
ip_address	str	IP address of the PLC	required
plc_type	Optional[str]	Specific PLC type (logix, slc, cip, auto)	None
connection_timeout	Optional[float]	Connection timeout in seconds	None
read_timeout	Optional[float]	Tag read timeout in seconds	None
write_timeout	Optional[float]	Tag write timeout in seconds	None
retry_count	Optional[int]	Number of retry attempts	None
retry_delay	Optional[float]	Delay between retries in seconds	None

Returns:

Type	Description
bool	True if successful

connect_plcs_batch async

connect_plcs_batch(plcs: List[PLCConnectRequest]) -> Dict[str, Any]

Connect to multiple PLCs in batch.

Parameters:

Name	Type	Description	Default
plcs	List[PLCConnectRequest]	List of PLC connection requests	required

Returns:

Type	Description
Dict[str, Any]	Batch operation results

disconnect_plc async

disconnect_plc(plc: str) -> bool

Disconnect from a PLC.

Parameters:

Name	Type	Description	Default
plc	str	PLC name to disconnect	required

Returns:

Type	Description
bool	True if successful

disconnect_plcs_batch async

disconnect_plcs_batch(plcs: List[str]) -> Dict[str, Any]

Disconnect from multiple PLCs in batch.

Parameters:

Name	Type	Description	Default
plcs	List[str]	List of PLC names to disconnect	required

Returns:

Type	Description
Dict[str, Any]	Batch operation results

disconnect_all_plcs async

disconnect_all_plcs() -> bool

Disconnect from all active PLCs.

Returns:

Type	Description
bool	True if successful

get_active_plcs async

get_active_plcs() -> List[str]

Get list of currently active PLCs.

Returns:

Type	Description
List[str]	List of active PLC names

read_tags async

read_tags(plc: str, tags: Union[str, List[str]]) -> Dict[str, Any]

Read tag values from a PLC.

Parameters:

Name	Type	Description	Default
plc	str	PLC name	required
tags	Union[str, List[str]]	Single tag name or list of tag names	required

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping tag names to their values

write_tags async

write_tags(
    plc: str, tags: Union[Tuple[str, Any], List[Tuple[str, Any]]]
) -> Dict[str, bool]

Write tag values to a PLC.

Parameters:

Name	Type	Description	Default
plc	str	PLC name	required
tags	Union[Tuple[str, Any], List[Tuple[str, Any]]]	Single (tag_name, value) tuple or list of tuples	required

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping tag names to write success status

read_tags_batch async

read_tags_batch(
    requests: List[Tuple[str, Union[str, List[str]]]],
) -> Dict[str, Dict[str, Any]]

Read tags from multiple PLCs in batch.

Parameters:

Name	Type	Description	Default
requests	List[Tuple[str, Union[str, List[str]]]]	List of (plc_name, tags) tuples	required

Returns:

Type	Description
Dict[str, Dict[str, Any]]	Dictionary mapping PLC names to their tag read results

write_tags_batch async

write_tags_batch(
    requests: List[Tuple[str, Union[Tuple[str, Any], List[Tuple[str, Any]]]]],
) -> Dict[str, Dict[str, bool]]

Write tags to multiple PLCs in batch.

Parameters:

Name	Type	Description	Default
requests	List[Tuple[str, Union[Tuple[str, Any], List[Tuple[str, Any]]]]]	List of (plc_name, tags) tuples	required

Returns:

Type	Description
Dict[str, Dict[str, bool]]	Dictionary mapping PLC names to their tag write results

list_tags async

list_tags(plc: str) -> List[str]

List all available tags on a PLC.

Parameters:

Name	Type	Description	Default
plc	str	PLC name	required

Returns:

Type	Description
List[str]	List of tag names

get_tag_info async

get_tag_info(plc: str, tag: str) -> Dict[str, Any]

Get detailed information about a specific tag.

Parameters:

Name	Type	Description	Default
plc	str	PLC name	required
tag	str	Tag name	required

Returns:

Type	Description
Dict[str, Any]	Tag information

get_plc_status async

get_plc_status(plc: str) -> Dict[str, Any]

Get PLC status information.

Parameters:

Name	Type	Description	Default
plc	str	PLC name to query	required

Returns:

Type	Description
Dict[str, Any]	PLC status information

get_plc_info async

get_plc_info(plc: str) -> Dict[str, Any]

Get detailed PLC information.

Parameters:

Name	Type	Description	Default
plc	str	PLC name to query	required

Returns:

Type	Description
Dict[str, Any]	PLC information

get_system_diagnostics async

get_system_diagnostics() -> Dict[str, Any]

Get system diagnostics information.

Returns:

Type	Description
Dict[str, Any]	System diagnostics data

PLCManagerService

PLCManagerService(**kwargs)

Bases: Service

PLC Management Service.

Provides comprehensive PLC management functionality through a Service-based architecture with MCP tool integration and async PLC operations.

Initialize PLCManagerService.

Parameters:

Name	Type	Description	Default
**kwargs		Additional Service initialization parameters	{}

shutdown_cleanup async

shutdown_cleanup()

Cleanup PLC manager on shutdown.

discover_backends

discover_backends() -> BackendsResponse

Discover available PLC backends.

get_backend_info

get_backend_info() -> BackendInfoResponse

Get detailed information about all backends.

discover_plcs async

discover_plcs(request: BackendFilterRequest) -> ListResponse

Discover available PLCs from all or specific backends.

connect_plc async

connect_plc(request: PLCConnectRequest) -> BoolResponse

Connect to a PLC.

connect_plcs_batch async

connect_plcs_batch(request: PLCConnectBatchRequest) -> BatchOperationResponse

Connect to multiple PLCs in batch.

disconnect_plc async

disconnect_plc(request: PLCDisconnectRequest) -> BoolResponse

Disconnect from a PLC.

disconnect_plcs_batch async

disconnect_plcs_batch(
    request: PLCDisconnectBatchRequest,
) -> BatchOperationResponse

Disconnect from multiple PLCs in batch.

disconnect_all_plcs async

disconnect_all_plcs() -> BoolResponse

Disconnect from all active PLCs.

get_active_plcs

get_active_plcs() -> ActivePLCsResponse

Get list of currently active PLCs.

read_tags async

read_tags(request: TagReadRequest) -> TagReadResponse

Read tag values from a PLC.

write_tags async

write_tags(request: TagWriteRequest) -> TagWriteResponse

Write tag values to a PLC.

read_tags_batch async

read_tags_batch(request: TagBatchReadRequest) -> BatchTagReadResponse

Read tags from multiple PLCs in batch.

write_tags_batch async

write_tags_batch(request: TagBatchWriteRequest) -> BatchTagWriteResponse

Write tags to multiple PLCs in batch.

list_tags async

list_tags(request: PLCQueryRequest) -> TagListResponse

List all available tags on a PLC.

get_tag_info async

get_tag_info(request: TagInfoRequest) -> TagInfoResponse

Get detailed information about a specific tag.

get_plc_status async

get_plc_status(request: PLCQueryRequest) -> PLCStatusResponse

Get PLC status information.

get_plc_info async

get_plc_info(request: PLCQueryRequest) -> PLCInfoResponse

Get detailed PLC information.

get_system_diagnostics async

get_system_diagnostics() -> SystemDiagnosticsResponse

Get system diagnostics information.

health_check

health_check() -> HealthCheckResponse

Health check endpoint for container healthcheck.

connection_manager

Connection Manager for PLCManagerService.

Provides a strongly-typed client interface for programmatic access to PLC management operations.

PLCManagerConnectionManager

PLCManagerConnectionManager(
    url: Url | None = None,
    server_id: UUID | None = None,
    server_pid_file: str | None = None,
)

Bases: ConnectionManager

Connection Manager for PLCManagerService.

Provides strongly-typed methods for all PLC management operations, making it easy to use the service programmatically from other applications.

get async

get(endpoint: str, http_timeout: float = 60.0) -> Dict[str, Any]

Make GET request to service endpoint.

post async

post(
    endpoint: str, data: Dict[str, Any] = None, http_timeout: float = 60.0
) -> Dict[str, Any]

Make POST request to service endpoint.

discover_backends async

discover_backends() -> List[str]

Discover available PLC backends.

Returns:

Type	Description
List[str]	List of available backend names

get_backend_info async

get_backend_info() -> Dict[str, Any]

Get detailed information about all backends.

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping backend names to their information

discover_plcs async

discover_plcs(backend: Optional[str] = None) -> List[str]

Discover available PLCs from all or specific backends.

Parameters:

Name	Type	Description	Default
backend	Optional[str]	Optional backend name to filter by	None

Returns:

Type	Description
List[str]	List of PLC identifiers

connect_plc async

connect_plc(
    plc_name: str,
    backend: str,
    ip_address: str,
    plc_type: Optional[str] = None,
    connection_timeout: Optional[float] = None,
    read_timeout: Optional[float] = None,
    write_timeout: Optional[float] = None,
    retry_count: Optional[int] = None,
    retry_delay: Optional[float] = None,
) -> bool

Connect to a PLC.

Parameters:

Name	Type	Description	Default
plc_name	str	Unique identifier for the PLC	required
backend	str	Backend type (AllenBradley, Siemens, Modbus)	required
ip_address	str	IP address of the PLC	required
plc_type	Optional[str]	Specific PLC type (logix, slc, cip, auto)	None
connection_timeout	Optional[float]	Connection timeout in seconds	None
read_timeout	Optional[float]	Tag read timeout in seconds	None
write_timeout	Optional[float]	Tag write timeout in seconds	None
retry_count	Optional[int]	Number of retry attempts	None
retry_delay	Optional[float]	Delay between retries in seconds	None

Returns:

Type	Description
bool	True if successful

connect_plcs_batch async

connect_plcs_batch(plcs: List[PLCConnectRequest]) -> Dict[str, Any]

Connect to multiple PLCs in batch.

Parameters:

Name	Type	Description	Default
plcs	List[PLCConnectRequest]	List of PLC connection requests	required

Returns:

Type	Description
Dict[str, Any]	Batch operation results

disconnect_plc async

disconnect_plc(plc: str) -> bool

Disconnect from a PLC.

Parameters:

Name	Type	Description	Default
plc	str	PLC name to disconnect	required

Returns:

Type	Description
bool	True if successful

disconnect_plcs_batch async

disconnect_plcs_batch(plcs: List[str]) -> Dict[str, Any]

Disconnect from multiple PLCs in batch.

Parameters:

Name	Type	Description	Default
plcs	List[str]	List of PLC names to disconnect	required

Returns:

Type	Description
Dict[str, Any]	Batch operation results

disconnect_all_plcs async

disconnect_all_plcs() -> bool

Disconnect from all active PLCs.

Returns:

Type	Description
bool	True if successful

get_active_plcs async

get_active_plcs() -> List[str]

Get list of currently active PLCs.

Returns:

Type	Description
List[str]	List of active PLC names

read_tags async

read_tags(plc: str, tags: Union[str, List[str]]) -> Dict[str, Any]

Read tag values from a PLC.

Parameters:

Name	Type	Description	Default
plc	str	PLC name	required
tags	Union[str, List[str]]	Single tag name or list of tag names	required

Returns:

Type	Description
Dict[str, Any]	Dictionary mapping tag names to their values

write_tags async

write_tags(
    plc: str, tags: Union[Tuple[str, Any], List[Tuple[str, Any]]]
) -> Dict[str, bool]

Write tag values to a PLC.

Parameters:

Name	Type	Description	Default
plc	str	PLC name	required
tags	Union[Tuple[str, Any], List[Tuple[str, Any]]]	Single (tag_name, value) tuple or list of tuples	required

Returns:

Type	Description
Dict[str, bool]	Dictionary mapping tag names to write success status

read_tags_batch async

read_tags_batch(
    requests: List[Tuple[str, Union[str, List[str]]]],
) -> Dict[str, Dict[str, Any]]

Read tags from multiple PLCs in batch.

Parameters:

Name	Type	Description	Default
requests	List[Tuple[str, Union[str, List[str]]]]	List of (plc_name, tags) tuples	required

Returns:

Type	Description
Dict[str, Dict[str, Any]]	Dictionary mapping PLC names to their tag read results

write_tags_batch async

write_tags_batch(
    requests: List[Tuple[str, Union[Tuple[str, Any], List[Tuple[str, Any]]]]],
) -> Dict[str, Dict[str, bool]]

Write tags to multiple PLCs in batch.

Parameters:

Name	Type	Description	Default
requests	List[Tuple[str, Union[Tuple[str, Any], List[Tuple[str, Any]]]]]	List of (plc_name, tags) tuples	required

Returns:

Type	Description
Dict[str, Dict[str, bool]]	Dictionary mapping PLC names to their tag write results

list_tags async

list_tags(plc: str) -> List[str]

List all available tags on a PLC.

Parameters:

Name	Type	Description	Default
plc	str	PLC name	required

Returns:

Type	Description
List[str]	List of tag names

get_tag_info async

get_tag_info(plc: str, tag: str) -> Dict[str, Any]

Get detailed information about a specific tag.

Parameters:

Name	Type	Description	Default
plc	str	PLC name	required
tag	str	Tag name	required

Returns:

Type	Description
Dict[str, Any]	Tag information

get_plc_status async

get_plc_status(plc: str) -> Dict[str, Any]

Get PLC status information.

Parameters:

Name	Type	Description	Default
plc	str	PLC name to query	required

Returns:

Type	Description
Dict[str, Any]	PLC status information

get_plc_info async

get_plc_info(plc: str) -> Dict[str, Any]

Get detailed PLC information.

Parameters:

Name	Type	Description	Default
plc	str	PLC name to query	required

Returns:

Type	Description
Dict[str, Any]	PLC information

get_system_diagnostics async

get_system_diagnostics() -> Dict[str, Any]

Get system diagnostics information.

Returns:

Type	Description
Dict[str, Any]	System diagnostics data

launcher

PLC API service launcher.

main

main()

Main launcher function.

models

PLC API models - Request and Response models.

BackendFilterRequest

Bases: BaseModel

Request model for backend filtering.

PLCConnectBatchRequest

Bases: BaseModel

Request model for batch PLC connection.

PLCConnectRequest

Bases: BaseModel

Request model for connecting to a PLC.

PLCDisconnectBatchRequest

Bases: BaseModel

Request model for batch PLC disconnection.

PLCDisconnectRequest

Bases: BaseModel

Request model for disconnecting from a PLC.

PLCQueryRequest

Bases: BaseModel

Request model for PLC query operations.

TagBatchReadRequest

Bases: BaseModel

Request model for batch tag reading from multiple PLCs.

validate_requests classmethod

validate_requests(
    v: List[Tuple[str, Union[str, List[str]]]],
) -> List[Tuple[str, Union[str, List[str]]]]

Validate batch read requests.

TagBatchWriteRequest

Bases: BaseModel

Request model for batch tag writing to multiple PLCs.

validate_requests classmethod

validate_requests(
    v: List[Tuple[str, Union[Tuple[str, Any], List[Tuple[str, Any]]]]],
) -> List[Tuple[str, Union[Tuple[str, Any], List[Tuple[str, Any]]]]]

Validate batch write requests.

TagInfoRequest

Bases: BaseModel

Request model for getting tag information.

TagReadRequest

Bases: BaseModel

Request model for reading tags from a PLC.

validate_tags classmethod

validate_tags(v: Union[str, List[str]]) -> Union[str, List[str]]

Ensure tags is not empty.

TagWriteRequest

Bases: BaseModel

Request model for writing tags to a PLC.

validate_tags classmethod

validate_tags(
    v: Union[Tuple[str, Any], List[Tuple[str, Any]]],
) -> Union[Tuple[str, Any], List[Tuple[str, Any]]]

Ensure tags is properly formatted.

ActivePLCsResponse

Bases: BaseResponse

Response model for active PLCs listing.

BackendInfo

Bases: BaseModel

Backend information model.

BackendInfoResponse

Bases: BaseResponse

Response model for detailed backend information.

BackendsResponse

Bases: BaseResponse

Response model for backend listing.

BaseResponse

Bases: BaseModel

Base response model for all API endpoints.

BatchOperationResponse

Bases: BaseResponse

Response model for batch operations.

BatchOperationResult

Bases: BaseModel

Batch operation result model.

BatchTagReadResponse

Bases: BaseResponse

Response model for batch tag read operations.

BatchTagWriteResponse

Bases: BaseResponse

Response model for batch tag write operations.

BoolResponse

Bases: BaseResponse

Response model for boolean operations.

DictResponse

Bases: BaseResponse

Response model for dictionary data.

FloatResponse

Bases: BaseResponse

Response model for float values.

HealthCheckResponse

Bases: BaseModel

Health check response model.

IntResponse

Bases: BaseResponse

Response model for integer values.

ListResponse

Bases: BaseResponse

Response model for list data.

PLCInfo

Bases: BaseModel

PLC information model.

PLCInfoResponse

Bases: BaseResponse

Response model for PLC information.

PLCStatus

Bases: BaseModel

PLC status model.

PLCStatusResponse

Bases: BaseResponse

Response model for PLC status.

StringResponse

Bases: BaseResponse

Response model for string values.

SystemDiagnostics

Bases: BaseModel

System diagnostics model.

SystemDiagnosticsResponse

Bases: BaseResponse

Response model for system diagnostics.

TagInfo

Bases: BaseModel

Tag information model.

TagInfoResponse

Bases: BaseResponse

Response model for tag information.

TagListResponse

Bases: BaseResponse

Response model for tag list operations.

TagReadResponse

Bases: BaseResponse

Response model for tag read operations.

TagWriteResponse

Bases: BaseResponse

Response model for tag write operations.

requests

Request models for PLCManagerService.

Contains all Pydantic models for API requests, ensuring proper input validation and documentation for all PLC operations.

BackendFilterRequest

Bases: BaseModel

Request model for backend filtering.

PLCConnectRequest

Bases: BaseModel

Request model for connecting to a PLC.

PLCConnectBatchRequest

Bases: BaseModel

Request model for batch PLC connection.

PLCDisconnectRequest

Bases: BaseModel

Request model for disconnecting from a PLC.

PLCDisconnectBatchRequest

Bases: BaseModel

Request model for batch PLC disconnection.

PLCQueryRequest

Bases: BaseModel

Request model for PLC query operations.

TagReadRequest

Bases: BaseModel

Request model for reading tags from a PLC.

validate_tags classmethod

validate_tags(v: Union[str, List[str]]) -> Union[str, List[str]]

Ensure tags is not empty.

TagWriteRequest

Bases: BaseModel

Request model for writing tags to a PLC.

validate_tags classmethod

validate_tags(
    v: Union[Tuple[str, Any], List[Tuple[str, Any]]],
) -> Union[Tuple[str, Any], List[Tuple[str, Any]]]

Ensure tags is properly formatted.

TagBatchReadRequest

Bases: BaseModel

Request model for batch tag reading from multiple PLCs.

validate_requests classmethod

validate_requests(
    v: List[Tuple[str, Union[str, List[str]]]],
) -> List[Tuple[str, Union[str, List[str]]]]

Validate batch read requests.

TagBatchWriteRequest

Bases: BaseModel

Request model for batch tag writing to multiple PLCs.

validate_requests classmethod

validate_requests(
    v: List[Tuple[str, Union[Tuple[str, Any], List[Tuple[str, Any]]]]],
) -> List[Tuple[str, Union[Tuple[str, Any], List[Tuple[str, Any]]]]]

Validate batch write requests.

TagInfoRequest

Bases: BaseModel

Request model for getting tag information.

responses

Response models for PLCManagerService.

Contains all Pydantic models for API responses, ensuring consistent response formatting across all PLC management endpoints.

BaseResponse

Bases: BaseModel

Base response model for all API endpoints.

BoolResponse

Bases: BaseResponse

Response model for boolean operations.

StringResponse

Bases: BaseResponse

Response model for string values.

IntResponse

Bases: BaseResponse

Response model for integer values.

FloatResponse

Bases: BaseResponse

Response model for float values.

ListResponse

Bases: BaseResponse

Response model for list data.

DictResponse

Bases: BaseResponse

Response model for dictionary data.

BackendInfo

Bases: BaseModel

Backend information model.

BackendsResponse

Bases: BaseResponse

Response model for backend listing.

BackendInfoResponse

Bases: BaseResponse

Response model for detailed backend information.

PLCInfo

Bases: BaseModel

PLC information model.

PLCStatus

Bases: BaseModel

PLC status model.

PLCInfoResponse

Bases: BaseResponse

Response model for PLC information.

PLCStatusResponse

Bases: BaseResponse

Response model for PLC status.

ActivePLCsResponse

Bases: BaseResponse

Response model for active PLCs listing.

TagReadResponse

Bases: BaseResponse

Response model for tag read operations.

TagWriteResponse

Bases: BaseResponse

Response model for tag write operations.

TagListResponse

Bases: BaseResponse

Response model for tag list operations.

TagInfo

Bases: BaseModel

Tag information model.

TagInfoResponse

Bases: BaseResponse

Response model for tag information.

BatchOperationResult

Bases: BaseModel

Batch operation result model.

BatchOperationResponse

Bases: BaseResponse

Response model for batch operations.

BatchTagReadResponse

Bases: BaseResponse

Response model for batch tag read operations.

BatchTagWriteResponse

Bases: BaseResponse

Response model for batch tag write operations.

SystemDiagnostics

Bases: BaseModel

System diagnostics model.

SystemDiagnosticsResponse

Bases: BaseResponse

Response model for system diagnostics.

HealthCheckResponse

Bases: BaseModel

Health check response model.

schemas

TaskSchemas for PLCManagerService endpoints.

backend_schemas

Backend and Discovery TaskSchemas.

health_schemas

Health check TaskSchema.

lifecycle_schemas

PLC Lifecycle TaskSchemas.

status_schemas

Status & Information TaskSchemas.

tag_schemas

Tag Operations TaskSchemas.

service

PLCManagerService - Service-based API for PLC management.

This service wraps PLCManager functionality in a Service-based architecture with comprehensive MCP tool integration and typed client access.

PLCManagerService

PLCManagerService(**kwargs)

Bases: Service

PLC Management Service.

Provides comprehensive PLC management functionality through a Service-based architecture with MCP tool integration and async PLC operations.

Initialize PLCManagerService.

Parameters:

Name	Type	Description	Default
**kwargs		Additional Service initialization parameters	{}

shutdown_cleanup async

shutdown_cleanup()

Cleanup PLC manager on shutdown.

discover_backends

discover_backends() -> BackendsResponse

Discover available PLC backends.

get_backend_info

get_backend_info() -> BackendInfoResponse

Get detailed information about all backends.

discover_plcs async

discover_plcs(request: BackendFilterRequest) -> ListResponse

Discover available PLCs from all or specific backends.

connect_plc async

connect_plc(request: PLCConnectRequest) -> BoolResponse

Connect to a PLC.

connect_plcs_batch async

connect_plcs_batch(request: PLCConnectBatchRequest) -> BatchOperationResponse

Connect to multiple PLCs in batch.

disconnect_plc async

disconnect_plc(request: PLCDisconnectRequest) -> BoolResponse

Disconnect from a PLC.

disconnect_plcs_batch async

disconnect_plcs_batch(
    request: PLCDisconnectBatchRequest,
) -> BatchOperationResponse

Disconnect from multiple PLCs in batch.

disconnect_all_plcs async

disconnect_all_plcs() -> BoolResponse

Disconnect from all active PLCs.

get_active_plcs

get_active_plcs() -> ActivePLCsResponse

Get list of currently active PLCs.

read_tags async

read_tags(request: TagReadRequest) -> TagReadResponse

Read tag values from a PLC.

write_tags async

write_tags(request: TagWriteRequest) -> TagWriteResponse

Write tag values to a PLC.

read_tags_batch async

read_tags_batch(request: TagBatchReadRequest) -> BatchTagReadResponse

Read tags from multiple PLCs in batch.

write_tags_batch async

write_tags_batch(request: TagBatchWriteRequest) -> BatchTagWriteResponse

Write tags to multiple PLCs in batch.

list_tags async

list_tags(request: PLCQueryRequest) -> TagListResponse

List all available tags on a PLC.

get_tag_info async

get_tag_info(request: TagInfoRequest) -> TagInfoResponse

Get detailed information about a specific tag.

get_plc_status async

get_plc_status(request: PLCQueryRequest) -> PLCStatusResponse

Get PLC status information.

get_plc_info async

get_plc_info(request: PLCQueryRequest) -> PLCInfoResponse

Get detailed PLC information.

get_system_diagnostics async

get_system_diagnostics() -> SystemDiagnosticsResponse

Get system diagnostics information.

health_check

health_check() -> HealthCheckResponse

Health check endpoint for container healthcheck.

sensors

Sensor API module providing service and connection management.

SensorConnectionManager

SensorConnectionManager(
    url: Url | None = None,
    server_id: UUID | None = None,
    server_pid_file: str | None = None,
)

Bases: ConnectionManager

Strongly-typed connection manager for sensor service operations.

connect_sensor async

connect_sensor(
    sensor_id: str, backend_type: str, config: Dict[str, Any], address: str
) -> SensorConnectionResponse

Connect to a sensor with specified configuration.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required
backend_type	str	Backend type (mqtt, http, serial)	required
config	Dict[str, Any]	Backend-specific configuration	required
address	str	Sensor address (topic, endpoint, or port)	required

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of connection

disconnect_sensor async

disconnect_sensor(sensor_id: str) -> SensorConnectionResponse

Disconnect from a connected sensor.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor to disconnect	required

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of disconnection

read_sensor_data async

read_sensor_data(
    sensor_id: str, timeout: Optional[float] = None
) -> SensorDataResponse

Read data from a connected sensor.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required
timeout	Optional[float]	Optional read timeout in seconds	None

Returns:

Type	Description
SensorDataResponse	Response containing sensor data or error information

get_sensor_status async

get_sensor_status(sensor_id: str) -> SensorStatusResponse

Get status information for a sensor.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required

Returns:

Type	Description
SensorStatusResponse	Response containing sensor status information

list_sensors async

list_sensors(include_status: bool = False) -> SensorListResponse

List all registered sensors.

Parameters:

Name	Type	Description	Default
include_status	bool	Whether to include connection status for each sensor	False

Returns:

Type	Description
SensorListResponse	Response containing list of sensors

connect_mqtt_sensor async

connect_mqtt_sensor(
    sensor_id: str, broker_url: str, identifier: str, address: str
) -> SensorConnectionResponse

Connect to an MQTT sensor with simplified parameters.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required
broker_url	str	MQTT broker URL (e.g., "mqtt://localhost:1883")	required
identifier	str	Client identifier for MQTT connection	required
address	str	MQTT topic to subscribe to	required

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of connection

connect_http_sensor async

connect_http_sensor(
    sensor_id: str,
    base_url: str,
    address: str,
    headers: Optional[Dict[str, str]] = None,
) -> SensorConnectionResponse

Connect to an HTTP sensor with simplified parameters.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required
base_url	str	Base URL for HTTP requests	required
address	str	Endpoint path for sensor data	required
headers	Optional[Dict[str, str]]	Optional HTTP headers	None

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of connection

connect_serial_sensor async

connect_serial_sensor(
    sensor_id: str, port: str, baudrate: int = 9600, timeout: float = 1.0
) -> SensorConnectionResponse

Connect to a serial sensor with simplified parameters.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required
port	str	Serial port (e.g., "/dev/ttyUSB0" or "COM1")	required
baudrate	int	Serial communication baud rate	9600
timeout	float	Serial read timeout	1.0

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of connection

SensorManagerService

SensorManagerService(manager: Optional[SensorManager] = None, **kwargs)

Bases: Service

Service wrapper for SensorManager with MCP endpoint registration.

Initialize the sensor manager service.

Parameters:

Name	Type	Description	Default
manager	Optional[SensorManager]	Optional SensorManager instance. If None, creates a new one.	None
**kwargs		Additional arguments passed to the Service base class	{}

manager property

manager: SensorManager

Get the underlying SensorManager instance.

connect_sensor async

connect_sensor(request: SensorConnectionRequest) -> SensorConnectionResponse

Connect to a sensor with specified configuration.

Parameters:

Name	Type	Description	Default
request	SensorConnectionRequest	Connection request with sensor configuration	required

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of connection

disconnect_sensor async

disconnect_sensor(request: SensorStatusRequest) -> SensorConnectionResponse

Disconnect from a connected sensor.

Parameters:

Name	Type	Description	Default
request	SensorStatusRequest	Request containing sensor_id to disconnect	required

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of disconnection

read_sensor_data async

read_sensor_data(request: SensorDataRequest) -> SensorDataResponse

Read data from a connected sensor.

Parameters:

Name	Type	Description	Default
request	SensorDataRequest	Request specifying sensor and read parameters	required

Returns:

Type	Description
SensorDataResponse	Response containing sensor data or error information

get_sensor_status async

get_sensor_status(request: SensorStatusRequest) -> SensorStatusResponse

Get status information for a sensor.

Parameters:

Name	Type	Description	Default
request	SensorStatusRequest	Request containing sensor_id	required

Returns:

Type	Description
SensorStatusResponse	Response containing sensor status information

list_sensors async

list_sensors(request: SensorListRequest) -> SensorListResponse

List all registered sensors.

Parameters:

Name	Type	Description	Default
request	SensorListRequest	Request with listing options	required

Returns:

Type	Description
SensorListResponse	Response containing list of sensors

shutdown_cleanup async

shutdown_cleanup()

Cleanup sensors on shutdown.

health_check

health_check() -> HealthCheckResponse

Health check endpoint for container healthcheck.

connection_manager

Connection manager for typed sensor service client access.

SensorConnectionManager

SensorConnectionManager(
    url: Url | None = None,
    server_id: UUID | None = None,
    server_pid_file: str | None = None,
)

Bases: ConnectionManager

Strongly-typed connection manager for sensor service operations.

connect_sensor async

connect_sensor(
    sensor_id: str, backend_type: str, config: Dict[str, Any], address: str
) -> SensorConnectionResponse

Connect to a sensor with specified configuration.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required
backend_type	str	Backend type (mqtt, http, serial)	required
config	Dict[str, Any]	Backend-specific configuration	required
address	str	Sensor address (topic, endpoint, or port)	required

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of connection

disconnect_sensor async

disconnect_sensor(sensor_id: str) -> SensorConnectionResponse

Disconnect from a connected sensor.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor to disconnect	required

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of disconnection

read_sensor_data async

read_sensor_data(
    sensor_id: str, timeout: Optional[float] = None
) -> SensorDataResponse

Read data from a connected sensor.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required
timeout	Optional[float]	Optional read timeout in seconds	None

Returns:

Type	Description
SensorDataResponse	Response containing sensor data or error information

get_sensor_status async

get_sensor_status(sensor_id: str) -> SensorStatusResponse

Get status information for a sensor.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required

Returns:

Type	Description
SensorStatusResponse	Response containing sensor status information

list_sensors async

list_sensors(include_status: bool = False) -> SensorListResponse

List all registered sensors.

Parameters:

Name	Type	Description	Default
include_status	bool	Whether to include connection status for each sensor	False

Returns:

Type	Description
SensorListResponse	Response containing list of sensors

connect_mqtt_sensor async

connect_mqtt_sensor(
    sensor_id: str, broker_url: str, identifier: str, address: str
) -> SensorConnectionResponse

Connect to an MQTT sensor with simplified parameters.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required
broker_url	str	MQTT broker URL (e.g., "mqtt://localhost:1883")	required
identifier	str	Client identifier for MQTT connection	required
address	str	MQTT topic to subscribe to	required

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of connection

connect_http_sensor async

connect_http_sensor(
    sensor_id: str,
    base_url: str,
    address: str,
    headers: Optional[Dict[str, str]] = None,
) -> SensorConnectionResponse

Connect to an HTTP sensor with simplified parameters.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required
base_url	str	Base URL for HTTP requests	required
address	str	Endpoint path for sensor data	required
headers	Optional[Dict[str, str]]	Optional HTTP headers	None

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of connection

connect_serial_sensor async

connect_serial_sensor(
    sensor_id: str, port: str, baudrate: int = 9600, timeout: float = 1.0
) -> SensorConnectionResponse

Connect to a serial sensor with simplified parameters.

Parameters:

Name	Type	Description	Default
sensor_id	str	Unique identifier for the sensor	required
port	str	Serial port (e.g., "/dev/ttyUSB0" or "COM1")	required
baudrate	int	Serial communication baud rate	9600
timeout	float	Serial read timeout	1.0

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of connection

launcher

Sensor API service launcher.

main

main()

Main launcher function.

models

Sensor API models for request/response data structures.

SensorConnectionRequest

Bases: BaseModel

Request to connect to a sensor.

SensorDataRequest

Bases: BaseModel

Request to read data from a connected sensor.

SensorListRequest

Bases: BaseModel

Request to list all sensors.

SensorStatusRequest

Bases: BaseModel

Request to get status of a sensor.

HealthCheckResponse

Bases: BaseModel

Health check response model.

SensorConnectionResponse

Bases: BaseModel

Response from sensor connection operation.

SensorConnectionStatus

Bases: str, Enum

Status of sensor connection.

SensorDataResponse

Bases: BaseModel

Response containing sensor data.

SensorInfo

Bases: BaseModel

Information about a sensor.

SensorListResponse

Bases: BaseModel

Response containing list of sensors.

SensorStatusResponse

Bases: BaseModel

Response containing sensor status information.

requests

Request models for sensor operations.

SensorConnectionRequest

Bases: BaseModel

Request to connect to a sensor.

SensorDataRequest

Bases: BaseModel

Request to read data from a connected sensor.

SensorStatusRequest

Bases: BaseModel

Request to get status of a sensor.

SensorListRequest

Bases: BaseModel

Request to list all sensors.

responses

Response models for sensor operations.

SensorConnectionStatus

Bases: str, Enum

Status of sensor connection.

SensorInfo

Bases: BaseModel

Information about a sensor.

SensorConnectionResponse

Bases: BaseModel

Response from sensor connection operation.

SensorDataResponse

Bases: BaseModel

Response containing sensor data.

SensorStatusResponse

Bases: BaseModel

Response containing sensor status information.

SensorListResponse

Bases: BaseModel

Response containing list of sensors.

HealthCheckResponse

Bases: BaseModel

Health check response model.

schemas

Sensor task schemas for service operations.

SensorDataSchemas

Task schemas for sensor data access.

SensorLifecycleSchemas

Task schemas for sensor lifecycle management.

data

Task schemas for sensor data operations.

SensorDataSchemas

Task schemas for sensor data access.

health

Health check TaskSchema.

lifecycle

Task schemas for sensor lifecycle operations.

SensorLifecycleSchemas

Task schemas for sensor lifecycle management.

service

Sensor Manager Service providing MCP endpoints for sensor operations.

SensorManagerService

SensorManagerService(manager: Optional[SensorManager] = None, **kwargs)

Bases: Service

Service wrapper for SensorManager with MCP endpoint registration.

Initialize the sensor manager service.

Parameters:

Name	Type	Description	Default
manager	Optional[SensorManager]	Optional SensorManager instance. If None, creates a new one.	None
**kwargs		Additional arguments passed to the Service base class	{}

manager property

manager: SensorManager

Get the underlying SensorManager instance.

connect_sensor async

connect_sensor(request: SensorConnectionRequest) -> SensorConnectionResponse

Connect to a sensor with specified configuration.

Parameters:

Name	Type	Description	Default
request	SensorConnectionRequest	Connection request with sensor configuration	required

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of connection

disconnect_sensor async

disconnect_sensor(request: SensorStatusRequest) -> SensorConnectionResponse

Disconnect from a connected sensor.

Parameters:

Name	Type	Description	Default
request	SensorStatusRequest	Request containing sensor_id to disconnect	required

Returns:

Type	Description
SensorConnectionResponse	Response indicating success/failure of disconnection

read_sensor_data async

read_sensor_data(request: SensorDataRequest) -> SensorDataResponse

Read data from a connected sensor.

Parameters:

Name	Type	Description	Default
request	SensorDataRequest	Request specifying sensor and read parameters	required

Returns:

Type	Description
SensorDataResponse	Response containing sensor data or error information

get_sensor_status async

get_sensor_status(request: SensorStatusRequest) -> SensorStatusResponse

Get status information for a sensor.

Parameters:

Name	Type	Description	Default
request	SensorStatusRequest	Request containing sensor_id	required

Returns:

Type	Description
SensorStatusResponse	Response containing sensor status information

list_sensors async

list_sensors(request: SensorListRequest) -> SensorListResponse

List all registered sensors.

Parameters:

Name	Type	Description	Default
request	SensorListRequest	Request with listing options	required

Returns:

Type	Description
SensorListResponse	Response containing list of sensors

shutdown_cleanup async

shutdown_cleanup()

Cleanup sensors on shutdown.

health_check

health_check() -> HealthCheckResponse

Health check endpoint for container healthcheck.

stereo_cameras

StereoCameraService - Service-based stereo camera management API.

StereoCameraConnectionManager

StereoCameraConnectionManager(
    url: Url | None = None,
    server_id: UUID | None = None,
    server_pid_file: str | None = None,
)

Bases: ConnectionManager

Connection Manager for StereoCameraService.

Provides strongly-typed methods for all stereo camera management operations, making it easy to use the service programmatically from other applications.

get async

get(endpoint: str, http_timeout: float = 60.0) -> Dict[str, Any]

Make GET request to service endpoint.

post async

post(
    endpoint: str, data: Dict[str, Any] = None, http_timeout: float = 60.0
) -> Dict[str, Any]

Make POST request to service endpoint.

discover_backends async

discover_backends() -> List[str]

Discover available stereo camera backends.

get_backend_info async

get_backend_info() -> Dict[str, Any]

Get detailed information about all backends.

discover_cameras async

discover_cameras(backend: Optional[str] = None) -> List[str]

Discover available stereo cameras.

open_camera async

open_camera(camera: str, test_connection: bool = True) -> bool

Open a stereo camera.

open_cameras_batch async

open_cameras_batch(
    cameras: List[str], test_connection: bool = True
) -> Dict[str, Any]

Open multiple stereo cameras.

close_camera async

close_camera(camera: str) -> bool

Close a stereo camera.

close_cameras_batch async

close_cameras_batch(cameras: List[str]) -> Dict[str, Any]

Close multiple stereo cameras.

close_all_cameras async

close_all_cameras() -> bool

Close all active stereo cameras.

get_active_cameras async

get_active_cameras() -> List[str]

Get list of currently active stereo cameras.

get_camera_status async

get_camera_status(camera: str) -> Dict[str, Any]

Get stereo camera status.

get_camera_info async

get_camera_info(camera: str) -> Dict[str, Any]

Get detailed stereo camera information.

get_system_diagnostics async

get_system_diagnostics() -> Dict[str, Any]

Get system diagnostics.

configure_camera async

configure_camera(camera: str, properties: Dict[str, Any]) -> bool

Configure stereo camera parameters.

configure_cameras_batch async

configure_cameras_batch(
    configurations: Dict[str, Dict[str, Any]],
) -> Dict[str, Any]

Configure multiple stereo cameras.

get_camera_configuration async

get_camera_configuration(camera: str) -> Dict[str, Any]

Get current stereo camera configuration.

capture_stereo_pair async

capture_stereo_pair(
    camera: str,
    save_intensity_path: Optional[str] = None,
    save_disparity_path: Optional[str] = None,
    enable_intensity: bool = True,
    enable_disparity: bool = True,
    calibrate_disparity: bool = True,
    timeout_ms: int = 20000,
    output_format: str = "pil",
) -> Dict[str, Any]

Capture stereo data (intensity + disparity).

capture_stereo_batch async

capture_stereo_batch(
    captures: List[Dict[str, Any]], output_format: str = "pil"
) -> Dict[str, Any]

Capture stereo data from multiple cameras.

capture_point_cloud async

capture_point_cloud(
    camera: str,
    save_path: Optional[str] = None,
    include_colors: bool = True,
    remove_outliers: bool = False,
    downsample_factor: int = 1,
    output_format: str = "numpy",
) -> Dict[str, Any]

Capture and generate 3D point cloud.

capture_point_cloud_batch async

capture_point_cloud_batch(
    captures: List[Dict[str, Any]], output_format: str = "numpy"
) -> Dict[str, Any]

Capture point clouds from multiple cameras.

StereoCameraService

StereoCameraService(**kwargs)

Bases: Service

Stereo Camera Management Service.

Provides comprehensive REST API and MCP tools for managing stereo cameras with multi-component capture capabilities (intensity, disparity, point clouds).

Supported Operations: - Backend discovery and information - Camera lifecycle management (open, close, status) - Multi-component capture (intensity + disparity) - Point cloud generation with optional color - Camera configuration (depth range, illumination, binning, quality, exposure, gain) - Batch operations for multiple cameras - System diagnostics and monitoring

Initialize StereoCameraService.

Parameters:

Name	Type	Description	Default
**kwargs		Additional arguments passed to Service base class	{}

health_check

health_check() -> HealthCheckResponse

Service health check for container healthcheck.

shutdown_cleanup async

shutdown_cleanup()

Cleanup cameras on shutdown.

get_backends

get_backends() -> BackendsResponse

Get list of available stereo camera backends.

get_backend_info

get_backend_info() -> BackendInfoResponse

Get detailed information about stereo camera backends.

discover_cameras

discover_cameras(request: BackendFilterRequest) -> ListResponse

Discover available stereo cameras.

open_camera async

open_camera(request: StereoCameraOpenRequest) -> BoolResponse

Open a stereo camera connection.

open_cameras_batch async

open_cameras_batch(
    request: StereoCameraOpenBatchRequest,
) -> BatchOperationResponse

Open multiple stereo cameras.

close_camera async

close_camera(request: StereoCameraCloseRequest) -> BoolResponse

Close a stereo camera connection.

close_cameras_batch async

close_cameras_batch(
    request: StereoCameraCloseBatchRequest,
) -> BatchOperationResponse

Close multiple stereo cameras.

close_all_cameras async

close_all_cameras() -> BoolResponse

Close all active stereo cameras.

get_active_cameras

get_active_cameras() -> ActiveStereoCamerasResponse

Get list of active stereo cameras.

get_camera_status async

get_camera_status(
    request: StereoCameraQueryRequest,
) -> StereoCameraStatusResponse

Get stereo camera status.

get_camera_info async

get_camera_info(request: StereoCameraQueryRequest) -> StereoCameraInfoResponse

Get detailed stereo camera information.

get_calibration

get_calibration(camera_name: str)

Get full calibration data including Q matrix for 2D-to-3D projection.

get_system_diagnostics

get_system_diagnostics() -> SystemDiagnosticsResponse

Get system diagnostics and statistics.

configure_camera async

configure_camera(request: StereoCameraConfigureRequest) -> BoolResponse

Configure stereo camera parameters.

configure_cameras_batch async

configure_cameras_batch(
    request: StereoCameraConfigureBatchRequest,
) -> BatchOperationResponse

Configure multiple stereo cameras.

get_camera_configuration async

get_camera_configuration(
    request: StereoCameraQueryRequest,
) -> StereoCameraConfigurationResponse

Get current stereo camera configuration.

capture_stereo_pair async

capture_stereo_pair(request: StereoCaptureRequest) -> StereoCaptureResponse

Capture stereo data (intensity + disparity).

capture_stereo_batch async

capture_stereo_batch(
    request: StereoCaptureBatchRequest,
) -> StereoCaptureBatchResponse

Capture stereo data from multiple cameras.

capture_point_cloud async

capture_point_cloud(request: PointCloudCaptureRequest) -> PointCloudResponse

Capture and generate 3D point cloud.

capture_point_cloud_batch async

capture_point_cloud_batch(
    request: PointCloudCaptureBatchRequest,
) -> PointCloudBatchResponse

Capture point clouds from multiple cameras.

start_stream

start_stream(camera: str, quality: int = 85, fps: int = 10)

Start stereo camera stream.

stop_stream

stop_stream(camera: str)

Stop stereo camera stream.

get_active_streams

get_active_streams()

Get list of active streams.

serve_stereo_stream async

serve_stereo_stream(camera_name: str)

Serve MJPEG video stream for stereo camera (intensity image).

connection_manager

Connection Manager for StereoCameraService.

Provides a strongly-typed client interface for programmatic access to stereo camera management operations.

StereoCameraConnectionManager

StereoCameraConnectionManager(
    url: Url | None = None,
    server_id: UUID | None = None,
    server_pid_file: str | None = None,
)

Bases: ConnectionManager

Connection Manager for StereoCameraService.

Provides strongly-typed methods for all stereo camera management operations, making it easy to use the service programmatically from other applications.

get async

get(endpoint: str, http_timeout: float = 60.0) -> Dict[str, Any]

Make GET request to service endpoint.

post async

post(
    endpoint: str, data: Dict[str, Any] = None, http_timeout: float = 60.0
) -> Dict[str, Any]

Make POST request to service endpoint.

discover_backends async

discover_backends() -> List[str]

Discover available stereo camera backends.

get_backend_info async

get_backend_info() -> Dict[str, Any]

Get detailed information about all backends.

discover_cameras async

discover_cameras(backend: Optional[str] = None) -> List[str]

Discover available stereo cameras.

open_camera async

open_camera(camera: str, test_connection: bool = True) -> bool

Open a stereo camera.

open_cameras_batch async

open_cameras_batch(
    cameras: List[str], test_connection: bool = True
) -> Dict[str, Any]

Open multiple stereo cameras.

close_camera async

close_camera(camera: str) -> bool

Close a stereo camera.

close_cameras_batch async

close_cameras_batch(cameras: List[str]) -> Dict[str, Any]

Close multiple stereo cameras.

close_all_cameras async

close_all_cameras() -> bool

Close all active stereo cameras.

get_active_cameras async

get_active_cameras() -> List[str]

Get list of currently active stereo cameras.

get_camera_status async

get_camera_status(camera: str) -> Dict[str, Any]

Get stereo camera status.

get_camera_info async

get_camera_info(camera: str) -> Dict[str, Any]

Get detailed stereo camera information.

get_system_diagnostics async

get_system_diagnostics() -> Dict[str, Any]

Get system diagnostics.

configure_camera async

configure_camera(camera: str, properties: Dict[str, Any]) -> bool

Configure stereo camera parameters.

configure_cameras_batch async

configure_cameras_batch(
    configurations: Dict[str, Dict[str, Any]],
) -> Dict[str, Any]

Configure multiple stereo cameras.

get_camera_configuration async

get_camera_configuration(camera: str) -> Dict[str, Any]

Get current stereo camera configuration.

capture_stereo_pair async

capture_stereo_pair(
    camera: str,
    save_intensity_path: Optional[str] = None,
    save_disparity_path: Optional[str] = None,
    enable_intensity: bool = True,
    enable_disparity: bool = True,
    calibrate_disparity: bool = True,
    timeout_ms: int = 20000,
    output_format: str = "pil",
) -> Dict[str, Any]

Capture stereo data (intensity + disparity).

capture_stereo_batch async

capture_stereo_batch(
    captures: List[Dict[str, Any]], output_format: str = "pil"
) -> Dict[str, Any]

Capture stereo data from multiple cameras.

capture_point_cloud async

capture_point_cloud(
    camera: str,
    save_path: Optional[str] = None,
    include_colors: bool = True,
    remove_outliers: bool = False,
    downsample_factor: int = 1,
    output_format: str = "numpy",
) -> Dict[str, Any]

Capture and generate 3D point cloud.

capture_point_cloud_batch async

capture_point_cloud_batch(
    captures: List[Dict[str, Any]], output_format: str = "numpy"
) -> Dict[str, Any]

Capture point clouds from multiple cameras.

launcher

Stereo Camera API service launcher.

main

main()

Main launcher function.

models

Models for StereoCameraService API.

BackendFilterRequest

Bases: BaseModel

Request model for backend filtering.

PointCloudCaptureBatchRequest

Bases: BaseModel

Request model for batch point cloud capture.

PointCloudCaptureRequest

Bases: BaseModel

Request model for point cloud capture.

StereoCameraCloseBatchRequest

Bases: BaseModel

Request model for batch stereo camera closing.

StereoCameraCloseRequest

Bases: BaseModel

Request model for closing a stereo camera.

StereoCameraConfigureBatchRequest

Bases: BaseModel

Request model for batch stereo camera configuration.

StereoCameraConfigureRequest

Bases: BaseModel

Request model for stereo camera configuration.

StereoCameraOpenBatchRequest

Bases: BaseModel

Request model for batch stereo camera opening.

StereoCameraOpenRequest

Bases: BaseModel

Request model for opening a stereo camera.

StereoCameraQueryRequest

Bases: BaseModel

Request model for stereo camera queries.

StereoCaptureBatchRequest

Bases: BaseModel

Request model for batch stereo capture.

StereoCaptureRequest

Bases: BaseModel

Request model for stereo capture.

ActiveStereoCamerasResponse

Bases: BaseResponse

Response model for listing active stereo cameras.

BackendInfo

Bases: BaseModel

Stereo camera backend information model.

BackendInfoResponse

Bases: BaseResponse

Response model for detailed backend information.

BackendsResponse

Bases: BaseResponse

Response model for backend listing.

BaseResponse

Bases: BaseModel

Base response model for all API endpoints.

BatchOperationResponse

Bases: BaseResponse

Response model for batch operations.

BatchOperationResult

Bases: BaseModel

Individual batch operation result.

BoolResponse

Bases: BaseResponse

Response model for boolean operations.

DictResponse

Bases: BaseResponse

Response model for dictionary data.

HealthCheckResponse

Bases: BaseModel

Health check response model.

ListResponse

Bases: BaseResponse

Response model for list data.

PointCloudBatchResponse

Bases: BaseResponse

Response model for batch point cloud capture.

PointCloudBatchResult

Bases: BaseModel

Batch point cloud capture result model.

PointCloudResponse

Bases: BaseResponse

Response model for point cloud capture.

PointCloudResult

Bases: BaseModel

Point cloud capture result model.

StereoCameraConfiguration

Bases: BaseModel

Stereo camera configuration model.

StereoCameraConfigurationResponse

Bases: BaseResponse

Response model for stereo camera configuration.

StereoCameraInfo

Bases: BaseModel

Stereo camera information model.

StereoCameraInfoResponse

Bases: BaseResponse

Response model for stereo camera information.

StereoCameraStatus

Bases: BaseModel

Stereo camera status model.

StereoCameraStatusResponse

Bases: BaseResponse

Response model for stereo camera status.

StereoCaptureBatchResponse

Bases: BaseResponse

Response model for batch stereo capture.

StereoCaptureBatchResult

Bases: BaseModel

Batch stereo capture result model.

StereoCaptureResponse

Bases: BaseResponse

Response model for stereo capture.

StereoCaptureResult

Bases: BaseModel

Stereo capture result model.

StringResponse

Bases: BaseResponse

Response model for string values.

SystemDiagnostics

Bases: BaseModel

System diagnostics model.

SystemDiagnosticsResponse

Bases: BaseResponse

Response model for system diagnostics.

requests

Request models for StereoCameraService.

Contains all Pydantic models for API requests, ensuring proper input validation and documentation for all stereo camera operations.

BackendFilterRequest

Bases: BaseModel

Request model for backend filtering.

StereoCameraOpenRequest

Bases: BaseModel

Request model for opening a stereo camera.

StereoCameraOpenBatchRequest

Bases: BaseModel

Request model for batch stereo camera opening.

StereoCameraCloseRequest

Bases: BaseModel

Request model for closing a stereo camera.

StereoCameraCloseBatchRequest

Bases: BaseModel

Request model for batch stereo camera closing.

StereoCameraQueryRequest

Bases: BaseModel

Request model for stereo camera queries.

StereoCameraConfigureRequest

Bases: BaseModel

Request model for stereo camera configuration.

StereoCameraConfigureBatchRequest

Bases: BaseModel

Request model for batch stereo camera configuration.

StereoCaptureRequest

Bases: BaseModel

Request model for stereo capture.

StereoCaptureBatchRequest

Bases: BaseModel

Request model for batch stereo capture.

PointCloudCaptureRequest

Bases: BaseModel

Request model for point cloud capture.

PointCloudCaptureBatchRequest

Bases: BaseModel

Request model for batch point cloud capture.

responses

Response models for StereoCameraService.

Contains all Pydantic models for API responses, ensuring consistent response formatting across all stereo camera management endpoints.

BaseResponse

Bases: BaseModel

Base response model for all API endpoints.

BoolResponse

Bases: BaseResponse

Response model for boolean operations.

StringResponse

Bases: BaseResponse

Response model for string values.

ListResponse

Bases: BaseResponse

Response model for list data.

DictResponse

Bases: BaseResponse

Response model for dictionary data.

BackendInfo

Bases: BaseModel

Stereo camera backend information model.

BackendsResponse

Bases: BaseResponse

Response model for backend listing.

BackendInfoResponse

Bases: BaseResponse

Response model for detailed backend information.

StereoCameraStatus

Bases: BaseModel

Stereo camera status model.

StereoCameraStatusResponse

Bases: BaseResponse

Response model for stereo camera status.

StereoCameraInfo

Bases: BaseModel

Stereo camera information model.

StereoCameraInfoResponse

Bases: BaseResponse

Response model for stereo camera information.

StereoCameraConfiguration

Bases: BaseModel

Stereo camera configuration model.

StereoCameraConfigurationResponse

Bases: BaseResponse

Response model for stereo camera configuration.

StereoCaptureResult

Bases: BaseModel

Stereo capture result model.

StereoCaptureResponse

Bases: BaseResponse

Response model for stereo capture.

StereoCaptureBatchResult

Bases: BaseModel

Batch stereo capture result model.

StereoCaptureBatchResponse

Bases: BaseResponse

Response model for batch stereo capture.

PointCloudResult

Bases: BaseModel

Point cloud capture result model.

PointCloudResponse

Bases: BaseResponse

Response model for point cloud capture.

PointCloudBatchResult

Bases: BaseModel

Batch point cloud capture result model.

PointCloudBatchResponse

Bases: BaseResponse

Response model for batch point cloud capture.

BatchOperationResult

Bases: BaseModel

Individual batch operation result.

BatchOperationResponse

Bases: BaseResponse

Response model for batch operations.

ActiveStereoCamerasResponse

Bases: BaseResponse

Response model for listing active stereo cameras.

SystemDiagnostics

Bases: BaseModel

System diagnostics model.

SystemDiagnosticsResponse

Bases: BaseResponse

Response model for system diagnostics.

HealthCheckResponse

Bases: BaseModel

Health check response model.

schemas

MCP TaskSchemas for StereoCameraService.

capture_schemas

Stereo Camera Capture TaskSchemas.

config_schemas

Stereo Camera Configuration TaskSchemas.

health_schemas

Health check TaskSchema.

info_schemas

Stereo Camera Information TaskSchemas.

lifecycle_schemas

Stereo Camera Lifecycle TaskSchemas.

service

StereoCameraService - Service-based API for stereo camera management.

This service provides comprehensive REST API and MCP tools for managing Basler Stereo ace cameras with multi-component capture (intensity, disparity, depth).

StereoCameraService

StereoCameraService(**kwargs)

Bases: Service

Stereo Camera Management Service.

Provides comprehensive REST API and MCP tools for managing stereo cameras with multi-component capture capabilities (intensity, disparity, point clouds).

Supported Operations: - Backend discovery and information - Camera lifecycle management (open, close, status) - Multi-component capture (intensity + disparity) - Point cloud generation with optional color - Camera configuration (depth range, illumination, binning, quality, exposure, gain) - Batch operations for multiple cameras - System diagnostics and monitoring

Initialize StereoCameraService.

Parameters:

Name	Type	Description	Default
**kwargs		Additional arguments passed to Service base class	{}

health_check

health_check() -> HealthCheckResponse

Service health check for container healthcheck.

shutdown_cleanup async

shutdown_cleanup()

Cleanup cameras on shutdown.

get_backends

get_backends() -> BackendsResponse

Get list of available stereo camera backends.

get_backend_info

get_backend_info() -> BackendInfoResponse

Get detailed information about stereo camera backends.

discover_cameras

discover_cameras(request: BackendFilterRequest) -> ListResponse

Discover available stereo cameras.

open_camera async

open_camera(request: StereoCameraOpenRequest) -> BoolResponse

Open a stereo camera connection.

open_cameras_batch async

open_cameras_batch(
    request: StereoCameraOpenBatchRequest,
) -> BatchOperationResponse

Open multiple stereo cameras.

close_camera async

close_camera(request: StereoCameraCloseRequest) -> BoolResponse

Close a stereo camera connection.

close_cameras_batch async

close_cameras_batch(
    request: StereoCameraCloseBatchRequest,
) -> BatchOperationResponse

Close multiple stereo cameras.

close_all_cameras async

close_all_cameras() -> BoolResponse

Close all active stereo cameras.

get_active_cameras

get_active_cameras() -> ActiveStereoCamerasResponse

Get list of active stereo cameras.

get_camera_status async

get_camera_status(
    request: StereoCameraQueryRequest,
) -> StereoCameraStatusResponse

Get stereo camera status.

get_camera_info async

get_camera_info(request: StereoCameraQueryRequest) -> StereoCameraInfoResponse

Get detailed stereo camera information.

get_calibration

get_calibration(camera_name: str)

Get full calibration data including Q matrix for 2D-to-3D projection.

get_system_diagnostics

get_system_diagnostics() -> SystemDiagnosticsResponse

Get system diagnostics and statistics.

configure_camera async

configure_camera(request: StereoCameraConfigureRequest) -> BoolResponse

Configure stereo camera parameters.

configure_cameras_batch async

configure_cameras_batch(
    request: StereoCameraConfigureBatchRequest,
) -> BatchOperationResponse

Configure multiple stereo cameras.

get_camera_configuration async

get_camera_configuration(
    request: StereoCameraQueryRequest,
) -> StereoCameraConfigurationResponse

Get current stereo camera configuration.

capture_stereo_pair async

capture_stereo_pair(request: StereoCaptureRequest) -> StereoCaptureResponse

Capture stereo data (intensity + disparity).

capture_stereo_batch async

capture_stereo_batch(
    request: StereoCaptureBatchRequest,
) -> StereoCaptureBatchResponse

Capture stereo data from multiple cameras.

capture_point_cloud async

capture_point_cloud(request: PointCloudCaptureRequest) -> PointCloudResponse

Capture and generate 3D point cloud.

capture_point_cloud_batch async

capture_point_cloud_batch(
    request: PointCloudCaptureBatchRequest,
) -> PointCloudBatchResponse

Capture point clouds from multiple cameras.

start_stream

start_stream(camera: str, quality: int = 85, fps: int = 10)

Start stereo camera stream.

stop_stream

stop_stream(camera: str)

Stop stereo camera stream.

get_active_streams

get_active_streams()

Get list of active streams.

serve_stereo_stream async

serve_stereo_stream(camera_name: str)

Serve MJPEG video stream for stereo camera (intensity image).

stereo_cameras

Stereo camera support for MindTrace hardware system.

This module provides backends and utilities for stereo camera systems that output multi-component data (intensity, disparity, depth, point clouds).

Available components

• backends: Stereo camera backend implementations
• core: Core stereo camera management classes
• setup: Installation scripts for stereo camera SDKs

Quick Start

from mindtrace.hardware.stereo_cameras import StereoCamera

Open first available stereo camera

camera = StereoCamera()

Capture multi-component data

result = camera.capture() print(f"Intensity: {result.intensity.shape}") print(f"Disparity: {result.disparity.shape}")

Generate point cloud

point_cloud = camera.capture_point_cloud() point_cloud.save_ply("output.ply")

camera.close()

BaslerStereoAceBackend

BaslerStereoAceBackend(
    serial_number: Optional[str] = None, op_timeout_s: float = 30.0
)

Bases: Mindtrace

Backend for Basler Stereo ace cameras using pypylon.

The Stereo ace camera is accessed through a unified device interface (DeviceClass: BaslerGTC/Basler/basler_xw) that presents the stereo pair as a single camera with multi-component output.

Initialize Basler Stereo ace backend.

Parameters:

Name	Type	Description	Default
serial_number	Optional[str]	Serial number or user-defined name of specific camera. If all digits, treated as serial number. Otherwise, treated as user-defined name. If None, opens first available Stereo ace camera.	None
op_timeout_s	float	Timeout in seconds for SDK operations (default 30s).	30.0

Raises:

Type	Description
SDKNotAvailableError	If pypylon is not available

name property

name: str

Get camera name.

is_open property

is_open: bool

Check if camera is open.

calibration property

calibration: Optional[StereoCalibrationData]

Get calibration data.

discover staticmethod

discover() -> List[str]

Discover available Stereo ace cameras.

Returns:

Type	Description
List[str]	List of serial numbers for available Stereo ace cameras

Raises:

Type	Description
SDKNotAvailableError	If pypylon is not available

discover_async async classmethod

discover_async() -> List[str]

Async wrapper for discover() - runs discovery in threadpool.

Use this instead of discover() when calling from async context to avoid blocking the event loop during camera discovery.

Returns:

Type	Description
List[str]	List of serial numbers for available Stereo ace cameras

discover_detailed staticmethod

discover_detailed() -> List[Dict[str, str]]

Discover Stereo ace cameras with detailed information.

Returns:

Type	Description
List[Dict[str, str]]	List of dictionaries containing camera information

Raises:

Type	Description
SDKNotAvailableError	If pypylon is not available

discover_detailed_async async classmethod

discover_detailed_async() -> List[Dict[str, str]]

Async wrapper for discover_detailed() - runs discovery in threadpool.

Returns:

Type	Description
List[Dict[str, str]]	List of dictionaries containing camera information

initialize async

initialize() -> bool

Initialize camera connection.

Returns:

Type	Description
bool	True if initialization successful, False otherwise

get_calibration async

get_calibration() -> StereoCalibrationData

Get factory calibration parameters from camera.

Returns:

Type	Description
StereoCalibrationData	StereoCalibrationData with factory calibration

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If calibration cannot be read

capture async

capture(
    timeout_ms: int = 20000,
    enable_intensity: bool = True,
    enable_disparity: bool = True,
    calibrate_disparity: bool = True,
) -> StereoGrabResult

Capture stereo data with multiple components.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Capture timeout in milliseconds	20000
enable_intensity	bool	Whether to capture intensity data	True
enable_disparity	bool	Whether to capture disparity data	True
calibrate_disparity	bool	Whether to apply calibration to disparity	True

Returns:

Type	Description
StereoGrabResult	StereoGrabResult containing captured data

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails

configure async

configure(**params) -> None

Configure camera parameters.

Parameters:

Name	Type	Description	Default
**params		Parameter name-value pairs to configure. Special parameters: - trigger_mode: "continuous" or "trigger" - depth_range: tuple of (min_depth, max_depth) - illumination_mode: "AlwaysActive" or "AlternateActive" - binning: tuple of (horizontal, vertical) - depth_quality: "Full", "High", "Normal", or "Low" - All other parameters passed directly to camera	{}

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If configuration fails

set_depth_range async

set_depth_range(min_depth: float, max_depth: float) -> None

Set depth measurement range.

Parameters:

Name	Type	Description	Default
min_depth	float	Minimum depth in meters (e.g., 0.3)	required
max_depth	float	Maximum depth in meters (e.g., 5.0)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

set_illumination_mode async

set_illumination_mode(mode: str) -> None

Set illumination mode.

Parameters:

Name	Type	Description	Default
mode	str	'AlwaysActive' (low latency) or 'AlternateActive' (clean intensity)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

set_binning async

set_binning(horizontal: int = 2, vertical: int = 2) -> None

Enable binning for latency reduction.

Parameters:

Name	Type	Description	Default
horizontal	int	Horizontal binning factor (typically 2)	2
vertical	int	Vertical binning factor (typically 2)	2

Note

When using binning for low latency, consider also setting depth quality to "Full" using set_depth_quality("Full").

Raises:

Type	Description
CameraConfigurationError	If configuration fails

set_depth_quality async

set_depth_quality(quality: str) -> None

Set depth quality level.

Parameters:

Name	Type	Description	Default
quality	str	Depth quality setting. Common values: - "Full": Highest quality, recommended with binning - "Normal": Standard quality - "Low": Lower quality, faster processing	required

Note

Setting quality to "Full" with binning reduces latency while maintaining depth quality. This is recommended for low-latency applications.

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Example

Low latency configuration

await camera.set_binning(2, 2) await camera.set_depth_quality("Full")

set_pixel_format async

set_pixel_format(format: str) -> None

Set pixel format for intensity component.

Parameters:

Name	Type	Description	Default
format	str	Pixel format ("RGB8", "Mono8", etc.)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If format not available or configuration fails

Example

await camera.set_pixel_format("Mono8") # Force grayscale

set_exposure_time async

set_exposure_time(microseconds: float) -> None

Set exposure time in microseconds.

Parameters:

Name	Type	Description	Default
microseconds	float	Exposure time in microseconds (e.g., 5000 = 5ms)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Example

await camera.set_exposure_time(5000) # 5ms exposure

set_gain async

set_gain(gain: float) -> None

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	float	Gain value (typically 0.0 to 24.0, camera-dependent)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Example

await camera.set_gain(2.0)

get_exposure_time async

get_exposure_time() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time in microseconds

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

exposure = await camera.get_exposure_time() print(f"Current exposure: {exposure}us")

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

gain = await camera.get_gain() print(f"Current gain: {gain}")

get_depth_quality async

get_depth_quality() -> str

Get current depth quality setting.

Returns:

Type	Description
str	Current depth quality level (e.g., "Full", "Normal", "Low")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

quality = await camera.get_depth_quality() print(f"Depth quality: {quality}")

get_pixel_format async

get_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format (e.g., "RGB8", "Mono8", "Coord3D_C16")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

format = await camera.get_pixel_format() print(f"Pixel format: {format}")

get_binning async

get_binning() -> tuple[int, int]

Get current binning settings.

Returns:

Type	Description
tuple[int, int]	Tuple of (horizontal_binning, vertical_binning)

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

h_bin, v_bin = await camera.get_binning() print(f"Binning: {h_bin}x{v_bin}")

get_illumination_mode async

get_illumination_mode() -> str

Get current illumination mode.

Returns:

Type	Description
str	Current illumination mode ("AlwaysActive" or "AlternateActive")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

mode = await camera.get_illumination_mode() print(f"Illumination: {mode}")

get_depth_range async

get_depth_range() -> tuple[float, float]

Get current depth measurement range in meters.

Returns:

Type	Description
tuple[float, float]	Tuple of (min_depth, max_depth) in meters

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

min_d, max_d = await camera.get_depth_range() print(f"Depth range: {min_d}m - {max_d}m")

set_trigger_mode async

set_trigger_mode(mode: str) -> None

Set trigger mode (simplified interface).

Parameters:

Name	Type	Description	Default
mode	str	Trigger mode ("continuous" or "trigger") - "continuous": Free-running continuous acquisition (TriggerMode=Off) - "trigger": Software-triggered acquisition (TriggerMode=On, TriggerSource=Software)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> await backend.set_trigger_mode("continuous")  # Free running
>>> await backend.set_trigger_mode("trigger")     # Software triggered

get_trigger_mode async

get_trigger_mode() -> str

Get current trigger mode (simplified interface).

Returns:

Type	Description
str	"continuous" if TriggerMode is Off, "trigger" if TriggerMode is On with Software source

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> mode = await backend.get_trigger_mode()
>>> print(f"Current mode: {mode}")

get_trigger_modes async

get_trigger_modes() -> List[str]

Get available trigger modes.

Returns:

Type	Description
List[str]	List of supported trigger modes: ["continuous", "trigger"]

Note

This provides a simplified interface. The underlying camera supports additional modes (SingleFrame, MultiFrame, hardware triggers) accessible via direct configure() calls if needed.

start_grabbing async

start_grabbing() -> None

Start grabbing frames.

This must be called before execute_trigger() in software trigger mode.

Raises:

Type	Description
CameraConnectionError	If camera not opened

execute_trigger async

execute_trigger() -> None

Execute software trigger.

Note: In software trigger mode, ensure start_grabbing() is called first, or call capture() once before the trigger loop to start grabbing.

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If trigger execution fails

close async

close() -> None

Close camera and release resources.

AsyncStereoCamera

AsyncStereoCamera(backend)

Bases: Mindtrace

Async stereo camera interface.

Provides high-level stereo camera operations including multi-component capture and 3D point cloud generation.

Initialize async stereo camera.

Parameters:

Name	Type	Description	Default
backend		Backend instance (e.g., BaslerStereoAceBackend)	required

name property

name: str

Get camera name.

calibration property

calibration: Optional[StereoCalibrationData]

Get calibration data.

is_open property

is_open: bool

Check if camera is open.

open async classmethod

open(name: Optional[str] = None) -> 'AsyncStereoCamera'

Open and initialize a stereo camera.

Parameters:

Name	Type	Description	Default
name	Optional[str]	Camera identifier. Format: "BaslerStereoAce:serial_number" If None, opens first available Stereo ace camera.	None

Returns:

Type	Description
'AsyncStereoCamera'	Initialized AsyncStereoCamera instance

Raises:

Type	Description
CameraNotFoundError	If camera not found
CameraConnectionError	If connection fails

Examples:

>>> camera = await AsyncStereoCamera.open()
>>> camera = await AsyncStereoCamera.open("BaslerStereoAce:40644640")

initialize async

initialize() -> bool

Initialize camera and load calibration.

Returns:

Type	Description
bool	True if initialization successful

Note

Usually not needed as open() handles initialization

close async

close() -> None

Close camera and release resources.

capture async

capture(
    enable_intensity: bool = True,
    enable_disparity: bool = True,
    calibrate_disparity: bool = True,
    timeout_ms: int = 20000,
) -> StereoGrabResult

Capture multi-component stereo data.

Parameters:

Name	Type	Description	Default
enable_intensity	bool	Whether to capture intensity image	True
enable_disparity	bool	Whether to capture disparity map	True
calibrate_disparity	bool	Whether to apply calibration to disparity	True
timeout_ms	int	Capture timeout in milliseconds	20000

Returns:

Type	Description
StereoGrabResult	StereoGrabResult containing captured data

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails

Examples:

>>> result = await camera.capture()
>>> print(f"Intensity: {result.intensity.shape}")
>>> print(f"Disparity: {result.disparity.shape}")

capture_point_cloud async

capture_point_cloud(
    include_colors: bool = True,
    remove_outliers: bool = False,
    downsample_factor: int = 1,
) -> PointCloudData

Capture and generate 3D point cloud.

Parameters:

Name	Type	Description	Default
include_colors	bool	Whether to include color information from intensity	True
remove_outliers	bool	Whether to remove statistical outliers	False
downsample_factor	int	Downsampling factor (1 = no downsampling)	1

Returns:

Type	Description
PointCloudData	PointCloudData with 3D points and optional colors

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails
CameraConfigurationError	If calibration not available

Examples:

>>> point_cloud = await camera.capture_point_cloud()
>>> point_cloud.save_ply("output.ply")
>>> pcd = point_cloud.to_open3d()

configure async

configure(**params) -> None

Configure camera parameters.

Parameters:

Name	Type	Description	Default
**params		Parameter name-value pairs	{}

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.configure(ExposureTime=15000, Gain=2.0)

set_depth_range async

set_depth_range(min_depth: float, max_depth: float) -> None

Set depth measurement range in meters.

Parameters:

Name	Type	Description	Default
min_depth	float	Minimum depth (e.g., 0.3 meters)	required
max_depth	float	Maximum depth (e.g., 5.0 meters)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.set_depth_range(0.5, 3.0)

set_illumination_mode async

set_illumination_mode(mode: str) -> None

Set illumination mode.

Parameters:

Name	Type	Description	Default
mode	str	'AlwaysActive' (low latency) or 'AlternateActive' (clean intensity)	required

Raises:

Type	Description
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> await camera.set_illumination_mode("AlternateActive")

set_binning async

set_binning(horizontal: int = 2, vertical: int = 2) -> None

Enable binning for latency reduction.

Binning reduces network transfer and computation.

Parameters:

Name	Type	Description	Default
horizontal	int	Horizontal binning factor (typically 2)	2
vertical	int	Vertical binning factor (typically 2)	2

Note

When using binning for low latency, consider also setting depth quality to "Full" using set_depth_quality("Full").

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.set_binning(2, 2)
>>> await camera.set_depth_quality("Full")  # Recommended for low latency

set_depth_quality async

set_depth_quality(quality: str) -> None

Set depth quality level.

Parameters:

Name	Type	Description	Default
quality	str	Depth quality setting. Common values: - "Full": Highest quality, recommended with binning - "Normal": Standard quality - "Low": Lower quality, faster processing	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> # Low latency configuration
>>> await camera.set_binning(2, 2)
>>> await camera.set_depth_quality("Full")

set_pixel_format async

set_pixel_format(format: str) -> None

Set pixel format for intensity component.

Parameters:

Name	Type	Description	Default
format	str	Pixel format ("RGB8", "Mono8", etc.)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If format not available or configuration fails

Examples:

>>> await camera.set_pixel_format("Mono8")  # Force grayscale

set_exposure_time async

set_exposure_time(microseconds: float) -> None

Set exposure time in microseconds.

Parameters:

Name	Type	Description	Default
microseconds	float	Exposure time in microseconds (e.g., 5000 = 5ms)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.set_exposure_time(5000)  # 5ms exposure

set_gain async

set_gain(gain: float) -> None

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	float	Gain value (typically 0.0 to 24.0, camera-dependent)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.set_gain(2.0)

get_exposure_time async

get_exposure_time() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time in microseconds

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> exposure = await camera.get_exposure_time()
>>> print(f"Exposure: {exposure}μs")

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> gain = await camera.get_gain()
>>> print(f"Gain: {gain}")

get_depth_quality async

get_depth_quality() -> str

Get current depth quality setting.

Returns:

Type	Description
str	Current depth quality level (e.g., "Full", "Normal", "Low")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> quality = await camera.get_depth_quality()
>>> print(f"Quality: {quality}")

get_pixel_format async

get_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format (e.g., "RGB8", "Mono8", "Coord3D_C16")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> format = await camera.get_pixel_format()
>>> print(f"Format: {format}")

get_binning async

get_binning() -> tuple[int, int]

Get current binning settings.

Returns:

Type	Description
tuple[int, int]	Tuple of (horizontal_binning, vertical_binning)

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> h_bin, v_bin = await camera.get_binning()
>>> print(f"Binning: {h_bin}x{v_bin}")

get_illumination_mode async

get_illumination_mode() -> str

Get current illumination mode.

Returns:

Type	Description
str	Current illumination mode ("AlwaysActive" or "AlternateActive")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> mode = await camera.get_illumination_mode()
>>> print(f"Illumination: {mode}")

get_depth_range async

get_depth_range() -> tuple[float, float]

Get current depth measurement range in meters.

Returns:

Type	Description
tuple[float, float]	Tuple of (min_depth, max_depth) in meters

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> min_d, max_d = await camera.get_depth_range()
>>> print(f"Range: {min_d}m - {max_d}m")

set_trigger_mode async

set_trigger_mode(mode: str) -> None

Set trigger mode (simplified interface).

Parameters:

Name	Type	Description	Default
mode	str	Trigger mode ("continuous" or "trigger") - "continuous": Free-running continuous acquisition - "trigger": Software-triggered acquisition	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> await camera.set_trigger_mode("continuous")  # Free running
>>> await camera.set_trigger_mode("trigger")     # Software triggered

get_trigger_mode async

get_trigger_mode() -> str

Get current trigger mode (simplified interface).

Returns:

Type	Description
str	"continuous" or "trigger"

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> mode = await camera.get_trigger_mode()
>>> print(f"Current mode: {mode}")

get_trigger_modes async

get_trigger_modes() -> list[str]

Get available trigger modes.

Returns:

Type	Description
list[str]	List of supported trigger modes: ["continuous", "trigger"]

Examples:

>>> modes = await camera.get_trigger_modes()
>>> print(f"Available modes: {modes}")

start_grabbing async

start_grabbing() -> None

Start grabbing frames.

Must be called after enable_software_trigger() and before execute_trigger().

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> await camera.enable_software_trigger()
>>> await camera.start_grabbing()
>>> for i in range(10):
...     await camera.execute_trigger()
...     result = await camera.capture()

execute_trigger async

execute_trigger() -> None

Execute software trigger.

Triggers a frame capture when in software trigger mode. Note: start_grabbing() must be called first after enabling software trigger.

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If trigger execution fails

Examples:

>>> await camera.enable_software_trigger()
>>> await camera.start_grabbing()
>>> for i in range(10):
...     await camera.execute_trigger()
...     result = await camera.capture()

PointCloudData dataclass

PointCloudData(
    points: ndarray,
    colors: Optional[ndarray] = None,
    num_points: int = 0,
    has_colors: bool = False,
)

3D point cloud data with optional color information.

Attributes:

Name	Type	Description
points	ndarray	Array of 3D points (N, 3) - (x, y, z) in meters
colors	Optional[ndarray]	Optional array of RGB colors (N, 3) - values in [0, 1]
num_points	int	Number of valid points
has_colors	bool	Flag indicating if color information is present

save_ply

save_ply(path: str, binary: bool = True) -> None

Save point cloud as PLY file.

Parameters:

Name	Type	Description	Default
path	str	Output file path	required
binary	bool	If True, save in binary format; otherwise ASCII	True

Raises:

Type	Description
ImportError	If plyfile is not installed

to_open3d

to_open3d()

Convert to Open3D PointCloud object.

Returns:

Type	Description
	open3d.geometry.PointCloud instance

Raises:

Type	Description
ImportError	If open3d is not installed

downsample

downsample(factor: int) -> 'PointCloudData'

Downsample point cloud by given factor.

Parameters:

Name	Type	Description	Default
factor	int	Downsampling factor (e.g., 2 = keep every 2nd point)	required

Returns:

Type	Description
'PointCloudData'	New PointCloudData with downsampled points

remove_statistical_outliers

remove_statistical_outliers(
    nb_neighbors: int = 20, std_ratio: float = 2.0
) -> "PointCloudData"

Remove statistical outliers from point cloud.

Parameters:

Name	Type	Description	Default
nb_neighbors	int	Number of neighbors to consider	20
std_ratio	float	Standard deviation ratio threshold	2.0

Returns:

Type	Description
'PointCloudData'	New PointCloudData with outliers removed

Raises:

Type	Description
ImportError	If open3d is not installed

StereoCalibrationData dataclass

StereoCalibrationData(
    baseline: float,
    focal_length: float,
    principal_point_u: float,
    principal_point_v: float,
    scale3d: float,
    offset3d: float,
    Q: ndarray,
)

Factory calibration parameters for stereo camera.

These parameters are provided by the camera manufacturer and used for 3D reconstruction from disparity maps.

Attributes:

Name	Type	Description
baseline	float	Stereo baseline in meters (distance between camera pair)
focal_length	float	Focal length in pixels
principal_point_u	float	Principal point U coordinate in pixels
principal_point_v	float	Principal point V coordinate in pixels
scale3d	float	Scale factor for disparity conversion
offset3d	float	Offset for disparity conversion
Q	ndarray	4x4 reprojection matrix for point cloud generation

from_camera_params classmethod

from_camera_params(params: dict) -> 'StereoCalibrationData'

Create calibration data from camera parameter dictionary.

Parameters:

Name	Type	Description	Default
params	dict	Dictionary containing calibration parameters: - Scan3dBaseline: Baseline in meters - Scan3dFocalLength: Focal length in pixels - Scan3dPrincipalPointU: Principal point U in pixels - Scan3dPrincipalPointV: Principal point V in pixels - Scan3dCoordinateScale: Scale factor - Scan3dCoordinateOffset: Offset	required

Returns:

Type	Description
'StereoCalibrationData'	StereoCalibrationData instance

calibrate_disparity

calibrate_disparity(disparity: ndarray) -> np.ndarray

Apply calibration to raw disparity map.

Parameters:

Name	Type	Description	Default
disparity	ndarray	Raw disparity map (uint16)	required

Returns:

Type	Description
ndarray	Calibrated disparity map (float32)

StereoCamera

StereoCamera(
    async_camera: Optional[AsyncStereoCamera] = None,
    loop: Optional[AbstractEventLoop] = None,
    name: Optional[str] = None,
    **kwargs
)

Bases: Mindtrace

Synchronous wrapper around AsyncStereoCamera.

All operations are executed on a background event loop. This provides a simple synchronous API for stereo camera operations.

Create a synchronous stereo camera wrapper.

Parameters:

Name	Type	Description	Default
async_camera	Optional[AsyncStereoCamera]	Existing AsyncStereoCamera instance	None
loop	Optional[AbstractEventLoop]	Event loop to use for async operations	None
name	Optional[str]	Camera identifier. Format: "BaslerStereoAce:serial_number" If None, opens first available Stereo ace camera.	None
**kwargs		Additional arguments passed to Mindtrace	{}

Examples:

>>> # Simple usage - opens first available
>>> camera = StereoCamera()

>>> # Open specific camera
>>> camera = StereoCamera(name="BaslerStereoAce:40644640")

>>> # Use existing async camera
>>> async_cam = await AsyncStereoCamera.open()
>>> sync_cam = StereoCamera(async_camera=async_cam, loop=loop)

name property

name: str

Get camera name.

Returns:

Type	Description
str	Camera name in format "Backend:serial_number"

calibration property

calibration: Optional[StereoCalibrationData]

Get calibration data.

Returns:

Type	Description
Optional[StereoCalibrationData]	StereoCalibrationData if available, None otherwise

is_open property

is_open: bool

Check if camera is open.

Returns:

Type	Description
bool	True if camera is open, False otherwise

close

close() -> None

Close camera and release resources.

Examples:

>>> camera = StereoCamera()
>>> # ... use camera ...
>>> camera.close()

capture

capture(
    enable_intensity: bool = True,
    enable_disparity: bool = True,
    calibrate_disparity: bool = True,
    timeout_ms: int = 20000,
) -> StereoGrabResult

Capture multi-component stereo data.

Parameters:

Name	Type	Description	Default
enable_intensity	bool	Whether to capture intensity image	True
enable_disparity	bool	Whether to capture disparity map	True
calibrate_disparity	bool	Whether to apply calibration to disparity	True
timeout_ms	int	Capture timeout in milliseconds	20000

Returns:

Type	Description
StereoGrabResult	StereoGrabResult containing captured data

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails

Examples:

>>> camera = StereoCamera()
>>> result = camera.capture()
>>> print(f"Intensity: {result.intensity.shape}")
>>> print(f"Disparity: {result.disparity.shape}")
>>> camera.close()

capture_point_cloud

capture_point_cloud(
    include_colors: bool = True,
    remove_outliers: bool = False,
    downsample_factor: int = 1,
) -> PointCloudData

Capture and generate 3D point cloud.

Parameters:

Name	Type	Description	Default
include_colors	bool	Whether to include color information from intensity	True
remove_outliers	bool	Whether to remove statistical outliers	False
downsample_factor	int	Downsampling factor (1 = no downsampling)	1

Returns:

Type	Description
PointCloudData	PointCloudData with 3D points and optional colors

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails
CameraConfigurationError	If calibration not available

Examples:

>>> camera = StereoCamera()
>>> point_cloud = camera.capture_point_cloud()
>>> print(f"Points: {point_cloud.num_points}")
>>> point_cloud.save_ply("output.ply")
>>> camera.close()

configure

configure(**params) -> None

Configure camera parameters.

Parameters:

Name	Type	Description	Default
**params		Parameter name-value pairs	{}

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.configure(ExposureTime=15000, Gain=2.0)
>>> camera.close()

set_depth_range

set_depth_range(min_depth: float, max_depth: float) -> None

Set depth measurement range in meters.

Parameters:

Name	Type	Description	Default
min_depth	float	Minimum depth (e.g., 0.3 meters)	required
max_depth	float	Maximum depth (e.g., 5.0 meters)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_depth_range(0.5, 3.0)
>>> camera.close()

set_illumination_mode

set_illumination_mode(mode: str) -> None

Set illumination mode.

Parameters:

Name	Type	Description	Default
mode	str	'AlwaysActive' (low latency) or 'AlternateActive' (clean intensity)	required

Raises:

Type	Description
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_illumination_mode("AlternateActive")
>>> camera.close()

set_binning

set_binning(horizontal: int = 2, vertical: int = 2) -> None

Enable binning for latency reduction.

Binning reduces network transfer and computation.

Parameters:

Name	Type	Description	Default
horizontal	int	Horizontal binning factor (typically 2)	2
vertical	int	Vertical binning factor (typically 2)	2

Note

When using binning for low latency, consider also setting depth quality to "Full" using set_depth_quality("Full").

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_binning(2, 2)
>>> camera.set_depth_quality("Full")  # Recommended for low latency
>>> camera.close()

set_depth_quality

set_depth_quality(quality: str) -> None

Set depth quality level.

Parameters:

Name	Type	Description	Default
quality	str	Depth quality setting. Common values: - "Full": Highest quality, recommended with binning - "Normal": Standard quality - "Low": Lower quality, faster processing	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> # Low latency configuration
>>> camera.set_binning(2, 2)
>>> camera.set_depth_quality("Full")
>>> camera.close()

set_pixel_format

set_pixel_format(format: str) -> None

Set pixel format for intensity component.

Parameters:

Name	Type	Description	Default
format	str	Pixel format ("RGB8", "Mono8", etc.)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If format not available or configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_pixel_format("Mono8")  # Force grayscale
>>> camera.close()

set_exposure_time

set_exposure_time(microseconds: float) -> None

Set exposure time in microseconds.

Parameters:

Name	Type	Description	Default
microseconds	float	Exposure time in microseconds (e.g., 5000 = 5ms)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_exposure_time(5000)  # 5ms exposure
>>> camera.close()

set_gain

set_gain(gain: float) -> None

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	float	Gain value (typically 0.0 to 24.0, camera-dependent)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_gain(2.0)
>>> camera.close()

get_exposure_time

get_exposure_time() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time in microseconds

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> exposure = camera.get_exposure_time()
>>> print(f"Exposure: {exposure}μs")
>>> camera.close()

get_gain

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> gain = camera.get_gain()
>>> print(f"Gain: {gain}")
>>> camera.close()

get_depth_quality

get_depth_quality() -> str

Get current depth quality setting.

Returns:

Type	Description
str	Current depth quality level (e.g., "Full", "Normal", "Low")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> quality = camera.get_depth_quality()
>>> print(f"Quality: {quality}")
>>> camera.close()

get_pixel_format

get_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format (e.g., "RGB8", "Mono8", "Coord3D_C16")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> format = camera.get_pixel_format()
>>> print(f"Format: {format}")
>>> camera.close()

get_binning

get_binning() -> tuple[int, int]

Get current binning settings.

Returns:

Type	Description
tuple[int, int]	Tuple of (horizontal_binning, vertical_binning)

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> h_bin, v_bin = camera.get_binning()
>>> print(f"Binning: {h_bin}x{v_bin}")
>>> camera.close()

get_illumination_mode

get_illumination_mode() -> str

Get current illumination mode.

Returns:

Type	Description
str	Current illumination mode ("AlwaysActive" or "AlternateActive")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> mode = camera.get_illumination_mode()
>>> print(f"Illumination: {mode}")
>>> camera.close()

get_depth_range

get_depth_range() -> tuple[float, float]

Get current depth measurement range in meters.

Returns:

Type	Description
tuple[float, float]	Tuple of (min_depth, max_depth) in meters

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> min_d, max_d = camera.get_depth_range()
>>> print(f"Range: {min_d}m - {max_d}m")
>>> camera.close()

enable_software_trigger

enable_software_trigger() -> None

Enable software triggering mode.

After enabling, use start_grabbing(), then execute_trigger() to capture frames on demand.

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.enable_software_trigger()
>>> camera.start_grabbing()  # Start grabbing first!
>>> for i in range(10):
...     camera.execute_trigger()
...     result = camera.capture()
>>> camera.close()

start_grabbing

start_grabbing() -> None

Start grabbing frames.

Must be called after enable_software_trigger() and before execute_trigger().

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> camera.enable_software_trigger()
>>> camera.start_grabbing()
>>> for i in range(10):
...     camera.execute_trigger()
...     result = camera.capture()
>>> camera.close()

execute_trigger

execute_trigger() -> None

Execute software trigger.

Triggers a frame capture when in software trigger mode. Note: start_grabbing() must be called first after enabling software trigger.

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If trigger execution fails

Examples:

>>> camera = StereoCamera()
>>> camera.enable_software_trigger()
>>> camera.start_grabbing()
>>> camera.execute_trigger()
>>> result = camera.capture()
>>> camera.close()

StereoGrabResult dataclass

StereoGrabResult(
    intensity: Optional[ndarray],
    disparity: Optional[ndarray],
    timestamp: float,
    frame_number: int,
    disparity_calibrated: Optional[ndarray] = None,
    has_intensity: bool = True,
    has_disparity: bool = True,
)

Result from stereo camera capture containing multi-component data.

Attributes:

Name	Type	Description
intensity	Optional[ndarray]	Intensity image - RGB8 (H, W, 3) or Mono8 (H, W)
disparity	Optional[ndarray]	Disparity map - uint16 (H, W)
timestamp	float	Capture timestamp in seconds
frame_number	int	Sequential frame number
disparity_calibrated	Optional[ndarray]	Calibrated disparity map - float32 (H, W), optional
has_intensity	bool	Flag indicating if intensity data is present
has_disparity	bool	Flag indicating if disparity data is present

intensity_shape property

intensity_shape: tuple

Get shape of intensity image.

disparity_shape property

disparity_shape: tuple

Get shape of disparity map.

is_color_intensity property

is_color_intensity: bool

Check if intensity is color (RGB) vs grayscale.

backends

Stereo camera backends.

BaslerStereoAceBackend

BaslerStereoAceBackend(
    serial_number: Optional[str] = None, op_timeout_s: float = 30.0
)

Bases: Mindtrace

Backend for Basler Stereo ace cameras using pypylon.

The Stereo ace camera is accessed through a unified device interface (DeviceClass: BaslerGTC/Basler/basler_xw) that presents the stereo pair as a single camera with multi-component output.

Initialize Basler Stereo ace backend.

Parameters:

Name	Type	Description	Default
serial_number	Optional[str]	Serial number or user-defined name of specific camera. If all digits, treated as serial number. Otherwise, treated as user-defined name. If None, opens first available Stereo ace camera.	None
op_timeout_s	float	Timeout in seconds for SDK operations (default 30s).	30.0

Raises:

Type	Description
SDKNotAvailableError	If pypylon is not available

name property

name: str

Get camera name.

is_open property

is_open: bool

Check if camera is open.

calibration property

calibration: Optional[StereoCalibrationData]

Get calibration data.

discover staticmethod

discover() -> List[str]

Discover available Stereo ace cameras.

Returns:

Type	Description
List[str]	List of serial numbers for available Stereo ace cameras

Raises:

Type	Description
SDKNotAvailableError	If pypylon is not available

discover_async async classmethod

discover_async() -> List[str]

Async wrapper for discover() - runs discovery in threadpool.

Use this instead of discover() when calling from async context to avoid blocking the event loop during camera discovery.

Returns:

Type	Description
List[str]	List of serial numbers for available Stereo ace cameras

discover_detailed staticmethod

discover_detailed() -> List[Dict[str, str]]

Discover Stereo ace cameras with detailed information.

Returns:

Type	Description
List[Dict[str, str]]	List of dictionaries containing camera information

Raises:

Type	Description
SDKNotAvailableError	If pypylon is not available

discover_detailed_async async classmethod

discover_detailed_async() -> List[Dict[str, str]]

Async wrapper for discover_detailed() - runs discovery in threadpool.

Returns:

Type	Description
List[Dict[str, str]]	List of dictionaries containing camera information

initialize async

initialize() -> bool

Initialize camera connection.

Returns:

Type	Description
bool	True if initialization successful, False otherwise

get_calibration async

get_calibration() -> StereoCalibrationData

Get factory calibration parameters from camera.

Returns:

Type	Description
StereoCalibrationData	StereoCalibrationData with factory calibration

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If calibration cannot be read

capture async

capture(
    timeout_ms: int = 20000,
    enable_intensity: bool = True,
    enable_disparity: bool = True,
    calibrate_disparity: bool = True,
) -> StereoGrabResult

Capture stereo data with multiple components.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Capture timeout in milliseconds	20000
enable_intensity	bool	Whether to capture intensity data	True
enable_disparity	bool	Whether to capture disparity data	True
calibrate_disparity	bool	Whether to apply calibration to disparity	True

Returns:

Type	Description
StereoGrabResult	StereoGrabResult containing captured data

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails

configure async

configure(**params) -> None

Configure camera parameters.

Parameters:

Name	Type	Description	Default
**params		Parameter name-value pairs to configure. Special parameters: - trigger_mode: "continuous" or "trigger" - depth_range: tuple of (min_depth, max_depth) - illumination_mode: "AlwaysActive" or "AlternateActive" - binning: tuple of (horizontal, vertical) - depth_quality: "Full", "High", "Normal", or "Low" - All other parameters passed directly to camera	{}

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If configuration fails

set_depth_range async

set_depth_range(min_depth: float, max_depth: float) -> None

Set depth measurement range.

Parameters:

Name	Type	Description	Default
min_depth	float	Minimum depth in meters (e.g., 0.3)	required
max_depth	float	Maximum depth in meters (e.g., 5.0)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

set_illumination_mode async

set_illumination_mode(mode: str) -> None

Set illumination mode.

Parameters:

Name	Type	Description	Default
mode	str	'AlwaysActive' (low latency) or 'AlternateActive' (clean intensity)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

set_binning async

set_binning(horizontal: int = 2, vertical: int = 2) -> None

Enable binning for latency reduction.

Parameters:

Name	Type	Description	Default
horizontal	int	Horizontal binning factor (typically 2)	2
vertical	int	Vertical binning factor (typically 2)	2

Note

When using binning for low latency, consider also setting depth quality to "Full" using set_depth_quality("Full").

Raises:

Type	Description
CameraConfigurationError	If configuration fails

set_depth_quality async

set_depth_quality(quality: str) -> None

Set depth quality level.

Parameters:

Name	Type	Description	Default
quality	str	Depth quality setting. Common values: - "Full": Highest quality, recommended with binning - "Normal": Standard quality - "Low": Lower quality, faster processing	required

Note

Setting quality to "Full" with binning reduces latency while maintaining depth quality. This is recommended for low-latency applications.

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Example

Low latency configuration

await camera.set_binning(2, 2) await camera.set_depth_quality("Full")

set_pixel_format async

set_pixel_format(format: str) -> None

Set pixel format for intensity component.

Parameters:

Name	Type	Description	Default
format	str	Pixel format ("RGB8", "Mono8", etc.)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If format not available or configuration fails

Example

await camera.set_pixel_format("Mono8") # Force grayscale

set_exposure_time async

set_exposure_time(microseconds: float) -> None

Set exposure time in microseconds.

Parameters:

Name	Type	Description	Default
microseconds	float	Exposure time in microseconds (e.g., 5000 = 5ms)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Example

await camera.set_exposure_time(5000) # 5ms exposure

set_gain async

set_gain(gain: float) -> None

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	float	Gain value (typically 0.0 to 24.0, camera-dependent)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Example

await camera.set_gain(2.0)

get_exposure_time async

get_exposure_time() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time in microseconds

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

exposure = await camera.get_exposure_time() print(f"Current exposure: {exposure}us")

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

gain = await camera.get_gain() print(f"Current gain: {gain}")

get_depth_quality async

get_depth_quality() -> str

Get current depth quality setting.

Returns:

Type	Description
str	Current depth quality level (e.g., "Full", "Normal", "Low")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

quality = await camera.get_depth_quality() print(f"Depth quality: {quality}")

get_pixel_format async

get_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format (e.g., "RGB8", "Mono8", "Coord3D_C16")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

format = await camera.get_pixel_format() print(f"Pixel format: {format}")

get_binning async

get_binning() -> tuple[int, int]

Get current binning settings.

Returns:

Type	Description
tuple[int, int]	Tuple of (horizontal_binning, vertical_binning)

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

h_bin, v_bin = await camera.get_binning() print(f"Binning: {h_bin}x{v_bin}")

get_illumination_mode async

get_illumination_mode() -> str

Get current illumination mode.

Returns:

Type	Description
str	Current illumination mode ("AlwaysActive" or "AlternateActive")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

mode = await camera.get_illumination_mode() print(f"Illumination: {mode}")

get_depth_range async

get_depth_range() -> tuple[float, float]

Get current depth measurement range in meters.

Returns:

Type	Description
tuple[float, float]	Tuple of (min_depth, max_depth) in meters

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

min_d, max_d = await camera.get_depth_range() print(f"Depth range: {min_d}m - {max_d}m")

set_trigger_mode async

set_trigger_mode(mode: str) -> None

Set trigger mode (simplified interface).

Parameters:

Name	Type	Description	Default
mode	str	Trigger mode ("continuous" or "trigger") - "continuous": Free-running continuous acquisition (TriggerMode=Off) - "trigger": Software-triggered acquisition (TriggerMode=On, TriggerSource=Software)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> await backend.set_trigger_mode("continuous")  # Free running
>>> await backend.set_trigger_mode("trigger")     # Software triggered

get_trigger_mode async

get_trigger_mode() -> str

Get current trigger mode (simplified interface).

Returns:

Type	Description
str	"continuous" if TriggerMode is Off, "trigger" if TriggerMode is On with Software source

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> mode = await backend.get_trigger_mode()
>>> print(f"Current mode: {mode}")

get_trigger_modes async

get_trigger_modes() -> List[str]

Get available trigger modes.

Returns:

Type	Description
List[str]	List of supported trigger modes: ["continuous", "trigger"]

Note

This provides a simplified interface. The underlying camera supports additional modes (SingleFrame, MultiFrame, hardware triggers) accessible via direct configure() calls if needed.

start_grabbing async

start_grabbing() -> None

Start grabbing frames.

This must be called before execute_trigger() in software trigger mode.

Raises:

Type	Description
CameraConnectionError	If camera not opened

execute_trigger async

execute_trigger() -> None

Execute software trigger.

Note: In software trigger mode, ensure start_grabbing() is called first, or call capture() once before the trigger loop to start grabbing.

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If trigger execution fails

close async

close() -> None

Close camera and release resources.

basler

Basler Stereo ace backend.

BaslerStereoAceBackend

BaslerStereoAceBackend(
    serial_number: Optional[str] = None, op_timeout_s: float = 30.0
)

Bases: Mindtrace

Backend for Basler Stereo ace cameras using pypylon.

The Stereo ace camera is accessed through a unified device interface (DeviceClass: BaslerGTC/Basler/basler_xw) that presents the stereo pair as a single camera with multi-component output.

Initialize Basler Stereo ace backend.

Parameters:

Name	Type	Description	Default
serial_number	Optional[str]	Serial number or user-defined name of specific camera. If all digits, treated as serial number. Otherwise, treated as user-defined name. If None, opens first available Stereo ace camera.	None
op_timeout_s	float	Timeout in seconds for SDK operations (default 30s).	30.0

Raises:

Type	Description
SDKNotAvailableError	If pypylon is not available

name property

name: str

Get camera name.

is_open property

is_open: bool

Check if camera is open.

calibration property

calibration: Optional[StereoCalibrationData]

Get calibration data.

discover staticmethod

discover() -> List[str]

Discover available Stereo ace cameras.

Returns:

Type	Description
List[str]	List of serial numbers for available Stereo ace cameras

Raises:

Type	Description
SDKNotAvailableError	If pypylon is not available

discover_async async classmethod

discover_async() -> List[str]

Async wrapper for discover() - runs discovery in threadpool.

Use this instead of discover() when calling from async context to avoid blocking the event loop during camera discovery.

Returns:

Type	Description
List[str]	List of serial numbers for available Stereo ace cameras

discover_detailed staticmethod

discover_detailed() -> List[Dict[str, str]]

Discover Stereo ace cameras with detailed information.

Returns:

Type	Description
List[Dict[str, str]]	List of dictionaries containing camera information

Raises:

Type	Description
SDKNotAvailableError	If pypylon is not available

discover_detailed_async async classmethod

discover_detailed_async() -> List[Dict[str, str]]

Async wrapper for discover_detailed() - runs discovery in threadpool.

Returns:

Type	Description
List[Dict[str, str]]	List of dictionaries containing camera information

initialize async

initialize() -> bool

Initialize camera connection.

Returns:

Type	Description
bool	True if initialization successful, False otherwise

get_calibration async

get_calibration() -> StereoCalibrationData

Get factory calibration parameters from camera.

Returns:

Type	Description
StereoCalibrationData	StereoCalibrationData with factory calibration

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If calibration cannot be read

capture async

capture(
    timeout_ms: int = 20000,
    enable_intensity: bool = True,
    enable_disparity: bool = True,
    calibrate_disparity: bool = True,
) -> StereoGrabResult

Capture stereo data with multiple components.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Capture timeout in milliseconds	20000
enable_intensity	bool	Whether to capture intensity data	True
enable_disparity	bool	Whether to capture disparity data	True
calibrate_disparity	bool	Whether to apply calibration to disparity	True

Returns:

Type	Description
StereoGrabResult	StereoGrabResult containing captured data

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails

configure async

configure(**params) -> None

Configure camera parameters.

Parameters:

Name	Type	Description	Default
**params		Parameter name-value pairs to configure. Special parameters: - trigger_mode: "continuous" or "trigger" - depth_range: tuple of (min_depth, max_depth) - illumination_mode: "AlwaysActive" or "AlternateActive" - binning: tuple of (horizontal, vertical) - depth_quality: "Full", "High", "Normal", or "Low" - All other parameters passed directly to camera	{}

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If configuration fails

set_depth_range async

set_depth_range(min_depth: float, max_depth: float) -> None

Set depth measurement range.

Parameters:

Name	Type	Description	Default
min_depth	float	Minimum depth in meters (e.g., 0.3)	required
max_depth	float	Maximum depth in meters (e.g., 5.0)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

set_illumination_mode async

set_illumination_mode(mode: str) -> None

Set illumination mode.

Parameters:

Name	Type	Description	Default
mode	str	'AlwaysActive' (low latency) or 'AlternateActive' (clean intensity)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

set_binning async

set_binning(horizontal: int = 2, vertical: int = 2) -> None

Enable binning for latency reduction.

Parameters:

Name	Type	Description	Default
horizontal	int	Horizontal binning factor (typically 2)	2
vertical	int	Vertical binning factor (typically 2)	2

Note

When using binning for low latency, consider also setting depth quality to "Full" using set_depth_quality("Full").

Raises:

Type	Description
CameraConfigurationError	If configuration fails

set_depth_quality async

set_depth_quality(quality: str) -> None

Set depth quality level.

Parameters:

Name	Type	Description	Default
quality	str	Depth quality setting. Common values: - "Full": Highest quality, recommended with binning - "Normal": Standard quality - "Low": Lower quality, faster processing	required

Note

Setting quality to "Full" with binning reduces latency while maintaining depth quality. This is recommended for low-latency applications.

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Example

Low latency configuration

await camera.set_binning(2, 2) await camera.set_depth_quality("Full")

set_pixel_format async

set_pixel_format(format: str) -> None

Set pixel format for intensity component.

Parameters:

Name	Type	Description	Default
format	str	Pixel format ("RGB8", "Mono8", etc.)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If format not available or configuration fails

Example

await camera.set_pixel_format("Mono8") # Force grayscale

set_exposure_time async

set_exposure_time(microseconds: float) -> None

Set exposure time in microseconds.

Parameters:

Name	Type	Description	Default
microseconds	float	Exposure time in microseconds (e.g., 5000 = 5ms)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Example

await camera.set_exposure_time(5000) # 5ms exposure

set_gain async

set_gain(gain: float) -> None

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	float	Gain value (typically 0.0 to 24.0, camera-dependent)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Example

await camera.set_gain(2.0)

get_exposure_time async

get_exposure_time() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time in microseconds

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

exposure = await camera.get_exposure_time() print(f"Current exposure: {exposure}us")

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

gain = await camera.get_gain() print(f"Current gain: {gain}")

get_depth_quality async

get_depth_quality() -> str

Get current depth quality setting.

Returns:

Type	Description
str	Current depth quality level (e.g., "Full", "Normal", "Low")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

quality = await camera.get_depth_quality() print(f"Depth quality: {quality}")

get_pixel_format async

get_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format (e.g., "RGB8", "Mono8", "Coord3D_C16")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

format = await camera.get_pixel_format() print(f"Pixel format: {format}")

get_binning async

get_binning() -> tuple[int, int]

Get current binning settings.

Returns:

Type	Description
tuple[int, int]	Tuple of (horizontal_binning, vertical_binning)

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

h_bin, v_bin = await camera.get_binning() print(f"Binning: {h_bin}x{v_bin}")

get_illumination_mode async

get_illumination_mode() -> str

Get current illumination mode.

Returns:

Type	Description
str	Current illumination mode ("AlwaysActive" or "AlternateActive")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

mode = await camera.get_illumination_mode() print(f"Illumination: {mode}")

get_depth_range async

get_depth_range() -> tuple[float, float]

Get current depth measurement range in meters.

Returns:

Type	Description
tuple[float, float]	Tuple of (min_depth, max_depth) in meters

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

min_d, max_d = await camera.get_depth_range() print(f"Depth range: {min_d}m - {max_d}m")

set_trigger_mode async

set_trigger_mode(mode: str) -> None

Set trigger mode (simplified interface).

Parameters:

Name	Type	Description	Default
mode	str	Trigger mode ("continuous" or "trigger") - "continuous": Free-running continuous acquisition (TriggerMode=Off) - "trigger": Software-triggered acquisition (TriggerMode=On, TriggerSource=Software)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> await backend.set_trigger_mode("continuous")  # Free running
>>> await backend.set_trigger_mode("trigger")     # Software triggered

get_trigger_mode async

get_trigger_mode() -> str

Get current trigger mode (simplified interface).

Returns:

Type	Description
str	"continuous" if TriggerMode is Off, "trigger" if TriggerMode is On with Software source

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> mode = await backend.get_trigger_mode()
>>> print(f"Current mode: {mode}")

get_trigger_modes async

get_trigger_modes() -> List[str]

Get available trigger modes.

Returns:

Type	Description
List[str]	List of supported trigger modes: ["continuous", "trigger"]

Note

This provides a simplified interface. The underlying camera supports additional modes (SingleFrame, MultiFrame, hardware triggers) accessible via direct configure() calls if needed.

start_grabbing async

start_grabbing() -> None

Start grabbing frames.

This must be called before execute_trigger() in software trigger mode.

Raises:

Type	Description
CameraConnectionError	If camera not opened

execute_trigger async

execute_trigger() -> None

Execute software trigger.

Note: In software trigger mode, ensure start_grabbing() is called first, or call capture() once before the trigger loop to start grabbing.

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If trigger execution fails

close async

close() -> None

Close camera and release resources.

basler_stereo_ace

Basler Stereo ace camera backend using pypylon.

This backend provides access to Basler Stereo ace cameras which combine two ace2 Pro cameras with a pattern projector into a unified stereo vision system.

BaslerStereoAceBackend

BaslerStereoAceBackend(
    serial_number: Optional[str] = None, op_timeout_s: float = 30.0
)

Bases: Mindtrace

Backend for Basler Stereo ace cameras using pypylon.

The Stereo ace camera is accessed through a unified device interface (DeviceClass: BaslerGTC/Basler/basler_xw) that presents the stereo pair as a single camera with multi-component output.

Initialize Basler Stereo ace backend.

Parameters:

Name	Type	Description	Default
serial_number	Optional[str]	Serial number or user-defined name of specific camera. If all digits, treated as serial number. Otherwise, treated as user-defined name. If None, opens first available Stereo ace camera.	None
op_timeout_s	float	Timeout in seconds for SDK operations (default 30s).	30.0

Raises:

Type	Description
SDKNotAvailableError	If pypylon is not available

name property

name: str

Get camera name.

is_open property

is_open: bool

Check if camera is open.

calibration property

calibration: Optional[StereoCalibrationData]

Get calibration data.

discover staticmethod

discover() -> List[str]

Discover available Stereo ace cameras.

Returns:

Type	Description
List[str]	List of serial numbers for available Stereo ace cameras

Raises:

Type	Description
SDKNotAvailableError	If pypylon is not available

discover_async async classmethod

discover_async() -> List[str]

Async wrapper for discover() - runs discovery in threadpool.

Use this instead of discover() when calling from async context to avoid blocking the event loop during camera discovery.

Returns:

Type	Description
List[str]	List of serial numbers for available Stereo ace cameras

discover_detailed staticmethod

discover_detailed() -> List[Dict[str, str]]

Discover Stereo ace cameras with detailed information.

Returns:

Type	Description
List[Dict[str, str]]	List of dictionaries containing camera information

Raises:

Type	Description
SDKNotAvailableError	If pypylon is not available

discover_detailed_async async classmethod

discover_detailed_async() -> List[Dict[str, str]]

Async wrapper for discover_detailed() - runs discovery in threadpool.

Returns:

Type	Description
List[Dict[str, str]]	List of dictionaries containing camera information

initialize async

initialize() -> bool

Initialize camera connection.

Returns:

Type	Description
bool	True if initialization successful, False otherwise

get_calibration async

get_calibration() -> StereoCalibrationData

Get factory calibration parameters from camera.

Returns:

Type	Description
StereoCalibrationData	StereoCalibrationData with factory calibration

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If calibration cannot be read

capture async

capture(
    timeout_ms: int = 20000,
    enable_intensity: bool = True,
    enable_disparity: bool = True,
    calibrate_disparity: bool = True,
) -> StereoGrabResult

Capture stereo data with multiple components.

Parameters:

Name	Type	Description	Default
timeout_ms	int	Capture timeout in milliseconds	20000
enable_intensity	bool	Whether to capture intensity data	True
enable_disparity	bool	Whether to capture disparity data	True
calibrate_disparity	bool	Whether to apply calibration to disparity	True

Returns:

Type	Description
StereoGrabResult	StereoGrabResult containing captured data

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails

configure async

configure(**params) -> None

Configure camera parameters.

Parameters:

Name	Type	Description	Default
**params		Parameter name-value pairs to configure. Special parameters: - trigger_mode: "continuous" or "trigger" - depth_range: tuple of (min_depth, max_depth) - illumination_mode: "AlwaysActive" or "AlternateActive" - binning: tuple of (horizontal, vertical) - depth_quality: "Full", "High", "Normal", or "Low" - All other parameters passed directly to camera	{}

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If configuration fails

set_depth_range async

set_depth_range(min_depth: float, max_depth: float) -> None

Set depth measurement range.

Parameters:

Name	Type	Description	Default
min_depth	float	Minimum depth in meters (e.g., 0.3)	required
max_depth	float	Maximum depth in meters (e.g., 5.0)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

set_illumination_mode async

set_illumination_mode(mode: str) -> None

Set illumination mode.

Parameters:

Name	Type	Description	Default
mode	str	'AlwaysActive' (low latency) or 'AlternateActive' (clean intensity)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

set_binning async

set_binning(horizontal: int = 2, vertical: int = 2) -> None

Enable binning for latency reduction.

Parameters:

Name	Type	Description	Default
horizontal	int	Horizontal binning factor (typically 2)	2
vertical	int	Vertical binning factor (typically 2)	2

Note

When using binning for low latency, consider also setting depth quality to "Full" using set_depth_quality("Full").

Raises:

Type	Description
CameraConfigurationError	If configuration fails

set_depth_quality async

set_depth_quality(quality: str) -> None

Set depth quality level.

Parameters:

Name	Type	Description	Default
quality	str	Depth quality setting. Common values: - "Full": Highest quality, recommended with binning - "Normal": Standard quality - "Low": Lower quality, faster processing	required

Note

Setting quality to "Full" with binning reduces latency while maintaining depth quality. This is recommended for low-latency applications.

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Example

Low latency configuration

await camera.set_binning(2, 2) await camera.set_depth_quality("Full")

set_pixel_format async

set_pixel_format(format: str) -> None

Set pixel format for intensity component.

Parameters:

Name	Type	Description	Default
format	str	Pixel format ("RGB8", "Mono8", etc.)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If format not available or configuration fails

Example

await camera.set_pixel_format("Mono8") # Force grayscale

set_exposure_time async

set_exposure_time(microseconds: float) -> None

Set exposure time in microseconds.

Parameters:

Name	Type	Description	Default
microseconds	float	Exposure time in microseconds (e.g., 5000 = 5ms)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Example

await camera.set_exposure_time(5000) # 5ms exposure

set_gain async

set_gain(gain: float) -> None

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	float	Gain value (typically 0.0 to 24.0, camera-dependent)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Example

await camera.set_gain(2.0)

get_exposure_time async

get_exposure_time() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time in microseconds

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

exposure = await camera.get_exposure_time() print(f"Current exposure: {exposure}us")

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

gain = await camera.get_gain() print(f"Current gain: {gain}")

get_depth_quality async

get_depth_quality() -> str

Get current depth quality setting.

Returns:

Type	Description
str	Current depth quality level (e.g., "Full", "Normal", "Low")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

quality = await camera.get_depth_quality() print(f"Depth quality: {quality}")

get_pixel_format async

get_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format (e.g., "RGB8", "Mono8", "Coord3D_C16")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

format = await camera.get_pixel_format() print(f"Pixel format: {format}")

get_binning async

get_binning() -> tuple[int, int]

Get current binning settings.

Returns:

Type	Description
tuple[int, int]	Tuple of (horizontal_binning, vertical_binning)

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

h_bin, v_bin = await camera.get_binning() print(f"Binning: {h_bin}x{v_bin}")

get_illumination_mode async

get_illumination_mode() -> str

Get current illumination mode.

Returns:

Type	Description
str	Current illumination mode ("AlwaysActive" or "AlternateActive")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

mode = await camera.get_illumination_mode() print(f"Illumination: {mode}")

get_depth_range async

get_depth_range() -> tuple[float, float]

Get current depth measurement range in meters.

Returns:

Type	Description
tuple[float, float]	Tuple of (min_depth, max_depth) in meters

Raises:

Type	Description
CameraConnectionError	If camera not opened

Example

min_d, max_d = await camera.get_depth_range() print(f"Depth range: {min_d}m - {max_d}m")

set_trigger_mode async

set_trigger_mode(mode: str) -> None

Set trigger mode (simplified interface).

Parameters:

Name	Type	Description	Default
mode	str	Trigger mode ("continuous" or "trigger") - "continuous": Free-running continuous acquisition (TriggerMode=Off) - "trigger": Software-triggered acquisition (TriggerMode=On, TriggerSource=Software)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> await backend.set_trigger_mode("continuous")  # Free running
>>> await backend.set_trigger_mode("trigger")     # Software triggered

get_trigger_mode async

get_trigger_mode() -> str

Get current trigger mode (simplified interface).

Returns:

Type	Description
str	"continuous" if TriggerMode is Off, "trigger" if TriggerMode is On with Software source

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> mode = await backend.get_trigger_mode()
>>> print(f"Current mode: {mode}")

get_trigger_modes async

get_trigger_modes() -> List[str]

Get available trigger modes.

Returns:

Type	Description
List[str]	List of supported trigger modes: ["continuous", "trigger"]

Note

This provides a simplified interface. The underlying camera supports additional modes (SingleFrame, MultiFrame, hardware triggers) accessible via direct configure() calls if needed.

start_grabbing async

start_grabbing() -> None

Start grabbing frames.

This must be called before execute_trigger() in software trigger mode.

Raises:

Type	Description
CameraConnectionError	If camera not opened

execute_trigger async

execute_trigger() -> None

Execute software trigger.

Note: In software trigger mode, ensure start_grabbing() is called first, or call capture() once before the trigger loop to start grabbing.

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If trigger execution fails

close async

close() -> None

Close camera and release resources.

core

Core stereo camera interfaces and data models.

AsyncStereoCamera

AsyncStereoCamera(backend)

Bases: Mindtrace

Async stereo camera interface.

Provides high-level stereo camera operations including multi-component capture and 3D point cloud generation.

Initialize async stereo camera.

Parameters:

Name	Type	Description	Default
backend		Backend instance (e.g., BaslerStereoAceBackend)	required

name property

name: str

Get camera name.

calibration property

calibration: Optional[StereoCalibrationData]

Get calibration data.

is_open property

is_open: bool

Check if camera is open.

open async classmethod

open(name: Optional[str] = None) -> 'AsyncStereoCamera'

Open and initialize a stereo camera.

Parameters:

Name	Type	Description	Default
name	Optional[str]	Camera identifier. Format: "BaslerStereoAce:serial_number" If None, opens first available Stereo ace camera.	None

Returns:

Type	Description
'AsyncStereoCamera'	Initialized AsyncStereoCamera instance

Raises:

Type	Description
CameraNotFoundError	If camera not found
CameraConnectionError	If connection fails

Examples:

>>> camera = await AsyncStereoCamera.open()
>>> camera = await AsyncStereoCamera.open("BaslerStereoAce:40644640")

initialize async

initialize() -> bool

Initialize camera and load calibration.

Returns:

Type	Description
bool	True if initialization successful

Note

Usually not needed as open() handles initialization

close async

close() -> None

Close camera and release resources.

capture async

capture(
    enable_intensity: bool = True,
    enable_disparity: bool = True,
    calibrate_disparity: bool = True,
    timeout_ms: int = 20000,
) -> StereoGrabResult

Capture multi-component stereo data.

Parameters:

Name	Type	Description	Default
enable_intensity	bool	Whether to capture intensity image	True
enable_disparity	bool	Whether to capture disparity map	True
calibrate_disparity	bool	Whether to apply calibration to disparity	True
timeout_ms	int	Capture timeout in milliseconds	20000

Returns:

Type	Description
StereoGrabResult	StereoGrabResult containing captured data

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails

Examples:

>>> result = await camera.capture()
>>> print(f"Intensity: {result.intensity.shape}")
>>> print(f"Disparity: {result.disparity.shape}")

capture_point_cloud async

capture_point_cloud(
    include_colors: bool = True,
    remove_outliers: bool = False,
    downsample_factor: int = 1,
) -> PointCloudData

Capture and generate 3D point cloud.

Parameters:

Name	Type	Description	Default
include_colors	bool	Whether to include color information from intensity	True
remove_outliers	bool	Whether to remove statistical outliers	False
downsample_factor	int	Downsampling factor (1 = no downsampling)	1

Returns:

Type	Description
PointCloudData	PointCloudData with 3D points and optional colors

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails
CameraConfigurationError	If calibration not available

Examples:

>>> point_cloud = await camera.capture_point_cloud()
>>> point_cloud.save_ply("output.ply")
>>> pcd = point_cloud.to_open3d()

configure async

configure(**params) -> None

Configure camera parameters.

Parameters:

Name	Type	Description	Default
**params		Parameter name-value pairs	{}

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.configure(ExposureTime=15000, Gain=2.0)

set_depth_range async

set_depth_range(min_depth: float, max_depth: float) -> None

Set depth measurement range in meters.

Parameters:

Name	Type	Description	Default
min_depth	float	Minimum depth (e.g., 0.3 meters)	required
max_depth	float	Maximum depth (e.g., 5.0 meters)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.set_depth_range(0.5, 3.0)

set_illumination_mode async

set_illumination_mode(mode: str) -> None

Set illumination mode.

Parameters:

Name	Type	Description	Default
mode	str	'AlwaysActive' (low latency) or 'AlternateActive' (clean intensity)	required

Raises:

Type	Description
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> await camera.set_illumination_mode("AlternateActive")

set_binning async

set_binning(horizontal: int = 2, vertical: int = 2) -> None

Enable binning for latency reduction.

Binning reduces network transfer and computation.

Parameters:

Name	Type	Description	Default
horizontal	int	Horizontal binning factor (typically 2)	2
vertical	int	Vertical binning factor (typically 2)	2

Note

When using binning for low latency, consider also setting depth quality to "Full" using set_depth_quality("Full").

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.set_binning(2, 2)
>>> await camera.set_depth_quality("Full")  # Recommended for low latency

set_depth_quality async

set_depth_quality(quality: str) -> None

Set depth quality level.

Parameters:

Name	Type	Description	Default
quality	str	Depth quality setting. Common values: - "Full": Highest quality, recommended with binning - "Normal": Standard quality - "Low": Lower quality, faster processing	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> # Low latency configuration
>>> await camera.set_binning(2, 2)
>>> await camera.set_depth_quality("Full")

set_pixel_format async

set_pixel_format(format: str) -> None

Set pixel format for intensity component.

Parameters:

Name	Type	Description	Default
format	str	Pixel format ("RGB8", "Mono8", etc.)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If format not available or configuration fails

Examples:

>>> await camera.set_pixel_format("Mono8")  # Force grayscale

set_exposure_time async

set_exposure_time(microseconds: float) -> None

Set exposure time in microseconds.

Parameters:

Name	Type	Description	Default
microseconds	float	Exposure time in microseconds (e.g., 5000 = 5ms)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.set_exposure_time(5000)  # 5ms exposure

set_gain async

set_gain(gain: float) -> None

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	float	Gain value (typically 0.0 to 24.0, camera-dependent)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.set_gain(2.0)

get_exposure_time async

get_exposure_time() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time in microseconds

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> exposure = await camera.get_exposure_time()
>>> print(f"Exposure: {exposure}μs")

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> gain = await camera.get_gain()
>>> print(f"Gain: {gain}")

get_depth_quality async

get_depth_quality() -> str

Get current depth quality setting.

Returns:

Type	Description
str	Current depth quality level (e.g., "Full", "Normal", "Low")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> quality = await camera.get_depth_quality()
>>> print(f"Quality: {quality}")

get_pixel_format async

get_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format (e.g., "RGB8", "Mono8", "Coord3D_C16")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> format = await camera.get_pixel_format()
>>> print(f"Format: {format}")

get_binning async

get_binning() -> tuple[int, int]

Get current binning settings.

Returns:

Type	Description
tuple[int, int]	Tuple of (horizontal_binning, vertical_binning)

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> h_bin, v_bin = await camera.get_binning()
>>> print(f"Binning: {h_bin}x{v_bin}")

get_illumination_mode async

get_illumination_mode() -> str

Get current illumination mode.

Returns:

Type	Description
str	Current illumination mode ("AlwaysActive" or "AlternateActive")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> mode = await camera.get_illumination_mode()
>>> print(f"Illumination: {mode}")

get_depth_range async

get_depth_range() -> tuple[float, float]

Get current depth measurement range in meters.

Returns:

Type	Description
tuple[float, float]	Tuple of (min_depth, max_depth) in meters

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> min_d, max_d = await camera.get_depth_range()
>>> print(f"Range: {min_d}m - {max_d}m")

set_trigger_mode async

set_trigger_mode(mode: str) -> None

Set trigger mode (simplified interface).

Parameters:

Name	Type	Description	Default
mode	str	Trigger mode ("continuous" or "trigger") - "continuous": Free-running continuous acquisition - "trigger": Software-triggered acquisition	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> await camera.set_trigger_mode("continuous")  # Free running
>>> await camera.set_trigger_mode("trigger")     # Software triggered

get_trigger_mode async

get_trigger_mode() -> str

Get current trigger mode (simplified interface).

Returns:

Type	Description
str	"continuous" or "trigger"

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> mode = await camera.get_trigger_mode()
>>> print(f"Current mode: {mode}")

get_trigger_modes async

get_trigger_modes() -> list[str]

Get available trigger modes.

Returns:

Type	Description
list[str]	List of supported trigger modes: ["continuous", "trigger"]

Examples:

>>> modes = await camera.get_trigger_modes()
>>> print(f"Available modes: {modes}")

start_grabbing async

start_grabbing() -> None

Start grabbing frames.

Must be called after enable_software_trigger() and before execute_trigger().

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> await camera.enable_software_trigger()
>>> await camera.start_grabbing()
>>> for i in range(10):
...     await camera.execute_trigger()
...     result = await camera.capture()

execute_trigger async

execute_trigger() -> None

Execute software trigger.

Triggers a frame capture when in software trigger mode. Note: start_grabbing() must be called first after enabling software trigger.

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If trigger execution fails

Examples:

>>> await camera.enable_software_trigger()
>>> await camera.start_grabbing()
>>> for i in range(10):
...     await camera.execute_trigger()
...     result = await camera.capture()

PointCloudData dataclass

PointCloudData(
    points: ndarray,
    colors: Optional[ndarray] = None,
    num_points: int = 0,
    has_colors: bool = False,
)

3D point cloud data with optional color information.

Attributes:

Name	Type	Description
points	ndarray	Array of 3D points (N, 3) - (x, y, z) in meters
colors	Optional[ndarray]	Optional array of RGB colors (N, 3) - values in [0, 1]
num_points	int	Number of valid points
has_colors	bool	Flag indicating if color information is present

save_ply

save_ply(path: str, binary: bool = True) -> None

Save point cloud as PLY file.

Parameters:

Name	Type	Description	Default
path	str	Output file path	required
binary	bool	If True, save in binary format; otherwise ASCII	True

Raises:

Type	Description
ImportError	If plyfile is not installed

to_open3d

to_open3d()

Convert to Open3D PointCloud object.

Returns:

Type	Description
	open3d.geometry.PointCloud instance

Raises:

Type	Description
ImportError	If open3d is not installed

downsample

downsample(factor: int) -> 'PointCloudData'

Downsample point cloud by given factor.

Parameters:

Name	Type	Description	Default
factor	int	Downsampling factor (e.g., 2 = keep every 2nd point)	required

Returns:

Type	Description
'PointCloudData'	New PointCloudData with downsampled points

remove_statistical_outliers

remove_statistical_outliers(
    nb_neighbors: int = 20, std_ratio: float = 2.0
) -> "PointCloudData"

Remove statistical outliers from point cloud.

Parameters:

Name	Type	Description	Default
nb_neighbors	int	Number of neighbors to consider	20
std_ratio	float	Standard deviation ratio threshold	2.0

Returns:

Type	Description
'PointCloudData'	New PointCloudData with outliers removed

Raises:

Type	Description
ImportError	If open3d is not installed

StereoCalibrationData dataclass

StereoCalibrationData(
    baseline: float,
    focal_length: float,
    principal_point_u: float,
    principal_point_v: float,
    scale3d: float,
    offset3d: float,
    Q: ndarray,
)

Factory calibration parameters for stereo camera.

These parameters are provided by the camera manufacturer and used for 3D reconstruction from disparity maps.

Attributes:

Name	Type	Description
baseline	float	Stereo baseline in meters (distance between camera pair)
focal_length	float	Focal length in pixels
principal_point_u	float	Principal point U coordinate in pixels
principal_point_v	float	Principal point V coordinate in pixels
scale3d	float	Scale factor for disparity conversion
offset3d	float	Offset for disparity conversion
Q	ndarray	4x4 reprojection matrix for point cloud generation

from_camera_params classmethod

from_camera_params(params: dict) -> 'StereoCalibrationData'

Create calibration data from camera parameter dictionary.

Parameters:

Name	Type	Description	Default
params	dict	Dictionary containing calibration parameters: - Scan3dBaseline: Baseline in meters - Scan3dFocalLength: Focal length in pixels - Scan3dPrincipalPointU: Principal point U in pixels - Scan3dPrincipalPointV: Principal point V in pixels - Scan3dCoordinateScale: Scale factor - Scan3dCoordinateOffset: Offset	required

Returns:

Type	Description
'StereoCalibrationData'	StereoCalibrationData instance

calibrate_disparity

calibrate_disparity(disparity: ndarray) -> np.ndarray

Apply calibration to raw disparity map.

Parameters:

Name	Type	Description	Default
disparity	ndarray	Raw disparity map (uint16)	required

Returns:

Type	Description
ndarray	Calibrated disparity map (float32)

StereoGrabResult dataclass

StereoGrabResult(
    intensity: Optional[ndarray],
    disparity: Optional[ndarray],
    timestamp: float,
    frame_number: int,
    disparity_calibrated: Optional[ndarray] = None,
    has_intensity: bool = True,
    has_disparity: bool = True,
)

Result from stereo camera capture containing multi-component data.

Attributes:

Name	Type	Description
intensity	Optional[ndarray]	Intensity image - RGB8 (H, W, 3) or Mono8 (H, W)
disparity	Optional[ndarray]	Disparity map - uint16 (H, W)
timestamp	float	Capture timestamp in seconds
frame_number	int	Sequential frame number
disparity_calibrated	Optional[ndarray]	Calibrated disparity map - float32 (H, W), optional
has_intensity	bool	Flag indicating if intensity data is present
has_disparity	bool	Flag indicating if disparity data is present

intensity_shape property

intensity_shape: tuple

Get shape of intensity image.

disparity_shape property

disparity_shape: tuple

Get shape of disparity map.

is_color_intensity property

is_color_intensity: bool

Check if intensity is color (RGB) vs grayscale.

StereoCamera

StereoCamera(
    async_camera: Optional[AsyncStereoCamera] = None,
    loop: Optional[AbstractEventLoop] = None,
    name: Optional[str] = None,
    **kwargs
)

Bases: Mindtrace

Synchronous wrapper around AsyncStereoCamera.

All operations are executed on a background event loop. This provides a simple synchronous API for stereo camera operations.

Create a synchronous stereo camera wrapper.

Parameters:

Name	Type	Description	Default
async_camera	Optional[AsyncStereoCamera]	Existing AsyncStereoCamera instance	None
loop	Optional[AbstractEventLoop]	Event loop to use for async operations	None
name	Optional[str]	Camera identifier. Format: "BaslerStereoAce:serial_number" If None, opens first available Stereo ace camera.	None
**kwargs		Additional arguments passed to Mindtrace	{}

Examples:

>>> # Simple usage - opens first available
>>> camera = StereoCamera()

>>> # Open specific camera
>>> camera = StereoCamera(name="BaslerStereoAce:40644640")

>>> # Use existing async camera
>>> async_cam = await AsyncStereoCamera.open()
>>> sync_cam = StereoCamera(async_camera=async_cam, loop=loop)

name property

name: str

Get camera name.

Returns:

Type	Description
str	Camera name in format "Backend:serial_number"

calibration property

calibration: Optional[StereoCalibrationData]

Get calibration data.

Returns:

Type	Description
Optional[StereoCalibrationData]	StereoCalibrationData if available, None otherwise

is_open property

is_open: bool

Check if camera is open.

Returns:

Type	Description
bool	True if camera is open, False otherwise

close

close() -> None

Close camera and release resources.

Examples:

>>> camera = StereoCamera()
>>> # ... use camera ...
>>> camera.close()

capture

capture(
    enable_intensity: bool = True,
    enable_disparity: bool = True,
    calibrate_disparity: bool = True,
    timeout_ms: int = 20000,
) -> StereoGrabResult

Capture multi-component stereo data.

Parameters:

Name	Type	Description	Default
enable_intensity	bool	Whether to capture intensity image	True
enable_disparity	bool	Whether to capture disparity map	True
calibrate_disparity	bool	Whether to apply calibration to disparity	True
timeout_ms	int	Capture timeout in milliseconds	20000

Returns:

Type	Description
StereoGrabResult	StereoGrabResult containing captured data

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails

Examples:

>>> camera = StereoCamera()
>>> result = camera.capture()
>>> print(f"Intensity: {result.intensity.shape}")
>>> print(f"Disparity: {result.disparity.shape}")
>>> camera.close()

capture_point_cloud

capture_point_cloud(
    include_colors: bool = True,
    remove_outliers: bool = False,
    downsample_factor: int = 1,
) -> PointCloudData

Capture and generate 3D point cloud.

Parameters:

Name	Type	Description	Default
include_colors	bool	Whether to include color information from intensity	True
remove_outliers	bool	Whether to remove statistical outliers	False
downsample_factor	int	Downsampling factor (1 = no downsampling)	1

Returns:

Type	Description
PointCloudData	PointCloudData with 3D points and optional colors

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails
CameraConfigurationError	If calibration not available

Examples:

>>> camera = StereoCamera()
>>> point_cloud = camera.capture_point_cloud()
>>> print(f"Points: {point_cloud.num_points}")
>>> point_cloud.save_ply("output.ply")
>>> camera.close()

configure

configure(**params) -> None

Configure camera parameters.

Parameters:

Name	Type	Description	Default
**params		Parameter name-value pairs	{}

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.configure(ExposureTime=15000, Gain=2.0)
>>> camera.close()

set_depth_range

set_depth_range(min_depth: float, max_depth: float) -> None

Set depth measurement range in meters.

Parameters:

Name	Type	Description	Default
min_depth	float	Minimum depth (e.g., 0.3 meters)	required
max_depth	float	Maximum depth (e.g., 5.0 meters)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_depth_range(0.5, 3.0)
>>> camera.close()

set_illumination_mode

set_illumination_mode(mode: str) -> None

Set illumination mode.

Parameters:

Name	Type	Description	Default
mode	str	'AlwaysActive' (low latency) or 'AlternateActive' (clean intensity)	required

Raises:

Type	Description
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_illumination_mode("AlternateActive")
>>> camera.close()

set_binning

set_binning(horizontal: int = 2, vertical: int = 2) -> None

Enable binning for latency reduction.

Binning reduces network transfer and computation.

Parameters:

Name	Type	Description	Default
horizontal	int	Horizontal binning factor (typically 2)	2
vertical	int	Vertical binning factor (typically 2)	2

Note

When using binning for low latency, consider also setting depth quality to "Full" using set_depth_quality("Full").

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_binning(2, 2)
>>> camera.set_depth_quality("Full")  # Recommended for low latency
>>> camera.close()

set_depth_quality

set_depth_quality(quality: str) -> None

Set depth quality level.

Parameters:

Name	Type	Description	Default
quality	str	Depth quality setting. Common values: - "Full": Highest quality, recommended with binning - "Normal": Standard quality - "Low": Lower quality, faster processing	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> # Low latency configuration
>>> camera.set_binning(2, 2)
>>> camera.set_depth_quality("Full")
>>> camera.close()

set_pixel_format

set_pixel_format(format: str) -> None

Set pixel format for intensity component.

Parameters:

Name	Type	Description	Default
format	str	Pixel format ("RGB8", "Mono8", etc.)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If format not available or configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_pixel_format("Mono8")  # Force grayscale
>>> camera.close()

set_exposure_time

set_exposure_time(microseconds: float) -> None

Set exposure time in microseconds.

Parameters:

Name	Type	Description	Default
microseconds	float	Exposure time in microseconds (e.g., 5000 = 5ms)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_exposure_time(5000)  # 5ms exposure
>>> camera.close()

set_gain

set_gain(gain: float) -> None

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	float	Gain value (typically 0.0 to 24.0, camera-dependent)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_gain(2.0)
>>> camera.close()

get_exposure_time

get_exposure_time() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time in microseconds

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> exposure = camera.get_exposure_time()
>>> print(f"Exposure: {exposure}μs")
>>> camera.close()

get_gain

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> gain = camera.get_gain()
>>> print(f"Gain: {gain}")
>>> camera.close()

get_depth_quality

get_depth_quality() -> str

Get current depth quality setting.

Returns:

Type	Description
str	Current depth quality level (e.g., "Full", "Normal", "Low")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> quality = camera.get_depth_quality()
>>> print(f"Quality: {quality}")
>>> camera.close()

get_pixel_format

get_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format (e.g., "RGB8", "Mono8", "Coord3D_C16")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> format = camera.get_pixel_format()
>>> print(f"Format: {format}")
>>> camera.close()

get_binning

get_binning() -> tuple[int, int]

Get current binning settings.

Returns:

Type	Description
tuple[int, int]	Tuple of (horizontal_binning, vertical_binning)

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> h_bin, v_bin = camera.get_binning()
>>> print(f"Binning: {h_bin}x{v_bin}")
>>> camera.close()

get_illumination_mode

get_illumination_mode() -> str

Get current illumination mode.

Returns:

Type	Description
str	Current illumination mode ("AlwaysActive" or "AlternateActive")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> mode = camera.get_illumination_mode()
>>> print(f"Illumination: {mode}")
>>> camera.close()

get_depth_range

get_depth_range() -> tuple[float, float]

Get current depth measurement range in meters.

Returns:

Type	Description
tuple[float, float]	Tuple of (min_depth, max_depth) in meters

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> min_d, max_d = camera.get_depth_range()
>>> print(f"Range: {min_d}m - {max_d}m")
>>> camera.close()

enable_software_trigger

enable_software_trigger() -> None

Enable software triggering mode.

After enabling, use start_grabbing(), then execute_trigger() to capture frames on demand.

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.enable_software_trigger()
>>> camera.start_grabbing()  # Start grabbing first!
>>> for i in range(10):
...     camera.execute_trigger()
...     result = camera.capture()
>>> camera.close()

start_grabbing

start_grabbing() -> None

Start grabbing frames.

Must be called after enable_software_trigger() and before execute_trigger().

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> camera.enable_software_trigger()
>>> camera.start_grabbing()
>>> for i in range(10):
...     camera.execute_trigger()
...     result = camera.capture()
>>> camera.close()

execute_trigger

execute_trigger() -> None

Execute software trigger.

Triggers a frame capture when in software trigger mode. Note: start_grabbing() must be called first after enabling software trigger.

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If trigger execution fails

Examples:

>>> camera = StereoCamera()
>>> camera.enable_software_trigger()
>>> camera.start_grabbing()
>>> camera.execute_trigger()
>>> result = camera.capture()
>>> camera.close()

async_stereo_camera

Async stereo camera interface providing high-level stereo capture operations.

AsyncStereoCamera

AsyncStereoCamera(backend)

Bases: Mindtrace

Async stereo camera interface.

Provides high-level stereo camera operations including multi-component capture and 3D point cloud generation.

Initialize async stereo camera.

Parameters:

Name	Type	Description	Default
backend		Backend instance (e.g., BaslerStereoAceBackend)	required

name property

name: str

Get camera name.

calibration property

calibration: Optional[StereoCalibrationData]

Get calibration data.

is_open property

is_open: bool

Check if camera is open.

open async classmethod

open(name: Optional[str] = None) -> 'AsyncStereoCamera'

Open and initialize a stereo camera.

Parameters:

Name	Type	Description	Default
name	Optional[str]	Camera identifier. Format: "BaslerStereoAce:serial_number" If None, opens first available Stereo ace camera.	None

Returns:

Type	Description
'AsyncStereoCamera'	Initialized AsyncStereoCamera instance

Raises:

Type	Description
CameraNotFoundError	If camera not found
CameraConnectionError	If connection fails

Examples:

>>> camera = await AsyncStereoCamera.open()
>>> camera = await AsyncStereoCamera.open("BaslerStereoAce:40644640")

initialize async

initialize() -> bool

Initialize camera and load calibration.

Returns:

Type	Description
bool	True if initialization successful

Note

Usually not needed as open() handles initialization

close async

close() -> None

Close camera and release resources.

capture async

capture(
    enable_intensity: bool = True,
    enable_disparity: bool = True,
    calibrate_disparity: bool = True,
    timeout_ms: int = 20000,
) -> StereoGrabResult

Capture multi-component stereo data.

Parameters:

Name	Type	Description	Default
enable_intensity	bool	Whether to capture intensity image	True
enable_disparity	bool	Whether to capture disparity map	True
calibrate_disparity	bool	Whether to apply calibration to disparity	True
timeout_ms	int	Capture timeout in milliseconds	20000

Returns:

Type	Description
StereoGrabResult	StereoGrabResult containing captured data

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails

Examples:

>>> result = await camera.capture()
>>> print(f"Intensity: {result.intensity.shape}")
>>> print(f"Disparity: {result.disparity.shape}")

capture_point_cloud async

capture_point_cloud(
    include_colors: bool = True,
    remove_outliers: bool = False,
    downsample_factor: int = 1,
) -> PointCloudData

Capture and generate 3D point cloud.

Parameters:

Name	Type	Description	Default
include_colors	bool	Whether to include color information from intensity	True
remove_outliers	bool	Whether to remove statistical outliers	False
downsample_factor	int	Downsampling factor (1 = no downsampling)	1

Returns:

Type	Description
PointCloudData	PointCloudData with 3D points and optional colors

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails
CameraConfigurationError	If calibration not available

Examples:

>>> point_cloud = await camera.capture_point_cloud()
>>> point_cloud.save_ply("output.ply")
>>> pcd = point_cloud.to_open3d()

configure async

configure(**params) -> None

Configure camera parameters.

Parameters:

Name	Type	Description	Default
**params		Parameter name-value pairs	{}

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.configure(ExposureTime=15000, Gain=2.0)

set_depth_range async

set_depth_range(min_depth: float, max_depth: float) -> None

Set depth measurement range in meters.

Parameters:

Name	Type	Description	Default
min_depth	float	Minimum depth (e.g., 0.3 meters)	required
max_depth	float	Maximum depth (e.g., 5.0 meters)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.set_depth_range(0.5, 3.0)

set_illumination_mode async

set_illumination_mode(mode: str) -> None

Set illumination mode.

Parameters:

Name	Type	Description	Default
mode	str	'AlwaysActive' (low latency) or 'AlternateActive' (clean intensity)	required

Raises:

Type	Description
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> await camera.set_illumination_mode("AlternateActive")

set_binning async

set_binning(horizontal: int = 2, vertical: int = 2) -> None

Enable binning for latency reduction.

Binning reduces network transfer and computation.

Parameters:

Name	Type	Description	Default
horizontal	int	Horizontal binning factor (typically 2)	2
vertical	int	Vertical binning factor (typically 2)	2

Note

When using binning for low latency, consider also setting depth quality to "Full" using set_depth_quality("Full").

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.set_binning(2, 2)
>>> await camera.set_depth_quality("Full")  # Recommended for low latency

set_depth_quality async

set_depth_quality(quality: str) -> None

Set depth quality level.

Parameters:

Name	Type	Description	Default
quality	str	Depth quality setting. Common values: - "Full": Highest quality, recommended with binning - "Normal": Standard quality - "Low": Lower quality, faster processing	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> # Low latency configuration
>>> await camera.set_binning(2, 2)
>>> await camera.set_depth_quality("Full")

set_pixel_format async

set_pixel_format(format: str) -> None

Set pixel format for intensity component.

Parameters:

Name	Type	Description	Default
format	str	Pixel format ("RGB8", "Mono8", etc.)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If format not available or configuration fails

Examples:

>>> await camera.set_pixel_format("Mono8")  # Force grayscale

set_exposure_time async

set_exposure_time(microseconds: float) -> None

Set exposure time in microseconds.

Parameters:

Name	Type	Description	Default
microseconds	float	Exposure time in microseconds (e.g., 5000 = 5ms)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.set_exposure_time(5000)  # 5ms exposure

set_gain async

set_gain(gain: float) -> None

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	float	Gain value (typically 0.0 to 24.0, camera-dependent)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> await camera.set_gain(2.0)

get_exposure_time async

get_exposure_time() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time in microseconds

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> exposure = await camera.get_exposure_time()
>>> print(f"Exposure: {exposure}μs")

get_gain async

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> gain = await camera.get_gain()
>>> print(f"Gain: {gain}")

get_depth_quality async

get_depth_quality() -> str

Get current depth quality setting.

Returns:

Type	Description
str	Current depth quality level (e.g., "Full", "Normal", "Low")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> quality = await camera.get_depth_quality()
>>> print(f"Quality: {quality}")

get_pixel_format async

get_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format (e.g., "RGB8", "Mono8", "Coord3D_C16")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> format = await camera.get_pixel_format()
>>> print(f"Format: {format}")

get_binning async

get_binning() -> tuple[int, int]

Get current binning settings.

Returns:

Type	Description
tuple[int, int]	Tuple of (horizontal_binning, vertical_binning)

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> h_bin, v_bin = await camera.get_binning()
>>> print(f"Binning: {h_bin}x{v_bin}")

get_illumination_mode async

get_illumination_mode() -> str

Get current illumination mode.

Returns:

Type	Description
str	Current illumination mode ("AlwaysActive" or "AlternateActive")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> mode = await camera.get_illumination_mode()
>>> print(f"Illumination: {mode}")

get_depth_range async

get_depth_range() -> tuple[float, float]

Get current depth measurement range in meters.

Returns:

Type	Description
tuple[float, float]	Tuple of (min_depth, max_depth) in meters

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> min_d, max_d = await camera.get_depth_range()
>>> print(f"Range: {min_d}m - {max_d}m")

set_trigger_mode async

set_trigger_mode(mode: str) -> None

Set trigger mode (simplified interface).

Parameters:

Name	Type	Description	Default
mode	str	Trigger mode ("continuous" or "trigger") - "continuous": Free-running continuous acquisition - "trigger": Software-triggered acquisition	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> await camera.set_trigger_mode("continuous")  # Free running
>>> await camera.set_trigger_mode("trigger")     # Software triggered

get_trigger_mode async

get_trigger_mode() -> str

Get current trigger mode (simplified interface).

Returns:

Type	Description
str	"continuous" or "trigger"

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> mode = await camera.get_trigger_mode()
>>> print(f"Current mode: {mode}")

get_trigger_modes async

get_trigger_modes() -> list[str]

Get available trigger modes.

Returns:

Type	Description
list[str]	List of supported trigger modes: ["continuous", "trigger"]

Examples:

>>> modes = await camera.get_trigger_modes()
>>> print(f"Available modes: {modes}")

start_grabbing async

start_grabbing() -> None

Start grabbing frames.

Must be called after enable_software_trigger() and before execute_trigger().

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> await camera.enable_software_trigger()
>>> await camera.start_grabbing()
>>> for i in range(10):
...     await camera.execute_trigger()
...     result = await camera.capture()

execute_trigger async

execute_trigger() -> None

Execute software trigger.

Triggers a frame capture when in software trigger mode. Note: start_grabbing() must be called first after enabling software trigger.

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If trigger execution fails

Examples:

>>> await camera.enable_software_trigger()
>>> await camera.start_grabbing()
>>> for i in range(10):
...     await camera.execute_trigger()
...     result = await camera.capture()

models

Data models for stereo camera operations.

This module provides data structures for handling stereo camera data including multi-component capture results, calibration parameters, and 3D point clouds.

StereoGrabResult dataclass

StereoGrabResult(
    intensity: Optional[ndarray],
    disparity: Optional[ndarray],
    timestamp: float,
    frame_number: int,
    disparity_calibrated: Optional[ndarray] = None,
    has_intensity: bool = True,
    has_disparity: bool = True,
)

Result from stereo camera capture containing multi-component data.

Attributes:

Name	Type	Description
intensity	Optional[ndarray]	Intensity image - RGB8 (H, W, 3) or Mono8 (H, W)
disparity	Optional[ndarray]	Disparity map - uint16 (H, W)
timestamp	float	Capture timestamp in seconds
frame_number	int	Sequential frame number
disparity_calibrated	Optional[ndarray]	Calibrated disparity map - float32 (H, W), optional
has_intensity	bool	Flag indicating if intensity data is present
has_disparity	bool	Flag indicating if disparity data is present

intensity_shape property

intensity_shape: tuple

Get shape of intensity image.

disparity_shape property

disparity_shape: tuple

Get shape of disparity map.

is_color_intensity property

is_color_intensity: bool

Check if intensity is color (RGB) vs grayscale.

StereoCalibrationData dataclass

StereoCalibrationData(
    baseline: float,
    focal_length: float,
    principal_point_u: float,
    principal_point_v: float,
    scale3d: float,
    offset3d: float,
    Q: ndarray,
)

Factory calibration parameters for stereo camera.

These parameters are provided by the camera manufacturer and used for 3D reconstruction from disparity maps.

Attributes:

Name	Type	Description
baseline	float	Stereo baseline in meters (distance between camera pair)
focal_length	float	Focal length in pixels
principal_point_u	float	Principal point U coordinate in pixels
principal_point_v	float	Principal point V coordinate in pixels
scale3d	float	Scale factor for disparity conversion
offset3d	float	Offset for disparity conversion
Q	ndarray	4x4 reprojection matrix for point cloud generation

from_camera_params classmethod

from_camera_params(params: dict) -> 'StereoCalibrationData'

Create calibration data from camera parameter dictionary.

Parameters:

Name	Type	Description	Default
params	dict	Dictionary containing calibration parameters: - Scan3dBaseline: Baseline in meters - Scan3dFocalLength: Focal length in pixels - Scan3dPrincipalPointU: Principal point U in pixels - Scan3dPrincipalPointV: Principal point V in pixels - Scan3dCoordinateScale: Scale factor - Scan3dCoordinateOffset: Offset	required

Returns:

Type	Description
'StereoCalibrationData'	StereoCalibrationData instance

calibrate_disparity

calibrate_disparity(disparity: ndarray) -> np.ndarray

Apply calibration to raw disparity map.

Parameters:

Name	Type	Description	Default
disparity	ndarray	Raw disparity map (uint16)	required

Returns:

Type	Description
ndarray	Calibrated disparity map (float32)

PointCloudData dataclass

PointCloudData(
    points: ndarray,
    colors: Optional[ndarray] = None,
    num_points: int = 0,
    has_colors: bool = False,
)

3D point cloud data with optional color information.

Attributes:

Name	Type	Description
points	ndarray	Array of 3D points (N, 3) - (x, y, z) in meters
colors	Optional[ndarray]	Optional array of RGB colors (N, 3) - values in [0, 1]
num_points	int	Number of valid points
has_colors	bool	Flag indicating if color information is present

save_ply

save_ply(path: str, binary: bool = True) -> None

Save point cloud as PLY file.

Parameters:

Name	Type	Description	Default
path	str	Output file path	required
binary	bool	If True, save in binary format; otherwise ASCII	True

Raises:

Type	Description
ImportError	If plyfile is not installed

to_open3d

to_open3d()

Convert to Open3D PointCloud object.

Returns:

Type	Description
	open3d.geometry.PointCloud instance

Raises:

Type	Description
ImportError	If open3d is not installed

downsample

downsample(factor: int) -> 'PointCloudData'

Downsample point cloud by given factor.

Parameters:

Name	Type	Description	Default
factor	int	Downsampling factor (e.g., 2 = keep every 2nd point)	required

Returns:

Type	Description
'PointCloudData'	New PointCloudData with downsampled points

remove_statistical_outliers

remove_statistical_outliers(
    nb_neighbors: int = 20, std_ratio: float = 2.0
) -> "PointCloudData"

Remove statistical outliers from point cloud.

Parameters:

Name	Type	Description	Default
nb_neighbors	int	Number of neighbors to consider	20
std_ratio	float	Standard deviation ratio threshold	2.0

Returns:

Type	Description
'PointCloudData'	New PointCloudData with outliers removed

Raises:

Type	Description
ImportError	If open3d is not installed

stereo_camera

Synchronous stereo camera interface.

This module provides a synchronous wrapper around AsyncStereoCamera, following the same pattern as the regular Camera class.

StereoCamera

StereoCamera(
    async_camera: Optional[AsyncStereoCamera] = None,
    loop: Optional[AbstractEventLoop] = None,
    name: Optional[str] = None,
    **kwargs
)

Bases: Mindtrace

Synchronous wrapper around AsyncStereoCamera.

All operations are executed on a background event loop. This provides a simple synchronous API for stereo camera operations.

Create a synchronous stereo camera wrapper.

Parameters:

Name	Type	Description	Default
async_camera	Optional[AsyncStereoCamera]	Existing AsyncStereoCamera instance	None
loop	Optional[AbstractEventLoop]	Event loop to use for async operations	None
name	Optional[str]	Camera identifier. Format: "BaslerStereoAce:serial_number" If None, opens first available Stereo ace camera.	None
**kwargs		Additional arguments passed to Mindtrace	{}

Examples:

>>> # Simple usage - opens first available
>>> camera = StereoCamera()

>>> # Open specific camera
>>> camera = StereoCamera(name="BaslerStereoAce:40644640")

>>> # Use existing async camera
>>> async_cam = await AsyncStereoCamera.open()
>>> sync_cam = StereoCamera(async_camera=async_cam, loop=loop)

name property

name: str

Get camera name.

Returns:

Type	Description
str	Camera name in format "Backend:serial_number"

calibration property

calibration: Optional[StereoCalibrationData]

Get calibration data.

Returns:

Type	Description
Optional[StereoCalibrationData]	StereoCalibrationData if available, None otherwise

is_open property

is_open: bool

Check if camera is open.

Returns:

Type	Description
bool	True if camera is open, False otherwise

close

close() -> None

Close camera and release resources.

Examples:

>>> camera = StereoCamera()
>>> # ... use camera ...
>>> camera.close()

capture

capture(
    enable_intensity: bool = True,
    enable_disparity: bool = True,
    calibrate_disparity: bool = True,
    timeout_ms: int = 20000,
) -> StereoGrabResult

Capture multi-component stereo data.

Parameters:

Name	Type	Description	Default
enable_intensity	bool	Whether to capture intensity image	True
enable_disparity	bool	Whether to capture disparity map	True
calibrate_disparity	bool	Whether to apply calibration to disparity	True
timeout_ms	int	Capture timeout in milliseconds	20000

Returns:

Type	Description
StereoGrabResult	StereoGrabResult containing captured data

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails

Examples:

>>> camera = StereoCamera()
>>> result = camera.capture()
>>> print(f"Intensity: {result.intensity.shape}")
>>> print(f"Disparity: {result.disparity.shape}")
>>> camera.close()

capture_point_cloud

capture_point_cloud(
    include_colors: bool = True,
    remove_outliers: bool = False,
    downsample_factor: int = 1,
) -> PointCloudData

Capture and generate 3D point cloud.

Parameters:

Name	Type	Description	Default
include_colors	bool	Whether to include color information from intensity	True
remove_outliers	bool	Whether to remove statistical outliers	False
downsample_factor	int	Downsampling factor (1 = no downsampling)	1

Returns:

Type	Description
PointCloudData	PointCloudData with 3D points and optional colors

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraCaptureError	If capture fails
CameraConfigurationError	If calibration not available

Examples:

>>> camera = StereoCamera()
>>> point_cloud = camera.capture_point_cloud()
>>> print(f"Points: {point_cloud.num_points}")
>>> point_cloud.save_ply("output.ply")
>>> camera.close()

configure

configure(**params) -> None

Configure camera parameters.

Parameters:

Name	Type	Description	Default
**params		Parameter name-value pairs	{}

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.configure(ExposureTime=15000, Gain=2.0)
>>> camera.close()

set_depth_range

set_depth_range(min_depth: float, max_depth: float) -> None

Set depth measurement range in meters.

Parameters:

Name	Type	Description	Default
min_depth	float	Minimum depth (e.g., 0.3 meters)	required
max_depth	float	Maximum depth (e.g., 5.0 meters)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_depth_range(0.5, 3.0)
>>> camera.close()

set_illumination_mode

set_illumination_mode(mode: str) -> None

Set illumination mode.

Parameters:

Name	Type	Description	Default
mode	str	'AlwaysActive' (low latency) or 'AlternateActive' (clean intensity)	required

Raises:

Type	Description
CameraConfigurationError	If invalid mode or configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_illumination_mode("AlternateActive")
>>> camera.close()

set_binning

set_binning(horizontal: int = 2, vertical: int = 2) -> None

Enable binning for latency reduction.

Binning reduces network transfer and computation.

Parameters:

Name	Type	Description	Default
horizontal	int	Horizontal binning factor (typically 2)	2
vertical	int	Vertical binning factor (typically 2)	2

Note

When using binning for low latency, consider also setting depth quality to "Full" using set_depth_quality("Full").

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_binning(2, 2)
>>> camera.set_depth_quality("Full")  # Recommended for low latency
>>> camera.close()

set_depth_quality

set_depth_quality(quality: str) -> None

Set depth quality level.

Parameters:

Name	Type	Description	Default
quality	str	Depth quality setting. Common values: - "Full": Highest quality, recommended with binning - "Normal": Standard quality - "Low": Lower quality, faster processing	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> # Low latency configuration
>>> camera.set_binning(2, 2)
>>> camera.set_depth_quality("Full")
>>> camera.close()

set_pixel_format

set_pixel_format(format: str) -> None

Set pixel format for intensity component.

Parameters:

Name	Type	Description	Default
format	str	Pixel format ("RGB8", "Mono8", etc.)	required

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If format not available or configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_pixel_format("Mono8")  # Force grayscale
>>> camera.close()

set_exposure_time

set_exposure_time(microseconds: float) -> None

Set exposure time in microseconds.

Parameters:

Name	Type	Description	Default
microseconds	float	Exposure time in microseconds (e.g., 5000 = 5ms)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_exposure_time(5000)  # 5ms exposure
>>> camera.close()

set_gain

set_gain(gain: float) -> None

Set camera gain.

Parameters:

Name	Type	Description	Default
gain	float	Gain value (typically 0.0 to 24.0, camera-dependent)	required

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.set_gain(2.0)
>>> camera.close()

get_exposure_time

get_exposure_time() -> float

Get current exposure time in microseconds.

Returns:

Type	Description
float	Current exposure time in microseconds

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> exposure = camera.get_exposure_time()
>>> print(f"Exposure: {exposure}μs")
>>> camera.close()

get_gain

get_gain() -> float

Get current camera gain.

Returns:

Type	Description
float	Current gain value

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> gain = camera.get_gain()
>>> print(f"Gain: {gain}")
>>> camera.close()

get_depth_quality

get_depth_quality() -> str

Get current depth quality setting.

Returns:

Type	Description
str	Current depth quality level (e.g., "Full", "Normal", "Low")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> quality = camera.get_depth_quality()
>>> print(f"Quality: {quality}")
>>> camera.close()

get_pixel_format

get_pixel_format() -> str

Get current pixel format.

Returns:

Type	Description
str	Current pixel format (e.g., "RGB8", "Mono8", "Coord3D_C16")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> format = camera.get_pixel_format()
>>> print(f"Format: {format}")
>>> camera.close()

get_binning

get_binning() -> tuple[int, int]

Get current binning settings.

Returns:

Type	Description
tuple[int, int]	Tuple of (horizontal_binning, vertical_binning)

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> h_bin, v_bin = camera.get_binning()
>>> print(f"Binning: {h_bin}x{v_bin}")
>>> camera.close()

get_illumination_mode

get_illumination_mode() -> str

Get current illumination mode.

Returns:

Type	Description
str	Current illumination mode ("AlwaysActive" or "AlternateActive")

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> mode = camera.get_illumination_mode()
>>> print(f"Illumination: {mode}")
>>> camera.close()

get_depth_range

get_depth_range() -> tuple[float, float]

Get current depth measurement range in meters.

Returns:

Type	Description
tuple[float, float]	Tuple of (min_depth, max_depth) in meters

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> min_d, max_d = camera.get_depth_range()
>>> print(f"Range: {min_d}m - {max_d}m")
>>> camera.close()

enable_software_trigger

enable_software_trigger() -> None

Enable software triggering mode.

After enabling, use start_grabbing(), then execute_trigger() to capture frames on demand.

Raises:

Type	Description
CameraConfigurationError	If configuration fails

Examples:

>>> camera = StereoCamera()
>>> camera.enable_software_trigger()
>>> camera.start_grabbing()  # Start grabbing first!
>>> for i in range(10):
...     camera.execute_trigger()
...     result = camera.capture()
>>> camera.close()

start_grabbing

start_grabbing() -> None

Start grabbing frames.

Must be called after enable_software_trigger() and before execute_trigger().

Raises:

Type	Description
CameraConnectionError	If camera not opened

Examples:

>>> camera = StereoCamera()
>>> camera.enable_software_trigger()
>>> camera.start_grabbing()
>>> for i in range(10):
...     camera.execute_trigger()
...     result = camera.capture()
>>> camera.close()

execute_trigger

execute_trigger() -> None

Execute software trigger.

Triggers a frame capture when in software trigger mode. Note: start_grabbing() must be called first after enabling software trigger.

Raises:

Type	Description
CameraConnectionError	If camera not opened
CameraConfigurationError	If trigger execution fails

Examples:

>>> camera = StereoCamera()
>>> camera.enable_software_trigger()
>>> camera.start_grabbing()
>>> camera.execute_trigger()
>>> result = camera.capture()
>>> camera.close()

setup

Setup scripts for stereo camera SDKs.

This module provides installation scripts for stereo camera systems.

Available CLI commands (after package installation): mindtrace-stereo-basler install # Install Stereo ace package mindtrace-stereo-basler uninstall # Uninstall Stereo ace package

Each setup script uses Typer for CLI and can be run independently.

StereoAceInstaller

StereoAceInstaller(
    installation_method: str = "tarball",
    install_dir: Optional[str] = None,
    package_path: Optional[str] = None,
)

Bases: Mindtrace

Basler Stereo ace Supplementary Package installer with guided wizard.

This class provides an interactive installation wizard that guides users through downloading and installing the Stereo ace package from the official Basler website.

Initialize the Stereo ace installer.

Parameters:

Name	Type	Description	Default
installation_method	str	Installation method ("deb" or "tarball")	'tarball'
install_dir	Optional[str]	Custom installation directory (for tarball method)	None
package_path	Optional[str]	Path to pre-downloaded package file (optional)	None

install

install() -> bool

Install the Stereo ace Supplementary Package.

Returns:

Type	Description
bool	True if installation successful, False otherwise

uninstall

uninstall() -> bool

Uninstall the Stereo ace Supplementary Package.

Returns:

Type	Description
bool	True if uninstallation successful, False otherwise

setup_stereo_ace

Basler Stereo ace Setup Script

This script provides a guided installation wizard for the Basler pylon Supplementary Package for Stereo ace cameras on Linux systems. The package provides the GenTL Producer needed to connect and use Stereo ace camera systems.

Features: - Interactive guided wizard with browser integration - Supports both Debian package (.deb) and tar.gz archive installation - Custom installation path support (default: ~/.local/share/pylon_stereo) - Environment variable setup for GenTL Producer - Shell environment script generation - Support for pre-downloaded packages (--package flag) - Comprehensive logging and error handling - Uninstallation support

Installation Methods

1. Debian Package (Recommended - requires sudo):
2. Installs to /opt/pylon
3. Automatic environment configuration

4. System-wide availability

5. tar.gz Archive (Portable - no sudo):

6. Installs to user-specified or default directory
7. Requires manual environment setup
8. Per-user installation

Usage

python setup_stereo_ace.py # Interactive wizard python setup_stereo_ace.py --method deb # Use Debian package python setup_stereo_ace.py --method tarball # Use tar.gz archive python setup_stereo_ace.py --package /path/to/file # Use pre-downloaded file python setup_stereo_ace.py --install-dir ~/pylon # Custom install location python setup_stereo_ace.py --uninstall # Uninstall mindtrace-stereo-basler-install # Console script (install) mindtrace-stereo-basler-uninstall # Console script (uninstall)

Environment Setup

After installation, you must set environment variables:

For Debian package: source /opt/pylon/bin/pylon-setup-env.sh /opt/pylon

For tar.gz archive: source /setup_stereo_env.sh

Or add to ~/.bashrc for persistence: echo "source /setup_stereo_env.sh" >> ~/.bashrc

StereoAceInstaller

StereoAceInstaller(
    installation_method: str = "tarball",
    install_dir: Optional[str] = None,
    package_path: Optional[str] = None,
)

Bases: Mindtrace

Basler Stereo ace Supplementary Package installer with guided wizard.

This class provides an interactive installation wizard that guides users through downloading and installing the Stereo ace package from the official Basler website.

Initialize the Stereo ace installer.

Parameters:

Name	Type	Description	Default
installation_method	str	Installation method ("deb" or "tarball")	'tarball'
install_dir	Optional[str]	Custom installation directory (for tarball method)	None
package_path	Optional[str]	Path to pre-downloaded package file (optional)	None

install

install() -> bool

Install the Stereo ace Supplementary Package.

Returns:

Type	Description
bool	True if installation successful, False otherwise

uninstall

uninstall() -> bool

Uninstall the Stereo ace Supplementary Package.

Returns:

Type	Description
bool	True if uninstallation successful, False otherwise

install

install(
    method: str = typer.Option(
        "tarball",
        "--method",
        "-m",
        help="Installation method: 'deb' (requires sudo) or 'tarball' (portable)",
    ),
    package: Optional[Path] = typer.Option(
        None,
        "--package",
        "-p",
        help="Path to pre-downloaded package file (.deb or .tar.gz)",
        exists=True,
        dir_okay=False,
    ),
    install_dir: Optional[Path] = typer.Option(
        None,
        "--install-dir",
        "-d",
        help="Custom installation directory (for tarball method)",
    ),
    verbose: bool = typer.Option(
        False, "--verbose", "-v", help="Enable verbose logging"
    ),
) -> None

Install the Basler Stereo ace Supplementary Package using an interactive wizard.

The wizard will guide you through downloading and installing the package from Basler's official website where you'll accept their EULA.

For CI/automation, use --package to provide a pre-downloaded file.

uninstall

uninstall(
    method: str = typer.Option(
        "tarball",
        "--method",
        "-m",
        help="Installation method used: 'deb' or 'tarball'",
    ),
    install_dir: Optional[Path] = typer.Option(
        None,
        "--install-dir",
        "-d",
        help="Custom installation directory (for tarball method)",
    ),
    verbose: bool = typer.Option(
        False, "--verbose", "-v", help="Enable verbose logging"
    ),
) -> None

Uninstall the Basler Stereo ace Supplementary Package.

main

main() -> None

Main entry point for the script.