Document Page Transformation

The DocumentPage class supports applying quick rotation (in 90-degree increments), flipping, and reversing. These operations are performed using the DocumentPage.Rotate, DocumentPage.Flip and DocumentPage.Reverse methods, respectively. These methods can be used on any page to quickly change its appearance.

Internally, the page holds the page coordinates in the ViewPerspective property, with an initial value of RasterViewPerspective.TopLeft, meaning the page has no rotation, flip, or reverse values.

Calling Rotate, Flip or Reverse does not modify the internal page image or SVG data itself. Instead, it changes the value of ViewPerspective to match the desired value. For instance, calling Rotate(90) results in ViewPerspective being set to RasterViewPerspective.RightTop, and so forth.

When any of these methods is called, the page will delete any previous cached raster or SVG images and text, since the existing values are for the previous state of the page.

After a transformation is applied, calling DocumentPage.GetImage returns a raster image that matches the view perspective applied. For instance, calling Rotate(90) and then GetImage will fetch the original image from the document for this page and then rotate it by 90 degrees before returning it to the user. This is performed internally on the page by calling ApplyImageViewPerspective (with apply set to true) on the original image. ApplyImageViewPerspective is a helper method that will apply the transformation (rotation, reverse, or flip) on the image data. Transformation is cumulative, meaning for example, if Rotate(90) is called twice, the page will be rotated by 180 degrees.

Transformation can also be applied by setting the value of ViewPerspective directly. For instance, to rotate a page that is TopLeft (initially) by 90 degrees, set the value of ViewPerspective to RightTop. To reset the transformation of a page, set the ViewPerspective to TopLeft.

The DocumentRotateFlip class can be used to quickly extract the rotation, flip, and reverse values from a view-perspective and vice-versa using the LEADDocument.GetRotateFlip or DocumentPage.GetRotateFlip helper methods. RotateViewPerspective and FlipViewPerspective can be used to quickly rotate, flip or reverse a RasterViewPerspective value.

When the ViewPerspective changes (either manually by setting it to a new value, or by calling any of the transformation methods), theIsViewPerspectiveModified property will be true and the view perspective value is saved into the cache entry for the page.

If caching is enabled for the page image, then the new rotated image is saved into the cache for any subsequent calls to GetImage.

Similar to raster images, the SVG image and annotations of the page obtained through DocumentPage.GetSvg and DocumentPage.GetAnnotations will apply the view perspective using the ApplySvgViewPerspective and ApplyAnnotationsViewPerspective methods to return the result using the latest page transformation.

The behavior of DocumentPage.GetText depends on the value of DocumentText.PreApplyViewPerspective. When the value of DocumentText.PreApplyViewPerspective is true (the default value), the page will apply the transformation before extracting the text using the OCR or SVG engine. Otherwise, the text will be extracted without this transformation, allowing user applications to treat the transformation as a view-only operation.

As mentioned earlier, applying a transformation on a page does not change the original data. Therefore, DocumentPage.Size will still refer to the page size as it was read from the original file used to load the document. DocumentPage.ViewPerspectiveSize can be used to obtain the page size based on the transformation (it will only be different when rotation is applied since flipping a page horizontally or vertically does not change its size). IsViewPerspectiveFlipped and IsViewPerspectiveRotated can be used to determine whether the page's current view perspective is flipped or rotated.

The DocumentPages class contains DocumentPages.Rotate, DocumentPages.Flip, and DocumentPages.Reverse methods, as well as the DocumentPages.SetViewPerspective method that can be used to apply a transformation on a group or all pages of the document in one function call.

When DocumentConverter is used to save or export this document, the transformation is applied and the resulting document will contain rotated, flipped, or reversed pages if any such methods were called.

Refer to DocumentPage.Rotate for an example.

Document Page Transformation

See Also