PerspectiveViewer Class

Perspective Viewer is used to do page boundaries manual adjustment & perspective transformation. The page data displayed on this viewer is its original data.

API Index

Create and Destroy Instances

Viewer Control

Document and Page Control

Perspective Transformation

Edit Operations

Events

Integrated Events

Create and Destroy Instances

PerspectiveViewer()

Default constructor of a PerspectiveViewer instance.

Syntax

new Dynamsoft.DDV.PerspectiveViewer(options?: PerspectiveViewerConstructorOptions);

Parameters

options: The constructor options for a PerspectiveViewer instance. Please refer to PerspectiveViewerConstructorOptions.

Code Snippet

const perspectiveViewer = new Dynamsoft.DDV.PerspectiveViewer({
    container: document.getElementById("viewer"),
});

Exception

destroy()

Destroy the PerspectiveViewer instance.

Syntax

destroy(): void;

Code Snippet

perspectiveViewer.destroy();

Remark

• The editing operations (rotating) in pages will be saved to document automatically when destroy the viewer instance.

See Also

saveOperations

Viewer Control

bindContainer()

Bind the viewer to the specified container.

Syntax

bindContainer(container: string | HTMLElement): void;

Parameters

container: The container which is used to show the viewer. Its id or HTMLElement is acceppted.

Code Snippet

// Assume there is a container with id "viewercontainer" on the page.
perspectiveViewer.bindContainer("viewercontainer");

Exception

Remark

• A viewer can only be bound to one container at once. If you bind the viewer to another container when it has been bound to a container, the viewer will be bound to the new container and unbound from the old container automatically.

unbindContainer()

Unbind the viewer from the specified container.

Syntax

unbindContainer(): void;

Code Snippet

perspectiveViewer.unbindContainer();

isBoundContainer

Return whether the viewer is bound to a container.

Syntax

readonly isBoundContainer: boolean;

getStyle()

Get the style object of PerspectiveViewer.

Syntax

getStyle(perspectiveViewerStyleName: PerspectiveViewerStyleName): PerspectiveViewerStyle | null;

Parameters

perspectiveViewerStyleName: A PerspectiveViewerStyleName can be one of three types.

type PerspectiveViewerStyleName = "canvasStyle" | "pageStyle" | "quadSelectionStyle";

Return values

The style object. Please refer to Style Interfaces..

Code Snippet

// Get pageStyle object;
const pageStyle = perspectiveViewer.getStyle("pageStyle");

Warning

updateStyle()

Update the style object of PerspectiveViewer.

Syntax

updateStyle(perspectiveViewerStyleName: PerspectiveViewerStyleName, perspectiveViewerStyle: PerspectiveViewerStyle): boolean;

Parameters

perspectiveViewerStyleName: A PerspectiveViewerStyleName can be one of three types.

type PerspectiveViewerStyleName = "canvasStyle" | "pageStyle" | "quadSelectionStyle";

perspectiveViewerStyle: The style object. Please refer to Style Interfaces.

Return Value

true: Successfully.

false: Failed.

Code Snippet

• First method

    // Get style object
    const pageStyle = perspectiveViewer.getStyle("pageStyle");
  
    // Modify the style object
    pageStyle.background = "red";
    pageStyle.border = "1px solid green";
  
    // Update page style
    perspectiveViewer.updateStyle("pageStyle", pageStyle);
  

• Second method

    // Update the style object directly
    perspectiveViewer.updateStyle("pageStyle", {
        background: "red",
        border: "1px solid green",
    });
  

Warning

Remark

• The updates are independent of whether the viewer is displayed and are updated in real time.

getUiConfig()

Get current UiConfig object.

Syntax

getUiConfig(): UiConfig;

Return Value

The UiConfig object.

Code Snippet

const viewerUi = perspectiveViewer.getUiConfig();

updateUiConfig()

Update UiConfig object.

Syntax

updateUiConfig(uiConfig: UiConfig): boolean;

Parameters

uiConfig: The UiConfig to update.

Return Value

true: Successfully.

false: Failed.

Code Snippet

const viewerUi = Dynamsoft.DDV.getDefaultUiConfig("perspectiveViewer");
const header = viewerUi.children[0];
header.children.splice(0,0,Dynamsoft.DDV.Elements.Load); //Add Load element in header.
perspectiveViewer.updateUiConfig(viewerUi);

Warning

Remark

• The updates are independent of whether the viewer is displayed and are updated in real time.

