repository·main·Indexed 22 days ago
https://github.com/raspberrypi/picamera2A libcamera-based Python interface for the Raspberry Pi camera stack, serving as the modern replacement for the legacy Picamera library. It provides high-level abstractions for camera control, stream management, and sensor configuration. Key features include support for YUV, RGB, and Bayer formats, DMA buffer allocation via DmaHeap, and utility methods for color space conversion and hardware-aligned stream sizing. Compatible with Raspberry Pi OS Bullseye and later on all Raspberry Pi boards.
Picamera2 is a libcamera-based replacement for the legacy Picamera Python interface.
Picamera2 is available via apt. It is recommended to use apt instead of pip to ensure compatibility between the Picamera2 Python package and the underlying libcamera libraries.
For a full installation including window system related elements:
sudo apt install python3-picamera2For a reduced installation (suitable for Raspberry Pi OS Lite) with fewer window system elements:
sudo apt install python3-picamera2 --no-install-recommendsA Job is an operation delegated to the Picamera2 camera event loop. While many jobs perform a single task (like copying a numpy array), complex jobs may consist of a sequence of functions that represent different stages (e.g., switching modes or waiting for controls).
Each function in a job's sequence must return a tuple: (done, result).
done (bool): If True, the current stage is complete, and the next function in the list will be attempted on the next frame. If False, the job stays at the current stage and will be retried.result (Any): The value returned by the function. The final result of the Job is the result returned by the very last function in the sequence.Jobs are typically created via Picamera2.dispatch_functions() or through high-level convenience methods like Picamera2.switch_mode_and_capture_array().
Many Picamera2 methods (like capture_file, switch_mode, drop_frames) support asynchronous execution by setting wait=False.
When wait=False, the method returns a Job object immediately. You can then use job.get_result(timeout=...) to block until the operation is complete and retrieve the result (such as metadata or a return value). This allows the main application thread to remain responsive or perform other tasks while the camera hardware processes the request.
picamera2 automatically attempts to set QT_QPA_PLATFORM to xcb to ensure compatibility with the underlying graphics layers. This is handled internally during package initialization if XDG_SESSION_TYPE is set to wayland.The picamera2 library uses a hierarchy of Configuration classes to manage settings for the camera, its sensor, and various streams (main, low-resolution, and raw).
Key features include:
_ALLOWED_FIELDS can be set; attempting to set others raises a RuntimeError._FIELD_CLASS_MAP (like lores or main) automatically converts that dictionary into the appropriate configuration object (e.g., StreamConfiguration)._FORWARD_FIELDS allows setting attributes on a parent object that are actually applied to a child object (e.g., setting CameraConfiguration.size updates CameraConfiguration.main.size)..make_dict().A CompletedRequest acts as a container and manager for buffers acquired from the camera allocator.
CompletedRequest object acquires the buffers and synchronizes them so they are ready for CPU access.acquire(). This increments an internal ref_count.release() is called, the ref_count decrements. Only when ref_count reaches zero does the object:If you fail to call release(), you will eventually run out of available buffers, causing the camera system to stall.
transform_to_orientation(transform) to map a libcamera.Transform object to a libcamera.Orientation enum. This is necessary because Transform objects cannot be used directly as dictionary keys and require manual lookup. If the transform does not match a known configuration in the internal mapping, a RuntimeError is raised.If you need to change the camera configuration (e.g., from a preview mode to a high-resolution still mode) to perform a capture, use these methods. They handle the mode switch, the capture, and the return to the original mode automatically.
Warning: Frequent mode switching may increase the risk of CMA heap fragmentation. For safer operations, consider using switch_mode_capture_request_and_stop and releasing the request before restarting the original mode.
Available methods:
switch_mode_and_capture_request(camera_config, ...)switch_mode_and_capture_buffer(camera_config, name="main", ...)switch_mode_and_capture_array(camera_config, name="main", ...)switch_mode_and_capture_image(camera_config, name="main", ...)Picamera2 provides several methods to convert camera frames into usable data formats:
capture_array(name="main"): Returns a 2D NumPy array (image) from the named stream.capture_buffer(name="main"): Returns a 1D NumPy array (buffer) from the named stream.capture_buffers(names=["main"]): Returns a tuple containing a list of 1D NumPy arrays and the frame metadata.capture_arrays(names=["main"]): Returns a tuple containing a list of 2D NumPy arrays and the frame metadata.capture_image(name="main"): Returns a PIL Image.Image object.All these methods support wait and signal_function for asynchronous control.
The picamera2 package provides high-level abstractions for camera control and stream management. The primary entry points for interacting with the camera are Picamera2 and Preview.
Key modules exported by the package include:
Picamera2: The main camera interface.Preview: For displaying a camera preview.CameraConfiguration and StreamConfiguration: For configuring camera and stream parameters.Controls: For managing camera controls.Metadata: For accessing frame metadata.SensorFormat: For querying sensor capabilities.MappedArray and CompletedRequest: For handling captured data and request lifecycles.For command-line applications, use these high-level functions to capture a sequence of images without manually managing mode switches and delays.
start_and_capture_file(name="image.jpg", ...): Captures a single image. It handles switching from preview mode to still mode, applying an initial delay, and saving the file.start_and_capture_files(name="image{:03d}.jpg", ...): Captures multiple images. Use a format directive (like {:03d}) in the name string to automatically increment the filename.Key Parameters:
initial_delay: Seconds to wait in preview mode before the first capture.preview_mode: Configuration to use during the preview phase.capture_mode: Configuration to use during the capture phase.num_files: Number of images to capture.delay: Delay between subsequent captures.exif_data: A dictionary of EXIF data (compatible with piexif) to be applied to the captured files.