A fast, helpful, and open-source document parser
feat: update http ocr to account for rotation
Logan Markewichd89a94285dfb
diff --git a/OCR_API_SPEC.md b/OCR_API_SPEC.mdindex 0a3d6f9..9db549c 100644--- a/OCR_API_SPEC.md+++ b/OCR_API_SPEC.md@@ -50,7 +50,8 @@ Your server should map these to whatever format your underlying OCR engine expec{"text": "recognized text","bbox": [x1, y1, x2, y2],- "confidence": 0.95+ "confidence": 0.95,+ "polygon": [[x1, y1], [x2, y2], [x3, y3], [x4, y4]]}]}@@ -62,8 +63,9 @@ Your server should map these to whatever format your underlying OCR engine expec|-------|------|-------------|| `results` | array | Array of text detection results || `results[].text` | string | Recognized text content |-| `results[].bbox` | [number, number, number, number] | Bounding box `[x1, y1, x2, y2]` where (x1,y1) is top-left and (x2,y2) is bottom-right |+| `results[].bbox` | [number, number, number, number] | Axis-aligned bounding box `[x1, y1, x2, y2]` where (x1,y1) is top-left and (x2,y2) is bottom-right || `results[].confidence` | number | Confidence score between 0.0 and 1.0 |+| `results[].polygon` | [[number, number], ×4] | **Optional.** 4-point detection polygon ordered top-left → top-right → bottom-right → bottom-left **in the glyphs' upright reading frame**. Lets LiteParse recover rotation for vertical/sideways text. |## Example@@ -126,7 +128,7 @@ Always return axis-aligned bounding boxes as `[x1, y1, x2, y2]`:- `x2, y2` = bottom-right corner- `x2 > x1` and `y2 > y1`-If your OCR engine returns rotated boxes or polygon coordinates, convert them to axis-aligned boxes by taking min/max coordinates.+If your OCR engine returns rotated boxes or polygon coordinates, convert them to axis-aligned boxes by taking min/max coordinates. **Additionally**, you are encouraged to forward the raw 4-point polygon as `polygon` (TL → TR → BR → BL in the upright reading frame) — LiteParse uses it to detect vertical/sideways text (e.g. legal-document sidebars) and route it through its rotation reading-order handler instead of flattening it into body lines.### Confidence Scores@@ -230,6 +232,7 @@ LiteParse handles page splitting. Your server only needs to process single image- [ ] Returns JSON with `results` array- [ ] Each result has `text`, `bbox`, and `confidence`- [ ] Bounding boxes in `[x1, y1, x2, y2]` format+- [ ] (Optional but recommended) `polygon` field with 4-point TL→TR→BR→BL polygon for rotated detections- [ ] Confidence normalized to 0.0-1.0 range- [ ] Returns 200 status on success- [ ] Returns appropriate error codes and messagesdiff --git a/crates/liteparse-wasm/src/lib.rs b/crates/liteparse-wasm/src/lib.rsindex 6c82a51..bff602d 100644--- a/crates/liteparse-wasm/src/lib.rs+++ b/crates/liteparse-wasm/src/lib.rs@@ -235,6 +235,7 @@ impl OcrEngine for JsOcrEngine {text: r.text,bbox: r.bbox,confidence: r.confidence,+ polygon: r.polygon,}).collect())})@@ -246,6 +247,8 @@ struct JsOcrResult {text: String,bbox: [f32; 4],confidence: f32,+ #[serde(default)]+ polygon: Option<[[f32; 2]; 4]>,}// ---------------------------------------------------------------------------diff --git a/crates/liteparse/src/ocr/http_simple.rs b/crates/liteparse/src/ocr/http_simple.rsindex b31fdb3..fc32b61 100644--- a/crates/liteparse/src/ocr/http_simple.rs+++ b/crates/liteparse/src/ocr/http_simple.rs@@ -14,6 +14,11 @@ pub struct HttpOcrResponseItem {text: String,bbox: [f32; 4],confidence: f32,+ /// Optional 4-point polygon [[x,y]×4] of the (possibly rotated) detection,+ /// ordered top-left → top-right → bottom-right → bottom-left in the+ /// glyphs' upright reading frame.+ #[serde(default)]+ polygon: Option<[[f32; 2]; 4]>,}#[derive(Debug, Serialize, Deserialize)]@@ -82,6 +87,7 @@ impl OcrEngine for HttpOcrEngine {.timeout(Duration::from_millis(60000)).send().await?+ .error_for_status()?.json().await?;@@ -92,6 +98,7 @@ impl OcrEngine for HttpOcrEngine {text: i.text.clone(),bbox: i.bbox,confidence: i.confidence,+ polygon: i.polygon,}).collect();diff --git a/crates/liteparse/src/ocr/mod.rs b/crates/liteparse/src/ocr/mod.rsindex 43f8efd..53deaf9 100644--- a/crates/liteparse/src/ocr/mod.rs+++ b/crates/liteparse/src/ocr/mod.rs@@ -13,6 +13,12 @@ pub struct OcrResult {pub bbox: [f32; 4],/// Confidence score in 0.0–1.0 range.pub confidence: f32,+ /// Optional 4-point polygon of the (possibly rotated) detection,+ /// ordered top-left → top-right → bottom-right → bottom-left in the+ /// glyphs' upright reading frame. When present, allows the projector+ /// to recover orientation for rotated text. None for axis-aligned-only+ /// engines (e.g. Tesseract word boxes).+ pub polygon: Option<[[f32; 2]; 4]>,}pub struct OcrOptions {@@ -87,6 +93,7 @@ mod tests {text: format!("lang={}", options.language),bbox: [0.0, 0.0, 10.0, 10.0],confidence: 0.9,+ polygon: None,}])})}diff --git a/crates/liteparse/src/ocr/tesseract.rs b/crates/liteparse/src/ocr/tesseract.rsindex b1ee979..e89017e 100644--- a/crates/liteparse/src/ocr/tesseract.rs+++ b/crates/liteparse/src/ocr/tesseract.rs@@ -99,6 +99,7 @@ impl OcrEngine for TesseractOcrEngine {text,bbox: [left as f32, top as f32, right as f32, bottom as f32],confidence: conf,+ polygon: None,});}}diff --git a/crates/liteparse/src/ocr_merge.rs b/crates/liteparse/src/ocr_merge.rsindex 12c428d..c39aaff 100644--- a/crates/liteparse/src/ocr_merge.rs+++ b/crates/liteparse/src/ocr_merge.rs@@ -192,10 +192,36 @@ pub(crate) async fn ocr_and_merge_rendered(continue;}- let ocr_x = r.bbox[0] * scale_factor;- let ocr_y = r.bbox[1] * scale_factor;- let ocr_w = (r.bbox[2] - r.bbox[0]) * scale_factor;- let ocr_h = (r.bbox[3] - r.bbox[1]) * scale_factor;+ // Prefer the screen-space axis-aligned bbox derived from the polygon+ // (when present) so rotated detections carry a tight upright bbox.+ // The polygon also lets us recover an explicit rotation angle so the+ // projector can route rotated sidebar text through its rotation+ // reading-order handler instead of mistaking it for body text.+ let (ocr_x, ocr_y, ocr_w, ocr_h, rotation) = match r.polygon {+ Some(poly) => {+ let xs = [poly[0][0], poly[1][0], poly[2][0], poly[3][0]];+ let ys = [poly[0][1], poly[1][1], poly[2][1], poly[3][1]];+ let x_min = xs.iter().copied().fold(f32::INFINITY, f32::min);+ let x_max = xs.iter().copied().fold(f32::NEG_INFINITY, f32::max);+ let y_min = ys.iter().copied().fold(f32::INFINITY, f32::min);+ let y_max = ys.iter().copied().fold(f32::NEG_INFINITY, f32::max);+ let rot = polygon_rotation_deg(&poly);+ (+ x_min * scale_factor,+ y_min * scale_factor,+ (x_max - x_min) * scale_factor,+ (y_max - y_min) * scale_factor,+ rot,+ )+ }+ None => (+ r.bbox[0] * scale_factor,+ r.bbox[1] * scale_factor,+ (r.bbox[2] - r.bbox[0]) * scale_factor,+ (r.bbox[3] - r.bbox[1]) * scale_factor,+ 0.0,+ ),+ };if overlaps_existing_text(&page.text_items[..native_count],@@ -213,14 +239,25 @@ pub(crate) async fn ocr_and_merge_rendered(continue;}+ // For native rotated text the font_size approximates line height,+ // which for 90/270° rotations corresponds to the *narrow* screen+ // dimension. Use the perpendicular extent for rotated OCR text so+ // downstream font-size heuristics stay sane.+ let font_size_hint = if rotation == 90.0 || rotation == 270.0 {+ ocr_w.max(1.0)+ } else {+ ocr_h+ };+page.text_items.push(TextItem {text: cleaned,x: ocr_x,y: ocr_y,width: ocr_w,height: ocr_h,+ rotation,font_name: Some("OCR".to_string()),- font_size: Some(ocr_h),+ font_size: Some(font_size_hint),confidence: Some((r.confidence * 1000.0).round() / 1000.0),..Default::default()});@@ -334,6 +371,39 @@ fn page_is_garbled(page: &Page) -> bool {total_vowels * 5 < total_letters}+/// Recover a discrete CCW rotation in degrees from a 4-point OCR polygon.+/// Returns one of 0.0, 90.0, 180.0, 270.0 — snapping to the nearest right+/// angle — or 0.0 for nearly-square/degenerate polygons.+///+/// Point ordering varies between OCR engines: some emit TL→TR→BR→BL in the+/// glyphs' upright reading frame (so poly[0]→poly[1] is always the reading+/// direction), but others (notably PaddleOCR 3.x with+/// `use_textline_orientation=True`) emit polygons in screen-axis order, where+/// poly[0]→poly[1] is always horizontal in screen space regardless of how the+/// text actually reads. To handle both, we pick the *longer* of the two+/// adjacent edges as the reading direction — the text always runs along the+/// long axis of its bounding quadrilateral.+fn polygon_rotation_deg(poly: &[[f32; 2]; 4]) -> f32 {+ let e0 = [poly[1][0] - poly[0][0], poly[1][1] - poly[0][1]];+ let e1 = [poly[2][0] - poly[1][0], poly[2][1] - poly[1][1]];+ let len0 = (e0[0] * e0[0] + e0[1] * e0[1]).sqrt();+ let len1 = (e1[0] * e1[0] + e1[1] * e1[1]).sqrt();+ if len0.max(len1) < 1.0 {+ return 0.0;+ }+ // Treat near-square polygons as un-rotated — there's no reliable reading+ // axis to pick from. Single-char/CJK detections fall in here.+ let (longer, shorter) = if len0 >= len1 { (len0, len1) } else { (len1, len0) };+ if shorter > 0.0 && longer / shorter < 1.3 {+ return 0.0;+ }+ let reading = if len0 >= len1 { e0 } else { e1 };+ // atan2 with screen-down y; negate to get the conventional CCW angle.+ let angle_ccw = -reading[1].atan2(reading[0]).to_degrees();+ let normalized = angle_ccw.rem_euclid(360.0);+ ((normalized / 90.0).round() as i32 * 90).rem_euclid(360) as f32+}+/// Check if an OCR bounding box overlaps with any existing text item.fn overlaps_existing_text(items: &[TextItem],@@ -395,6 +465,50 @@ fn clean_ocr_table_artifacts(text: &str) -> String {mod tests {use super::*;+ #[test]+ fn test_polygon_rotation_horizontal() {+ let p = [[0.0, 0.0], [100.0, 0.0], [100.0, 20.0], [0.0, 20.0]];+ assert_eq!(polygon_rotation_deg(&p), 0.0);+ }++ #[test]+ fn test_polygon_rotation_90_ccw() {+ // Upright text rotated 90° CCW: TL→TR edge points upward (screen y decreasing).+ let p = [[10.0, 100.0], [10.0, 0.0], [30.0, 0.0], [30.0, 100.0]];+ assert_eq!(polygon_rotation_deg(&p), 90.0);+ }++ #[test]+ fn test_polygon_rotation_270_ccw() {+ // Upright text rotated 270° CCW (= 90° CW): TL→TR edge points downward.+ let p = [[10.0, 0.0], [10.0, 100.0], [30.0, 100.0], [30.0, 0.0]];+ assert_eq!(polygon_rotation_deg(&p), 270.0);+ }++ #[test]+ fn test_polygon_rotation_screen_axis_vertical() {+ // PaddleOCR-style: tall+narrow sidebar polygon in screen-axis order+ // (smallest-y first). poly[0]→poly[1] is the SHORT horizontal edge,+ // not the reading direction. The longer edge picks out the rotation.+ let p = [[20.0, 50.0], [50.0, 50.0], [50.0, 750.0], [20.0, 750.0]];+ let r = polygon_rotation_deg(&p);+ assert!(r == 90.0 || r == 270.0, "expected 90 or 270, got {r}");+ }++ #[test]+ fn test_polygon_rotation_near_square() {+ // Single-char detections (CJK glyphs, etc.) should not be classified+ // as rotated — there's no reliable reading axis.+ let p = [[0.0, 0.0], [20.0, 0.0], [20.0, 22.0], [0.0, 22.0]];+ assert_eq!(polygon_rotation_deg(&p), 0.0);+ }++ #[test]+ fn test_polygon_rotation_180() {+ let p = [[100.0, 20.0], [0.0, 20.0], [0.0, 0.0], [100.0, 0.0]];+ assert_eq!(polygon_rotation_deg(&p), 180.0);+ }+#[test]fn test_clean_ocr_table_artifacts() {assert_eq!(clean_ocr_table_artifacts("44520]"), "44520");diff --git a/crates/liteparse/src/projection.rs b/crates/liteparse/src/projection.rsindex aba917d..d56107c 100644--- a/crates/liteparse/src/projection.rs+++ b/crates/liteparse/src/projection.rs@@ -182,6 +182,25 @@ fn handle_rotation_reading_order(items: &mut [ProjectedTextItem], page_height: fcontinue;}+ // Long-span guard: a rotated group whose screen-space extent along its+ // reading direction spans a large fraction of the page is almost+ // always sidebar/marginalia (page footers, signature stamps, vertical+ // disclaimers on legal/scanned docs) — never an inline label. Force the+ // separate-block branch so it doesn't get flattened onto body lines.+ //+ // For 90/270° text the reading direction is screen-vertical, so the+ // group's vertical screen span is the relevant axis.+ let group_min_y = group+ .iter()+ .map(|idx| items[*idx].item.y)+ .fold(f32::INFINITY, f32::min);+ let group_max_y = group+ .iter()+ .map(|idx| items[*idx].item.y + items[*idx].item.height)+ .fold(f32::NEG_INFINITY, f32::max);+ let group_vspan = (group_max_y - group_min_y).max(0.0);+ let long_span = page_height > 0.0 && group_vspan > page_height * 0.4;+// Check if non-rotated/other-rotated items visually overlap or are near this group.// Use a proximity margin so rotated labels in diagrams (e.g. pin diagrams)// that are close to but don't strictly overlap non-rotated items are kept inline.@@ -210,7 +229,7 @@ fn handle_rotation_reading_order(items: &mut [ProjectedTextItem], page_height: f}}- if global_overlap {+ if global_overlap && !long_span {// For 90/270° groups kept inline, compute a common y from the// group's average vertical midpoint so all labels land on one row.// Keep original w/h to preserve x-spacing between labels.diff --git a/ocr/paddleocr/server.py b/ocr/paddleocr/server.pyindex 1cb3b14..3c0ecda 100644--- a/ocr/paddleocr/server.py+++ b/ocr/paddleocr/server.py@@ -103,16 +103,27 @@ class PaddleOCRServer:res_data = (result.get("res", result) if isinstance(result, dict) else result)- # Extract texts, scores, and boxes from the result+ # Extract texts, scores, axis-aligned boxes, and quad polygons.+ # PaddleOCR exposes the 4-point detection polygons under+ # ``rec_polys`` (or ``dt_polys`` upstream) in TL→TR→BR→BL order+ # relative to each detection's upright reading frame. We forward+ # them so LiteParse can recover the rotation of vertical+ # sidebar text instead of treating it as a horizontal line.if isinstance(res_data, dict):texts = res_data.get("rec_texts", [])scores = res_data.get("rec_scores", [])boxes = res_data.get("rec_boxes", [])+ polys = res_data.get("rec_polys", res_data.get("dt_polys", []))else:# Fallback for result object with attributestexts = getattr(res_data, "rec_texts", []) or []scores = getattr(res_data, "rec_scores", []) or []boxes = getattr(res_data, "rec_boxes", []) or []+ polys = (+ getattr(res_data, "rec_polys", None)+ or getattr(res_data, "dt_polys", None)+ or []+ )# Convert numpy arrays to lists if neededif hasattr(texts, "tolist"):@@ -121,6 +132,8 @@ class PaddleOCRServer:scores = scores.tolist()if hasattr(boxes, "tolist"):boxes = boxes.tolist()+ if hasattr(polys, "tolist"):+ polys = polys.tolist()# Combine them - they should be parallel arraysfor i in range(len(texts)):@@ -139,9 +152,27 @@ class PaddleOCRServer:else:bbox = [0, 0, 0, 0]- formatted.append(- {"text": text, "bbox": bbox, "confidence": confidence}- )+ polygon = None+ if i < len(polys):+ poly = polys[i]+ if hasattr(poly, "tolist"):+ poly = poly.tolist()+ # Expect a 4×2 sequence; coerce to floats and validate+ # shape before forwarding.+ if len(poly) == 4 and all(len(pt) == 2 for pt in poly):+ polygon = [[float(pt[0]), float(pt[1])] for pt in poly]+ # When rec_boxes is missing/zero (rotated detections in+ # some PaddleOCR builds only populate rec_polys), derive+ # an axis-aligned fallback from the polygon.+ if polygon is not None and bbox == [0, 0, 0, 0]:+ xs = [pt[0] for pt in polygon]+ ys = [pt[1] for pt in polygon]+ bbox = [min(xs), min(ys), max(xs), max(ys)]++ item = {"text": text, "bbox": bbox, "confidence": confidence}+ if polygon is not None:+ item["polygon"] = polygon+ formatted.append(item)return OcrResponse(results=formatted)