Skip to main content

glypho/
document.rs

1use std::collections::HashSet;
2
3use serde::{Deserialize, Serialize};
4
5use crate::{Error, Result};
6
7pub const SCHEMA_VERSION: &str = "glypho.annotation.v1";
8
9#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
10#[serde(deny_unknown_fields)]
11pub struct Document {
12    pub schema_version: String,
13    pub coordinate_system: CoordinateSystem,
14    pub image: ImageInfo,
15    pub text: String,
16    #[serde(skip_serializing_if = "Option::is_none")]
17    pub corrected_text: Option<String>,
18    pub lines: Vec<TextLine>,
19    pub language_hints: Vec<String>,
20    pub metadata: Metadata,
21}
22
23impl Document {
24    pub fn new(image: ImageInfo) -> Self {
25        Self {
26            schema_version: SCHEMA_VERSION.to_owned(),
27            coordinate_system: CoordinateSystem::PixelTopLeft,
28            image,
29            text: String::new(),
30            corrected_text: None,
31            lines: Vec::new(),
32            language_hints: Vec::new(),
33            metadata: Metadata::default(),
34        }
35    }
36
37    pub fn rebuild_text(&mut self) {
38        self.lines.sort_by_key(|line| line.order);
39        self.text = self
40            .lines
41            .iter()
42            .filter(|line| !line.ignored && !line.text.trim().is_empty())
43            .map(|line| line.text.trim())
44            .collect::<Vec<_>>()
45            .join("\n");
46        let corrected = self
47            .lines
48            .iter()
49            .filter(|line| !line.ignored && !line.text.trim().is_empty())
50            .map(|line| line.corrected_text.as_deref().unwrap_or(&line.text).trim())
51            .collect::<Vec<_>>()
52            .join("\n");
53        self.corrected_text = (corrected != self.text).then_some(corrected);
54    }
55
56    pub fn sort_reading_order(&mut self) {
57        self.lines.sort_by(|left, right| {
58            left.quad
59                .bounds()
60                .y
61                .total_cmp(&right.quad.bounds().y)
62                .then_with(|| left.quad.bounds().x.total_cmp(&right.quad.bounds().x))
63        });
64
65        let mut rows: Vec<Vec<TextLine>> = Vec::new();
66        for line in self.lines.drain(..) {
67            let bounds = line.quad.bounds();
68            let same_row = rows.last().is_some_and(|row| {
69                let reference = row.last().expect("a row is never empty").quad.bounds();
70                let tolerance = bounds.height.min(reference.height) * 0.5;
71                (bounds.center_y() - reference.center_y()).abs() <= tolerance
72            });
73            if same_row {
74                rows.last_mut().expect("the row exists").push(line);
75            } else {
76                rows.push(vec![line]);
77            }
78        }
79
80        for row in &mut rows {
81            row.sort_by(|left, right| left.quad.bounds().x.total_cmp(&right.quad.bounds().x));
82        }
83        self.lines = rows.into_iter().flatten().collect();
84
85        for (order, line) in self.lines.iter_mut().enumerate() {
86            line.order = order as u32;
87        }
88        self.rebuild_text();
89    }
90
91    pub fn validate(&self) -> Result<()> {
92        let mut errors = Vec::new();
93
94        if self.schema_version != SCHEMA_VERSION {
95            errors.push(format!(
96                "schema_version must be {SCHEMA_VERSION}, got {}",
97                self.schema_version
98            ));
99        }
100        if self.image.id.trim().is_empty() {
101            errors.push("image.id must not be empty".to_owned());
102        }
103        if self.image.file_name.trim().is_empty() {
104            errors.push("image.file_name must not be empty".to_owned());
105        }
106        if self.image.width == 0 || self.image.height == 0 {
107            errors.push("image dimensions must be greater than zero".to_owned());
108        }
109        if let Some(sha256) = &self.image.sha256
110            && (sha256.len() != 64
111                || !sha256
112                    .bytes()
113                    .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte)))
114        {
115            errors.push("image.sha256 must be 64 lowercase hexadecimal characters".to_owned());
116        }
117        validate_non_empty_unique(&self.language_hints, "language_hints", &mut errors);
118        validate_non_empty_unique(&self.metadata.tags, "metadata.tags", &mut errors);
119        if self
120            .metadata
121            .group_id
122            .as_ref()
123            .is_some_and(|group_id| group_id.trim().is_empty())
124        {
125            errors.push("metadata.group_id must not be empty".to_owned());
126        }
127
128        let mut ids = HashSet::new();
129        let mut orders = HashSet::new();
130        for (index, line) in self.lines.iter().enumerate() {
131            let path = format!("lines[{index}]");
132            validate_id(&line.id, &path, &mut ids, &mut errors);
133            if !orders.insert(line.order) {
134                errors.push(format!("{path}.order {} is duplicated", line.order));
135            }
136            validate_quad(
137                &line.quad,
138                self.image.width,
139                self.image.height,
140                &format!("{path}.quad"),
141                &mut errors,
142            );
143            validate_confidence(line.confidence, &path, &mut errors);
144            if line
145                .language
146                .as_ref()
147                .is_some_and(|language| language.trim().is_empty())
148            {
149                errors.push(format!("{path}.language must not be empty"));
150            }
151            if line
152                .script
153                .as_ref()
154                .is_some_and(|script| script.trim().is_empty())
155            {
156                errors.push(format!("{path}.script must not be empty"));
157            }
158            validate_non_empty_unique(&line.flags, &format!("{path}.flags"), &mut errors);
159            for (alternative_index, alternative) in line.alternatives.iter().enumerate() {
160                validate_confidence(
161                    Some(alternative.confidence),
162                    &format!("{path}.alternatives[{alternative_index}]"),
163                    &mut errors,
164                );
165            }
166
167            if self.metadata.status.is_final()
168                && !line.ignored
169                && line.evaluation.recognition
170                && line.text.trim().is_empty()
171            {
172                errors.push(format!(
173                    "{path}.text must not be empty in a reviewed document"
174                ));
175            }
176
177            for (word_index, word) in line.words.iter().enumerate() {
178                let word_path = format!("{path}.words[{word_index}]");
179                validate_id(&word.id, &word_path, &mut ids, &mut errors);
180                validate_quad(
181                    &word.quad,
182                    self.image.width,
183                    self.image.height,
184                    &format!("{word_path}.quad"),
185                    &mut errors,
186                );
187                validate_confidence(word.confidence, &word_path, &mut errors);
188            }
189        }
190
191        if self.metadata.status.is_final() {
192            let mut ordered = self.lines.iter().collect::<Vec<_>>();
193            ordered.sort_by_key(|line| line.order);
194            let expected = ordered
195                .into_iter()
196                .filter(|line| !line.ignored && !line.text.trim().is_empty())
197                .map(|line| line.text.trim())
198                .collect::<Vec<_>>()
199                .join("\n");
200            if self.text != expected {
201                errors.push("text must match non-ignored lines in reading order".to_owned());
202            }
203        }
204
205        if errors.is_empty() {
206            Ok(())
207        } else {
208            Err(Error::InvalidDocument(errors))
209        }
210    }
211}
212
213#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
214#[serde(deny_unknown_fields)]
215pub struct ImageInfo {
216    pub id: String,
217    pub file_name: String,
218    pub width: u32,
219    pub height: u32,
220    #[serde(skip_serializing_if = "Option::is_none")]
221    pub sha256: Option<String>,
222}
223
224#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
225#[serde(deny_unknown_fields)]
226pub struct TextLine {
227    pub id: String,
228    pub order: u32,
229    pub quad: Quad,
230    pub text: String,
231    #[serde(skip_serializing_if = "Option::is_none")]
232    pub corrected_text: Option<String>,
233    #[serde(default, skip_serializing_if = "Vec::is_empty")]
234    pub alternatives: Vec<TextAlternative>,
235    #[serde(skip_serializing_if = "Option::is_none")]
236    pub confidence: Option<f32>,
237    #[serde(skip_serializing_if = "Option::is_none")]
238    pub language: Option<String>,
239    #[serde(skip_serializing_if = "Option::is_none")]
240    pub script: Option<String>,
241    pub direction: TextDirection,
242    pub legibility: Legibility,
243    #[serde(default, skip_serializing_if = "Vec::is_empty")]
244    pub flags: Vec<String>,
245    pub evaluation: EvaluationPolicy,
246    pub source: RegionSource,
247    pub words: Vec<TextWord>,
248    pub ignored: bool,
249}
250
251#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
252#[serde(deny_unknown_fields)]
253pub struct TextWord {
254    pub id: String,
255    pub quad: Quad,
256    pub text: String,
257    #[serde(skip_serializing_if = "Option::is_none")]
258    pub confidence: Option<f32>,
259}
260
261#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
262#[serde(deny_unknown_fields)]
263pub struct TextAlternative {
264    pub text: String,
265    pub confidence: f32,
266}
267
268#[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq, Serialize)]
269#[serde(rename_all = "snake_case")]
270pub enum CoordinateSystem {
271    #[default]
272    PixelTopLeft,
273}
274
275#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
276#[serde(deny_unknown_fields)]
277pub struct Point {
278    pub x: f32,
279    pub y: f32,
280}
281
282#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
283#[serde(deny_unknown_fields)]
284pub struct Quad {
285    pub points: [Point; 4],
286}
287
288impl Quad {
289    pub fn from_rect(x: f32, y: f32, width: f32, height: f32) -> Self {
290        Self {
291            points: [
292                Point { x, y },
293                Point { x: x + width, y },
294                Point {
295                    x: x + width,
296                    y: y + height,
297                },
298                Point { x, y: y + height },
299            ],
300        }
301    }
302
303    pub fn bounds(&self) -> Bounds {
304        let mut min_x = f32::INFINITY;
305        let mut min_y = f32::INFINITY;
306        let mut max_x = f32::NEG_INFINITY;
307        let mut max_y = f32::NEG_INFINITY;
308
309        for point in self.points {
310            min_x = min_x.min(point.x);
311            min_y = min_y.min(point.y);
312            max_x = max_x.max(point.x);
313            max_y = max_y.max(point.y);
314        }
315
316        Bounds {
317            x: min_x,
318            y: min_y,
319            width: max_x - min_x,
320            height: max_y - min_y,
321        }
322    }
323
324    fn signed_area(&self) -> f32 {
325        let mut area = 0.0;
326        for index in 0..self.points.len() {
327            let current = self.points[index];
328            let next = self.points[(index + 1) % self.points.len()];
329            area += current.x * next.y - next.x * current.y;
330        }
331        area * 0.5
332    }
333}
334
335#[derive(Clone, Copy, Debug, PartialEq)]
336pub struct Bounds {
337    pub x: f32,
338    pub y: f32,
339    pub width: f32,
340    pub height: f32,
341}
342
343impl Bounds {
344    fn center_y(&self) -> f32 {
345        self.y + self.height * 0.5
346    }
347}
348
349#[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq, Serialize)]
350#[serde(rename_all = "snake_case")]
351pub enum RegionSource {
352    #[default]
353    Manual,
354    Model,
355    Imported,
356}
357
358#[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq, Serialize)]
359#[serde(rename_all = "snake_case")]
360pub enum AnnotationStatus {
361    #[default]
362    Draft,
363    Reviewed,
364    Verified,
365}
366
367impl AnnotationStatus {
368    fn is_final(self) -> bool {
369        matches!(self, Self::Reviewed | Self::Verified)
370    }
371}
372
373#[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq, Serialize)]
374#[serde(rename_all = "snake_case")]
375pub enum TextDirection {
376    #[default]
377    Auto,
378    LeftToRight,
379    RightToLeft,
380    Vertical,
381}
382
383#[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq, Serialize)]
384#[serde(rename_all = "snake_case")]
385pub enum Legibility {
386    #[default]
387    Clear,
388    Ambiguous,
389    Unreadable,
390}
391
392#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
393#[serde(deny_unknown_fields)]
394pub struct EvaluationPolicy {
395    pub detection: bool,
396    pub recognition: bool,
397}
398
399impl Default for EvaluationPolicy {
400    fn default() -> Self {
401        Self {
402            detection: true,
403            recognition: true,
404        }
405    }
406}
407
408#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
409#[serde(deny_unknown_fields)]
410pub struct Metadata {
411    pub status: AnnotationStatus,
412    #[serde(skip_serializing_if = "Option::is_none")]
413    pub annotator: Option<String>,
414    #[serde(skip_serializing_if = "Option::is_none")]
415    pub created_at: Option<String>,
416    #[serde(skip_serializing_if = "Option::is_none")]
417    pub updated_at: Option<String>,
418    #[serde(skip_serializing_if = "Option::is_none")]
419    pub engine: Option<EngineInfo>,
420    #[serde(skip_serializing_if = "Option::is_none")]
421    pub notes: Option<String>,
422    #[serde(default, skip_serializing_if = "is_false")]
423    pub sensitive: bool,
424    #[serde(default, skip_serializing_if = "Vec::is_empty")]
425    pub tags: Vec<String>,
426    #[serde(skip_serializing_if = "Option::is_none")]
427    pub group_id: Option<String>,
428}
429
430fn is_false(value: &bool) -> bool {
431    !value
432}
433
434#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
435#[serde(deny_unknown_fields)]
436pub struct EngineInfo {
437    pub name: String,
438    pub version: String,
439    pub backend: String,
440    #[serde(skip_serializing_if = "Option::is_none")]
441    pub model: Option<String>,
442    pub languages: Vec<String>,
443    pub elapsed_ms: u64,
444}
445
446fn validate_id(id: &str, path: &str, ids: &mut HashSet<String>, errors: &mut Vec<String>) {
447    if id.trim().is_empty() {
448        errors.push(format!("{path}.id must not be empty"));
449        return;
450    }
451    if !ids.insert(id.to_owned()) {
452        errors.push(format!("{path}.id {id:?} is duplicated"));
453    }
454}
455
456fn validate_confidence(value: Option<f32>, path: &str, errors: &mut Vec<String>) {
457    if let Some(value) = value
458        && (!value.is_finite() || !(0.0..=1.0).contains(&value))
459    {
460        errors.push(format!("{path}.confidence must be between 0 and 1"));
461    }
462}
463
464fn validate_non_empty_unique(values: &[String], path: &str, errors: &mut Vec<String>) {
465    let mut seen = HashSet::new();
466    for (index, value) in values.iter().enumerate() {
467        if value.trim().is_empty() {
468            errors.push(format!("{path}[{index}] must not be empty"));
469        }
470        if !seen.insert(value) {
471            errors.push(format!("{path}[{index}] is duplicated"));
472        }
473    }
474}
475
476fn validate_quad(quad: &Quad, width: u32, height: u32, path: &str, errors: &mut Vec<String>) {
477    for (index, point) in quad.points.iter().enumerate() {
478        if !point.x.is_finite() || !point.y.is_finite() {
479            errors.push(format!("{path}.points[{index}] must be finite"));
480            continue;
481        }
482        if point.x < 0.0 || point.x > width as f32 {
483            errors.push(format!("{path}.points[{index}].x is outside the image"));
484        }
485        if point.y < 0.0 || point.y > height as f32 {
486            errors.push(format!("{path}.points[{index}].y is outside the image"));
487        }
488    }
489
490    if quad.signed_area().abs() < 0.5 {
491        errors.push(format!("{path} has no area"));
492    }
493}