Deskewing PDF pages

Pages that come off a scanner or a phone camera are rarely square to the page. A few degrees of rotation is enough to hurt OCR accuracy, throw off barcode and table detection, and make an otherwise clean archive look sloppy. Deskewing straightens the page before any of that downstream work runs.

Deskewing at the page level keeps the operation narrow. You correct the pages you know came from a scanner and leave the rest of the document untouched, which matters in mixed documents where born-digital pages are already square.

This sample shows how to straighten a single page of a document using Nutrient Java SDK and save the result. The input can be any document format the SDK supports. If the input isn’t already a PDF, the SDK converts it to PDF automatically when you create the editor.

How Nutrient helps

Nutrient Java SDK detects and corrects skew behind a single method call. The SDK:

• Implicitly converts non-PDF inputs (images, multipage TIFFs, Office documents) to PDF when the editor is created
• Rasterizes the target page and measures its dominant text baseline angle
• Rotates the page content by the detected angle to bring it back to square
• Applies the correction to the page content stream, so text and vector art stay vector — the page isn’t flattened to an image
• Leaves the page alone when no skew is detected

Other pages in the document aren’t touched.

Preparing the project

Specify a package name and create the main class:

package io.nutrient.Sample;

Import the classes used in the sample:

import io.nutrient.sdk.Document;
import io.nutrient.sdk.editors.PdfEditor;
import io.nutrient.sdk.editors.pdf.pages.PdfPage;
import io.nutrient.sdk.editors.pdf.pages.PdfPageCollection;

public class DeskewPdfPage {

Opening the document

The entry point opens the source document and attaches a PDF editor to it:

    public static void main(String[] args) {
        try (Document document = Document.open("input_skewed_scan.pdf")) {
            PdfEditor editor = PdfEditor.edit(document);

PdfEditor.edit(document) attaches an editor to the open document. If the input isn’t already a PDF, the SDK converts it to PDF at this step.

Tuning detection

Three document settings control the detector, and they must be set before you deskew.

skewTolerance is the search window in degrees — skew larger than this isn’t corrected. Narrow it when you know your scans are only slightly off and you want to avoid over-correcting a page whose layout merely looks slanted.

optimisticSkewDetection relaxes the confidence checks that suppress a borderline result. Enable it when you already know a batch is skewed and the conservative pass is reporting nothing. Leave it off for mixed input, where it raises the chance of rotating a page that was actually straight.

skewBinarizationMethod chooses how the page is reduced to black and white before the skew is measured. Set it to "sauvola" for faint, grayish, or unevenly lit scans, where a global threshold loses too much text for the detector to lock onto. "default" and "otsu" both use Modified Otsu.

            document.getSettings().getDeskewSettings().setSkewTolerance(10.0f);
            document.getSettings().getDeskewSettings().setOptimisticSkewDetection(false);
            document.getSettings().getDeskewSettings().setSkewBinarizationMethod("default");

All three have sensible defaults (a 15-degree window, conservative detection, Modified Otsu), so you can skip this step entirely and call autoDeskew() directly.

These settings are shared with the recognition pipelines, so the same values apply if you later run OCR or data extraction over the document. The other properties on DeskewSettings cover model-based cardinal orientation correction, which runs only in those pipelines and doesn’t affect a page-level deskew.

Straightening a single page

Get the target page from the editor and deskew it:

            PdfPageCollection pages = editor.getPageCollection();

            PdfPage page = pages.getFirst();
            float appliedAngle = page.autoDeskew();

            System.out.println(appliedAngle != 0
                ? String.format("Corrected a skew of %.2f degrees.", appliedAngle)
                : "No skew detected, page left unchanged.");

editor.getPageCollection().getFirst() returns the first page of the document as a PdfPage, and autoDeskew() measures that page’s skew and rotates its content to correct it. A page the detector reads as already square is left unchanged, so the call is safe to run over pages you aren’t sure about.

The return value is the rotation that was applied, in degrees, and is 0 when nothing was corrected. Use it to log what happened or to flag pages that came in badly skewed.

To target a different page, use the page collection accessor (for example, pages.get(2) for the third page) and call autoDeskew() on that page instead.

Saving the result

Save the modified document to a new file and close the editor:

            editor.saveAs("output.pdf");
            editor.close();
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

The try block uses try-with-resources, so the Document is closed automatically when the block exits, even if deskewing throws. The catch clause surfaces any licensing or I/O issue raised by the SDK. Deskewing requires an unencrypted document — an encrypted source raises an error rather than silently skipping the page.

Conclusion

The workflow for deskewing a single PDF page is:

1. Open the source document.
2. Create a PdfEditor for the document.
3. Optionally tune skewTolerance and optimisticSkewDetection on the document settings.
4. Get the target page from editor.getPageCollection().
5. Call autoDeskew() on that page.
6. Save the result and close the editor.

Only the targeted page is straightened. The rest of the document is left as it was.

For related workflows, refer to the Java SDK guides.