tessl/pypi-picamera2

The libcamera-based Python interface to Raspberry Pi cameras, based on the original Picamera library

—

Pending

Overview

Eval results

Files

Camera Configuration

Name: tessl/pypi-picamera2
Author: tessl

Camera and stream configuration system for setting up different capture modes, stream parameters, and camera settings. The configuration system supports multiple concurrent streams with different resolutions and formats.

Capabilities

Configuration Creation

Create camera configurations optimized for different use cases.

def create_preview_configuration(
    main: dict = None,
    lores: dict = None,
    raw: dict = None,
    transform: libcamera.Transform = None,
    colour_space: libcamera.ColorSpace = None,
    buffer_count: int = None,
    controls: dict = None,
    display: str = None,
    encode: str = None
) -> CameraConfiguration:
    """
    Create configuration optimized for real-time preview.
    
    Parameters:
    - main: dict, main stream configuration {"size": (width, height), "format": "format_name"}
    - lores: dict, low-resolution stream configuration (optional)
    - raw: dict, raw stream configuration (optional)
    - transform: libcamera.Transform, image transform (rotation/flip)
    - colour_space: libcamera.ColorSpace, color space specification
    - buffer_count: int, number of buffers per stream
    - controls: dict, camera control values
    - display: str, stream name for display ("main", "lores")
    - encode: str, stream name for encoding ("main", "lores")
    
    Returns:
    CameraConfiguration: Optimized for low-latency preview
    """

def create_still_configuration(
    main: dict = None,
    lores: dict = None,
    raw: dict = None,
    transform: libcamera.Transform = None,
    colour_space: libcamera.ColorSpace = None,
    buffer_count: int = None,
    controls: dict = None,
    display: str = None,
    encode: str = None
) -> CameraConfiguration:
    """
    Create configuration optimized for high-quality still capture.
    
    Parameters: Same as create_preview_configuration
    
    Returns:
    CameraConfiguration: Optimized for maximum image quality
    """

def create_video_configuration(
    main: dict = None,
    lores: dict = None,
    raw: dict = None,
    transform: libcamera.Transform = None,
    colour_space: libcamera.ColorSpace = None,
    buffer_count: int = None,
    controls: dict = None,
    display: str = None,
    encode: str = None
) -> CameraConfiguration:
    """
    Create configuration optimized for video recording.
    
    Parameters: Same as create_preview_configuration
    
    Returns:
    CameraConfiguration: Optimized for sustained video capture
    """

Configuration Classes

Core configuration classes for camera and stream setup.

class CameraConfiguration:
    """Camera configuration container."""
    
    use_case: str  # Configuration use case identifier
    buffer_count: int  # Number of buffers per stream
    transform: libcamera.Transform  # Image transform
    colour_space: libcamera.ColorSpace  # Color space
    controls: Controls  # Camera controls
    display: str  # Display stream name
    encode: str  # Encode stream name
    
    # Stream configurations
    main: StreamConfiguration  # Main stream
    lores: StreamConfiguration  # Low-resolution stream
    raw: StreamConfiguration  # Raw stream
    
    # Forwarded properties from main stream
    @property
    def size(self) -> tuple[int, int]:
        """Main stream size as (width, height)."""
    
    @property
    def format(self) -> str:
        """Main stream pixel format."""
    
    def enable_lores(self, onoff: bool = True):
        """Enable or disable low-resolution stream."""
    
    def enable_raw(self, onoff: bool = True):
        """Enable or disable raw stream."""
    
    def align(self, optimal: bool = True):
        """Align stream configurations for optimal performance."""

class StreamConfiguration:
    """Individual stream configuration."""
    
    size: tuple[int, int]  # Stream dimensions (width, height)
    format: str  # Pixel format
    stride: int  # Row stride in bytes
    framesize: int  # Total frame size in bytes
    preserve_ar: bool  # Preserve aspect ratio flag
    
    def align(self, optimal: bool = True):
        """Align size for optimal performance."""

class SensorConfiguration:
    """Sensor-level configuration."""
    
    output_size: tuple[int, int]  # Sensor output size
    bit_depth: int  # Bit depth per pixel

Stream Management

Enable and configure multiple camera streams.

def enable_lores(self, onoff: bool = True):
    """
    Enable or disable low-resolution stream.
    
    Parameters:
    - onoff: bool, True to enable, False to disable
    """

def enable_raw(self, onoff: bool = True):
    """
    Enable or disable raw stream.
    
    Parameters:
    - onoff: bool, True to enable, False to disable
    """

Configuration Optimization

Optimize configurations for performance and compatibility.

def align(self, optimal: bool = True):
    """
    Align stream sizes for optimal performance.
    
    Parameters:
    - optimal: bool, use optimal alignment (may change sizes slightly)
    """

Usage Examples

Basic Configuration

from picamera2 import Picamera2

picam2 = Picamera2()

# Simple still configuration with default settings
still_config = picam2.create_still_configuration()
print(f"Main stream: {still_config.size} {still_config.format}")

# Custom main stream size and format
still_config = picam2.create_still_configuration(
    main={"size": (1920, 1080), "format": "RGB888"}
)

picam2.configure(still_config)

Multi-Stream Configuration

from picamera2 import Picamera2

picam2 = Picamera2()

# Configuration with main and low-resolution streams
config = picam2.create_video_configuration(
    main={"size": (1920, 1080), "format": "YUV420"},
    lores={"size": (640, 480), "format": "YUV420"}
)

# Specify which stream to use for display and encoding
config.display = "lores"  # Use low-res for preview display
config.encode = "main"    # Use high-res for recording

picam2.configure(config)

Advanced Configuration

from picamera2 import Picamera2
import libcamera

picam2 = Picamera2()

# Configuration with transforms and color space
config = picam2.create_still_configuration(
    main={"size": (2592, 1944), "format": "RGB888"},
    raw={"size": (2592, 1944)},  # Enable raw capture
    transform=libcamera.Transform(hflip=1, vflip=1),  # Flip image
    colour_space=libcamera.ColorSpace.Rec709(),
    buffer_count=2,  # Use 2 buffers per stream
    controls={"ExposureTime": 10000, "AnalogueGain": 1.0}
)

# Enable raw stream for advanced processing
config.enable_raw(True)

# Optimize for performance
config.align(optimal=True)

picam2.configure(config)

Configuration Inspection

from picamera2 import Picamera2

picam2 = Picamera2()
config = picam2.create_preview_configuration()

# Examine configuration details
print(f"Use case: {config.use_case}")
print(f"Buffer count: {config.buffer_count}")
print(f"Transform: {config.transform}")

# Stream details
print(f"Main stream: {config.main.size} {config.main.format}")
print(f"Frame size: {config.main.framesize} bytes")
print(f"Stride: {config.main.stride} bytes")

if config.lores:
    print(f"Lores stream: {config.lores.size} {config.lores.format}")

Dynamic Configuration Changes

from picamera2 import Picamera2

picam2 = Picamera2()

# Start with preview configuration
preview_config = picam2.create_preview_configuration()
picam2.configure(preview_config)
picam2.start()

# Later switch to high-resolution still capture
picam2.stop()
still_config = picam2.create_still_configuration(
    main={"size": (4056, 3040), "format": "RGB888"}
)
picam2.configure(still_config)
picam2.start()

# Now ready for high-quality capture

Install with Tessl CLI