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 the 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