Camera Controls

Relevant source files

The following files were used as context for generating this wiki page: - [picamera2/controls.py](https://github.com/przkos/picamera2/blob/HEAD/picamera2/controls.py) - [examples/controls.py](https://github.com/przkos/picamera2/blob/HEAD/examples/controls.py) - [examples/exposure_fixed.py](https://github.com/przkos/picamera2/blob/HEAD/examples/exposure_fixed.py) - [examples/zoom.py](https://github.com/przkos/picamera2/blob/HEAD/examples/zoom.py) - [picamera2/picamera2.py](https://github.com/przkos/picamera2/blob/HEAD/picamera2/picamera2.py) - [apps/app_full.py](https://github.com/przkos/picamera2/blob/HEAD/apps/app_full.py) - [tests/autofocus_test.py](https://github.com/przkos/picamera2/blob/HEAD/tests/autofocus_test.py)

The picamera2 library provides a powerful and flexible mechanism for adjusting camera parameters in real-time. These "controls" allow for fine-tuning of image properties such as exposure, gain, white balance, saturation, contrast, and digital zoom. The system is designed to be intuitive, offering an object-oriented interface to the underlying libcamera control system.

Controls are managed through the Controls class, which is accessible via the controls attribute of a Picamera2 instance (e.g., picam2.controls). This object acts as a dictionary, storing control values that are applied to the camera with the next submitted request. This ensures that changes are synchronized with the camera's frame processing pipeline.

Sources: picamera2/controls.py, picamera2/picamera2.py:1450-1452

Core Concepts

The Controls Class

The Controls class is a wrapper that provides an object-like view of the camera's control list. It allows for getting and setting control values using standard attribute access.

This diagram shows the relationship between the Picamera2 object and its Controls helper.

The Controls object maintains an internal dictionary of control values. When you set an attribute on picam2.controls, it updates this dictionary. These pending changes are then bundled with the next frame request sent to the camera hardware.

Sources: picamera2/controls.py:11-48, picamera2/picamera2.py:465

Applying Controls

There are three primary ways to set camera controls:

1. Direct Attribute Assignment: Set controls individually as if they were attributes of the controls object. This is the most common and intuitive method.

   # examples/controls.py:10-10
   picam2.controls.ExposureTime = 20000
   

   Sources: examples/controls.py:10

2. Dictionary Update with set_controls: Set multiple controls at once by passing a dictionary to the set_controls method.

   # tests/aegc.py:10-10
   picam2.set_controls({control: value})
   

   This is useful for applying a group of settings simultaneously. The AECTab in the full application example uses this method extensively to manage groups of related controls.
   Sources: tests/aegc.py:10, apps/app_full.py:1001-1002

3. Context Manager: The controls object can be used as a context manager. This is particularly useful for applying a control temporarily and ensuring it reverts to its previous state, although the examples primarily use it for applying a single set of changes.

   # examples/zoom.py:15-16
   with picam2.controls as controls:
       controls.ScalerCrop = (x, y, w, h)
   

   Sources: examples/zoom.py:15-16, picamera2/controls.py:33-40

The following sequence diagram illustrates the flow of setting a control and its application.

Available Controls

The picamera2 library exposes a wide range of controls available from libcamera. You can query the available controls and their valid ranges (minimum, maximum, and default values) through the camera_controls property.

# picamera2/picamera2.py:461-464
@property
def camera_controls(self) -> dict[str, tuple[Any, Any, Any]]:
    return {k: (utils.convert_from_libcamera_type(v[1].min),
                utils.convert_from_libcamera_type(v[1].max),
                utils.convert_from_libcamera_type(v[1].default)) for k, v in self.camera_ctrl_info.items()}

Sources: picamera2/picamera2.py:461-464

The following table lists some of the most common controls.

Control Name	Description	Value Type	Example Usage
ExposureTime	Sets the exposure time in microseconds. Setting it to 0 enables auto-exposure.	int	picam2.controls.ExposureTime = 10000
AnalogueGain	Sets the analogue gain of the sensor. Setting it to 0 enables auto-gain.	float	picam2.controls.AnalogueGain = 2.0
AeEnable	Enables or disables the Auto Exposure Control (AEC) algorithm.	bool	picam2.controls.AeEnable = False
AwbEnable	Enables or disables the Auto White Balance (AWB) algorithm.	bool	picam2.controls.AwbEnable = False
ColourGains	Sets manual Red and Blue colour gains when AWB is disabled.	tuple(float, float)	picam2.controls.ColourGains = (1.5, 1.2)
Brightness	Adjusts the image brightness.	float	picam2.controls.Brightness = 0.1
Contrast	Adjusts the image contrast.	float	picam2.controls.Contrast = 1.2
Saturation	Adjusts the image colour saturation.	float	picam2.controls.Saturation = 1.5
Sharpness	Adjusts the image sharpness.	float	picam2.controls.Sharpness = 1.0
ScalerCrop	Defines the digital zoom window as (x, y, width, height).	tuple(int, int, int, int)	picam2.controls.ScalerCrop = (100, 100, 640, 480)
AfMode	Sets the Autofocus mode (e.g., Auto, Continuous, Manual).	AfModeEnum	picam2.set_controls({'AfMode': controls.AfModeEnum.Continuous})
AfTrigger	Triggers an autofocus cycle.	AfTriggerEnum	picam2.set_controls({'AfTrigger': controls.AfTriggerEnum.Start})

Sources: apps/app_full.py:1120-1143, 1024-1043, examples/zoom.py:16, tests/autofocus_test.py:34

Control Categories

Exposure and Gain (AEC)

Automatic Exposure Control (AEC) can be disabled to set manual exposure values. This is useful for scenarios requiring consistent image brightness, such as time-lapses or scientific imaging.

To set a fixed exposure time and analogue gain, you must first disable AEC.

# examples/exposure_fixed.py:9-12
picam2.set_controls({"AeEnable": False, "AwbEnable": False, "FrameRate": 30})
# And wait for those settings to take effect
time.sleep(1)

# Set a fixed exposure time and analogue gain
picam2.set_controls({"ExposureTime": 20000, "AnalogueGain": 1.0})

When AeEnable is True, the camera automatically adjusts ExposureTime and AnalogueGain. When False, the user-provided values are used. Setting ExposureTime or AnalogueGain to 0 re-enables the automatic algorithm for that specific control.

Sources: examples/exposure_fixed.py:9-16, tests/aegc.py:21-23

White Balance (AWB)

Similar to AEC, Auto White Balance (AWB) can be disabled to set manual colour gains. This is useful for environments with consistent but unusual lighting.

# To disable AWB and set manual gains
picam2.set_controls({"AwbEnable": False, "ColourGains": (2.0, 1.5)})

The ColourGains tuple corresponds to (red_gain, blue_gain).

Sources: apps/app_full.py:1046-1052

Digital Zoom (ScalerCrop)

Digital zoom is achieved by manipulating the ScalerCrop control. This control defines a rectangular region of the full sensor area that is then scaled up to the size of the output stream. By changing the size and position of this rectangle, you can pan and zoom digitally.

The ScalerCrop is a tuple of (x, y, width, height).

This diagram illustrates how a smaller ScalerCrop rectangle results in a zoomed-in image.

The zoom.py example demonstrates how to implement a smooth digital zoom by progressively shrinking the ScalerCrop rectangle towards the center of the image.

# examples/zoom.py:11-20
size = picam2.capture_metadata()['ScalerCrop'][2:]
full_res = picam2.camera_properties['PixelArraySize']
picam2.start()

for i in range(1, 100):
    # In this example, we're zooming in on the centre of the image.
    x = (full_res[0] - size[0] / i) // 2
    y = (full_res[1] - size[1] / i) // 2
    with picam2.controls as controls:
        controls.ScalerCrop = (x, y, size[0] // i, size[1] // i)

The full application in apps/app_full.py contains a panZoomDisplay widget that provides an interactive way to control ScalerCrop via mouse movements and scrolling for panning and zooming.

Sources: examples/zoom.py:11-20, apps/app_full.py:700-781

Autofocus (AF)

For camera modules that support it, picamera2 provides controls for autofocus. Key controls include:

• AfMode: Can be set to Continuous, Auto, or Manual.
• AfTrigger: Used to start a new AF cycle in Auto mode.
• LensPosition: Manually sets the lens position when AfMode is Manual.

The library also provides a convenient high-level method, autofocus_cycle(), which triggers an AF cycle and waits for it to complete.

# tests/autofocus_test.py:59-60
print("Try AF cycle from lens position", i)
result = picam2.autofocus_cycle()

This method returns True if the focus was successful. The underlying implementation sets the AfMode to Auto and AfTrigger to Start, then waits for the AfState metadata to report Focused or Failed.

Sources: tests/autofocus_test.py:59-60, picamera2/picamera2.py:2286-2304

Summary

The camera control system in picamera2 is a fundamental feature for tailoring image output. It provides a simple yet powerful API to manipulate a wide range of hardware parameters. By using the controls object, the set_controls() method, or querying the camera_controls property, developers can dynamically adjust everything from basic brightness and contrast to advanced features like digital zoom and autofocus. The provided examples and the full GUI application serve as excellent references for implementing these controls in practice.