CaptureViewer Class

Capture Viewer is used to control camera, play video stream, and capture the images from camera.

API Index

Create and Destroy Instances

Viewer Control

Document Control

Camera Control

Events

Integrated Events

Create and Destroy Instances

CaptureViewer()

Default constructor of a CaptureViewer instance.

Syntax

new Dynamsoft.DDV.CaptureViewer(options?: CaptureViewerConstructorOptions);

Parameters

options: The constructor options for a CaptureViewer instance. Please refer to CaptureViewerConstructorOptions.

Code Snippet

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

Exception

Warning

destroy()

Destroy the CaptureViewer instance.

Syntax

destroy(): void;

Code Snippet

captureViewer.destroy();

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.
captureViewer.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

captureViewer.unbindContainer();

isBoundContainer

Return whether the viewer is bound to a container.

Syntax

readonly isBoundContainer: boolean;

getStyle()

Get the style object of CaptureViewer.

Syntax

getStyle(captureViewerStyleName: CaptureViewerStyleName): CaptureViewerStyle | null;

Parameters

captureViewerStyleName: A CaptureViewerStyleName can be one of two types.

type CaptureViewerStyleName = "canvasStyle" | "quadSelectionStyle";

Return values

The style object. Please refer to Style Interfaces.

Code Snippet

// Get canvasStyle object;
const canvasStyle = captureViewer.getStyle("canvasStyle");

Warning

updateStyle()

Update the style object of CaptureViewer.

Syntax

updateStyle(captureViewerStyleName: CaptureViewerStyleName, captureViewerStyle: CaptureViewerStyle): boolean;

Parameters

captureViewerStyleName: A CaptureViewerStyleName can be one of two types.

type CaptureViewerStyleName = "canvasStyle" | "quadSelectionStyle";

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

Return Value

true: Successfully.

false: Failed.

Code Snippet

• First method

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

