or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced.mdcapture.mdconfiguration.mdcontrols.mdcore-operations.mdindex.mdpreview.mdrecording.md
tile.json

tessl/pypi-picamera2

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/picamera2@0.3.x

To install, run

npx @tessl/cli install tessl/pypi-picamera2@0.3.0

index.mddocs/

Picamera2

A comprehensive Python library that serves as the libcamera-based replacement for the original Picamera library, providing an intuitive Python API for interfacing with Raspberry Pi cameras. The library offers advanced camera control capabilities including configuration of multiple camera streams, capture of high-quality images and videos, real-time preview functionality, and extensive customization options for camera settings.

Package Information

  • Package Name: picamera2
  • Language: Python
  • Installation: pip install picamera2
  • Python Version: >=3.9
  • Platform: Raspberry Pi (Linux)

Core Imports

from picamera2 import Picamera2

For advanced functionality:

from picamera2 import (
    Picamera2, Preview,
    CameraConfiguration, StreamConfiguration,
    Controls, Metadata,
    CompletedRequest, MappedArray,
    CancelledError
)

For device-specific features:

from picamera2.devices.imx500 import IMX500
from picamera2.encoders import H264Encoder, JpegEncoder
from picamera2.outputs import FileOutput
from picamera2.previews import QtPreview
from picamera2.allocators import DmaAllocator, PersistentAllocator

Basic Usage

from picamera2 import Picamera2
import time

# Initialize camera
picam2 = Picamera2()

# Create and configure for still capture
camera_config = picam2.create_still_configuration()
picam2.configure(camera_config)

# Start camera
picam2.start()

# Wait for camera to settle
time.sleep(2)

# Capture image
picam2.capture_file("image.jpg")

# Stop camera
picam2.stop()
picam2.close()

Architecture

The Picamera2 library is built on a modular architecture centered around the main Picamera2 class:

  • Picamera2 Class: Main camera interface providing high-level API for camera operations
  • Configuration System: Manages camera, stream, and sensor configurations
  • Request Pipeline: Handles asynchronous camera requests and completed frames
  • Encoder System: Provides video and image encoding capabilities
  • Output System: Manages various output destinations (files, streams, circular buffers)
  • Preview System: Supports different preview display methods (Qt, DRM, headless)
  • Allocator System: Handles memory allocation strategies for camera buffers
  • Device Integration: Platform-specific support for AI sensors and accelerators

This modular design enables flexible camera applications from simple photography to complex computer vision systems while maintaining high performance through efficient memory management and optimized capture pipelines.

Capabilities

Core Camera Operations

Essential camera functionality including initialization, configuration, start/stop control, and basic capture operations. These form the foundation of all picamera2 applications.

class Picamera2:
    def __init__(self, camera_num: int = 0, tuning: Tuning = None): ...
    def start(self, config: CameraConfiguration = None, show_preview: bool = None): ...
    def stop(self): ...
    def close(self): ...
    def configure(self, camera_config: CameraConfiguration): ...

Core Camera Operations

Camera Configuration

Camera and stream configuration system for setting up different capture modes, stream parameters, and camera settings. Supports preview, still capture, and video recording configurations.

def create_preview_configuration(
    main: dict = None,
    lores: dict = None, 
    raw: dict = None,
    **kwargs
) -> CameraConfiguration: ...

def create_still_configuration(
    main: dict = None,
    lores: dict = None,
    raw: dict = None, 
    **kwargs
) -> CameraConfiguration: ...

def create_video_configuration(
    main: dict = None,
    lores: dict = None,
    raw: dict = None,
    **kwargs
) -> CameraConfiguration: ...

Camera Configuration

Image and Video Capture

Comprehensive capture functionality supporting various output formats, synchronous and asynchronous operations, and different data types including files, arrays, and PIL images.

def capture_file(self, file_output: str, name: str = "main", **kwargs): ...
def capture_array(self, name: str = "main", **kwargs) -> np.ndarray: ...
def capture_image(self, name: str = "main", **kwargs) -> PIL.Image: ...
def capture_buffer(self, name: str = "main", **kwargs) -> bytes: ...
def capture_buffers(self, names: list[str] = None, **kwargs) -> dict[str, bytes]: ...
def capture_request(self, **kwargs) -> CompletedRequest: ...
def capture_metadata(self, **kwargs) -> dict: ...

Image and Video Capture

Camera Controls

Advanced camera control system for setting exposure, gain, white balance, focus, and other camera parameters with real-time adjustment capabilities.

class Controls:
    def set_controls(self, controls: dict): ...
    def __setattr__(self, name: str, value): ...

def set_controls(self, controls: dict): ...

Camera Controls

Video Recording and Encoding

Video recording capabilities with support for multiple encoders (H.264, MJPEG, etc.), various output formats, and hardware acceleration when available.

def start_recording(self, encoder: Encoder, output: Output, **kwargs): ...
def stop_recording(self): ...
def start_encoder(self, encoder: Encoder, output: Output, **kwargs): ...
def stop_encoder(self, encoders: list = None): ...

Video Recording and Encoding

Preview and Display

Preview system supporting multiple display methods including Qt widgets, DRM/KMS direct rendering, and headless operation with overlay support.

def start_preview(self, preview: Preview = None, **kwargs): ...
def stop_preview(self): ...
def set_overlay(self, overlay): ...

Preview and Display

Advanced Features

Advanced functionality including mode switching, autofocus control, frame dropping, device-specific AI sensor integration, and platform-specific optimizations.

def switch_mode(self, camera_config: CameraConfiguration, **kwargs): ...
def autofocus_cycle(self, **kwargs): ...
def drop_frames(self, num_frames: int, **kwargs): ...
def wait(self, job, timeout: float = None): ...
def dispatch_functions(self, functions: list[callable], **kwargs): ...

Advanced Features

Memory Management and Allocators

Advanced memory allocation strategies for optimized performance including DMA buffers and persistent allocation for reduced overhead in high-performance applications.

class DmaAllocator:
    def allocate(self, libcamera_config, use_case): ...

class PersistentAllocator:
    def allocate(self, libcamera_config, use_case): ...
    
class MappedArray:
    def __enter__(self) -> 'MappedArray': ...
    def __exit__(self, exc_type, exc_val, exc_tb): ...
    @property
    def array(self) -> np.ndarray: ...

Types

class CameraConfiguration:
    use_case: str
    buffer_count: int
    transform: libcamera.Transform
    colour_space: libcamera.ColorSpace
    controls: Controls
    main: StreamConfiguration
    lores: StreamConfiguration
    raw: StreamConfiguration

class StreamConfiguration:
    size: tuple[int, int]
    format: str
    stride: int
    framesize: int

class CompletedRequest:
    request: libcamera.Request
    config: CameraConfiguration
    def make_array(self, name: str = "main") -> np.ndarray: ...
    def make_image(self, name: str = "main") -> PIL.Image: ...
    def save(self, name: str, file_output: str, **kwargs): ...

class Controls:
    def set_controls(self, controls: dict): ...

class Metadata:
    def make_dict(self) -> dict: ...

class Job:
    def wait(self, timeout: float = None): ...
    def result(self): ...
    def signal(self): ...
    @property
    def finished(self) -> bool: ...

class CancelledError(Exception):
    """Exception raised when operations are cancelled."""

Preview = Literal["null", "drm", "qt", "qtgl"]