Camera
Defined under the namespace Scandit.Datacapture.Core
- TorchState
Added in version 6.13.0
Possible values for the torch state.
- On
Added in version 6.13.0
Value to indicate that the torch is turned on.
- Off
Added in version 6.13.0
Value to indicate that the torch is turned off.
- VideoFrameResolution
interface VideoFrameResolutionAdded in version 6.13.0
Resolution of a video frame.
- Camera
class Camera : FrameSource
Added in version 6.13.0
Gives access to the built-in camera on Web. It implements the FrameSource interface, and, as such can be set as the frame source for the DataCaptureContext.
Instances of this class are created through one of the static methods pickBestGuess(), pickBestGuessForPosition() or forDeviceId().
The camera is started by changing the desired state to FrameSourceState.On.
By default, the resolution of captured frames as well as auto-focus and exposure settings are chosen such that they work best for a variety of use cases. To fine-tune recognition, the camera settings can be changed through applying new camera settings.
Cameras on web are not accessible by default, their details can only be retrieved once the user has granted permission.
Important
The permission prompt will be triggered when starting the camera, or if you gather Cameras from the device in advance by using getAll(). So you should not initiate the camera too early or the user will be prompted for permission when they are not expecting it.
Properties like deviceId and label will be updated on the instance only once the camera has been accessed. Similarly, the currentResolution will be updated only once the camera has been started.
Please bear in mind that web cameras do not always have meaningful metadata. The SDK will try to infer the position and other properties of the camera based on the metadata, but it is not always possible. That’s why the static methods pickBestGuess() and pickBestGuessForPosition() may not always return the camera you expect.
- desiredState
get desiredState(): FrameSourceState
Added in version 6.13.0
Implemented from FrameSource. See FrameSource.desiredState.
- getCurrentState()
getCurrentState(): FrameSourceState
Added in version 6.13.0
Implemented from FrameSource. See FrameSource.getCurrentState.
- position
position: CameraPosition
Added in version 6.13.0
The direction that the camera faces.
Note that this property represents a desirable position before the camera has started, but may get updated to a different value once the camera has started to reflect what the camera reports as position.
- currentResolution
get currentResolution(): VideoFrameResolution | null
Added in version 6.13.0
The current video frame resolution of the camera.
- addListener(listener)
addListener(listener: FrameSourceListener | null):
voidAdded in version 6.13.0
Implemented from FrameSource. See FrameSource.addListener().
- removeListener(listener)
removeListener(listener: FrameSourceListener | null):
voidAdded in version 6.13.0
Implemented from FrameSource. See FrameSource.removeListener().
- pickBestGuess()
static pickBestGuess(): Camera
Added in version 8.0.0
Returns a Camera instance representing the optimal camera detected on the device to capture data. Given the wide variation in web camera implementations and often incomplete metadata, this method employs heuristics to automatically select the camera best suited for reliable data capture operations.
Note that this function always return the same Camera instance.
- pickBestGuessForPosition(position)
static pickBestGuessForPosition(position: CameraPosition): Camera
Added in version 8.0.0
Returns a Camera instance representing the best camera detected on the device to capture data for the given position. Given the wide variation in web camera implementations and often incomplete metadata, this method employs heuristics to automatically select the camera that best matches the given position. In rare case the automatic detection may fail to select the right camera, either because no camera was found for the given position or because the algorithm could not determine the correct position from the metadata it received.
Note that until cameras have not been discovered on the device (happens when a camera starts or if you call getAll()), you cannot have more than one camera for a given position. Calling multiple times pickBestGuessForPosition() with the same position will return the same Camera instance.
- forDeviceId(deviceId)
static forDeviceId(deviceId: string): Camera
Added in version 8.0.0
Returns a Camera instance with the given deviceId. This method allows you to access a camera that you have already gathered from the device in advance using getAll(). Once started, the camera properties label and position will be updated.
Calling multiple times forDeviceId() with the same deviceId` will return the same instance.
- getAll(refreshDevices, cameraAlreadyAccessed)
static getAll(refreshDevices?: boolean, cameraAlreadyAccessed?: boolean): Promise<Camera[]>
Added in version 6.13.0
- Param [refreshDevices]
Force a call to refresh available video devices even when information is already available, defaults to false
- Param [cameraAlreadyAccessed]
Hint that a camera has already been accessed before, avoiding a possible initial camera access permission request on the first call, in cases this cannot be already reliably detected, defaults to false
Get a list of cameras (if any) available on the device, a camera access permission is requested to the user the first time this method is called if needed.
If the user denies the necessary camera access permission, a list of cameras with the correct amount of devices is returned in any case, but the cameras will have no available (empty) label and deviceId and can thus not be accessed.
If the browser is incompatible the returned promise is rejected with a UnsupportedBrowserError error.
When refreshing available devices, if updated deviceId information is detected, cameras’ deviceId are updated accordingly. This could happen after a camera is accessed and then stopped in some situations.
- switchToDesiredState(state)
switchToDesiredState(state: FrameSourceState): Promise<
void>Added in version 6.13.0
Implemented from FrameSource. See FrameSource.switchToDesiredState().
- applySettings(settings)
applySettings(settings: CameraSettings): Promise<
void>Added in version 6.13.0
Applies the camera settings to the camera. The task will complete when the settings have been applied and the camera has switched to use the new settings. If the camera is currently in FrameSourceState.Off state, the task will complete immediately. If, on the other hand, the camera is currently in FrameSourceState.On state, the settings will be modified on the fly.
- settings
get settings(): CameraSettings
Added in version 6.20.0
Get the currently set CameraSettings on this camera. Use applySettings() to apply new settings.
- isTorchAvailable()
isTorchAvailable(): Promise<boolean>
Added in version 6.13.0
Whether the torch is available for the given camera.
Available only on Chrome Android. When the camera is off, this method always returns false. When the camera is on, it returns true for cameras that support the torch, false otherwise.
- getDesiredTorchState()
getDesiredTorchState(): TorchState
Added in version 6.13.0
Get the desired torch state for this camera. By default, the torch state is TorchState.Off. When setting the desired torch state to TorchState.On, the torch will be on as long as the camera is running (the camera’s state is FrameSourceState.On) and off otherwise.
- setDesiredTorchState(desiredTorchState)
setDesiredTorchState(desiredTorchState: TorchState): Promise<
void>Added in version 6.13.0
Set the desired torch state for this camera. By default, the torch state is TorchState.Off. When setting the desired torch state to TorchState.On, the torch will be on as long as the camera is running (the camera’s state is FrameSourceState.On) and off otherwise. When setting the desired torch state for a camera that does not have a torch (see isTorchAvailable()), this call has no effect.
- getMirrorImageEnabled()
getMirrorImageEnabled(): boolean
Added in version 6.13.0
Get whether the currently selected camera’s video is mirrored along the vertical axis. By default front cameras are automatically mirrored.
- setMirrorImageEnabled(enabled)
setMirrorImageEnabled(enabled: boolean): Promise<
void>Added in version 6.13.0
Set whether the currently selected camera’s video is mirrored along the vertical axis. By default front cameras are automatically mirrored. This setting is applied per camera and the method has no effect if no camera is currently selected. In Single Image Mode this method has no effect.
- setClipArea(area)
setClipArea(area?: Rect): Promise<
void>Added in version 7.2.0
Clip the video stream to the given area. Must be called after switching the camera to FrameSourceState.On.