feat(ocr): add rotatePages option for automatic page orientation correction#6697
Open
andreiblaj wants to merge 1 commit into
Open
feat(ocr): add rotatePages option for automatic page orientation correction#6697andreiblaj wants to merge 1 commit into
andreiblaj wants to merge 1 commit into
Conversation
…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>
01d0e96 to
60bad52
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description of Changes
What was changed
Added a new boolean request parameter
rotatePagesto the OCR endpoint(
POST /api/v1/misc/ocr-pdf). When set totrue, the OCRmyPDF command nowgets
--rotate-pagesappended, mirroring how the existingdeskew/cleanflags are handled.
ProcessPdfWithOcrRequest— newrotatePagesfield with a Swagger description.OCRController— readsrequest.isRotatePages(), threads it through thecommand-builder method signature, and appends
--rotate-pageswhen set.Why
Stirling's OCR is built on OCRmyPDF + Tesseract, which already ships
--rotate-pages. It uses Tesseract OSD (Orientation & Script Detection) toauto-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-pdfonly takes a singleangleapplied to the whole document (noper-page, no auto-detect).
ocr-pdfexposeddeskew, but--deskewonly corrects small skew, not90/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 calledocr-pdfwithrotatePages=trueon a real 20-page scan with mixed 0°/180° pages. Theupside-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-pagesuses OCRmyPDF'sconservative default
--rotate-pages-threshold(15). For noisy/sparse scans amore 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)
scripts/counter_translation.pyUI Changes (if applicable)
Testing (if applicable)
task checkto verify linters, typechecks, and tests pass