1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
//! Simplified camera interface definitions.
//!
//! The interfaces focus on two core capabilities:
//! 1. Querying supported camera configurations.
//! 2. Processing asynchronous video streams.
use crate::pixels::Pixels as Array3;
use crate::{
CameraConfig, CameraControlRange, CameraControlType, CameraControlValue, CameraDeviceInfo,
CameraResult,
};
use std::time::Duration;
/// Simplified camera management interface.
pub trait CameraManager {
/// Lists all available camera devices.
fn list_devices() -> CameraResult<Vec<CameraDeviceInfo>>;
/// Returns the configurations supported by a device.
fn get_supported_configs(device_index: u32) -> CameraResult<Vec<CameraConfig>>;
/// Checks whether a device supports a specific configuration.
fn is_config_supported(device_index: u32, config: &CameraConfig) -> CameraResult<bool>;
}
/// Streaming camera interface backed by a ring buffer.
#[allow(async_fn_in_trait)]
pub trait StreamingCamera: Send + Sync {
/// Shared snapshots supplied by native callback/worker backends.
fn frame_hub(&self) -> Option<&crate::FrameHub> {
None
}
fn get_shared_frame(&self) -> CameraResult<Option<std::sync::Arc<crate::CapturedFrame>>> {
self.frame_hub().map(|hub| hub.latest()).ok_or_else(|| {
crate::CameraError::stream_error("Shared frames unavailable for this backend".into())
})
}
async fn wait_for_shared_frame(
&self,
after: Option<crate::FrameKey>,
timeout: Duration,
) -> CameraResult<std::sync::Arc<crate::CapturedFrame>> {
self.frame_hub()
.ok_or_else(|| {
crate::CameraError::stream_error(
"Shared frames unavailable for this backend".into(),
)
})?
.wait_after(after, timeout)
.await
}
/// Starts the asynchronous video stream.
///
/// Once started, frames are captured in the background and stored in the ring buffer.
async fn start_stream(&self, config: CameraConfig) -> CameraResult<()>;
/// Stops the video stream.
async fn stop_stream(&self) -> CameraResult<()>;
/// Returns the latest frame immediately without blocking.
///
/// Returns `None` when the buffer is empty.
/// The returned `Array3<u8>` contains RGB data shaped as `(height, width, 3)`.
fn get_latest_frame(&self) -> CameraResult<Option<Array3<u8>>>;
/// Waits for the next frame until the timeout expires.
/// The returned `Array3<u8>` contains RGB data shaped as `(height, width, 3)`.
async fn wait_for_frame(&self, timeout: Duration) -> CameraResult<Array3<u8>>;
/// Returns whether the stream is running.
fn is_streaming(&self) -> bool;
/// Returns the current configuration.
fn get_config(&self) -> Option<CameraConfig>;
/// Returns stream statistics.
fn get_stats(&self) -> StreamStats;
/// Sets the buffer size by reconfiguring the ring buffer.
async fn set_buffer_size(&self, size: usize) -> CameraResult<()>;
}
/// Stream statistics.
#[derive(Debug, Clone, Default)]
pub struct StreamStats {
/// Total number of captured frames.
pub total_frames: u64,
/// Number of frames dropped because the buffer was full.
pub dropped_frames: u64,
/// Current frame rate.
pub current_fps: f64,
/// Current buffer capacity.
pub buffer_size: usize,
/// Current number of frames in the buffer.
pub buffered_frames: usize,
/// Running time in seconds.
pub uptime_seconds: u64,
}
impl StreamStats {
/// Calculates the frame drop ratio.
pub fn drop_rate(&self) -> f64 {
if self.total_frames == 0 {
0.0
} else {
self.dropped_frames as f64 / self.total_frames as f64
}
}
/// Calculates buffer utilization.
pub fn buffer_usage(&self) -> f64 {
if self.buffer_size == 0 {
0.0
} else {
self.buffered_frames as f64 / self.buffer_size as f64
}
}
}
// ============================================================================
// Camera control interface.
// ============================================================================
/// Camera control parameter interface.
#[allow(async_fn_in_trait)]
pub trait CameraControl {
/// Returns the current value of the specified control.
fn get_control(&self, control: CameraControlType) -> CameraResult<CameraControlValue>;
/// Sets the specified control value.
fn set_control(
&self,
control: CameraControlType,
value: CameraControlValue,
) -> CameraResult<()>;
/// Returns the valid range for the specified control.
fn get_control_range(&self, control: CameraControlType) -> CameraResult<CameraControlRange>;
/// Checks whether the device supports the specified control.
fn supports_control(&self, control: CameraControlType) -> bool;
/// Returns all controls supported by the device.
fn get_supported_controls(&self) -> Vec<CameraControlType>;
/// Resets the specified control to its default value.
fn reset_control(&self, control: CameraControlType) -> CameraResult<()> {
let range = self.get_control_range(control)?;
self.set_control(control, CameraControlValue::manual(range.default))
}
/// Resets all controls to their default values.
fn reset_all_controls(&self) -> CameraResult<()> {
let mut failures = Vec::new();
for control in self.get_supported_controls() {
if let Err(error) = self.reset_control(control) {
failures.push(std::sync::Arc::new(
error.with_operation(format!("{control:?}")),
));
}
}
if failures.is_empty() {
Ok(())
} else {
Err(crate::CameraError::control_batch(failures))
}
}
}
#[cfg(test)]
mod camera_control_tests {
use super::*;
#[test]
fn test_stream_stats_default() {
let stats = StreamStats::default();
assert_eq!(stats.total_frames, 0);
assert_eq!(stats.dropped_frames, 0);
assert_eq!(stats.current_fps, 0.0);
assert_eq!(stats.buffer_size, 0);
assert_eq!(stats.buffered_frames, 0);
assert_eq!(stats.uptime_seconds, 0);
}
#[test]
fn test_stream_stats_drop_rate() {
let mut stats = StreamStats::default();
// No captured frames means a zero drop ratio.
assert_eq!(stats.drop_rate(), 0.0);
// Captured frames with no drops.
stats.total_frames = 100;
stats.dropped_frames = 0;
assert_eq!(stats.drop_rate(), 0.0);
// Some captured frames were dropped.
stats.dropped_frames = 10;
assert_eq!(stats.drop_rate(), 0.1);
// Every captured frame was dropped.
stats.dropped_frames = 100;
assert_eq!(stats.drop_rate(), 1.0);
}
#[test]
fn test_stream_stats_buffer_usage() {
let mut stats = StreamStats::default();
// No buffer means zero utilization.
assert_eq!(stats.buffer_usage(), 0.0);
// Empty buffer.
stats.buffer_size = 10;
stats.buffered_frames = 0;
assert_eq!(stats.buffer_usage(), 0.0);
// Half-full buffer.
stats.buffered_frames = 5;
assert_eq!(stats.buffer_usage(), 0.5);
// Full buffer.
stats.buffered_frames = 10;
assert_eq!(stats.buffer_usage(), 1.0);
}
#[test]
fn test_stream_stats_calculations() {
let stats = StreamStats {
total_frames: 1000,
dropped_frames: 50,
current_fps: 29.5,
buffer_size: 20,
buffered_frames: 15,
uptime_seconds: 60,
};
assert_eq!(stats.drop_rate(), 0.05);
assert_eq!(stats.buffer_usage(), 0.75);
}
}