FlattenPageRotation - TPdf - PDFium Delphi Component

Component: TPdf · Unit: PDFium

Bakes the current /Rotate of every page into the content stream, page boxes, and annotation rectangles, then resets /Rotate to 0 so the visual layout is preserved without relying on the rotation display hint

Syntax

function FlattenPageRotation(
const Options : TPdfFlattenRotationOptions;
out Report : TPdfFlattenRotationReport): Boolean; overload;

function FlattenPageRotation(
  const PageNumbers : array of Integer;
  const Options : TPdfFlattenRotationOptions;
  out Report : TPdfFlattenRotationReport): Boolean; overload;

Description

Many downstream tools (older print pipelines, image extractors, OCR preprocessors, raster converters) ignore the /Rotate page entry and render rotated pages in the wrong orientation. FlattenPageRotation applies the inverse of the current rotation to the page content, annotation rectangles, and page boxes, then sets /Rotate to 0. After the call the visible page is identical to the rotated original, but no longer relies on the viewer applying the rotation hint.

The single-argument overload processes every page; the PageNumbers overload accepts a zero-based array so callers can flatten a subset. Pages already at /Rotate=0 are counted in Report.SkippedPageCount and left untouched.

Internally each rotated page runs through FPDFPage_CountObjects + FPDFPage_GetObject + FPDFPageObj_TransformF for the content, then FPDFPage_GetAnnot + FPDFAnnot_GetRect / FPDFAnnot_SetRect for annotations, then FPDFPage_SetMediaBox / FPDFPage_SetCropBox for the page boxes, and finally FPDFPage_SetRotation with 0. The matrix is derived from the unrotated MediaBox returned by FPDFPage_GetMediaBox.

Parameters

PageNumbers — zero-based page indices to process. Pass an empty array (or use the single-argument overload) to flatten every page.
Options — TPdfFlattenRotationOptions with TransformAnnotations, TransformPageBoxes, and AutoUpdate. Default transforms annotations, swaps page boxes, and calls UpdatePage after each rotated page.
Report — TPdfFlattenRotationReport with ProcessedPageCount, SkippedPageCount, FailedPageCount, TotalObjectsTransformed, and TotalAnnotationsTransformed, plus Succeeded and ErrorMessage.

Remarks

Rotation matrices: 90° uses [0, 1, -1, 0, H, 0], 180° uses [-1, 0, 0, -1, W, H], 270° uses [0, -1, 1, 0, 0, W], where W and H are the unrotated MediaBox dimensions.
For 90° and 270° rotations the MediaBox and CropBox dimensions are swapped so the visible page keeps its aspect ratio. Disable with TransformPageBoxes=False when callers intend to rewrite boxes themselves.
Annotation rectangles are remapped through the same matrix and rebuilt from all four transformed corners because axis swaps can flip the left <= right / bottom <= top invariants.
The caller's current PageNumber is saved and restored around the call, so callers can safely continue working on their previously active page.
Pages already at /Rotate=0 are skipped and counted in Report.SkippedPageCount; an all-skipped run still returns True because nothing failed.

Example

var
  Options: TPdfFlattenRotationOptions;
  Report: TPdfFlattenRotationReport;
begin
  Pdf1.FileName := 'C:\Scanned.pdf';
  Pdf1.Active := True;
  Options := TPdfFlattenRotationOptions.Default;
  Pdf1.FlattenPageRotation(Options, Report);
  Pdf1.SaveAs('C:\Scanned_flat.pdf');
end;

FlattenPageRotation method