Resource Base
Table of contents

DSCameraEnhancer

The DSCameraEnhancer class is the primary class of Dynamsoft Camera Enhancer that defines the camera controlling APIs. It is a subclass of DSImageSourceAdapter.

Definition

Assembly: DynamsoftCameraEnhancer.xcframework

  • Objective-C
  • Swift
  1. @interface DSCameraEnhancer: DSImageSourceAdapter
    
  2. class CameraEnhancer : ImageSourceAdapter
    

Methods

Method Description
addListener Add a DSVideoFrameListener to receive callback when video frames are output.
removeListener Remove a DSVideoFrameListener.
takePhoto Take a photo.
getCameraPosition Get the camera position.
setZoomFactor Set the zoom factor of the camera. You can use getCapabilities to check the maximum available zoom factor.
getZoomFactor Get the zoom factor of the camera.
getFocusMode Get the currently actived focus mode.
initSystemSettingsFromFile Initialize system settings from a JSON file. The system settings contain more precise camera control parameters.
initSystemSettings Initialize system settings from a JSON string. The system settings contain more precise camera control parameters.
resetSystemSettings Reset the system settings to default value.
initEnhancedSettingsFromFile Initialize enhanced settings from a JSON file. The enhanced settings contain auxiliary parameters of enhanced features.
initEnhancedSettings Initialize enhanced settings from a JSON string. The enhanced settings contain auxiliary parameters of enhanced features.
outputEnhancedSettings Output the enhanced settings to a JSON string. The enhanced settings contain auxiliary parameters of enhanced features.
outputEnhancedSettingsToFile Output the enhanced settings to a JSON file. The enhanced settings contain auxiliary parameters of enhanced features.
resetEnhancedSettings Reset the enhanced settings to default value.
getCapabilities Get the device capabilities including zoom factor, ISO, exposure time, etc.
getCameraState Tells you whether the camera is open, opening, closing, or closed - each state being represented by a member of the CameraState enumeration.
setCameraStateListener Set a DSCameraStateListener to receive callback when the camera state changed.
enableEnhancedFeatures Enable the specified enhanced features. View DSEnhancedFeatures for more details.
disableEnhancedFeatures Disable the specified enhanced features. View DSEnhancedFeatures for more details.
initWithView Create an instance of DSCameraEnhancer.
init Create an instance of DSCameraEnhancer.
setScanRegion Set a scan region. The video frame is cropped based on the scan region.
getScanRegion Get a scan region.
open Open the camera.
close Close the camera.
setResolution Set the resolution. If the targeting resolution is not available for your device, a closest available resolutionll be selected.
getResolution Get the current resolution.
getAllCameras Get the IDs of all available cameras.
selectCamera Select a camera with a camera ID.
selectCameraWithPosition Select a camera with a camera position.
getSelectedCamera Get the currently actived camera.
getFrameRate Get the frame rate.
turnOnTorch Turn on the torch.
turnOffTorch Turn off the torch.
setFocus Set the focus point of interest and trigger an one-off auto-focus.
setFocus(subsequentFocusMode) Set the focus point of interest and trigger an one-off auto-focus. After the focus, you can either lock the focalngth or keep the continuous auto focus enabled by configuring the subsequent focus mode.
convertRectToViewCoordinates Convert the coordinates of a DSRect under video coordinate system to a CGRect under camera view coordinate system.
convertPointToViewCoordinates Convert the coordinates of a CGPoint under video coordinate system to another CGPoint under camera view coordinate system.

Attributes

Attributes Type Description
imageCaptureDistanceMode Set/get the capture distance property of the video frame. The capture distance property will be recorded by DSVideoFrameTag.  
autoZoomRange Set/get the range of auto zoom.  
cameraView Set/get the DSCameraView instance that bind with this DSCameraEnhancer instance.  

Inherited Methods

The following methods are inherited from base class ImageSourceAdapter

Method Description
startFetching Start fetching images from the source to the Video Buffer of ImageSourceAdapter.
stopFetching Stop fetching images from the source to the Video Buffer of ImageSourceAdapter.
getImage Get an image from the Video Buffer.
setNextImageToReturn Specify the next image that is returned by method getImage.
hasImage Check the availability of the specified image.
addImageToBuffer Adds an image to the buffer of the adapter.
clearBuffer Clears the image buffer.
setErrorListener Registers a ImageSourceErrorListener to be used as a callback when an error occurs in the ImageSourceAdapter.

