DocumentPage supports applying quick rotation (in 90 degrees increment), flipping or reversing. This is performed using the DocumentPage.rotate, DocumentPage.flip and DocumentPage.reverse methods. These can be used on any page to quickly change its appearance.
Calling rotate, flip and reverse does not modify the internal page image or SVG data itself. Instead, it will change the value of viewPerspective to match the desired value. For instance, calling
rotate(90) will result in
viewPerspective 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 values are for the previous state of the page.
After a transformation is applied, calling DocumentPage.getImage will return 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. Transformation is cumulative, meaning 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 (initial) by 90 degrees, set the value of viewPerspective to rightTop. To reset the transformation of a page, set 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 LEADDocument.getRotateFlip or DocumentPage.getRotateFlip helper methods. rotateViewPerspective and flipViewPerspective can be used to quickly rotate, flip or reverse a RasterViewPerspective value.
When viewPerspective changes either manually by setting it to a new value or by calling any of the transformation methods, isViewPerspectiveModified will be true and the view perspective value is saved into the cache entry for this page.
If caching is enabled for this page image, then this newly 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 to return the result using the latest page transformation.
The behavior of DocumentPage.getText depends on the value of DocumentText.preApplyViewPerspective, when the value 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 operations.
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, isViewPerspectiveRotated can be used to determine if the page current view perspective is flipped or rotated.
DocumentPages contains DocumentPages.rotate, DocumentPages.flip, DocumentPages.reverse as well as DocumentPages.setViewPerspective methods that can be used to apply a transformation on a group or all pages of the document in one function call.
When Document Converter 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.