Skip to content

feat(ocr): add rotatePages option for automatic page orientation correction#6697

Open
andreiblaj wants to merge 1 commit into
Stirling-Tools:mainfrom
andreiblaj:feat/ocr-rotate-pages
Open

feat(ocr): add rotatePages option for automatic page orientation correction#6697
andreiblaj wants to merge 1 commit into
Stirling-Tools:mainfrom
andreiblaj:feat/ocr-rotate-pages

Conversation

@andreiblaj

@andreiblaj andreiblaj commented Jun 17, 2026

Copy link
Copy Markdown

Description of Changes

What was changed

Added a new boolean request parameter rotatePages to the OCR endpoint
(POST /api/v1/misc/ocr-pdf). When set to true, the OCRmyPDF command now
gets --rotate-pages appended, mirroring how the existing deskew / clean
flags are handled.

  • ProcessPdfWithOcrRequest — new rotatePages field with a Swagger description.
  • OCRController — reads request.isRotatePages(), threads it through the
    command-builder method signature, and appends --rotate-pages when set.

Why

Stirling's OCR is built on OCRmyPDF + Tesseract, which already ships
--rotate-pages. It uses Tesseract OSD (Orientation & Script Detection) to
auto-correct the cardinal orientation (90/180/270) of each page — the standard
fix for scanned documents that arrive sideways or upside-down. Until now there
was no way to trigger it from Stirling:

  • rotate-pdf only takes a single angle applied to the whole document (no
    per-page, no auto-detect).
  • ocr-pdf exposed deskew, but --deskew only corrects small skew, not
    90/180/270 rotation, so it does not cover this case.

This is a long-standing gap — see #725, where users asked for automatic
orientation/skew correction on scans back in 2024.

Scope

12 lines across 2 files, no new dependencies, no behavior change unless the
caller opts in by sending rotatePages=true.

Verified

Built locally (./gradlew bootJar), ran the server, and called ocr-pdf with
rotatePages=true on a real 20-page scan with mixed 0°/180° pages. The
upside-down pages came out upright, already-upright pages were left untouched,
and the resulting OCR text layer was correct.

Possible follow-up (not in this PR): bare --rotate-pages uses OCRmyPDF's
conservative default --rotate-pages-threshold (15). For noisy/sparse scans a
more aggressive threshold catches more low-confidence pages. That could be
exposed as an additional optional param if maintainers want it — happy to add.

Relates to #725


Checklist

General

Documentation

Translations (if applicable)

UI Changes (if applicable)

  • Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR)

Testing (if applicable)

  • I have run task check to verify linters, typechecks, and tests pass
  • I have tested my changes locally. Refer to the Testing Guide for more details.

@stirlingbot stirlingbot Bot added enhancement New feature or request Java Pull requests that update Java code Back End Issues related to back-end development API API-related issues or pull requests labels Jun 17, 2026
…ection

Stirling already shells out to OCRmyPDF and conditionally appends flags such
as --deskew and --clean, but it never exposed OCRmyPDF's --rotate-pages, which
uses Tesseract OSD (Orientation & Script Detection) to auto-correct the
cardinal orientation (90/180/270) of each page. This is the standard fix for
scanned documents that come in sideways or upside-down.

This adds a new boolean `rotatePages` request param to the OCR endpoint and
appends `--rotate-pages` to the OCRmyPDF command when it is set, mirroring the
existing `deskew` handling. Note that --deskew only corrects small skew, not
90/180/270 rotation, so it does not cover this case.

Verified on a real 20-page scan with mixed 0/180 orientations: the upside-down
pages came out upright while already-upright pages were left untouched, and the
resulting OCR text layer was correct.

Relates to Stirling-Tools#725

Signed-off-by: Andrei Blaj <andrei@atta.systems>
@andreiblaj andreiblaj force-pushed the feat/ocr-rotate-pages branch from 01d0e96 to 60bad52 Compare June 17, 2026 06:59
@andreiblaj andreiblaj marked this pull request as ready for review June 17, 2026 07:00
@dosubot dosubot Bot added the size:S This PR changes 10-29 lines ignoring generated files. label Jun 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

API API-related issues or pull requests Back End Issues related to back-end development enhancement New feature or request Java Pull requests that update Java code size:S This PR changes 10-29 lines ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants