0
# Camera Controls
1
2
Advanced camera control system for setting exposure, gain, white balance, focus, and other camera parameters. The controls system provides both immediate parameter adjustment and thread-safe access for real-time applications.
3
4
## Capabilities
5
6
### Control Setting
7
8
Set camera controls individually or in groups with immediate effect.
9
10
```python { .api }
11
def set_controls(self, controls: dict):
12
"""
13
Set multiple camera controls.
14
15
Parameters:
16
- controls: dict, control name to value mapping
17
Common controls include:
18
- ExposureTime: int, exposure time in microseconds
19
- AnalogueGain: float, analog gain multiplier
20
- DigitalGain: float, digital gain multiplier
21
- Brightness: float, brightness adjustment (-1.0 to 1.0)
22
- Contrast: float, contrast adjustment (0.0 to 10.0)
23
- Saturation: float, saturation adjustment (0.0 to 10.0)
24
- AwbEnable: bool, automatic white balance enable
25
- AwbMode: int, white balance mode
26
- AeEnable: bool, automatic exposure enable
27
- AeExposureMode: int, exposure mode
28
- AfMode: int, autofocus mode
29
- AfTrigger: int, autofocus trigger
30
31
Raises:
32
- RuntimeError: If control values are invalid or out of range
33
"""
34
```
35
36
### Controls Class
37
38
Thread-safe controls interface for real-time parameter adjustment.
39
40
```python { .api }
41
class Controls:
42
"""Thread-safe camera controls interface."""
43
44
def __init__(self, picam2: Picamera2, controls: dict = None):
45
"""
46
Initialize Controls object.
47
48
Parameters:
49
- picam2: Picamera2 instance
50
- controls: dict, initial control values
51
"""
52
53
def set_controls(self, controls: dict):
54
"""
55
Update multiple controls from dictionary.
56
57
Parameters:
58
- controls: dict or Controls object with new values
59
"""
60
61
def __setattr__(self, name: str, value):
62
"""
63
Set individual control using attribute syntax.
64
65
Parameters:
66
- name: str, control name
67
- value: control value
68
69
Example:
70
controls.ExposureTime = 10000
71
controls.AnalogueGain = 2.0
72
"""
73
74
def __getattribute__(self, name: str):
75
"""
76
Get control value using attribute syntax.
77
78
Returns:
79
Current control value or raises AttributeError if not found
80
"""
81
82
def __enter__(self):
83
"""Context manager entry for thread-safe access."""
84
return self
85
86
def __exit__(self, exc_type, exc_val, exc_tb):
87
"""Context manager exit for thread-safe access."""
88
89
def get_libcamera_controls(self) -> dict:
90
"""
91
Convert to libcamera control format.
92
93
Returns:
94
dict: Controls in libcamera format
95
"""
96
97
def make_dict(self) -> dict:
98
"""
99
Convert to standard dictionary.
100
101
Returns:
102
dict: Control name to value mapping
103
"""
104
```
105
106
### Virtual Control Fields
107
108
Special control fields that provide convenient access to complex parameters.
109
110
```python { .api }
111
# FrameRate virtual field
112
@property
113
def FrameRate(self) -> float:
114
"""
115
Frame rate in frames per second (virtual field).
116
Maps to FrameDurationLimits with automatic conversion.
117
118
Setting this adjusts both minimum and maximum frame durations.
119
"""
120
121
@FrameRate.setter
122
def FrameRate(self, fps: float):
123
"""Set frame rate, converting to FrameDurationLimits."""
124
```
125
126
## Common Control Parameters
127
128
### Exposure Controls
129
130
```python { .api }
131
# Exposure time in microseconds
132
ExposureTime: int # Range typically 10-60000000 depending on sensor
133
134
# Automatic exposure enable
135
AeEnable: bool # True for auto, False for manual
136
137
# Exposure mode
138
AeExposureMode: int
139
# Common values:
140
# 0: Normal
141
# 1: Short
142
# 2: Long
143
# 3: Custom
144
145
# Exposure compensation
146
ExposureValue: float # Range typically -8.0 to 8.0 in EV units
147
148
# Metering mode
149
AeMeteringMode: int
150
# Common values:
151
# 0: Centre-weighted
152
# 1: Spot
153
# 2: Matrix
154
```
155
156
### Gain Controls
157
158
```python { .api }
159
# Analog gain multiplier
160
AnalogueGain: float # Range typically 1.0-16.0
161
162
# Digital gain multiplier
163
DigitalGain: float # Range typically 1.0-64.0
164
165
# Overall gain
166
Gain: float # Combined analog and digital gain
167
```
168
169
### White Balance Controls
170
171
```python { .api }
172
# Automatic white balance enable
173
AwbEnable: bool
174
175
# White balance mode
176
AwbMode: int
177
# Common values:
178
# 0: Auto
179
# 1: Incandescent
180
# 2: Tungsten
181
# 3: Fluorescent
182
# 4: Indoor
183
# 5: Daylight
184
# 6: Cloudy
185
186
# Manual color gains (when AwbEnable=False)
187
ColourGains: tuple[float, float] # (red_gain, blue_gain)
188
```
189
190
### Focus Controls
191
192
```python { .api }
193
# Autofocus mode
194
AfMode: int
195
# Common values:
196
# 0: Manual
197
# 1: Auto
198
# 2: Continuous
199
200
# Autofocus trigger
201
AfTrigger: int
202
# Values:
203
# 0: Idle
204
# 1: Start
205
# 2: Cancel
206
207
# Manual focus position (when AfMode=0)
208
LensPosition: float # Range 0.0-10.0 typically
209
```
210
211
### Image Enhancement
212
213
```python { .api }
214
# Brightness adjustment
215
Brightness: float # Range -1.0 to 1.0
216
217
# Contrast adjustment
218
Contrast: float # Range 0.0 to 10.0, 1.0 = normal
219
220
# Saturation adjustment
221
Saturation: float # Range 0.0 to 10.0, 1.0 = normal
222
223
# Sharpness adjustment
224
Sharpness: float # Range 0.0 to 10.0, 1.0 = normal
225
```
226
227
## Usage Examples
228
229
### Basic Control Setting
230
231
```python
232
from picamera2 import Picamera2
233
234
picam2 = Picamera2()
235
picam2.configure(picam2.create_preview_configuration())
236
picam2.start()
237
238
# Set controls using dictionary
239
picam2.set_controls({
240
"ExposureTime": 20000, # 20ms exposure
241
"AnalogueGain": 2.0, # 2x gain
242
"AwbEnable": False, # Manual white balance
243
"ColourGains": (1.2, 1.8) # Red and blue gains
244
})
245
246
# Check available controls
247
print("Available controls:")
248
for control, info in picam2.camera_controls.items():
249
print(f" {control}: {info}")
250
251
picam2.close()
252
```
253
254
### Using Controls Class
255
256
```python
257
from picamera2 import Picamera2, Controls
258
259
picam2 = Picamera2()
260
picam2.configure(picam2.create_preview_configuration())
261
picam2.start()
262
263
# Create controls object
264
controls = Controls(picam2)
265
266
# Set controls using attribute syntax
267
controls.ExposureTime = 10000
268
controls.AnalogueGain = 1.5
269
controls.Brightness = 0.1
270
271
# Apply all changes
272
picam2.set_controls(controls)
273
274
# Or use context manager for thread safety
275
with controls:
276
controls.ExposureTime = 30000
277
controls.AnalogueGain = 3.0
278
# Changes applied automatically on exit
279
280
picam2.close()
281
```
282
283
### Manual Exposure Control
284
285
```python
286
from picamera2 import Picamera2
287
import time
288
289
picam2 = Picamera2()
290
picam2.configure(picam2.create_still_configuration())
291
picam2.start()
292
293
# Disable automatic exposure
294
picam2.set_controls({
295
"AeEnable": False,
296
"ExposureTime": 5000, # 5ms
297
"AnalogueGain": 1.0
298
})
299
300
# Take bracket of exposures
301
exposures = [1000, 5000, 10000, 20000, 50000]
302
for i, exp_time in enumerate(exposures):
303
picam2.set_controls({"ExposureTime": exp_time})
304
time.sleep(0.1) # Allow settling
305
picam2.capture_file(f"exposure_{exp_time}us.jpg")
306
307
picam2.close()
308
```
309
310
### White Balance Control
311
312
```python
313
from picamera2 import Picamera2
314
315
picam2 = Picamera2()
316
picam2.configure(picam2.create_preview_configuration())
317
picam2.start()
318
319
# Try different white balance modes
320
wb_modes = {
321
"auto": {"AwbEnable": True, "AwbMode": 0},
322
"daylight": {"AwbEnable": True, "AwbMode": 5},
323
"tungsten": {"AwbEnable": True, "AwbMode": 2},
324
"manual_warm": {"AwbEnable": False, "ColourGains": (1.5, 1.2)},
325
"manual_cool": {"AwbEnable": False, "ColourGains": (1.0, 2.0)}
326
}
327
328
for name, settings in wb_modes.items():
329
picam2.set_controls(settings)
330
time.sleep(1) # Allow white balance to settle
331
picam2.capture_file(f"wb_{name}.jpg")
332
333
picam2.close()
334
```
335
336
### Focus Control
337
338
```python
339
from picamera2 import Picamera2
340
import time
341
342
picam2 = Picamera2()
343
picam2.configure(picam2.create_preview_configuration())
344
picam2.start()
345
346
# Enable continuous autofocus
347
picam2.set_controls({
348
"AfMode": 2, # Continuous AF
349
"AfTrigger": 0 # Idle
350
})
351
352
# Wait for focus to settle
353
time.sleep(2)
354
355
# Trigger single autofocus
356
picam2.set_controls({"AfTrigger": 1}) # Start AF
357
time.sleep(1) # Wait for focus
358
picam2.capture_file("autofocus.jpg")
359
360
# Manual focus sweep
361
picam2.set_controls({"AfMode": 0}) # Manual focus
362
focus_positions = [0.5, 1.0, 2.0, 5.0, 10.0]
363
for pos in focus_positions:
364
picam2.set_controls({"LensPosition": pos})
365
time.sleep(0.5)
366
picam2.capture_file(f"focus_{pos:.1f}.jpg")
367
368
picam2.close()
369
```
370
371
### Real-time Control Adjustment
372
373
```python
374
from picamera2 import Picamera2, Controls
375
import time
376
377
picam2 = Picamera2()
378
picam2.configure(picam2.create_preview_configuration())
379
picam2.start()
380
381
controls = Controls(picam2)
382
383
# Slowly increase exposure
384
for exp in range(1000, 50000, 1000):
385
controls.ExposureTime = exp
386
picam2.set_controls(controls)
387
time.sleep(0.1)
388
389
# Could capture frame or analyze preview here
390
print(f"Exposure: {exp}us")
391
392
picam2.close()
393
```
394
395
### Frame Rate Control
396
397
```python
398
from picamera2 import Picamera2, Controls
399
400
picam2 = Picamera2()
401
config = picam2.create_video_configuration()
402
picam2.configure(config)
403
picam2.start()
404
405
controls = Controls(picam2)
406
407
# Set frame rate using virtual field
408
controls.FrameRate = 30.0 # 30 fps
409
picam2.set_controls(controls)
410
411
# Or set manually using frame duration
412
picam2.set_controls({
413
"FrameDurationLimits": (33333, 33333) # 30fps (33.33ms per frame)
414
})
415
416
picam2.close()
417
```