show()

Show the viewer.

Syntax

show(): void;

Code Snippet

perspectiveViewer.show();

Remark

• The viewer is shown automatically when it is created.

hide()

Hide the viewer.

Syntax

hide(): void;

Code Snippet

perspectiveViewer.hide();

isVisible

Return whether the viewer is shown or hidden.

Syntax

readonly isVisible: boolean;

Remark

• The viewer is shown automatically when it is created which means the default value of isVisible is true.

Document and Page Control

openDocument()

Open the specified document.

Syntax

openDocument(docUid: string | doc: IDocument): void;

Parameters

docUid: The uid of the specified document.

doc: The object of the document to open. Please refer to IDocument.

Code Snippet

// Assume there is a document whose id is "lnn0ll9o124".
perspectiveViewer.openDocument("lnn0ll9o124");

// OR
// Assume there is a document object firstDoc.
const docUid = firstDoc.uid;
perspectiveViewer.openDocument(docUid);
perspectiveViewer.openDocument(firstDoc);

Exception

Remark

• If another ducument is opened when there is a document already opened, the opened document will be closed automatically.

closeDocument()

Close current document.

Syntax

closeDocument(): boolean; 

Return Value

true: Successfully.

false: Failed.

Code Snippet

perspectiveViewer.closeDocument();

Warning

currentDocument

Return the object of the current document.

Syntax

readonly currentDocument: IDocument | null;

Code Snippet

const currentDoc = perspectiveViewer.currentDocument;

See Also

IDocument

getPageCount()

Get the page count in the viewer.

Syntax

getPageCount(): number;

Return Value

The page count.

Code Snippet

const pageCount = perspectiveViewer.getPageCount();

Warning

goToPage()

Navigate to the specified page by index.

Syntax

goToPage(index: number): number;

Parameters

index: The index of the page which need to navigate to.

Return Value

The index of the page which navigate to.

Code Snippet

// Navigate to page 4.
perspectiveViewer.goToPage(3);

Warning

getCurrentPageIndex()

Get the index of the current page.

Syntax

getCurrentPageIndex(): number; 

Return Value

The index of the current page.

Code Snippet

const currentIndex = perspectiveViewer.getCurrentPageIndex();

Warning

getCurrentPageUid()

Get the uid of the current page.

Syntax

getCurrentPageUid(): string;

Return Value

The uid of the current page.

Code Snippet

const curPageUid = perspectiveViewer.getCurrentPageUid();

Warning

indexToUid()

Get the uid of the specified page by its index.

Syntax

indexToUid(index: number): string;

Parameters

index: The index of the specified page.

Return Value

The uid of the page.

Code Snippet

// Get the first page's uid
const firstPageUid = perspectiveViewer.indexToUid(0);

Warning

uidToIndex()

Get the index of the specified page by its uid.

Syntax

uidToIndex(pageUid: string): number;

Parameters

pageUid: The uid of the specified page.

Return Value

The index of the page.

Code Snippet

const curPageUid = perspectiveViewer.getCurrentPageUid();
perspectiveViewer.uidToIndex(curPageUid);

Warning

Perspective Transformation

setQuadSelection()

Set a quadrilateral selection on the current page.

Syntax

setQuadSelection(quad: Quad): boolean;

Parameters

quad: A quadrangle. Please refer to Quad.

Example

const quad = [
	[80,200],
	[180,120],
	[115,340],
	[70,330]
];

perspectiveViewer.setQuadSelection(quad);

Warning

Remark

• In the viewer, only one quadrilateral selection can exist on the page at a time, which means if there is a quadrilateral selection existed when a new selection is drawn, the old one will be clear automatically.

getQuadSelection()

Get the quadrilateral selection.

Syntax

getQuadSelection(): Quad | null;

Return value

A quadrangle. Please refer to Quad.

Example

const quad = perspectiveViewer.getQuadSelection();

Warning

resetQuadSelection()

Reset the quadrilateral selection to the original one. The original selection means the last saved one.

Syntax

resetQuadSelection(indices?: number[]): boolean;

Parameters

indices: The array of the pages indices which will be reset. If not set, the current page will be reset.

Return Value

true: Successfully.

false: Failed.

Example

perspectiveViewer.resetQuadSelection();

Warning

applyPerspective()

Performs a perspective transformation in current page based on the specified quadrangle.

Syntax

applyPerspective(quad: Quad): Promise<Blob>;