Inherited Properties

The following properties are inherited from base class ImageSourceAdapter

Attributes Type Description
hasNextImageToFetch BOOL Determines whether there are more images left to fetch.
maxImageCount NSUInteger The property defines the maximum capability of the Video Buffer.
bufferOverflowProtectionMode DSBufferOverflowProtectionMode Sets a mode that determines the action to take when there is a new incoming image and the buffer is full. You can either block the Video Buffer or push out the oldest image and append a new one.
imageCount NSUInteger The property defines current image count in the Video Buffer.
bufferEmpty BOOL The read only property indicates whether the Video Buffer is empty.
colourChannelUsageType colourChannelUsageType The usage type of a color channel in an image.

addListener

Add a DSVideoFrameListener to receive callback when video frames are output.

  • Objective-C
  • Swift
  1. - (void)addListener:(nonnull id<DSVideoFrameListener>)listener NS_SWIFT_NAME(addListener(_:));
    
  2. func addListener(_ listener: DSVideoFrameListener)
    

Parameters

listener: A delegate object of DSVideoFrameListener to receive video frame as a DSImageData.

removeListener

Remove a DSVideoFrameListener.

  • Objective-C
  • Swift
  1. - (void)removeListener:(nonnull id<DSVideoFrameListener>)listener NS_SWIFT_NAME(removeListener(_:));
    
  2. func removeListener(_ listener: DSVideoFrameListener)
    

Parameters

listener: A delegate object of VideoFrameListener.

takePhoto

Take a photo.

  • Objective-C
  • Swift
  1. - (void)takePhoto:(DSPhotoListener)photoListener;
    
  2. func takePhoto(_ photoListener: PhotoListener)
    

Parameters

photolistener: A delegate object of DSPhotoListener to receive the captured photo.

getCameraPosition

Get the camera position.

  • Objective-C
  • Swift
  1. - (DSCameraPosition)getCameraPosition;
    
  2. func getCameraPosition() -> CameraPosition
    

Return Value

The camera position.

setZoomFactor

Set the zoom factor of the camera. You can use getCapabilities to check the maximum available zoom factor.

  • Objective-C
  • Swift
  1. - (void)setZoomFactor:(CGFloat)factor;
    
  2. func setZoomFactor(_ factor: CGFloat)
    

Parameters

factor: The zoom factor.

getZoomFactor

Get the zoom factor of the camera.

  • Objective-C
  • Swift
  1. - (CGFloat)getZoomFactor;
    
  2. func getZoomFactor() -> CGFloat
    

Return Value

The zoom factor.

getFocusMode

Get the currently actived focus mode.

  • Objective-C
  • Swift
  1. - (DSFocusMode)getFocusMode;
    
  2. func getFocusMode() -> FocusMode
    

Return Value

The focus mode.

initSystemSettingsFromFile

Initialize system settings from a JSON file. The system settings contain more precise camera control parameters.

  • Objective-C
  • Swift
  1. - (BOOL)initSystemSettingsFromFile:(NSString*)filePath error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(initSettingsFromFile(_:));
    
  2. func initSystemSettingsFromFile(_ filePath: String) throws -> BOOL
    

Parameters

filePath: The path of the JSON file.

error: A NSError pointer. An error occurs when the file path is not available or the JSON datacludes invalid keys or values.

Return Value

A bool value that indicates whether the system settings are initialized successfully.

initSystemSettings

Initialize system settings from a JSON string. The system settings contain more precise camera control parameters.

  • Objective-C
  • Swift
  1. - (BOOL)initSystemSettings:(NSString*)JsonString error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(initSettings(_:));
    
  2. func initSystemSettings(_ filePath: String) throws -> BOOL
    

Parameters

JsonString: The JSON string.

error: A NSError pointer. An error occurs when the JSON data includes invalid keys or values.

Return Value

A bool value that indicates whether the system settings are initialized successfully.

resetSystemSettings

Reset the system settings to default value.

  • Objective-C
  • Swift
  1. - (void)resetSystemSettings;
    
  2. func resetSystemSettings()
    

