generic_camera/
controls.rs

1/*!
2 * # Controls
3 * Defines standard controls for cameras.
4 */
5#[allow(unused_imports)]
6use crate::PropertyType;
7use documented::{Documented, DocumentedVariants};
8use serde::{Deserialize, Serialize};
9
10#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Hash, Eq)]
11/// A custom name for a control.
12///
13/// This is a 32-byte array that can be used to store a custom name for a control.
14///
15/// # Note
16/// The name is trimmed to 32 bytes, so it is possible that the name is truncated.
17///
18/// # Example
19/// ```
20/// use generic_camera::controls::CustomName;
21///
22/// let name: CustomName = "UUID".into();
23/// assert_eq!(name.as_str(), "UUID");
24///
25/// let name: CustomName = "My Custom Very Long Name".into();
26/// assert_eq!(name.as_str(), "My Custom Very L");
27/// ```
28pub struct CustomName([u8; 16]);
29
30impl CustomName {
31    /// Create a new custom name.
32    fn new(name: &str) -> Self {
33        let mut bytes = [0; 16];
34        let len = name.len().min(16);
35        bytes[..len].copy_from_slice(&name.as_bytes()[..len]);
36        Self(bytes)
37    }
38
39    /// Get the custom name as a string.
40    pub fn as_str(&self) -> &str {
41        std::str::from_utf8(&self.0)
42            .unwrap() // This is safe because the array is always valid UTF-8
43            .trim_end_matches(char::from(0))
44    }
45}
46
47impl<'a, T: Into<&'a str>> From<T> for CustomName {
48    fn from(name: T) -> Self {
49        Self::new(name.into())
50    }
51}
52
53/// Describes device-specific control options.
54#[derive(
55    Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Hash, Eq, Documented, DocumentedVariants,
56)]
57#[non_exhaustive]
58pub enum DeviceCtrl {
59    /// Query line or area scan type, usually [`PropertyType::EnumStr`]
60    ScanType,
61    /// Query device vendor ([`PropertyType::EnumStr`])
62    VendorName,
63    /// Query device model ([`PropertyType::EnumStr`])
64    ModelName,
65    /// Query device family ([`PropertyType::EnumStr`])
66    FamilyName,
67    /// Query manufacturer information ([`PropertyType::EnumStr`])
68    MfgInfo,
69    /// Query version ([`PropertyType::EnumStr`])
70    Version,
71    /// Query firmware version ([`PropertyType::EnumStr`])
72    FwVersion,
73    /// Query serial number ([`PropertyType::EnumStr`])
74    SerialNumber,
75    /// Query unique ID ([`PropertyType::EnumStr`])
76    Id,
77    /// Query user-set ID ([`PropertyType::EnumStr`])
78    UserId,
79    /// Query transport layer type ([`PropertyType::EnumStr`])
80    TlType,
81    /// Select device temperature source ([`PropertyType::EnumStr`])
82    TemperatureSelector,
83    /// Query selected temperature ([`PropertyType::Float`])
84    Temperature,
85    /// Reset device ([`PropertyType::Command`])
86    Reset,
87    /// Configure the cooler temperature ([`PropertyType::Float`])
88    CoolerTemp,
89    /// Configure the cooler power ([`PropertyType::Float`])
90    CoolerPower,
91    /// Enable or disable the cooler ([`PropertyType::Bool`])
92    CoolerEnable,
93    /// Configure high speed mode ([`PropertyType::Bool`])
94    HighSpeedMode,
95    /// Configure device fan ([`PropertyType::Bool`])
96    FanToggle,
97    /// A custom command
98    Custom(CustomName),
99}
100
101/// Describes sensor-specific control options.
102#[derive(
103    Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Hash, Eq, Documented, DocumentedVariants,
104)]
105#[non_exhaustive]
106pub enum SensorCtrl {
107    /// Query pixel width ([`PropertyType::Float`])
108    PixelWidth,
109    /// Query pixel height ([`PropertyType::Float`])
110    PixelHeight,
111    /// Query sensor name ([`PropertyType::EnumStr`])
112    Name,
113    /// Query sensor shutter mode ([`PropertyType::EnumStr`])
114    ShutterMode,
115    /// Query sensor max width ([`PropertyType::Unsigned`])
116    WidthMax,
117    /// Query sensor max height ([`PropertyType::Unsigned`])
118    HeightMax,
119    /// Query the binning method ([`PropertyType::EnumStr`])
120    BinningSelector,
121    /// Query binning factor on both axes ([`PropertyType::EnumUnsigned`] or [`PropertyType::Unsigned`])
122    BinningBoth,
123    /// Query the horizontal binning mode ([`PropertyType::EnumStr`])
124    BinningHorzlMode,
125    /// Query the vertical binning mode ([`PropertyType::EnumStr`])
126    BinningVertMode,
127    /// Query the horizontal binning factor ([`PropertyType::Unsigned`] or [`PropertyType::EnumUnsigned`])
128    BinningHorz,
129    /// Query the vertical binning factor ([`PropertyType::Unsigned`] or [`PropertyType::EnumUnsigned`])
130    BinningVert,
131    /// Query the horizontal decimation method ([`PropertyType::EnumStr`])
132    DecimationHorzMode,
133    /// Query the horizontal decimation mode ([`PropertyType::EnumStr`])
134    DecimationHorz,
135    /// Query the vertical decimation method ([`PropertyType::EnumStr`])
136    DecimationVertMode,
137    /// Query the vertical decimation mode ([`PropertyType::EnumStr`])
138    DecimationVert,
139    /// Reverse the image about the X axis ([`PropertyType::Bool`])
140    ReverseX,
141    /// Reverse the image about the Y axis ([`PropertyType::Bool`])
142    ReverseY,
143    /// Query the pixel format ([`PropertyType::EnumStr`])
144    PixelFormat,
145    /// Apply a test pattern to the image ([`PropertyType::EnumStr`])
146    TestPattern,
147    /// A custom command
148    Custom(CustomName),
149}
150
151/// Describes trigger-specific control options.
152#[derive(
153    Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Hash, Eq, Documented, DocumentedVariants,
154)]
155#[non_exhaustive]
156pub enum TriggerCtrl {
157    /// Select trigger line ([`PropertyType::EnumStr`])
158    Sel,
159    /// Get or set trigger mode on the selected trigger line ([`PropertyType::EnumStr`])
160    Mod,
161    /// Get or set trigger source on the selected trigger line ([`PropertyType::EnumStr`])
162    Src,
163    /// Get or set the type trigger overlap permitted with the previous frame or line ([`PropertyType::EnumStr`])
164    Overlap,
165    /// Specifies the delay in microseconds (us) to apply after the trigger reception before activating it ([`PropertyType::Float`])
166    Delay,
167    /// Specifies a division factor for the incoming trigger pulses ([`PropertyType::Float`])
168    Divider,
169    /// Specifies a multiplication factor for the incoming trigger pulses ([`PropertyType::Float`])
170    Multiplier,
171    /// A custom command
172    Custom(CustomName),
173}
174
175/// Describes exposure control options.
176#[derive(
177    Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Hash, Eq, Documented, DocumentedVariants,
178)]
179#[non_exhaustive]
180pub enum ExposureCtrl {
181    /// Select exposure mode ([`PropertyType::EnumStr`])
182    Mode,
183    /// Select exposure time ([`PropertyType::Float`])
184    ExposureTime,
185    /// Select exposure auto mode ([`PropertyType::EnumStr`] or [`PropertyType::Bool`])
186    Auto,
187    /// Select maximum auto exposure time ([`PropertyType::Duration`])
188    AutoMaxExposure,
189    /// Select exposure auto target brightness ([`PropertyType::Float`])
190    AutoTargetBrightness,
191    /// Select maximum gain for auto exposure ([`PropertyType::Float`])
192    AutoMaxGain,
193    /// A custom command
194    Custom(CustomName),
195}
196
197/// Describes frame rate control options.
198#[derive(
199    Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Hash, Eq, Documented, DocumentedVariants,
200)]
201#[non_exhaustive]
202pub enum FrameTimeCtrl {
203    /// Select frame time mode ([`PropertyType::EnumStr`])
204    Mode,
205    /// Select frame time ([`PropertyType::Duration`])
206    FrameTime,
207    /// Select frame time auto mode ([`PropertyType::EnumStr`] or [`PropertyType::Bool`])
208    Auto,
209    /// A custom command
210    Custom(CustomName),
211}
212
213#[derive(
214    Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Hash, Eq, Documented, DocumentedVariants,
215)]
216#[non_exhaustive]
217/// Describes analog control options.
218pub enum AnalogCtrl {
219    /// Select which gain to control ([`PropertyType::EnumStr`])
220    GainSelector,
221    /// Select gain value ([`PropertyType::Float`])
222    Gain,
223    /// Select gain auto mode ([`PropertyType::EnumStr`] or [`PropertyType::Bool`])
224    GainAuto,
225    /// Select gain auto balance ([`PropertyType::Float`])
226    GainAutoBalance,
227    /// Select which black level to control ([`PropertyType::EnumStr`])
228    BlackLevelSel,
229    /// Select black level value ([`PropertyType::Float`])
230    BlackLevel,
231    /// Select black level auto mode ([`PropertyType::EnumStr`] or [`PropertyType::Bool`])
232    BlackLevelAuto,
233    /// Select black level auto balance ([`PropertyType::Float`])
234    BlackLevelAutoBalance,
235    /// Select which white clip to control ([`PropertyType::EnumStr`])
236    WhiteClipSel,
237    /// Select white clip value ([`PropertyType::Float`])
238    WhiteClip,
239    /// Select white balance ratio mode ([`PropertyType::EnumStr`])
240    BalanceRatioSel,
241    /// Configure white balance ratio value ([`PropertyType::Float`])
242    BalanceRatio,
243    /// Configure white balance ratio auto mode ([`PropertyType::EnumStr`] or [`PropertyType::Bool`])
244    BalanceWhiteAuto,
245    /// Configure gamma value ([`PropertyType::Float`])
246    Gamma,
247    /// A custom command
248    Custom(CustomName),
249}
250
251#[derive(
252    Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Hash, Eq, Documented, DocumentedVariants,
253)]
254#[non_exhaustive]
255/// Describes digital I/O control options.
256pub enum DigitalIoCtrl {
257    /// Select which line to control ([`PropertyType::EnumStr`])
258    LineSel,
259    /// Select the line mode ([`PropertyType::EnumStr`])
260    LineMod,
261    /// Line I/O inversion ([`PropertyType::Bool`] or [`PropertyType::EnumStr`])
262    LineInvert,
263    /// Query line status ([`PropertyType::EnumStr`])
264    LineStat,
265    /// Configure the line signal source ([`PropertyType::EnumStr`])
266    LineSrc,
267    /// Configure as user output selector ([`PropertyType::EnumStr`] or [`PropertyType::Bool`])
268    UserOutSel,
269    /// Configure as user output value ([`PropertyType::Float`] or [`PropertyType::Bool`])
270    UserOutVal,
271    /// A custom command
272    Custom(CustomName),
273}
274
275#[derive(
276    Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Hash, Eq, Documented, DocumentedVariants,
277)]
278#[non_exhaustive]
279/// Describes the general camera control zones.
280pub enum GenCamCtrl {
281    /// Device-specific control options.
282    Device(DeviceCtrl),
283    /// Sensor-specific control options.
284    Sensor(SensorCtrl),
285    /// Trigger-specific control options.
286    Trigger(TriggerCtrl),
287    /// Exposure-specific control options.
288    Exposure(ExposureCtrl),
289    /// Frame rate-specific control options.
290    FrameTime(FrameTimeCtrl),
291    /// Analog-specific control options.
292    Analog(AnalogCtrl),
293    /// Digital I/O-specific control options.
294    DigitalIo(DigitalIoCtrl),
295}
296
297macro_rules! impl_from_ctrl {
298    ($ctrl:ident, $variant:ident) => {
299        impl From<$ctrl> for GenCamCtrl {
300            fn from(ctrl: $ctrl) -> Self {
301                GenCamCtrl::$variant(ctrl)
302            }
303        }
304    };
305}
306
307impl_from_ctrl!(DeviceCtrl, Device);
308impl_from_ctrl!(SensorCtrl, Sensor);
309impl_from_ctrl!(TriggerCtrl, Trigger);
310impl_from_ctrl!(ExposureCtrl, Exposure);
311impl_from_ctrl!(FrameTimeCtrl, FrameTime);
312impl_from_ctrl!(AnalogCtrl, Analog);
313impl_from_ctrl!(DigitalIoCtrl, DigitalIo);
314
315/// Trait for controls that have a tooltip.
316pub trait ToolTip {
317    /// The tooltip for this control.
318    fn tooltip(&self) -> &'static str;
319}
320
321macro_rules! impl_tooltip {
322    ($ctrl:ident) => {
323        impl ToolTip for $ctrl {
324            fn tooltip(&self) -> &'static str {
325                self.get_variant_docs().unwrap()
326            }
327        }
328    };
329}
330
331impl_tooltip!(DeviceCtrl);
332impl_tooltip!(SensorCtrl);
333impl_tooltip!(TriggerCtrl);
334impl_tooltip!(ExposureCtrl);
335impl_tooltip!(FrameTimeCtrl);
336impl_tooltip!(AnalogCtrl);
337impl_tooltip!(DigitalIoCtrl);
338impl_tooltip!(GenCamCtrl);
generic_camera/controls.rs

generic_camera/
controls.rs
