Configuration and Sensor Modes

Relevant source files

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

• picamera2/picamera2.py
• picamera2/configuration.py
• examples/still_capture_with_config.py
• tests/config_with_sensor.py
• apps/app_full.py
• tests/mode_test.py
• picamera2/devices/imx500/imx500.py

The picamera2 library provides a powerful and flexible system for configuring the camera. This is primarily managed through configuration objects and dictionaries that define stream properties, camera controls, and the underlying sensor mode. Users can use high-level helper methods to create standard configurations or dive deeper to select and customize specific sensor modes for advanced applications.

At its core, a camera configuration is a Python dictionary that specifies how different data streams (main, lores, raw) should be set up, along with other parameters like color space, transformations, and initial control values. The Picamera2 object provides methods to create, apply, and manage these configurations.

Camera Configuration

The Picamera2 class offers several ways to manage camera configurations, from simple helper methods for common use cases to direct manipulation of configuration dictionaries.

Configuration Helper Methods

The library provides three main helper methods to generate configurations for common tasks: preview, still image capture, and video recording.

Method	Default Main Stream Format	Default Main Stream Size	Use Case
create_preview_configuration()	XBGR8888	(640, 480)	Low-latency viewfinder applications.
create_still_configuration()	BGR888	self.sensor_resolution	High-resolution, high-quality still capture.
create_video_configuration()	XBGR8888	(1280, 720)	Video recording.

These methods return a configuration dictionary that can be further customized before being applied.

Sources: picamera2/picamera2.py:1003-1111

Structure of a Configuration Dictionary

A configuration is a dictionary that defines all aspects of the camera's operation. The key parameters are:

Key	Type	Description
use_case	str	A string like "preview", "still", or "video". Passed to the allocator.
transform	libcamera.Transform	Specifies image orientation (hflip, vflip).
colour_space	libcamera.ColorSpace	Defines the color space for YUV and RGB streams.
buffer_count	int	The number of frame buffers to allocate for each stream.
queue	bool	If True, picamera2 keeps the last completed request available for immediate capture.
main	dict	Configuration for the main, high-resolution stream.
lores	dict or None	Optional configuration for a low-resolution YUV stream, often used for display or video encoding.
raw	dict or None	Optional configuration for the raw sensor data stream.
controls	dict	A dictionary of control values (e.g., ExposureTime, AnalogueGain) to be applied when the camera starts.
sensor	dict or None	A dictionary to explicitly set the sensor's output size and bit depth, overriding defaults derived from the raw stream.
display	str or None	The name of the stream to be used for display in a preview window (e.g., "main" or "lores").
encode	str or None	The name of the stream to be passed to any active encoders (e.g., "main" or "lores").

A stream configuration dictionary (for main, lores, raw) contains keys like format (e.g., "XBGR8888"), size (a (width, height) tuple), and stride.

Sources: picamera2/picamera2.py:1003-1025, picamera2/picamera2.py:1141-1191

Applying a Configuration

Once a configuration dictionary is created, it is applied using the picam2.configure() method. This method must be called when the camera is stopped. It validates the configuration, translates it into a format libcamera understands, and configures the camera hardware.

The basic workflow is shown in the diagram below.

This diagram illustrates the standard process for configuring and starting the camera.

For example, to capture a still image with a specific configuration:

picam2 = Picamera2()
config = picam2.create_still_configuration()
picam2.configure(config)

Sources: examples/still_capture_with_config.py:9-11

Pre-defined Configuration Objects

For convenience, Picamera2 instances come with three pre-initialized CameraConfiguration objects: preview_configuration, still_configuration, and video_configuration. These can be used as shortcuts.

# This is equivalent to picam2.configure(picam2.preview_configuration)
picam2.configure("preview")

These objects can also be modified directly before being applied, offering an object-oriented alternative to manipulating the dictionary.

Sources: picamera2/picamera2.py:350-367, picamera2/picamera2.py:1294-1302

Sensor Modes

Sensor modes represent the native operating modes of the camera hardware. They define properties like resolution, bit depth, and maximum frame rate. The picamera2 library exposes these modes to allow for fine-grained control over the camera's output.

Querying Sensor Modes

The available sensor modes can be queried via the picam2.sensor_modes property. This returns a list of dictionaries, where each dictionary describes a single mode.

The properties of a sensor mode are:

Key	Type	Description
format	SensorFormat	The pixel format of the raw sensor data (e.g., SRGGB10_CSI2P).
unpacked	str	The "unpacked" version of the format string (e.g., SRGGB10).
bit_depth	int	The bit depth of the sensor data (e.g., 10, 12).
size	tuple	The resolution (width, height) of the mode.
fps	float	The maximum frame rate achievable in this mode.
crop_limits	tuple	The full field of view of the sensor in this mode.
exposure_limits	tuple	The minimum and maximum exposure times (in microseconds) for this mode.

Sources: picamera2/picamera2.py:592-626, tests/mode_test.py:59-62

Using Sensor Modes in Configurations

A sensor mode can be passed directly as the raw stream configuration. This is a convenient way to set the raw stream's size and format to match a specific hardware mode.

The following diagram shows how a user can select a sensor mode and apply it.

An example from apps/app_full.py shows how sensor modes are populated in a UI dropdown, allowing the user to select one to configure the camera for still capture or video recording.

# In vidTab class
self.raw_format.addItems([f'{x["format"].format} {x["size"]}, {x["fps"]:.0f}fps' for x in picam2.sensor_modes])

# ... later, when applying settings
picam2.video_configuration = picam2.create_video_configuration(
    main={"size": (self.resolution_w.value(), self.resolution_h.value())},
    raw=self.sensor_mode # self.sensor_mode gets the selected mode
)
switch_config("video")

Sources: apps/app_full.py:844-845, apps/app_full.py:890-894

Advanced Configuration with SensorConfiguration

The CameraConfiguration class provides an object-oriented interface to a configuration dictionary. A key feature is its sensor property, which is an instance of SensorConfiguration. This allows for more explicit control over the sensor's operating mode.

This class diagram shows the relationship between the main Picamera2 class and its configuration objects.

When picam2.configure() is called, the system determines the best hardware sensor mode to use. The SensorConfiguration provides a way to influence this choice directly.

1. If sensor configuration is provided: The system will try to find a sensor mode that best matches the specified output_size and bit_depth.
2. If sensor is None: The system falls back to matching based on the raw stream's configuration.

The tests/config_with_sensor.py file demonstrates this behavior clearly.

This sequence diagram shows how updating the SensorConfiguration and re-configuring the camera changes the underlying raw stream.

If the sensor configuration is cleared by setting it to None, the system reverts to using the raw stream properties to select the sensor mode.

# Clear the sensor config, now it should obey the raw stream config again.
picam2.still_configuration.sensor = None
picam2.still_configuration.raw.size = min_mode['size']
picam2.configure("still")

# The raw stream size will now be min_mode['size']
config = picam2.camera_configuration()

Sources: tests/config_with_sensor.py:73-77

Conclusion

The picamera2 library offers a layered approach to camera configuration. For most users, the create_*_configuration() helpers and pre-defined configuration objects provide a simple and effective way to set up the camera. For advanced users who need precise control over hardware capabilities, the sensor_modes property and the SensorConfiguration object provide the necessary tools to select specific sensor resolutions, bit-depths, and frame rates, ensuring optimal performance for demanding applications.