0
# Picamera2
1

2
A comprehensive Python library that serves as the libcamera-based replacement for the original Picamera library, providing an intuitive Python API for interfacing with Raspberry Pi cameras. The library offers advanced camera control capabilities including configuration of multiple camera streams, capture of high-quality images and videos, real-time preview functionality, and extensive customization options for camera settings.
3

4
## Package Information
5

6
- **Package Name**: picamera2
7
- **Language**: Python
8
- **Installation**: `pip install picamera2`
9
- **Python Version**: >=3.9
10
- **Platform**: Raspberry Pi (Linux)
11

12
## Core Imports
13

14
```python
15
from picamera2 import Picamera2
16
```
17

18
For advanced functionality:
19

20
```python
21
from picamera2 import (
22
    Picamera2, Preview,
23
    CameraConfiguration, StreamConfiguration,
24
    Controls, Metadata,
25
    CompletedRequest, MappedArray,
26
    CancelledError
27
)
28
```
29

30
For device-specific features:
31

32
```python
33
from picamera2.devices.imx500 import IMX500
34
from picamera2.encoders import H264Encoder, JpegEncoder
35
from picamera2.outputs import FileOutput
36
from picamera2.previews import QtPreview
37
from picamera2.allocators import DmaAllocator, PersistentAllocator
38
```
39

40
## Basic Usage
41

42
```python
43
from picamera2 import Picamera2
44
import time
45

46
# Initialize camera
47
picam2 = Picamera2()
48

49
# Create and configure for still capture
50
camera_config = picam2.create_still_configuration()
51
picam2.configure(camera_config)
52

53
# Start camera
54
picam2.start()
55

56
# Wait for camera to settle
57
time.sleep(2)
58

59
# Capture image
60
picam2.capture_file("image.jpg")
61

62
# Stop camera
63
picam2.stop()
64
picam2.close()
65
```
66

67
## Architecture
68

69
The Picamera2 library is built on a modular architecture centered around the main `Picamera2` class:
70

71
- **Picamera2 Class**: Main camera interface providing high-level API for camera operations
72
- **Configuration System**: Manages camera, stream, and sensor configurations
73
- **Request Pipeline**: Handles asynchronous camera requests and completed frames
74
- **Encoder System**: Provides video and image encoding capabilities
75
- **Output System**: Manages various output destinations (files, streams, circular buffers)
76
- **Preview System**: Supports different preview display methods (Qt, DRM, headless)
77
- **Allocator System**: Handles memory allocation strategies for camera buffers
78
- **Device Integration**: Platform-specific support for AI sensors and accelerators
79

80
This modular design enables flexible camera applications from simple photography to complex computer vision systems while maintaining high performance through efficient memory management and optimized capture pipelines.
81

82
## Capabilities
83

84
### Core Camera Operations
85

86
Essential camera functionality including initialization, configuration, start/stop control, and basic capture operations. These form the foundation of all picamera2 applications.
87

88
```python { .api }
89
class Picamera2:
90
    def __init__(self, camera_num: int = 0, tuning: Tuning = None): ...
91
    def start(self, config: CameraConfiguration = None, show_preview: bool = None): ...
92
    def stop(self): ...
93
    def close(self): ...
94
    def configure(self, camera_config: CameraConfiguration): ...
95
```
96

97
[Core Camera Operations](./core-operations.md)
98

99
### Camera Configuration
100

101
Camera and stream configuration system for setting up different capture modes, stream parameters, and camera settings. Supports preview, still capture, and video recording configurations.
102

103
```python { .api }
104
def create_preview_configuration(
105
    main: dict = None,
106
    lores: dict = None, 
107
    raw: dict = None,
108
    **kwargs
109
) -> CameraConfiguration: ...
110

111
def create_still_configuration(
112
    main: dict = None,
113
    lores: dict = None,
114
    raw: dict = None, 
115
    **kwargs
116
) -> CameraConfiguration: ...
117

118
def create_video_configuration(
119
    main: dict = None,
120
    lores: dict = None,
121
    raw: dict = None,
122
    **kwargs
123
) -> CameraConfiguration: ...
124
```
125

126
[Camera Configuration](./configuration.md)
127

128
### Image and Video Capture
129

130
Comprehensive capture functionality supporting various output formats, synchronous and asynchronous operations, and different data types including files, arrays, and PIL images.
131

