Skip to content

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.md
index 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 messages
diff --git a/crates/liteparse-wasm/src/lib.rs b/crates/liteparse-wasm/src/lib.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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: f
continue;
}
+ // 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.py
index 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 attributes
texts = 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 needed
if 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 arrays
for 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)