Class CameraEnhancer
Basic Camera Control
API Name | Description |
---|---|
static testCameraAccess() |
Tests whether there is an available camera. |
getAllCameras() | Returns information of all available cameras on the device. |
selectCamera() | Chooses a camera as the video source. |
getSelectedCamera() | Returns information about the selected / current camera. |
getCameraState() | Returns the state of the selected camera which could be “opening”, “open” or “closed” |
open() | Turns on the camera to start streaming live video. |
cameraOpenTimeout | Sets or returns the maximum time allowed for opending a selected camera. |
close() | Stops video streaming and releases the camera. |
isOpen() | Returns whether the selected camera is turned on / occupied. |
pause() | Pauses video streaming without releasing the camera. |
isPaused() | Returns whether the video streaming is paused. |
resume() | Resumes video streaming. |
getVideoSettings() | Returns the current video settings. |
updateVideoSettings() | Changes the video input. |
setResolution() | Sets the resolution of the selected camera. |
getResolution() | Returns the resolution of the selected camera. |
getAvailableResolutions() | Returns the resolutions supported by the selected camera. |
ifSaveLastUsedCamera | Returns or sets whether to save the last used camera and resolution. |
videoSrc | Sets or returns the source of the video. |
ifSkipCameraInspection | Whether to opt for an optimal rear camera at the first open() . |
Advanced Camera Control
API Name | Description |
---|---|
setFrameRate() | Adjusts the frame rate. |
getFrameRate() | Returns the real-time frame rate. |
turnOnTorch() | Turns on the torch/flashlight if the current camera supports it. |
turnOffTorch() | Turns off the torch/flashlight. |
getZoomSettings() | Returns the zoom settings. |
setZoom() | Zooms the video stream. |
resetZoom() | Resets the zoom level of the video. |
getFocusSettings() | Returns the focus settings. |
setFocus() | Sets how the camera focuses. |
getCapabilities() | Inspects and returns the capabilities of the selected camera. |
getCameraSettings() | Returns the current values for each constrainable property of the selected camera. |
getColorTemperature() | Returns the color temperature of the selected camera. |
setColorTemperature() | Adjusts the color temperature of the selected camera. |
getExposureCompensation() | Returns the exposure compensation index of the selected camera. |
setExposureCompensation() | Sets the exposure compensation index of the selected camera. |
setAutoZoomRange() | Sets the range (minimum to maximum) for zoom when it is done automatically. |
getAutoZoomRange() | Returns the auto zoom range. |
enableEnhancedFeatures() | Enables the specified enhanced features. |
disableEnhancedFeatures() | Disables the specified enhanced features. |
getAllCameras
Returns information of all available cameras on the device.
getAllCameras(): Promise<VideoDeviceInfo[]>;
Parameters
None.
Return value
A promise resolving to an array of VideoDeviceInfo
objects.
Code Snippet
let cameras = await cameraEnhancer.getAllCameras();
if (cameras.length) {
await cameraEnhancer.selectCamera(cameras[0]);
}
See also
selectCamera
Chooses a camera as the video source.
If called before
open()
orshow()
, the selected camera will be used. Otherwise, the system will decide which one to use.
selectCamera(cameraObjectOrDeviceID: VideoDeviceInfo | string): Promise<PlayCallbackInfo>;
Parameters
cameraObjectOrDeviceID
: specifies the camera.
Return value
A promise resolving to a PlayCallbackInfo
object.
Code Snippet
let cameras = await cameraEnhancer.getAllCameras();
if (cameras.length) {
await cameraEnhancer.selectCamera(cameras[0]);
}
See also
getSelectedCamera
Returns information about the selected / current camera.
getSelectedCamera(): VideoDeviceInfo;
Parameters
None.
Return value
A VideoDeviceInfo
object with details about the selected camera.
Code Snippet
let camera = cameraEnhancer.getSelectedCamera();
console.log(camera.label);
See also
getCameraState
Returns the state of the selected camera which could be “opening”, “open” or “closed”.
getCameraState(): string;
Parameters
None.
Return value
A string indicating the camera state, it is either “opening”, “open” or “closed”.
Code Snippet
let state = cameraEnhancer.getCameraState();
console.log("The camera is " + state);
open
Turns on the camera to start streaming live video.
open(): Promise<PlayCallbackInfo>;
Parameters
None.
Return value
A promise resolving to a PlayCallbackInfo
object.
Code Snippet
<div id="enhancerUIContainer" style="width:1280px;height:720px;">
let view = await Dynamsoft.DCE.CameraView.createInstance();
document.getElementById("enhancerUIContainer").append(view.getUIElement());
let cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance(view);
await cameraEnhancer.open();
See also
cameraOpenTimeout
Sets or returns the maximum time allowed for opending a selected camera. The default value is 4000 ms.
Setting 0 means canceling the timeout or waiting indefinitely.
cameraOpenTimeout: number;
Code Snippet
cameraEnhancer.cameraOpenTimeout = 10000; // Set the timeout to 10 seconds.
close
Stops video streaming and releases the camera.
close(): void;
Parameters
None.
Return value
None.
isOpen
Returns whether the selected camera is turned on / occupied.
isOpen(): boolean;
Parameters
None.
Return value
true
means the camera is turned on and false
the opposite.
pause
Pauses video streaming without releasing the camera.
pause(): void;
Parameters
None.
Return value
None.
isPaused
Returns whether the video streaming is paused.
isPaused(): boolean;
Parameters
None.
Return value
A Boolean value indicating whether the video streaming is paused.
resume
Resumes video streaming.
resume(): Promise<void>;
Parameters
None.
Return value
A promise that resolves when the operation succeeds.
getVideoSettings
Returns the current video settings.
getVideoSettings(): MediaStreamConstraints
Return value
A MediaStreamConstraints
object.
See also
updateVideoSettings
Changes the video input.
updateVideoSettings(constraints: MediaStreamConstraints): Promise<ScannerPlayCallbackInfo | void>
Parameters
constraints
: specifies the new video settings.
Return value
A promise resolving to a ScannerPlayCallbackInfo
object.
Code Snippet
await scanner.updateVideoSettings({
video: {
width: {
ideal: 1280
},
height: {
ideal: 720
},
facingMode: {
ideal: 'environment'
}
}
});
See also
setResolution
Sets the resolution of the selected camera. If the specified resolution is not exactly supported, the closest resolution will be applied.
If called before
open()
orshow()
, the camera will use the set resolution when it opens. Otherwise, the default resolution of 1920x1080 is used (1280x720 on mobile phones and pad devices).
setResolution(resolution: Resolution): Promise<PlayCallbackInfo>;
Parameters
resolution
: specifies the resolution.
Return value
A promise resolving to a PlayCallbackInfo
object.
Code Snippet
await cameraEnhancer.setResolution({width:1280, height:720});
See also
getResolution
Returns the resolution of the selected camera.
getResolution(): Resolution;
Parameters
None.
Return value
The resolution.
Code Snippet
let resolution = cameraEnhancer.getResolution();
console.log(resolution.width + " x " + resolution.height);
See also
getAvailableResolutions
Returns the resolutions supported by the selected camera.
NOTE
- The returned resolutions are limited to these values “160 by 120”, “320 by 240”, “480 by 360”, “640 by 480”, “800 by 600”, “960 by 720”, “1280 by 720”, “1920 by 1080”, “2560 by 1440”, “3840 by 2160”.
- The SDK tests all these resolutions to find out which ones are supported. As a result, the method may be time-consuming.
getAvailableResolutions(): Promise<Array<Resolution>>;
Parameters
None.
Return value
A promise that resolves when the operation succeeds.
Code Snippet
const resolutions = await cameraEnhancer.getAvailableResolutions();
console.log(resolutions);
testCameraAccess
Tests whether there is an available camera. This method offers the additional advantage of accelerating the camera opening process for the first time.
static testCameraAccess(): Promise<{ ok: boolean, message: string }>;
Parameters
None.
Return value
A promise resolving to a object containing two properties
ok and message
.
Code Snippet
const testResponse = await Dynamsoft.DCE.CameraEnhancer.testCameraAccess();
if (testResponse.ok) {
console.log(testResponse.message);
}
ifSaveLastUsedCamera
Returns or sets whether to save the last used camera and resolution. This feature makes use of the localStorage of the browser.
NOTE
This feature only works on mainstream browsers like Chrome, Firefox and Safari. Other browsers may change the device IDs dynamically thus making it impossible to track the camera.
ifSaveLastUsedCamera: boolean;
videoSrc
Sets or returns the source of the video.
You can use this property to specify an existing video as the source to play which will be processed the same way as the video feed from a live camera.
When playing an existing video, the camera selection and video selection boxes will be hidden.
videoSrc: string;
setFrameRate
Adjusts the frame rate.
At present, this method only works in Edge, Safari, Chrome and other Chromium-based browsers (Firefox is not supported). Also, it should be called when a camera is open. If you provide a value that exceeds the camera’s capabilities, we will automatically adjust it to the maximum value that can be applied.
setFrameRate(rate: number): Promise<void>;
Parameters
rate
: specifies the new frame rate.
Return value
A promise that resolves when the operation succeeds.
Code Snippet
await cameraEnhancer.setFrameRate(10);
See also
getFrameRate
Returns the real-time frame rate.
getFrameRate(): number;
Parameters
None.
Return value
The calculated real-time frame rate.
Code Snippet
await cameraEnhancer.getFrameRate();
turnOnTorch
Turns on the torch/flashlight if the current camera supports it.
This method should be called when the camera is turned on. 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.
turnOnTorch(): Promise<void>;
Parameters
None.
Return value
A promise that resolves when the operation succeeds.
Code Snippet
await cameraEnhancer.turnOnTorch();
See also
turnOffTorch
Turns off the torch/flashlight.
This method should be called when the camera is turned on. 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(): Promise<void>;
Parameters
None.
Return value
A promise that resolves when the operation succeeds.
Code Snippet
await cameraEnhancer.turnOffTorch();
See also
getZoomSettings
Returns the zoom settings.
getZoomSettings(): { factor: number };
Parameters
None.
Return value
An object that describes the zoom settings. As of version 3.2, it contains only the zoom factor.
Code Snippet
console.log(cameraEnhancer.getZoomSettings().factor);
setZoom
Zooms the video.
How it works:
- If the camera supports zooming and the zoom factor is within its supported range, zooming is done directly by the camera.
- If the camera does not support zooming, software-based magnification is used instead.
- If the camera supports zooming but the zoom factor is beyond what it supports, the camera’s maximum zoom is used, and software-based magnification is used to do the rest. (In this case, you may see a brief video flicker between the two zooming processes).
setZoom(settings:{factor: number}): Promise<void>;
Parameters
settings
: specifies how to zoom the video. As of version 3.2, the setting only contains a zoom factor.
Return value
A promise that resolves when the operation succeeds.
Code Snippet
if(cameraEnhancer.getCapabilities().zoom) {
await cameraEnhancer.setZoom({
factor: 3
});
}
See also
resetZoom
Resets the zoom level of the video.
resetZoom(): Promise<void>;
Parameters
None.
Return value
A promise that resolves when the operation succeeds.
Code Snippet
await cameraEnhancer.resetZoom();
getFocusSettings
Returns the focus settings.
type FocusArea = {
centerPoint: { x: string, y: string };
width: string;
height: string;
};
getFocusSettings(): {mode: string} | {mode: "manual", area: FocusArea} | {mode: "manual", distance: number};
Parameters
None.
Return value
The current focus settings.
Code Snippet
cameraEnhancer.getFocusSettings();
See also
setFocus
Sets how the camera focuses.
NOTE:
- This method should be called when the camera is turned on. 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.
- Typically,
continuous
mode works best.manual
mode based on a specific area helps the camera focus on that particular area which may seem blurry undercontinuous
mode.manual
mode with specified distances is for those rare cases where the camera distance must be fine-tuned to get the best results.
setFocus(settings: { mode: string } | { mode: 'manual', distance: number } | {
mode: 'manual', area: {
centerPoint: { x: string, y: string };
// If not specified, the width is 1/6 of the video width or height, whichever is narrower
width?: string;
// If not specified, the height is 1/6 of the video width or height, whichever is narrower
height?: string;
}
}): Promise<void>;
Parameters
settings
: specifies the focus settings. The value of mode
depends on the capabilities of the current camera. Typically, “continuous” and “manual” are supported. distance
and area
are only effective when mode
is set to manual
and they should not coexist. The combinations are shown in the code snippet.
Return value
A promise that resolves when the operation succeeds.
Code Snippet
The “continuous” mode invokes the camera to focus automatically and continuously. Use getCapabilities() to inspect whether the camera supports “continuous” mode.
if (cameraEnhancer.getCapabilities().focusMode.find(mode => mode.localeCompare('continuous') == 0)) {
await cameraEnhancer.setFocus({
mode: "continuous"
});
}
The “manual” mode means manually specifying the focus distance. Use getCapabilities() to inspect the distance range.
cameraEnhancer.getCapabilities().focusDistance; > //{max: 1024, min: 0, step: 10}
NOTE: If the set distance is between two allowed values, it will be rounded to the nearest value.
await cameraEnhancer.setFocus({
mode: "manual",
distance: 200
});
The SDK also has a built-in algorithm that adjusts focus distance based on the blurriness of a particular area. Specify the area with the parameter
area
.NOTE: the area is a rectangle defined by its center point and its width and height. All coordinates can be in pixels or percentages, such as “500px” or “50%”. Percentages are based on stream dimensions.
await cameraEnhancer.setFocus({
mode: "manual",
area: {
centerPoint: {
x: "50%",
y: "50%"
},
width: "50%",
height: "50%"
}
});
See also
getCapabilities
Inspects and returns the capabilities of the selected camera.
At present, this method only works in Edge, Safari, Chrome and other Chromium-based browsers (Firefox is not supported). Also, it should be called when a camera is open.
getCapabilities(): MediaTrackCapabilities;
Parameters
None.
Return value
A MediaTrackCapabilities
object which specifies the values or range of values for each constrainable property of the current camera.
Code Snippet
cameraEnhancer.getCapabilities();
/* Result sample
{
aspectRatio: {max: 1280, min: 0.001388888888888889},
brightness: {max: 64, min: -64, step: 1},
colorTemperature: {max: 6500, min: 2800, step: 10},
contrast: {max: 95, min: 0, step: 1},
deviceId: "3a505c29a3312600ea0afd79f8e2b4ba4fba3e539257801ff1de8718c27f2bed",
exposureMode: ["continuous", "manual"],
exposureTime: {max: 10000, min: 39.0625, step: 39.0625},
facingMode: [],
focusDistance: {max: 1024, min: 0, step: 10},
focusMode: ["continuous", "manual"],
frameRate: {max: 30, min: 0},
groupId: "35a82dcb7d5b0ef5bda550718d194f04a812c976175e926ccb81fb9d235d010f",
height: {max: 720, min: 1},
resizeMode: ["none", "crop-and-scale"],
saturation: {max: 100, min: 0, step: 1},
sharpness: {max: 7, min: 1, step: 1},
whiteBalanceMode: ["continuous", "manual"],
width: {max: 1280, min: 1}
}
*/
See also
getCameraSettings
Returns the current values for each constrainable property of the selected camera.
getCameraSettings(): MediaTrackSettings;
Parameters
None.
Return value
The current values for each constrainable property of the current camera in the form of a MediaTrackSettings object.
Code Snippet
cameraEnhancer.getCameraSettings();
/* Result sample
{
aspectRatio: 1.3333333333333333,
brightness: 0,
colorTemperature: 4600,
contrast: 0,
deviceId: "3a505c29a3312600ea0afd79f8e2b4ba4fba3e539257801ff1de8718c27f2bed",
exposureMode: "continuous",
exposureTime: 156.25,
focusDistance: 120,
focusMode: "continuous",
frameRate: 30,
groupId: "35a82dcb7d5b0ef5bda550718d194f04a812c976175e926ccb81fb9d235d010f",
height: 480,
resizeMode: "none",
saturation: 73,
sharpness: 2,
whiteBalanceMode: "continuous",
width: 640
}
*/
See also
getColorTemperature
Returns the color temperature of the selected camera.
This method should be called when the camera is turned on. 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.
getColorTemperature(): number;
setColorTemperature
Adjusts the color temperature of the selected camera.
This method should be called when the camera is turned on. 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.
setColorTemperature(colorTemperatur: number): Promise<void>;
Parameters
colorTemperatur
: specifies the new color temperature.
Return value
A promise that resolves when the operation succeeds.
Code Snippet
await cameraEnhancer.setColorTemperature(5000);
See also
getExposureCompensation
Returns the exposure compensation index of the selected camera.
This method should be called when the camera is turned on. 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.
getExposureCompensation(): number;
setExposureCompensation
Sets the exposure compensation index of the selected camera.
This method should be called when the camera is turned on. 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.
setExposureCompensation(exposureCompensation: number): Promise<void>;
Parameters
exposureCompensation
: specifies the new exposure compensation index.
Return value
A promise that resolves when the operation succeeds.
Code Snippet
await cameraEnhancer.setExposureCompensation(-0.7);
See also
setAutoZoomRange
Sets the range (minimum to maximum) for zoom when it is done automatically.
EF_AUTO_ZOOM
is one of the enhanced features that require a license, and is only effective when used in conjunction with other functional products of Dynamsoft.
setAutoZoomRange(range: { min: number, max: number }): void;
Parameters
range
: specifies the zoom range (from minimum value to maximum value).
Return value
None.
Code Snippet
cameraEnhancer.setAutoZoomRange({min: 1, max: 5});
getAutoZoomRange
Returns the auto zoom range.
getAutoZoomRange(): { min: number, max: number };
Parameters
None.
Return value
The zoom range.
Code Snippet
let zoomRange = cameraEnhancer.getAutoZoomRange();
enableEnhancedFeatures
Enables the specified enhanced features.
- The enhanced features require a license, and only take effect when used in conjunction with other functional products under Dynamsoft Capture Vision(DCV)architecture:
EF_ENHANCED_FOCUS
,EF_AUTO_ZOOM
,EF_TAP_TO_FOCUS
.EF_ENHANCED_FOCUS
andEF_TAP_TO_FOCUS
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.
enableEnhancedFeatures(features: EnumEnhancedFeatures): Promise<void>;
Parameters
features
: specifies the features to enable.
Return value
None.
Code Snippet
//you need to include cvr and initialize the license for enabling enhanced features
Dynamsoft.License.LicenseManager.initLicense("YOUR-LICENSE");
await cameraEnhancer.enableEnhancedFeatures(EnumEnhancedFeatures.EF_AUTO_ZOOM);
See also
disableEnhancedFeatures
Disables the specified enhanced features.
disableEnhancedFeatures(features: EnumEnhancedFeatures): void;
Parameters
features
: specifies the features to disable.
Return value
None.
Code Snippet
await cameraEnhancer.disableEnhancedFeatures(EnumEnhancedFeatures.EF_AUTO_ZOOM);
See also
ifSkipCameraInspection
Sets or returns whether to opt for an optimal rear camera at the first open()
. If skipped, the instantiation is done faster. Note that if a previously used camera is already available in the localStorage, the inspection is skipped automatically. Read more on ifSaveLastUsedCamera.
ifSkipCameraInspection: boolean;