regain_core/
model.rs

1use anyhow::{Result, ensure};
2use serde::{Deserialize, Serialize};
3use serde_json::Value;
4use std::{
5    collections::BTreeMap,
6    sync::{Arc, Mutex},
7};
8
9#[derive(Debug)]
10pub enum Failure {
11    Invalid(String),
12    Cancelled,
13    Worker { message: String, code: Option<i32> },
14}
15impl std::fmt::Display for Failure {
16    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
17        match self {
18            Self::Invalid(m) | Self::Worker { message: m, .. } => f.write_str(m),
19            Self::Cancelled => f.write_str("Exposure aborted"),
20        }
21    }
22}
23impl std::error::Error for Failure {}
24pub fn invalid(message: impl Into<String>) -> anyhow::Error {
25    Failure::Invalid(message.into()).into()
26}
27pub fn retryable(error: &anyhow::Error) -> bool {
28    match error.downcast_ref::<Failure>() {
29        Some(Failure::Invalid(_) | Failure::Cancelled) => false,
30        Some(Failure::Worker { code: Some(c), .. }) => {
31            matches!(c, 1 | 2 | 4 | 5 | 11 | 12 | 15 | 16)
32        }
33        _ => true,
34    }
35}
36#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
37pub struct Exposure {
38    pub width: u32,
39    pub height: u32,
40    pub bin: u32,
41    pub x: u32,
42    pub y: u32,
43    pub microseconds: u64,
44    pub dark: bool,
45}
46impl Exposure {
47    pub fn bytes(&self) -> Result<usize> {
48        let count = u64::from(self.width) * u64::from(self.height) * 2;
49        ensure!(
50            count > 0 && count <= 512 * 1024 * 1024,
51            Failure::Invalid("Invalid frame size".into())
52        );
53        Ok(count as usize)
54    }
55}
56#[derive(Clone, Debug, Serialize, Deserialize)]
57pub struct Control {
58    #[serde(rename = "type")]
59    pub kind: i32,
60    pub min: i64,
61    pub max: i64,
62    pub value: i64,
63    pub writable: bool,
64}
65#[derive(Clone, Debug, Serialize, Deserialize)]
66#[serde(default, rename_all = "camelCase")]
67pub struct RecoveryOptions {
68    pub max_retries: u32,
69    pub maximum_retry_exposure_seconds: f64,
70    pub reconnect_delay_seconds: f64,
71    pub command_timeout_seconds: f64,
72    pub download_timeout_seconds: f64,
73    pub exposure_grace_seconds: f64,
74    pub cooling_timeout_seconds: f64,
75    pub temperature_tolerance_c: f64,
76    pub cooling_stable_samples: u32,
77    pub cooling_sample_seconds: f64,
78    pub ready_frame_download_retries: u32,
79    pub direct_read_retries: u32,
80    /// Zero disables hardware recovery. At most one operation per capture.
81    pub usb_reset_after_failures: u32,
82    /// Linux: cycle the downstream port instead of USBDEVFS_RESET.
83    pub usb_port_cycle: bool,
84}
85impl Default for RecoveryOptions {
86    fn default() -> Self {
87        Self {
88            max_retries: 3,
89            maximum_retry_exposure_seconds: 30.,
90            reconnect_delay_seconds: 5.,
91            command_timeout_seconds: 15.,
92            download_timeout_seconds: 60.,
93            exposure_grace_seconds: 30.,
94            cooling_timeout_seconds: 300.,
95            temperature_tolerance_c: 2.,
96            cooling_stable_samples: 3,
97            cooling_sample_seconds: 2.,
98            ready_frame_download_retries: 2,
99            direct_read_retries: 2,
100            usb_reset_after_failures: 0,
101            usb_port_cycle: false,
102        }
103    }
104}
105impl RecoveryOptions {
106    pub fn validate(&self) -> Result<()> {
107        ensure!(
108            self.max_retries <= 20
109                && self.ready_frame_download_retries <= 5
110                && self.direct_read_retries <= 5
111                && self.usb_reset_after_failures <= 20
112                && (1..=60).contains(&self.cooling_stable_samples),
113            Failure::Invalid("Invalid retry limits".into())
114        );
115        ensure!(
116            self.maximum_retry_exposure_seconds.is_finite()
117                && (0.0..=86400.).contains(&self.maximum_retry_exposure_seconds),
118            Failure::Invalid("Invalid replacement exposure limit".into())
119        );
120        for v in [
121            self.reconnect_delay_seconds,
122            self.command_timeout_seconds,
123            self.download_timeout_seconds,
124            self.exposure_grace_seconds,
125            self.cooling_timeout_seconds,
126            self.temperature_tolerance_c,
127            self.cooling_sample_seconds,
128        ] {
129            ensure!(
130                v.is_finite() && v > 0. && v <= 3600.,
131                Failure::Invalid("Invalid recovery timeout or tolerance".into())
132            );
133        }
134        Ok(())
135    }
136}
137#[derive(Clone, Debug, Serialize, Deserialize)]
138#[serde(rename_all = "camelCase")]
139pub struct Selection {
140    pub name: String,
141    pub serial: Option<String>,
142    pub direct: bool,
143    pub sdk_fallback: bool,
144    pub recovery: RecoveryOptions,
145}
146#[derive(Clone, Debug, Default, Serialize)]
147#[serde(rename_all = "camelCase")]
148pub struct Status {
149    pub info: Value,
150    pub serial: Option<String>,
151    pub sdk_version: String,
152    pub backend: String,
153    pub sdk_fallback: bool,
154    pub phase: String,
155    pub error: Option<String>,
156    pub retry: RetryStatus,
157    pub controls: BTreeMap<i32, Control>,
158    pub values: BTreeMap<i32, i64>,
159    pub connected: bool,
160    pub control_connection_available: bool,
161    pub sdk_exposure_state: Option<i64>,
162    pub sdk_error_code: Option<i32>,
163    pub process_id: Option<u32>,
164    pub white_balance_capabilities: Value,
165    pub white_balance: Option<crate::white_balance::Settings>,
166}
167/// Attempts made for the current/latest capture; the last failure survives
168/// successful recovery and subsequent healthy captures in this connection.
169#[derive(Clone, Debug, Default, Serialize)]
170#[serde(rename_all = "camelCase")]
171pub struct RetryStatus {
172    pub recaptures: u32,
173    pub downloads: u32,
174    pub usb_reads: u32,
175    pub last_failure: Option<String>,
176}
177impl Status {
178    pub fn recovery_info(&self) -> String {
179        let retry = &self.retry;
180        let failure = retry.last_failure.as_deref().unwrap_or("none");
181        let failure = failure.split_whitespace().collect::<Vec<_>>().join(" ");
182        format!(
183            "state: {}; retries: {} (recaptures: {}, downloads: {}, USB reads: {}); last failure: {}",
184            if self.phase.is_empty() {
185                "Disconnected"
186            } else {
187                &self.phase
188            },
189            u64::from(retry.recaptures) + u64::from(retry.downloads) + u64::from(retry.usb_reads),
190            retry.recaptures,
191            retry.downloads,
192            retry.usb_reads,
193            failure
194        )
195    }
196}
197pub type SharedStatus = Arc<Mutex<Status>>;
198pub type Diagnostic = Arc<dyn Fn(&str, &str, &str) + Send + Sync>;
199#[derive(Clone)]
200pub struct Frame {
201    pub exposure: Exposure,
202    pub pixels: Arc<[u8]>,
203    pub metadata: Value,
204}
205
206pub fn validate_exposure(
207    info: &Value,
208    controls: &BTreeMap<i32, Control>,
209    e: &Exposure,
210) -> Result<()> {
211    e.bytes()?;
212    let bins = info["bins"]
213        .as_array()
214        .ok_or_else(|| invalid("Camera binning is unavailable"))?;
215    let w = info["width"].as_u64().unwrap_or(0);
216    let h = info["height"].as_u64().unwrap_or(0);
217    let exp = controls
218        .get(&1)
219        .ok_or_else(|| invalid("Exposure control unavailable"))?;
220    let alignment = info["originAlignment"]
221        .as_u64()
222        .or_else(|| info["originAlignmentX"].as_u64())
223        .unwrap_or(1)
224        .max(1);
225    let align_y = info["originAlignmentY"]
226        .as_u64()
227        .unwrap_or(if info["originAlignment"].is_number() {
228            2
229        } else {
230            1
231        })
232        .max(1);
233    ensure!(e.bin>0 && bins.iter().any(|b|b.as_u64()==Some(e.bin as u64)) && e.width.is_multiple_of(8) && e.height.is_multiple_of(2) &&
234        (u64::from(e.x)+u64::from(e.width))*u64::from(e.bin)<=w && (u64::from(e.y)+u64::from(e.height))*u64::from(e.bin)<=h &&
235        u64::from(e.width)*u64::from(e.bin)>=info["minimumWidth"].as_u64().unwrap_or(8) && u64::from(e.height)*u64::from(e.bin)>=info["minimumHeight"].as_u64().unwrap_or(2) &&
236        u64::from(e.x)*u64::from(e.bin)%alignment==0 && u64::from(e.y)*u64::from(e.bin)%align_y==0 &&
237        e.microseconds>0 && e.microseconds>=exp.min.max(0) as u64 && e.microseconds<=exp.max.max(0) as u64,
238        Failure::Invalid("Exposure or ROI is outside camera capabilities (width multiple of 8, height multiple of 2; see camera alignment)".into()));
239    Ok(())
240}
241
242/// Validate against the SDK's ROI rules when fallback is explicitly permitted.
243/// The worker's validate command decides whether it must switch before exposing.
244pub fn validate_capture(
245    info: &Value,
246    controls: &BTreeMap<i32, Control>,
247    e: &Exposure,
248    sdk_fallback: bool,
249) -> Result<()> {
250    if !sdk_fallback {
251        return validate_exposure(info, controls, e);
252    }
253    let mut info = info.clone();
254    info["minimumWidth"] = serde_json::json!(8);
255    info["minimumHeight"] = serde_json::json!(2);
256    info["originAlignment"] = serde_json::json!(1);
257    info["originAlignmentX"] = serde_json::json!(1);
258    info["originAlignmentY"] = serde_json::json!(1);
259    validate_exposure(&info, controls, e)
260}
regain_core/model.rs

regain_core/
model.rs
