0
# Camera Configuration
1
2
Camera and stream configuration system for setting up different capture modes, stream parameters, and camera settings. The configuration system supports multiple concurrent streams with different resolutions and formats.
3
4
## Capabilities
5
6
### Configuration Creation
7
8
Create camera configurations optimized for different use cases.
9
10
```python { .api }
11
def create_preview_configuration(
12
main: dict = None,
13
lores: dict = None,
14
raw: dict = None,
15
transform: libcamera.Transform = None,
16
colour_space: libcamera.ColorSpace = None,
17
buffer_count: int = None,
18
controls: dict = None,
19
display: str = None,
20
encode: str = None
21
) -> CameraConfiguration:
22
"""
23
Create configuration optimized for real-time preview.
24
25
Parameters:
26
- main: dict, main stream configuration {"size": (width, height), "format": "format_name"}
27
- lores: dict, low-resolution stream configuration (optional)
28
- raw: dict, raw stream configuration (optional)
29
- transform: libcamera.Transform, image transform (rotation/flip)
30
- colour_space: libcamera.ColorSpace, color space specification
31
- buffer_count: int, number of buffers per stream
32
- controls: dict, camera control values
33
- display: str, stream name for display ("main", "lores")
34
- encode: str, stream name for encoding ("main", "lores")
35
36
Returns:
37
CameraConfiguration: Optimized for low-latency preview
38
"""
39
40
def create_still_configuration(
41
main: dict = None,
42
lores: dict = None,
43
raw: dict = None,
44
transform: libcamera.Transform = None,
45
colour_space: libcamera.ColorSpace = None,
46
buffer_count: int = None,
47
controls: dict = None,
48
display: str = None,
49
encode: str = None
50
) -> CameraConfiguration:
51
"""
52
Create configuration optimized for high-quality still capture.
53
54
Parameters: Same as create_preview_configuration
55
56
Returns:
57
CameraConfiguration: Optimized for maximum image quality
58
"""
59
60
def create_video_configuration(
61
main: dict = None,
62
lores: dict = None,
63
raw: dict = None,
64
transform: libcamera.Transform = None,
65
colour_space: libcamera.ColorSpace = None,
66
buffer_count: int = None,
67
controls: dict = None,
68
display: str = None,
69
encode: str = None
70
) -> CameraConfiguration:
71
"""
72
Create configuration optimized for video recording.
73
74
Parameters: Same as create_preview_configuration
75
76
Returns:
77
CameraConfiguration: Optimized for sustained video capture
78
"""
79
```
80
81
### Configuration Classes
82
83
Core configuration classes for camera and stream setup.
84
85
```python { .api }
86
class CameraConfiguration:
87
"""Camera configuration container."""
88
89
use_case: str # Configuration use case identifier
90
buffer_count: int # Number of buffers per stream
91
transform: libcamera.Transform # Image transform
92
colour_space: libcamera.ColorSpace # Color space
93
controls: Controls # Camera controls
94
display: str # Display stream name
95
encode: str # Encode stream name
96
97
# Stream configurations
98
main: StreamConfiguration # Main stream
99
lores: StreamConfiguration # Low-resolution stream
100
raw: StreamConfiguration # Raw stream
101
102
# Forwarded properties from main stream
103
@property
104
def size(self) -> tuple[int, int]:
105
"""Main stream size as (width, height)."""
106
107
@property
108
def format(self) -> str:
109
"""Main stream pixel format."""
110
111
def enable_lores(self, onoff: bool = True):
112
"""Enable or disable low-resolution stream."""
113
114
def enable_raw(self, onoff: bool = True):
115
"""Enable or disable raw stream."""
116
117
def align(self, optimal: bool = True):
118
"""Align stream configurations for optimal performance."""
119
120
class StreamConfiguration:
121
"""Individual stream configuration."""
122
123
size: tuple[int, int] # Stream dimensions (width, height)
124
format: str # Pixel format
125
stride: int # Row stride in bytes
126
framesize: int # Total frame size in bytes
127
preserve_ar: bool # Preserve aspect ratio flag
128
129
def align(self, optimal: bool = True):
130
"""Align size for optimal performance."""
131
132
class SensorConfiguration:
133
"""Sensor-level configuration."""
134
135
output_size: tuple[int, int] # Sensor output size
136
bit_depth: int # Bit depth per pixel
137
```
138
139
### Stream Management
140
141
Enable and configure multiple camera streams.
142
143
```python { .api }
144
def enable_lores(self, onoff: bool = True):
145
"""
146
Enable or disable low-resolution stream.
147
148
Parameters:
149
- onoff: bool, True to enable, False to disable
150
"""
151
152
def enable_raw(self, onoff: bool = True):
153
"""
154
Enable or disable raw stream.
155
156
Parameters:
157
- onoff: bool, True to enable, False to disable
158
"""
159
```
160
161
### Configuration Optimization
162
163
Optimize configurations for performance and compatibility.
164
165
```python { .api }
166
def align(self, optimal: bool = True):
167
"""
168
Align stream sizes for optimal performance.
169
170
Parameters:
171
- optimal: bool, use optimal alignment (may change sizes slightly)
172
"""
173
```
174
175
## Usage Examples
176
177
### Basic Configuration
178
179
```python
180
from picamera2 import Picamera2
181
182
picam2 = Picamera2()
183
184
# Simple still configuration with default settings
185
still_config = picam2.create_still_configuration()
186
print(f"Main stream: {still_config.size} {still_config.format}")
187
188
# Custom main stream size and format
189
still_config = picam2.create_still_configuration(
190
main={"size": (1920, 1080), "format": "RGB888"}
191
)
192
193
picam2.configure(still_config)
194
```
195
196
### Multi-Stream Configuration
197
198
```python
199
from picamera2 import Picamera2
200
201
picam2 = Picamera2()
202
203
# Configuration with main and low-resolution streams
204
config = picam2.create_video_configuration(
205
main={"size": (1920, 1080), "format": "YUV420"},
206
lores={"size": (640, 480), "format": "YUV420"}
207
)
208
209
# Specify which stream to use for display and encoding
210
config.display = "lores" # Use low-res for preview display
211
config.encode = "main" # Use high-res for recording
212
213
picam2.configure(config)
214
```
215
216
### Advanced Configuration
217
218
```python
219
from picamera2 import Picamera2
220
import libcamera
221
222
picam2 = Picamera2()
223
224
# Configuration with transforms and color space
225
config = picam2.create_still_configuration(
226
main={"size": (2592, 1944), "format": "RGB888"},
227
raw={"size": (2592, 1944)}, # Enable raw capture
228
transform=libcamera.Transform(hflip=1, vflip=1), # Flip image
229
colour_space=libcamera.ColorSpace.Rec709(),
230
buffer_count=2, # Use 2 buffers per stream
231
controls={"ExposureTime": 10000, "AnalogueGain": 1.0}
232
)
233
234
# Enable raw stream for advanced processing
235
config.enable_raw(True)
236
237
# Optimize for performance
238
config.align(optimal=True)
239
240
picam2.configure(config)
241
```
242
243
### Configuration Inspection
244
245
```python
246
from picamera2 import Picamera2
247
248
picam2 = Picamera2()
249
config = picam2.create_preview_configuration()
250
251
# Examine configuration details
252
print(f"Use case: {config.use_case}")
253
print(f"Buffer count: {config.buffer_count}")
254
print(f"Transform: {config.transform}")
255
256
# Stream details
257
print(f"Main stream: {config.main.size} {config.main.format}")
258
print(f"Frame size: {config.main.framesize} bytes")
259
print(f"Stride: {config.main.stride} bytes")
260
261
if config.lores:
262
print(f"Lores stream: {config.lores.size} {config.lores.format}")
263
```
264
265
### Dynamic Configuration Changes
266
267
```python
268
from picamera2 import Picamera2
269
270
picam2 = Picamera2()
271
272
# Start with preview configuration
273
preview_config = picam2.create_preview_configuration()
274
picam2.configure(preview_config)
275
picam2.start()
276
277
# Later switch to high-resolution still capture
278
picam2.stop()
279
still_config = picam2.create_still_configuration(
280
main={"size": (4056, 3040), "format": "RGB888"}
281
)
282
picam2.configure(still_config)
283
picam2.start()
284
285
# Now ready for high-quality capture
286
```