The Picamera2 Main Class

Relevant source files

The following files were used as context for generating this wiki page:

• picamera2/picamera2.py
• picamera2/request.py
• apps/app_full.py
• examples/picamera2_multiprocessing.py
• picamera2/devices/imx500/imx500.py
• README.md
• CHANGELOG.md

The Picamera2 class is the central high-level interface for controlling Raspberry Pi cameras using the libcamera framework. It is designed to replace the legacy Picamera library and provides an easy-to-use Python API for a wide range of camera operations, from simple previews and captures to complex video recording and stream manipulation.

This class encapsulates the underlying libcamera objects and manages the camera's lifecycle, configuration, and data flow. It handles camera initialization, stream configuration, request queuing, and resource management, presenting developers with a simplified but powerful set of methods for still image capture, video recording, and accessing frame metadata.

Sources: README.md, picamera2/picamera2.py:42-44

Architecture and Core Components

The Picamera2 class orchestrates several key components to manage camera operations. It interacts with a CameraManager to handle camera discovery and events, uses CameraConfiguration objects to define stream properties, and returns CompletedRequest objects which contain the captured image data and metadata.

This diagram shows the main classes and their relationships centered around the Picamera2 instance.

Initialization

A Picamera2 object is initialized by specifying a camera number. Upon instantiation, it discovers available cameras via the CameraManager, acquires the specified camera, and sets up internal structures.

# picamera2/picamera2.py:255-285
def __init__(self, camera_num=0, verbose_console=None, tuning=None, allocator=None):
    # ...
    camera_num = self.global_camera_info()[camera_num]['Num']
    self._cm.add(camera_num, self)
    # ...
    self._open_camera()
    # ...
    self.preview_configuration_ = CameraConfiguration(self.create_preview_configuration(), self)
    self.still_configuration_ = CameraConfiguration(self.create_still_configuration(), self)
    self.video_configuration_ = CameraConfiguration(self.create_video_configuration(), self)
    # ...

The constructor also pre-creates default configuration objects: preview_configuration, still_configuration, and video_configuration.

Sources: picamera2/picamera2.py:255-285

CameraManager

The static CameraManager class runs a background thread to listen for events from libcamera, such as completed requests. When a request is ready, it is packaged into a CompletedRequest object and added to the appropriate Picamera2 instance's queue. This mechanism is fundamental to the asynchronous operation of the library.

Sources: picamera2/picamera2.py:101-163

Global Camera Information

The class provides a static method global_camera_info() to enumerate all attached cameras. This is useful in multi-camera systems to identify the correct camera_num for initialization.

Field	Type	Description
Model	str	The model name of the camera, as advertised by the camera driver.
Location	int	A number reporting how the camera is mounted, as reported by libcamera.
Rotation	int	How the camera is rotated for normal operation, as reported by libcamera.
Id	str	An identifier string for the camera, indicating how it is connected (e.g., a bus path).
Num	int	The internal libcamera camera index.

Sources: picamera2/picamera2.py:90-99, picamera2/picamera2.py:221-233

Camera Lifecycle and State

The Picamera2 object follows a distinct lifecycle, managed by methods like configure(), start(), stop(), and close().

This state diagram illustrates the possible states and transitions of a Picamera2 object.

1. Unconfigured: The initial state after __init__. The camera is open but no streams are configured.
2. Configured: After configure() is called. Streams are defined and buffers are allocated, but the camera is not yet streaming.
3. Started: After start() is called. The camera is actively streaming frames. Captures and recording can occur.
4. Closed: After close() is called. All resources are released. The object can no longer be used.

Sources: picamera2/picamera2.py

Configuration

Camera configuration is managed through dictionary-based CameraConfiguration objects. The Picamera2 class provides helper methods to create standard configurations for different use cases.

Method	Description
create_preview_configuration()	Creates a configuration suitable for a live preview, typically with a display stream like XBGR8888.
create_still_configuration()	Creates a configuration for high-resolution still captures, often using the full sensor resolution.
create_video_configuration()	Creates a configuration optimized for video recording, often at standard resolutions like 720p or 1080p.

These methods return a dictionary that can be customized before being passed to the configure() method. A configuration dictionary defines streams (main, lores, raw), buffer count, color space, and initial controls.

# Example of creating and applying a still configuration
picam2 = Picamera2()
# The create_* methods return a dictionary
still_config = picam2.create_still_configuration()
# This dictionary can be modified before being applied
still_config["main"]["size"] = (1920, 1080)
# The configure method applies the configuration
picam2.configure(still_config)

Sources: picamera2/picamera2.py:616-773, apps/app_full.py:80-84

The configure() Method

The configure() method is the core of the configuration process. It takes a configuration dictionary (or a string like "preview", "still", "video") and performs the following steps:

1. Stops the camera if it is running.
2. Validates the user-provided configuration.
3. Translates the Python-style configuration into a libcamera configuration object.
4. Submits the configuration to libcamera, which may adjust it based on hardware constraints.
5. Updates the internal camera_config with the final, adjusted values.
6. Allocates memory buffers for all streams.
7. Sets initial camera controls specified in the configuration.