132
```python { .api }
133
def capture_file(self, file_output: str, name: str = "main", **kwargs): ...
134
def capture_array(self, name: str = "main", **kwargs) -> np.ndarray: ...
135
def capture_image(self, name: str = "main", **kwargs) -> PIL.Image: ...
136
def capture_buffer(self, name: str = "main", **kwargs) -> bytes: ...
137
def capture_buffers(self, names: list[str] = None, **kwargs) -> dict[str, bytes]: ...
138
def capture_request(self, **kwargs) -> CompletedRequest: ...
139
def capture_metadata(self, **kwargs) -> dict: ...
140
```
141

142
[Image and Video Capture](./capture.md)
143

144
### Camera Controls
145

146
Advanced camera control system for setting exposure, gain, white balance, focus, and other camera parameters with real-time adjustment capabilities.
147

148
```python { .api }
149
class Controls:
150
    def set_controls(self, controls: dict): ...
151
    def __setattr__(self, name: str, value): ...
152

153
def set_controls(self, controls: dict): ...
154
```
155

156
[Camera Controls](./controls.md)
157

158
### Video Recording and Encoding
159

160
Video recording capabilities with support for multiple encoders (H.264, MJPEG, etc.), various output formats, and hardware acceleration when available.
161

162
```python { .api }
163
def start_recording(self, encoder: Encoder, output: Output, **kwargs): ...
164
def stop_recording(self): ...
165
def start_encoder(self, encoder: Encoder, output: Output, **kwargs): ...
166
def stop_encoder(self, encoders: list = None): ...
167
```
168

169
[Video Recording and Encoding](./recording.md)
170

171
### Preview and Display
172

173
Preview system supporting multiple display methods including Qt widgets, DRM/KMS direct rendering, and headless operation with overlay support.
174

175
```python { .api }
176
def start_preview(self, preview: Preview = None, **kwargs): ...
177
def stop_preview(self): ...
178
def set_overlay(self, overlay): ...
179
```
180

181
[Preview and Display](./preview.md)
182

183
### Advanced Features
184

185
Advanced functionality including mode switching, autofocus control, frame dropping, device-specific AI sensor integration, and platform-specific optimizations.
186

187
```python { .api }
188
def switch_mode(self, camera_config: CameraConfiguration, **kwargs): ...
189
def autofocus_cycle(self, **kwargs): ...
190
def drop_frames(self, num_frames: int, **kwargs): ...
191
def wait(self, job, timeout: float = None): ...
192
def dispatch_functions(self, functions: list[callable], **kwargs): ...
193
```
194

195
[Advanced Features](./advanced.md)
196

197
### Memory Management and Allocators
198

199
Advanced memory allocation strategies for optimized performance including DMA buffers and persistent allocation for reduced overhead in high-performance applications.
200

201
```python { .api }
202
class DmaAllocator:
203
    def allocate(self, libcamera_config, use_case): ...
204

205
class PersistentAllocator:
206
    def allocate(self, libcamera_config, use_case): ...
207
    
208
class MappedArray:
209
    def __enter__(self) -> 'MappedArray': ...
210
    def __exit__(self, exc_type, exc_val, exc_tb): ...
211
    @property
212
    def array(self) -> np.ndarray: ...
213
```
214

215
## Types
216

217
```python { .api }
218
class CameraConfiguration:
219
    use_case: str
220
    buffer_count: int
221
    transform: libcamera.Transform
222
    colour_space: libcamera.ColorSpace
223
    controls: Controls
224
    main: StreamConfiguration
225
    lores: StreamConfiguration
226
    raw: StreamConfiguration
227

228
class StreamConfiguration:
229
    size: tuple[int, int]
230
    format: str
231
    stride: int
232
    framesize: int
233

234
class CompletedRequest:
235
    request: libcamera.Request
236
    config: CameraConfiguration
237
    def make_array(self, name: str = "main") -> np.ndarray: ...
238
    def make_image(self, name: str = "main") -> PIL.Image: ...
239
    def save(self, name: str, file_output: str, **kwargs): ...
240

241
class Controls:
242
    def set_controls(self, controls: dict): ...
243

244
class Metadata:
245
    def make_dict(self) -> dict: ...
246

247
class Job:
248
    def wait(self, timeout: float = None): ...
249
    def result(self): ...
250
    def signal(self): ...
251
    @property
252
    def finished(self) -> bool: ...
253

254
class CancelledError(Exception):
255
    """Exception raised when operations are cancelled."""
256

257
Preview = Literal["null", "drm", "qt", "qtgl"]
258
```