Getting Started

Relevant source files

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

• README.md
• setup.py
• CHANGELOG.md
• tools/checkstyle.py
• tests/test_list.txt
• tests/colour_spaces.py
• apps/app_full.py
• picamera2/picamera2.py
• tests/config_with_sensor.py
• picamera2/request.py
• examples/imx500/imx500_segmentation_demo.py
• picamera2/previews/q_gl_picamera2.py
• examples/opencv_mertens_merge.py

Picamera2 is the official, libcamera-based Python library for controlling Raspberry Pi cameras. It serves as the modern replacement for the original Picamera library, offering an accessible and powerful API for a wide range of camera applications. This library is currently in a beta release phase, with ongoing work focused on improving stability, documentation, and bug fixes.

The project provides numerous examples in the examples folder and more complex Qt application examples in the apps folder to help users get started.

Sources: README.md:10-17, setup.py:12-13

Installation

System Requirements

Supported Systems:

• Raspberry Pi OS Bullseye (or later), both 32-bit and 64-bit versions.
• As of September 2022, picamera2 is pre-installed on standard Raspberry Pi OS images.
• It is compatible with all Raspberry Pi boards, including the Pi Zero, though performance may vary on less powerful devices.

Unsupported Systems:

• Images based on Buster or earlier releases.
• Raspberry Pi OS Legacy images.
• Systems where the legacy camera stack has been re-enabled.

Sources: README.md:20-30

Installation Methods

The recommended way to install picamera2 is through the apt package manager, as this ensures that the versions of picamera2 and the underlying libcamera libraries are compatible.

• Full Installation (Recommended for desktop environments):

  sudo apt install python3-picamera2
  

• Reduced Installation (For headless/Lite systems):
  This version omits some window system-related dependencies.

  sudo apt install python3-picamera2 --no-install-recommends
  

While installation via pip is possible, it is not recommended because it does not guarantee compatibility with the system's libcamera version.

Sources: README.md:31-41

Dependencies

The library relies on several Python packages. The core dependencies are installed automatically, while GUI-related dependencies are optional.

Dependency	Purpose	GUI Extra?
numpy	Core numerical operations and image array handling.	No
PiDNG	DNG (RAW) file creation.	No
piexif	Manipulation of EXIF data in JPEGs.	No
pillow	The Python Imaging Library (PIL) for image manipulation.	No
simplejpeg	A fast, optimized JPEG encoder.	No
v4l2-python3	Bindings for the Video4Linux2 API.	No
python-prctl	Python wrapper for prctl(2).	No
av	Bindings for FFmpeg libraries (e.g., for MP4 encoding).	No
pyopengl	Python bindings for OpenGL, used by QGlPicamera2.	Yes
PyQt5	Qt GUI framework for creating preview windows.	Yes

Sources: setup.py:38-41

Basic Usage

The fundamental workflow for using picamera2 involves initializing the camera, configuring it for a specific use case (like preview or still capture), starting the camera stream, performing one or more captures, and finally stopping the camera.

This diagram illustrates the typical sequence of operations for a simple capture.

Sources: picamera2/picamera2.py, examples/opencv_mertens_merge.py

Core Concepts

The Picamera2 Class

The Picamera2 class is the central component of the library. It manages all interactions with the camera hardware.

• Initialization: picam2 = Picamera2() finds and opens the default camera. You can specify a camera index with Picamera2(camera_num=1).
• Configuration: The configure() method applies a specific camera configuration, preparing the hardware for a certain type of capture (e.g., high-resolution still or standard-definition video).
• Lifecycle: The start() and stop() methods control the camera stream. The camera must be stopped before it can be reconfigured.
• Capture: A suite of capture_* methods (capture_file, capture_array, capture_request) are available to get image data from the camera.

Sources: picamera2/picamera2.py:202-229, picamera2/picamera2.py:734-752

Camera Configurations

A camera configuration is a Python dictionary that defines how the camera should operate, including resolution, color space, and frame rates. Picamera2 provides helper methods to create standard configurations.

• create_preview_configuration(): For live viewfinder streams.
• create_still_configuration(): For high-resolution still image captures.
• create_video_configuration(): For recording video.

These methods return a dictionary that can be customized before being passed to picam2.configure(). The main components of a configuration are the different output streams.

This diagram shows the structure of a typical configuration dictionary.

The CompletedRequest Object

When you capture an image, you receive a CompletedRequest object. This object is a wrapper around the captured frame buffer and its associated metadata. It is crucial to manage this object correctly to avoid stalling the camera pipeline.

• Data Access: Provides methods to access the image data in various formats:
  • make_array(): Returns a NumPy array.
  • make_image(): Returns a Pillow (PIL) Image.
  • save(): Saves the image directly to a file (e.g., JPEG, PNG).
  • save_dng(): Saves a RAW image to a DNG file.
• Metadata: get_metadata() returns a dictionary of all the metadata associated with the frame (e.g., exposure time, gain).
• Lifecycle: A CompletedRequest holds onto a camera buffer. You must call release() on the object when you are finished with it to return the buffer to the camera system. A with picam2.captured_request() as request: block can be used to manage this automatically.

Sources: picamera2/request.py:46-248, picamera2/picamera2.py:1612-1619

This class diagram shows the main methods of the CompletedRequest class.

Example Walkthrough: HDR Imaging

The example examples/opencv_mertens_merge.py demonstrates a simple High Dynamic Range (HDR) imaging technique. It captures three images at different exposure levels and merges them using OpenCV.

The sequence of operations is as follows:

1. Start the camera and capture metadata to determine a "normal" exposure level.
2. Stop the camera and reconfigure it to use manual exposure controls.
3. Capture three arrays: one with a short exposure, one with the normal exposure, and one with a long exposure.
4. Use cv2.createMergeMertens() to blend the three images into a single HDR result.

This sequence diagram illustrates the interactions between the user script and the Picamera2 object.

Advanced Usage: GUI Applications

For more complex applications, such as those with a graphical user interface, picamera2 integrates with the Qt framework. The apps/app_full.py file is a comprehensive example of this.

• Preview: The QGlPicamera2 class provides an efficient, OpenGL-accelerated preview widget.
• Event Loop: The application is event-driven. QGlPicamera2 uses a QSocketNotifier to listen for new frames from the camera. When a frame is ready, a signal is emitted, which triggers the handle_requests slot.
• Callbacks: The pre_callback and post_callback hooks on the Picamera2 object can be used to process metadata or draw overlays on frames as they arrive, before they are displayed or encoded.

The following diagram shows the data flow in a Qt-based application.

Contributing

Contributions to picamera2 are welcome. The development process follows standard open-source practices.

• Branches: Development for upcoming releases occurs on the next branch. The main branch corresponds to the current stable release.
• Pull Requests: PRs should be restricted to a single feature or fix and have a clean, reviewable commit history.
• Commit Messages: Commits must be signed off using Signed-off-by: Your Name <your.email@your.domain>.
• Coding Style: The project follows the PEP 8 style guide. A pre-commit hook is provided to help enforce this. To install it, run:

  pip3 install pre-commit
  pre-commit install
  

• Testing: Before submitting a pull request, ensure all automated tests pass by running the tools/run_tests script.

Sources: README.md:47-92, tools/checkstyle.py