Sources: picamera2/picamera2.py:819-938

Sensor Configuration

For advanced use cases, the sensor key within a configuration dictionary allows direct control over the camera sensor's mode, such as output size and bit depth. If the sensor configuration is provided, it takes precedence over the raw stream configuration for selecting the hardware camera mode. If sensor is None or absent, the raw stream's properties are used instead.

# In this example, the sensor is explicitly set to a high-resolution mode.
# The raw stream will automatically match this.
picam2.still_configuration.sensor.output_size = max_mode['size']
picam2.still_configuration.sensor.bit_depth = max_mode['format'].bit_depth
picam2.configure("still")

Sources: tests/config_with_sensor.py:29-41, picamera2/picamera2.py:800-817

Capturing Images and Data

Picamera2 provides a suite of capture_* methods for retrieving data from the camera. These methods can operate synchronously (blocking until the capture is complete) or asynchronously.

Asynchronous Operations and Jobs

Most capture methods accept wait and signal_function parameters.

• wait=False: The method returns immediately with a Job object. The application can later call picam2.wait(job) to get the result.
• signal_function=my_func: A callback function my_func is registered, which will be called with the Job object as its argument once the operation is complete.

This sequence diagram shows a typical asynchronous file capture.

Key Capture Methods

Method	Return Type (Synchronous)	Description
capture_file()	dict (metadata)	Captures a frame and saves it to a file (e.g., JPEG, PNG, DNG).
capture_array()	np.ndarray	Captures a frame and returns it as a NumPy array. This involves a memory copy.
capture_buffer()	np.ndarray	Captures a frame and returns it as a 1D NumPy array (buffer). This involves a memory copy.
capture_request()	CompletedRequest	Returns the entire CompletedRequest object. The user is responsible for calling release() on it.
capture_metadata()	dict	Returns only the metadata from the next frame.

Sources: picamera2/picamera2.py:1172-1550

The CompletedRequest Object

The CompletedRequest object is a wrapper around a libcamera request that has been fulfilled. It is the primary way to access captured data and is returned by capture_request().

Key methods include:

• get_metadata(): Returns a dictionary of frame metadata (e.g., ExposureTime, AnalogueGain).
• make_array(name): Creates a NumPy array for the specified stream (e.g., "main", "lores").
• save(name, output): Saves the specified stream to a file.
• save_dng(output): Saves the raw stream as a DNG file.
• release(): Releases the request back to the camera system. This is crucial for preventing resource leaks.

The MappedArray class can be used with a CompletedRequest to access the underlying memory buffer without a copy, which is useful for in-place modifications.

Sources: picamera2/request.py:44-240, apps/app_full.py:38-55

Mode Switching

A powerful feature of Picamera2 is the ability to switch between different camera configurations on the fly. This is often used to have a low-resolution, high-framerate preview mode and switch to a high-resolution, low-framerate still capture mode only when taking a picture.

The switch_mode(camera_config) method handles this by stopping the camera, re-configuring it, and restarting it.

This diagram illustrates the flow of switch_mode_and_capture_file, which encapsulates the entire process of temporarily changing modes for a capture and then returning to the original state.

Sources: picamera2/picamera2.py:1212-1234, picamera2/picamera2.py:1269-1306, tests/switch_mode_exposure.py

Callbacks and Event Processing

The Picamera2 class allows user-defined functions to be executed at specific points in the frame processing pipeline.

• pre_callback: Called after a request is completed but before it is used for any other purpose (e.g., encoding, application copies). This is suitable for drawing overlays on frames that will be encoded or displayed.
• post_callback: Called after application copies have been made but before the frame is passed to any encoders.

# apps/app_full.py:40-42
def post_callback(request):
    metadata = request.get_metadata()
    # ... process and display metadata ...

picam2.post_callback = post_callback

The main event processing happens in the process_requests method, which is typically driven by a QSocketNotifier in a Qt application or by a NullPreview background thread for headless applications.

Sources: picamera2/picamera2.py:302-303, picamera2/picamera2.py:1021-1085, apps/app_full.py:37-60

Video Encoding

Picamera2 integrates video encoding through Encoder objects. The library provides H264Encoder and MJPEGEncoder.

• start_encoder(encoder, output): Attaches an encoder to the encode stream and starts it.
• stop_encoder(): Stops the attached encoder.
• start_recording(encoder, output): A convenience function that configures the camera for video, starts the encoder, and starts the camera.
• stop_recording(): Stops the camera and the encoder.

Multiple encoders can be run simultaneously.

Sources: picamera2/picamera2.py:1641-1711, CHANGELOG.md:175-177

Conclusion

The Picamera2 class serves as the primary entry point for developers using the picamera2 library. It provides a high-level, Pythonic API that abstracts the underlying libcamera complexities. Through its comprehensive set of methods for configuration, capture, and control, it supports a wide range of applications, from simple still photography to complex, multi-stream video processing with custom callbacks and hardware-accelerated encoding. Its design, centered around configuration dictionaries and asynchronous job handling, offers a flexible and powerful foundation for camera-based projects on the Raspberry Pi.

Sources: picamera2/picamera2.py, README.md