0
# Core Camera Operations
1

2
Essential camera functionality that forms the foundation of all picamera2 applications. These operations handle camera initialization, lifecycle management, and basic control functions.
3

4
## Capabilities
5

6
### Camera Initialization
7

8
Create and initialize a Picamera2 instance with optional camera selection and tuning parameters.
9

10
```python { .api }
11
def __init__(self, camera_num: int = 0, tuning: Tuning = None):
12
    """
13
    Initialize Picamera2 instance.
14
    
15
    Parameters:
16
    - camera_num: int, camera index (default 0 for first camera)
17
    - tuning: Tuning object or file path for camera tuning parameters
18
    
19
    Raises:
20
    - RuntimeError: If camera cannot be acquired or libcamera fails to initialize
21
    """
22
```
23

24
### Camera Lifecycle Control
25

26
Start, stop, and close camera operations with proper resource management.
27

28
```python { .api }
29
def start(self, config: CameraConfiguration = None, show_preview: bool = None):
30
    """
31
    Start the camera system.
32
    
33
    Parameters:
34
    - config: CameraConfiguration, optional configuration to apply before starting
35
    - show_preview: bool, whether to automatically start preview (if available)
36
    
37
    Raises:
38
    - RuntimeError: If camera fails to start or configuration is invalid
39
    """
40

41
def stop(self):
42
    """
43
    Stop the camera system and all active operations.
44
    
45
    Stops preview, encoders, and request processing. Camera remains configured
46
    and can be restarted with start().
47
    """
48

49
def close(self):
50
    """
51
    Close camera and release all resources.
52
    
53
    Stops camera if running, releases libcamera resources, and closes all
54
    associated objects. Camera cannot be used after closing.
55
    """
56
```
57

58
### Configuration Application
59

60
Apply camera configurations to set up streams and camera parameters.
61

62
```python { .api }
63
def configure(self, camera_config: CameraConfiguration):
64
    """
65
    Configure camera with specified configuration.
66
    
67
    Parameters:
68
    - camera_config: CameraConfiguration object defining camera setup
69
    
70
    Raises:
71
    - RuntimeError: If configuration is invalid or cannot be applied
72
    """
73
```
74

75
### Camera Information
76

77
Access camera properties and capabilities.
78

79
```python { .api }
80
@property
81
def camera_properties(self) -> dict:
82
    """
83
    Dictionary of camera properties including model, sensor capabilities, etc.
84
    
85
    Returns:
86
    dict: Camera properties from libcamera
87
    """
88

89
@property
90
def camera_controls(self) -> dict:
91
    """
92
    Dictionary of available camera controls and their ranges.
93
    
94
    Returns:
95
    dict: Available controls with min/max/default values
96
    """
97

98
@staticmethod
99
def global_camera_info() -> list[GlobalCameraInfo]:
100
    """
101
    Get information about all available cameras.
102
    
103
    Returns:
104
    list: List of GlobalCameraInfo dictionaries with camera details
105
    """
106
```
107

108
### Current Configuration Access
109

110
Retrieve current camera and stream configurations.
111

112
```python { .api }
113
def camera_configuration(self) -> CameraConfiguration:
114
    """
115
    Get current camera configuration.
116
    
117
    Returns:
118
    CameraConfiguration: Current active configuration
119
    """
120

121
def stream_configuration(self, name: str) -> StreamConfiguration:
122
    """
123
    Get configuration for specific stream.
124
    
125
    Parameters:
126
    - name: str, stream name ("main", "lores", "raw")
127
    
128
    Returns:
129
    StreamConfiguration: Configuration for specified stream
130
    
131
    Raises:
132
    - KeyError: If stream name is not found
133
    """
134
```
135

136
## Usage Examples
137

138
### Basic Camera Setup
139

140
```python
141
from picamera2 import Picamera2
142

143
# Initialize camera
144
picam2 = Picamera2()
145

146
# Check camera properties
147
print(f"Camera model: {picam2.camera_properties.get('Model', 'Unknown')}")
148
print(f"Available controls: {list(picam2.camera_controls.keys())}")
149

150
# Create and apply configuration
151
config = picam2.create_still_configuration()
152
picam2.configure(config)
153

154
# Start camera
155
picam2.start()
156

157
# Camera is now ready for capture operations
158
# ... perform captures ...
159

160
# Clean shutdown
161
picam2.stop()
162
picam2.close()
163
```
164

165
### Multiple Camera Setup
166

167
```python
168
from picamera2 import Picamera2
169

170
# Check available cameras
171
cameras = Picamera2.global_camera_info()
172
print(f"Found {len(cameras)} cameras")
173

174
for i, cam_info in enumerate(cameras):
175
    print(f"Camera {i}: {cam_info['Model']}")
176

177
# Initialize specific camera
178
if len(cameras) > 1:
179
    picam2 = Picamera2(camera_num=1)
180
else:
181
    picam2 = Picamera2()
182
```
183

184
### Configuration Lifecycle
185

186
```python
187
from picamera2 import Picamera2
188

189
picam2 = Picamera2()
190

191
# Create different configurations
192
preview_config = picam2.create_preview_configuration()
193
still_config = picam2.create_still_configuration()
194

195
# Start with preview
196
picam2.configure(preview_config)
197
picam2.start()
198

199
# Later switch to still capture
200
picam2.stop()
201
picam2.configure(still_config)
202
picam2.start()
203

204
# Camera ready for high-quality still capture
205
```