camera Module

Camera interface using picamera2 library.

This module provides a Camera class that wraps the picamera2 library for Raspberry Pi camera modules. It handles camera initialization, frame capture, and automatic detection of full sensor resolution to avoid cropping.

The Camera class automatically detects and uses the full sensor resolution (e.g., 3280x2464 for Camera Module 2) instead of cropping to a smaller resolution, ensuring the full field of view is captured.

Key Features:

• Automatic full sensor resolution detection

• Frame rate control

• Camera validation

• Error handling and recovery

• Support for IR camera controls (exposure, gain)

Example

Basic usage::

camera = Camera(device=”0”, resolution=(640, 480), fps=10) if camera.open():

frame = camera.read_frame() camera.release()

Using context manager::

with Camera() as cam:

for frame in cam.read_frames():

# Process frame pass

class camera.Camera(device: str = '0', resolution: Tuple[int, int] = (640, 480), fps: int = 10)

Bases: object

Wrapper for picamera2 camera interface.

Provides a high-level interface for Raspberry Pi camera modules using picamera2. Automatically detects full sensor resolution and handles frame conversion to OpenCV-compatible BGR format.

The camera automatically uses the full sensor resolution (detected from preview configuration) to ensure the complete field of view is captured, matching the behavior of rpicam-hello.

device

Camera device identifier (string, typically “0” for first camera).

resolution

Requested resolution tuple (width, height). Note: Actual resolution may be full sensor size.

fps

Target frames per second.

picam2

Internal Picamera2 instance (None until opened).

frame_time

Calculated time per frame (1.0 / fps).

last_frame_time

Timestamp of last frame read.

Example

>>> camera = Camera(device="0", resolution=(640, 480), fps=10)
>>> if camera.open():
...     actual_res = camera.get_resolution()
...     print(f"Actual resolution: {actual_res}")
>>>     success, frame = camera.read_frame()
>>>     camera.release()

__init__(device: str = '0', resolution: Tuple[int, int] = (640, 480), fps: int = 10)

Initialize camera instance.

Creates a Camera instance but does not open the camera hardware. Call open() to actually start the camera.

Parameters:

• device – Camera device identifier. Can be: - Camera index as string: “0”, “1”, etc. (recommended) - Device path: “/dev/video0” (converted to index) Defaults to “0” for first camera.

• resolution – Requested resolution tuple (width, height). Note: The actual resolution used will be the full sensor resolution (detected automatically) to avoid cropping.

• fps – Target frames per second for frame capture. Must be positive.

Raises:

ImportError – If picamera2 is not installed or not available in the current Python environment.

Note

The camera hardware is not accessed until open() is called. This allows creating Camera instances without immediately claiming the camera resource.

open() → bool

Open and configure the camera using picamera2.

Initializes the camera hardware, detects full sensor resolution, and configures video capture. Applies optional camera controls from config (exposure time, gain, auto-exposure) for IR/low-light optimization.

The camera automatically uses the full sensor resolution (e.g., 3280x2464 for Camera Module 2) instead of cropping to the requested resolution, ensuring the complete field of view is captured.

Returns:

True if camera opened and configured successfully, False otherwise.

Note

This method must be called before reading frames. If it fails, check camera hardware connections and ensure no other process is using the camera.

read_frame() → Tuple[bool, ndarray | None] | None

Read a single frame from the camera.

Returns:

Tuple of (success, frame) or None if camera not opened

read_frames() → Generator[ndarray | None, None, None]

Generator that yields frames at the configured FPS rate.

Yields:

Frame as numpy array, or None if read failed

get_resolution() → Tuple[int, int]

Get the actual camera resolution.

Returns:

Tuple of (width, height)

validate_camera(test_frames: int = 5, success_threshold: int = 3, timeout: float = 5.0) → bool

Validate that the camera can successfully read frames.

Parameters:

• test_frames – Number of frames to attempt reading

• success_threshold – Minimum number of successful reads required

• timeout – Maximum time to wait for frames in seconds

Returns:

True if camera can read frames successfully, False otherwise

release() → None

Release the camera resource.

__enter__()

Context manager entry.

__exit__(exc_type, exc_val, exc_tb)

Context manager exit.