initEnhancedSettingsFromFile

Initialize enhanced settings from a JSON file. The enhanced settings contain auxiliary parameters of enhanced features.

  • Objective-C
  • Swift
  1. - (BOOL)initEnhancedSettingsFromFile:(NSString*)filePath error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(initSettingsFromFile(_:));
    
  2. func initEnhancedSettingsFromFile(_ filePath: String) throws -> BOOL
    

Parameters

filePath: The JSON string.

error: A NSError pointer. An error occurs when the file path is not available or the JSON data includes invalid keys or values.

Return Value

A bool value that indicates whether the enhanced settings are initialized successfully.

initEnhancedSettings

Initialize enhanced settings from a JSON string. The enhanced settings contain auxiliary parameters of enhanced features.

  • Objective-C
  • Swift
  1. - (BOOL)initEnhancedSettings:(NSString*)JsonString error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(initSettings(_:));
    
  2. func initEnhancedSettings(_ JsonString: String) throws -> BOOL
    

Parameters

JsonString: The JSON string.

error: A NSError pointer. An error occurs when the JSON data includes invalid keys or values.

Return Value

A bool value that indicates whether the enhanced settings are initialized successfully.

outputEnhancedSettings

Output the enhanced settings to a JSON string. The enhanced settings contain auxiliary parameters of enhanced features.

  • Objective-C
  • Swift
  1. - (nullable NSString *)outputEnhancedSettings:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(outputSettings());
    
  2. func outputEnhancedSettings() throws -> String
    

Parameters

error: A NSError pointer. An error occurs when the JSON data includes invalid keys or values.

Return Value

The enhanced settings in a JSON string.

outputEnhancedSettingsToFile

Output the enhanced settings to a JSON file. The enhanced settings contain auxiliary parameters of enhanced features.

  • Objective-C
  • Swift
  1. - (BOOL)outputEnhancedSettingsToFile:(NSString *)file error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(outputSettingsToFile(_:templateName:));
    
  2. func outputEnhancedSettingsToFile(_ file: String) throws -> String
    

Parameters

file The path that you want to output the JSON file.

error A NSError pointer. An error occurs when the file path is not available.

Return Value

A bool value that indicates whether the enhanced settings are output successfully.

resetEnhancedSettings

Reset the enhanced settings to default value.

  • Objective-C
  • Swift
  1. - (void)resetEnhancedSettings;
    
  2. func resetEnhancedSettings()
    

getCapabilities

Get the device capabilities including zoom factor, ISO, exposure time, etc.

  • Objective-C
  • Swift
  1. - (DSCapabilities *)getCapabilities;
    
  2. func getCapabilities() -> Capabilities
    

Return Value

A DSCapabilities object.

getCameraState

Tells you whether the camera is open, opening, closing, or closed - each state being represented by a member of the CameraState enumeration.

  • Objective-C
  • Swift
  1. - (DSCameraState)getCameraState;
    
  2. func getCameraState() -> CameraState
    

Return Value

The camera state.

setCameraStateListener

Set a DSCameraStateListener to receive callback when the camera state changes.

  • Objective-C
  • Swift
  1. - (void)setCameraStateListener:(nullable id<DSCameraStateListener>)listener;
    
  2. func setCameraStateListener(_ listener: CameraStateListener)
    

Parameters

listener: A delegate object of DSCameraStateListener to the camera state.

enableEnhancedFeatures

Enable the specified enhanced features. View DSEnhancedFeatures to learn about these enhanced features. By default, these enhanced features are all disabled.

  • Objective-C
  • Swift
  1. - (bool)enableEnhancedFeatures:(NSInteger)enhancedFeatures;
    
  2. func enableEnhancedFeatures(_ enhancedFeatures: Int) -> BOOL
    

Parameters

enhancedFeatures: A combined value of DSEnhancedFeatures which indicates a series of enhanced features.

Return Value

A bool value that indicates whether the enhanced features are enabled successfully.

disableEnhancedFeatures

Disable any enhanced features that have been previously enabled. View DSEnhancedFeatures to learn about these enhanced features.

  • Objective-C
  • Swift
  1. - (void)disableEnhancedFeatures:(NSInteger)enhancedFeatures;
    
  2. func disableEnhancedFeatures(_ enhancedFeatures: Int)
    

