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}