Parameters

quad: The quadrangle to be transferred. Please refer to Quad.

Return value

The Blob of the result image after perspective transformation.

Example

const quad = perspectiveViewer.getQuadSelection();

await perspectiveViewer.applyPerspective(quad);

Promise Exception

Edit Operations

rotate()

Rotate the specified pages.

Syntax

rotate(
    angle: number,
    indices?: number[] 
): boolean; 

Parameters

angle: Specify the angle. Only multiples of 90 degrees are supported. Clockwise rotation is positive, counterclockwise rotation is negative.

indices: The array of the pages indices which will be rotated. If not set, the current page will be rotated.

Return Value

true: Successfully.

false: Failed.

Code Snippet

// Rotate the first and second pages 90 degrees clockwise.
perspectiveViewer.rotate(90, [0,1]);

// Rotate current page 90 degrees counterclockwise.
perspectiveViewer.rotate(-90);

Warning

saveOperations()

This method takes effect only for rotate operation.

Save the edit operations in pages to document.

Syntax

saveOperations(): boolean;

Return Value

true: Successfully.

false: Failed.

Code Snippet

perspectiveViewer.saveOperations();

Warning

Events

on()

Bind a listener to the specified event.

Syntax

on(eventName: EventName, listener:(event:EventObject)=>void): void;

Parameters

eventName: Specify the event name. It can be an integrated event name or a custom event name configured through UiConfig-events.

listener: Specify the listener.

Code Snippet

// Bind a listener to the integrated event resized.
const eventFunc = (e)=>{
    console.log(e);
    console.log(e.oldWidth);
    console.log(e.newWidth);
};

perspectiveViewer.on("resized", eventFunc);

Warning

off()

Unbind event listener(s) from the specified event.

Syntax

off(eventName: EventName, listener?:(event:EventObject)=>void): void;

Parameters

eventName: Specify the event name. It can be an integrated event name or a custom event name configured through UiConfig-events.

listener: Specify the listener. If no listener is specified, unbind all event listeners from the specified event.

Code Snippet

const eventFunc = (e)=>{
    console.log(e);
    console.log(e.oldWidth);
    console.log(e.newWidth);
};

perspectiveViewer.on("resized", eventFunc);

// Unbind the specified event listener.
perspectiveViewer.off("resized", eventFunc);

Warning

Integrated Events

resized

Triggered when the viewer is resized.

Callback

ResizedEvent: An EventObject.

Attributes

oldWidth: The old width of the viewer.

oldHeight: The old height of the viewer.

newWidth: The new width of the viewer.

newHeight: The new height of the viewer.

pageRendered

Triggered when a page has been completely rendered. We only render the pages that are visible on the screen, so this event won’t get fired for every page in the document at once. This event will get called when the user scrolls up and down the document, or when a page is rotated, or anything else that makes it rerender.

Callback

PageRenderedEvent: An EventObject.

Attributes

index: The index of the rendered page.

pageUid: The pageUid of the rendered page.

currentIndexChanged

Triggered when currentIndex is changed.

Callback

CurrentindexChangedEvent: An EventObject.

Attributes

oldIndex: The old current index.

newIndex: The new current index. If there is no index in the viewer, return -1.

currentPageChanged

Triggered when current page is changed.

Callback

CurrentPageChangedEvent: An EventObject.

Attributes

oldPageUid: The uid of the page which is old current index. If the old page is removed, return ''.

newPageUid: The uid of the page which is new current index. If there is no index in the viewer, return ''.

quadModified

Triggered when the quadrilateral selection is modified.

Callback

QuadModifiedEvent: An EventObject.

Attributes

oldQuad: The old quadrangle.

newQuad: The new quadrangle.

Mouse Events

click

Triggered when click in the viewer’s viewing area. On mobile device, triggered when tap in the viewer’s viewing area.

dblclick

Triggered when double click in the viewer’s viewing area.

rightclick

Triggered when right click in the viewer’s viewing area. On mobile device, triggered when long-tap in the viewer’s viewing area.

Callback for mouse events

VPointerEvent: An EventObject.

Attributes

index: The page index.

pageUid: The page uid.

imageX: The relative x-coordinate of the click pointer on the image.

imageY: The relative y-coordinate of the click pointer on the image.

canvasX: The relative x-coordinate of the click pointer on the canvas.

canvasY: The relative x-coordinate of the click pointer on the canvas.

nativeEvent: PointerEvent