Parameters

enhancedFeatures: A combined value of DSEnhancedFeatures which indicates a series of enhanced features.

initWithView

Create an instance of DSCameraEnhancer with a DSCameraView object.

  • Objective-C
  • Swift
  1. - (instancetype)initWithView:(DSCameraView *)view NS_SWIFT_NAME(init(view:));
    
  2. init(view: CameraView)
    

Parameters

view A DSCameraView instance.

Return Value

An instance of DSCameraEnhancer.

init

Create an instance of DSCameraEnhancer.

  • Objective-C
  • Swift
  1. - (instancetype)init;
    
  2. init()
    

Return Value

An instance of DSCameraEnhancer.

setScanRegion

Set a scan region. The video frame is cropped based on the scan region. To learn the full code to setting a scan region, please refer to the scan region article.

  • Objective-C
  • Swift
  1. - (BOOL)setScanRegion:(DSRect* _Nullable)scanRegion error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(setScanRegion(_:));
    
  2. func setScanRegion(_ scanRegion: DSRect) -> BOOL
    

Parameters

scanRegion: A DSRect object.

error: A NSError pointer. An error occurs when the DSRect data is invalid.

Return Value

A bool value that indicates whether the scan region has been successfully set or not.

getScanRegion

Get the scan region if one has been set.

  • Objective-C
  • Swift
  1. - (nullable DSRect*)getScanRegion;
    
  2. func getScanRegion() -> DSRect
    

Return Value

A DSRect object that represent the scan region area.

open

Open the camera.

  • Objective-C
  • Swift
  1. - (void)open;
    
  2. func open()
    

close

Close the camera.

  • Objective-C
  • Swift
  1. - (void)close;
    
  2. func close()
    

setResolution

Set the resolution. If the targeted resolution is not available for your device, the closest available resolution will be selected.

  • Objective-C
  • Swift
  1. - (void)setResolution:(DSResolution)resolution;
    
  2. func setResolution(_ resolution: Resolution)
    

Parameters

resolution One of the DSResolution value.

getResolution

Get the current resolution.

  • Objective-C
  • Swift
  1. - (NSString*)getResolution;
    
  2. func getResolution() -> Resolution
    

Return Value

The current resolution.

getAllCameras

Get the IDs of all available cameras.

  • Objective-C
  • Swift
  1. - (NSArray<NSString*>*)getAllCameras;
    
  2. func getAllCameras() -> [String]
    

Return Value

An array of camera IDs.

selectCamera

Select a camera with a camera ID.

  • Objective-C
  • Swift
  1. - (BOOL)selectCamera:(NSString*)cameraId error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(selectCamera(_:));
    
  2. func selectCamera(_ cameraId: String) -> BOOL
    

Parameters

position: One of the Camera IDs.

error: A NSError pointer. An error occurs when failed to switch the camera.

Return Value

A bool value that indicates whether the camera selection is successful.

selectCameraWithPosition

Select a camera with a camera position.

  • Objective-C
  • Swift
  1. - (BOOL)selectCameraWithPosition:(DSCameraPosition)position error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(selectCameraWithPosition(_:));
    
  2. func selectCameraWithPosition(_ position: CameraPosition) -> BOOL
    

Parameters

position: One of the DSCameraPosition value.

error: A NSError pointer. An error occurs when failed to switch the camera.

Return Value

A bool value that indicates whether the camera selection is successful.

getSelectedCamera

Get the currently actived camera.

  • Objective-C
  • Swift
  1. - (NSString*)getSelectedCamera;
    
  2. func getSelectedCamera() -> String
    

Return Value

The ID of the currently actived camera.

getFrameRate

Get the frame rate.

  • Objective-C
  • Swift
  1. - (NSInteger)getFrameRate;
    
  2. func getFrameRate() -> Int
    

Return Value

The current frame rate.

turnOnTorch

Turn on the torch.

  • Objective-C
  • Swift
  1. - (void)turnOnTorch;
    
  2. func turnOnTorch()
    

turnOffTorch

Turn off the torch.

  • Objective-C
  • Swift
  1. - (void)turnOffTorch;
    
  2. func turnOffTorch()
    