• Second method

    // Update the style object directly
    captureViewer.updateStyle("canvasStyle", {
        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 = captureViewer.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("captureViewer");
const header = viewerUi.children[0];
header.children.splice(0,1); //Remove Resolution element
captureViewer.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

captureViewer.show();

Remark

• The viewer is shown automatically when it is created.

hide()

Hide the viewer.

Syntax

hide(): void;

Code Snippet

captureViewer.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 Control

openDocument()

Open the specified document by document uid.

Syntax

openDocument(docUid: string): void;

Parameters

docUid: The uid of the specified document.

Code Snippet

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

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

Exception

Remark

• If another ducument is opened when there is a document already opened, the opened document will be closed automatically.
• If there are already pages in the opened document, the number of existing pages and the preview image of the last page will appear in the elements Dynamsoft.DDV.Elements.ImagePreview.

closeDocument()

Close current document.

Syntax

closeDocument(): boolean; 

Return Value

true: Successfully.

false: Failed.

Code Snippet

captureViewer.closeDocument();

Warning

currentDocument

Return the object of the current document.

Syntax

readonly currentDocument: IDocument | null;

Code Snippet

const currentDoc = captureViewer.currentDocument;

See Also

IDocument

Camera Control

play()

Play the camera video stream.

Syntax

play(videoConfig?: VideoConfig): Promise<void>;

Parameter

videoConfig: The object VideoConfig which can be used to set resolution, etc.

Code Snippet

const captureViewer = new Dynamsoft.DDV.CaptureViewer({
    container: document.getElementById("viewer"),
});
await captureViewer.play({
	 resolution: [1080, 720], 
	 fill: true, 
});

Promise Exception

Remark

• The value of videoConfig will be remembered and automatically applied the next time play() is called, unless another videoConfig is specified.

stop()

Stop the camera video stream.

Syntax

stop(): void;

Code Snippet

captureViewer.stop();

Warning

capture()

Capture a frame from video stream.

Syntax

capture(): Promise<Blob>;

Return value

The Blob of the captured image.

Code Snippet

const captureViewer = new Dynamsoft.DDV.CaptureViewer({
    container: document.getElementById("viewer"),
});
await captureViewer.play( {
	 resolution: [1080, 720], 
	 fill: true, 
});

const capturedPage = await captureViewer.capture();

Promise Exception

Remark

• If there is no document opened while capturing, a new document will be created and opened automatically.

getAllCameras()

Return information of all available cameras on the device.

Syntax

getAllCameras(): Promise<VideoDeviceInfo[]>;

Return value

A promise resolving to an array of VideoDeviceInfo objects.

Code Snippet

const cameras = await captureViewer.getAllCameras();

selectCamera()

Select a camera as the video source.

Syntax

selectCamera(cameraObjectOrDeviceID: VideoDeviceInfo | string): Promise<PlayCallbackInfo>;

Parameters

cameraObjectOrDeviceID: Specify the camera by an object VideoDeviceInfo or the device id string.

Return value

A promise resolving to a PlayCallbackInfo object.

Code Snippet

const cameras = await captureViewer.getAllCameras();
if (cameras.length) {
    await captureViewer.selectCamera(cameras[0]);
}

Promise Exception

Remark

• If called before play(), the selected camera will be used. Otherwise, the system will decide which one to use.

getCurrentCamera()

Return information about the current camera.

Syntax

getCurrentCamera(): VideoDeviceInfo;

Parameters

None.

Return value

A VideoDeviceInfo object with details about the current camera.

Code Snippet

const currentCamera = captureViewer.getCurrentCamera();
console.log("Current camera is "currentCamera.label);

getCurrentResolution()

Return the resolution of the current video input.

Syntax

getCurrentResolution(): [number, number]; //current resolution

Parameters

None.

Return value

An array of two numbers representing the resolution in the sequence of [width, height].

Code Snippet

const currentRes = captureViewer.getCurrentResolution();
console.log("Current resolution is " + currentRes[0] + " x " + currentRes[1]);

turnOnTorch()

Turn on the torch/flashlight if the current camera supports it.

Syntax

turnOnTorch(): Promise<void>; 

Return value

A promise that resolves when the operation succeeds.

Code Snippet

await captureViewer.turnOnTorch();

Promise Exception

Remark

• This method should be called when the camera is played.
• Note that it only works with Chromium-based browsers such as Edge and Chrome on Windows or Android. Other browsers such as Firefox or Safari are not supported.
• Note that all browsers on iOS (including Chrome) use WebKit as the rendering engine and are not supported.

turnOffTorch()

Turn off the torch/flashlight.

Syntax

turnOffTorch(): Promise<void>;

Return value

A promise that resolves when the operation succeeds.

Code Snippet

await captureViewer.turnOffTorch();

Promise Exception

Remark

• This method should be called when the camera is played.
• Note that it only works with Chromium-based browsers such as Edge and Chrome on Windows or Android. Other browsers such as Firefox or Safari are not supported.
• Note that all browsers on iOS (including Chrome) use WebKit as the rendering engine and are not supported.

enableAutoCapture

Specify or return whether to enable automatic capture.

Syntax

enableAutoCapture: boolean; 

Code Snippet

captureViewer.enableAutoCapture = true;

Warning

Remark

• If it is not specified in viewerConfig while creating the viewer additionally, the default value is false.
• If the auto detect is disabled, it will automatically capture a frame every 1 second by default. It can be set by autoCaptureDelay.
• If the auto detect is enabled, automatic capturing will only be performed when the detection result meets expectations. See also enableAutoDetect.

enableAutoDetect

Specify or return whether to enable automatic border detection in video stream.

Syntax

enableAutoDetect: boolean; 

Code Snippet

captureViewer.enableAutoDetect = true;

Warning

Remark

• If it is not specified in viewerConfig while creating the viewer additionally, the default value is false.
• This API only takes effect when DocumentDetect is set by setProcessingHandler().

acceptedPolygonConfidence

Specify or return the threshold confidence level when detecting boundaries.

Syntax

acceptedPolygonConfidence: number; 

Code Snippet

captureViewer.acceptedPolygonConfidence = 60;

Warning

Remark

• If it is not specified in viewerConfig while creating the viewer additionally, the default value is 80.
• The range of available values is [0,100] on a percentage scale.
• The higher the setting, the more accurate the automatic border detection.

maxFrameNumber

Specify or return the maximum number of frames detected per second.

Syntax

maxFrameNumber: number; 

Code Snippet

captureViewer.maxFrameNumber = 3;

Warning

Remark

• If it is not specified in viewerConfig while creating the viewer additionally, the default value is 10.
• The value range is (0,60].

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);
};

captureViewer.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);
};

captureViewer.on("resized", eventFunc);

// Unbind the specified event listener.
captureViewer.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.

played

Triggered when the camera video stream is played.

Callback

PlayedEvent: An EventObject.

Attributes

deviceId: The camera device id.

resolution: The resolution used.

stopped

Triggered when the camera video stream is stopped.

Callback

StoppedEvent: An EventObject.

Attributes

deviceId: The camera device id.

captured

Triggered when a frame is captured.

Callback

CapturedEvent: An EventObject.

Attributes

pageUid: The pageUid of the captured image.

cameraChanged

Triggered when the used camera is changed.

Callback

CameraChangedEvent: An EventObject.

Attributes

oldDeviceId: The old camera device id.

newDeviceId: The new camera device id.

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