setFocus

Set the focus point of interest and trigger an one-off auto-focus.

  • Objective-C
  • Swift
  1. - (void)setFocus:(CGPoint)focusPoint;
    
  2. func setFocus(_ focusPoint: CGPoint)
    

Parameters

focusPoint: The focus point of interest. The coordinate base of the point is “image”.

setFocus(subsequentFocusMode)

Set the focus point of interest and trigger an one-off auto-focus. After the focus, you can either lock the focalngth or keep the continuous auto focus enabled by configuring the subsequent focus mode.

  • Objective-C
  • Swift
  1. - (void)setFocus:(CGPoint)focusPoint focusMode:(DSFocusMode)subsequentFocusMode;
    
  2. func setFocus(_ focusPoint: CGPoint, subsequentFocusMode: FocusMode)
    

Parameters

focusPoint: The focus point of interest. The coordinate base of the point is “image”.

subsequentFocusMode: The subsequent focus mode.

convertRectToViewCoordinates

Convert the coordinates of a DSRect under video coordinate system to a CGRect under camera view coordinate system.

  • Objective-C
  • Swift
  1. - (CGRect)convertRectToViewCoordinates:(DSRect)videoRect;
    
  2. func convertRectToViewCoordinates(_ videoRect: DSRect) -> CGRect
    

Parameters

videoRect: The DSRect that you want to convert.

Return Value

A CGRect (coordinate measured in PT) converted from the DSRect.

Code Snippet

  • Objective-C
  • Swift
  1. CGRect rect = [cameraView convertRectToViewCoordinates:videoRect];
    
  2. let rect = cameraView.convertRectToViewCoordinates(videoRect)
    

convertPointToViewCoordinates

Convert the coordinates of a CGPoint under video coordinate system to another CGPoint under camera view coordinate system.

  • Objective-C
  • Swift
  1. - (CGPoint)convertPointToViewCoordinates:(CGPoint)point;
    
  2. func convertPointToViewCoordinates(_ point: CGPoint) -> CGPoint
    

Parameters

point: The CGPoint that you want to convert.

Return Value

A CGPoint (coordinate measured in PT) converted from the video CGPoint measured in PT.

Code Snippet

  • Objective-C
  • Swift
  1. CGPoint convertedPoint = [cameraView convertPointToViewCoordinates:videoPoint];
    
  2. let convertedPoint = cameraView.convertPointToViewCoordinates(point)
    

imageCaptureDistanceMode

Set/get the capture distance property of the video frame. The capture distance property will be recorded by DSVideoFrameTag.

  • Objective-C
  • Swift
  1. @property (nonatomic, assign) DSImageCaptureDistanceMode imageCaptureDistanceMode;
    
  2. var imageCaptureDistanceMode: CGPoint { get set }
    

autoZoomRange

Set/get the range of auto zoom.

  • Objective-C
  • Swift
  1. @property (nonatomic, assign) UIFloatRange autoZoomRange;
    
  2. var autoZoomRange: UIFloatRange { get set }
    

cameraView

Set/get the DSCameraView instance that bind with this DSCameraEnhancer instance.

  • Objective-C
  • Swift
  1. @property (nonatomic, assign) DSCameraView * cameraView;
    
  2. var cameraView: CameraView { get set }
    

This page is compatible for:

Version 1.0

Is this page helpful?

YesYes NoNo

In this article:

latest version

  • Latest version
  • Version 4.x
    • Version 4.2.10
    • Version 4.2.1
    • Version 4.2.0
    • Version 4.0.2
    • Version 4.0.1
    • Version 4.0.0
  • Version 3.x
    • Version 3.0.3
    • Version 3.0.2
    • Version 3.0.1
    • Version 3.0.0
  • Version 2.x
    • Version 2.3.21
    • Version 2.3.20
    • Version 2.3.12
    • Version 2.3.11
    • Version 2.3.10
    • Version 2.3.5
    • Version 2.3.4
    • Version 2.3.3
    • Version 2.3.2
    • Version 2.3.1
    • Version 2.3.0
    • Version 2.1.4
    • Version 2.1.3
    • Version 2.1.1
    • Version 2.0.0
Change +