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

@interface DSCameraEnhancer: DSImageSourceAdapter

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`	Get the device capabilities including zoom factor, ISO, exposure time, etc.
`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

- (void)addListener:(nonnull id<DSVideoFrameListener>)listener NS_SWIFT_NAME(addListener(_:));

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

- (void)removeListener:(nonnull id<DSVideoFrameListener>)listener NS_SWIFT_NAME(removeListener(_:));

func removeListener(_ listener: DSVideoFrameListener)

Parameters

listener: A delegate object of VideoFrameListener.

takePhoto

Take a photo.

Objective-C
Swift

- (void)takePhoto:(DSPhotoListener)photoListener;

func takePhoto(_ photoListener: PhotoListener)

Parameters

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

getCameraPosition

Get the camera position.

Objective-C
Swift

```
- (DSCameraPosition)getCameraPosition;
```

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

```
- (void)setZoomFactor:(CGFloat)factor;
```
```
func setZoomFactor(_ factor: CGFloat)
```

Parameters

factor: The zoom factor.

getZoomFactor

Get the zoom factor of the camera.

Objective-C
Swift

```
- (CGFloat)getZoomFactor;
```
```
func getZoomFactor() -> CGFloat
```

Return Value

The zoom factor.

getFocusMode

Get the currently actived focus mode.

Objective-C
Swift

```
- (DSFocusMode)getFocusMode;
```
```
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

- (BOOL)initSystemSettingsFromFile:(NSString*)filePath error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(initSettingsFromFile(_:));

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

- (BOOL)initSystemSettings:(NSString*)JsonString error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(initSettings(_:));

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

```
- (void)resetSystemSettings;
```
```
func resetSystemSettings()
```

initEnhancedSettingsFromFile

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

Objective-C
Swift

- (BOOL)initEnhancedSettingsFromFile:(NSString*)filePath error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(initSettingsFromFile(_:));

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

- (BOOL)initEnhancedSettings:(NSString*)JsonString error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(initSettings(_:));

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

- (nullable NSString *)outputEnhancedSettings:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(outputSettings());

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

- (BOOL)outputEnhancedSettingsToFile:(NSString *)file error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(outputSettingsToFile(_:templateName:));

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

```
- (void)resetEnhancedSettings;
```
```
func resetEnhancedSettings()
```

getCapabilities

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

Objective-C
Swift

```
- (DSCapabilities *)getCapabilities;
```
```
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

```
- (DSCameraState)getCameraState;
```
```
func getCameraState() -> CameraState
```

Return Value

The camera state.

setCameraStateListener

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

Objective-C
Swift

- (void)setCameraStateListener:(nullable id<DSCameraStateListener>)listener;

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

- (bool)enableEnhancedFeatures:(NSInteger)enhancedFeatures;

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

- (void)disableEnhancedFeatures:(NSInteger)enhancedFeatures;

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

- (instancetype)initWithView:(DSCameraView *)view NS_SWIFT_NAME(init(view:));

```
init(view: CameraView)
```

Parameters

view A DSCameraView instance.

Return Value

An instance of DSCameraEnhancer.

init

Create an instance of DSCameraEnhancer.

Objective-C

Swift
- (instancetype)init;
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

- (BOOL)setScanRegion:(DSRect* _Nullable)scanRegion error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(setScanRegion(_:));

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

```
- (nullable DSRect*)getScanRegion;
```
```
func getScanRegion() -> DSRect
```

Return Value

A DSRect object that represent the scan region area.

open

Open the camera.

Objective-C

Swift
- (void)open;
func open()

close

Close the camera.

Objective-C
Swift

```
- (void)close;
```
```
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

- (void)setResolution:(DSResolution)resolution;

func setResolution(_ resolution: Resolution)

Parameters

resolution One of the DSResolution value.

getResolution

Get the current resolution.

Objective-C
Swift

```
- (NSString*)getResolution;
```
```
func getResolution() -> Resolution
```

Return Value

The current resolution.

getAllCameras

Get the IDs of all available cameras.

Objective-C
Swift

```
- (NSArray<NSString*>*)getAllCameras;
```
```
func getAllCameras() -> [String]
```

Return Value

An array of camera IDs.

selectCamera

Select a camera with a camera ID.

Objective-C
Swift

- (BOOL)selectCamera:(NSString*)cameraId error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(selectCamera(_:));

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

- (BOOL)selectCameraWithPosition:(DSCameraPosition)position error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(selectCameraWithPosition(_:));

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

```
- (NSString*)getSelectedCamera;
```
```
func getSelectedCamera() -> String
```

Return Value

The ID of the currently actived camera.

getFrameRate

Get the frame rate.

Objective-C
Swift

```
- (NSInteger)getFrameRate;
```
```
func getFrameRate() -> Int
```

Return Value

The current frame rate.

turnOnTorch

Turn on the torch.

Objective-C
Swift

```
- (void)turnOnTorch;
```
```
func turnOnTorch()
```

turnOffTorch

Turn off the torch.

Objective-C
Swift

```
- (void)turnOffTorch;
```
```
func turnOffTorch()
```

setFocus

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

Objective-C
Swift

```
- (void)setFocus:(CGPoint)focusPoint;
```
```
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

- (void)setFocus:(CGPoint)focusPoint focusMode:(DSFocusMode)subsequentFocusMode;

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

- (CGRect)convertRectToViewCoordinates:(DSRect)videoRect;

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

CGRect rect = [cameraView convertRectToViewCoordinates:videoRect];

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

- (CGPoint)convertPointToViewCoordinates:(CGPoint)point;

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

CGPoint convertedPoint = [cameraView convertPointToViewCoordinates:videoPoint];

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

@property (nonatomic, assign) DSImageCaptureDistanceMode imageCaptureDistanceMode;

var imageCaptureDistanceMode: CGPoint { get set }

autoZoomRange

Set/get the range of auto zoom.

Objective-C
Swift

@property (nonatomic, assign) UIFloatRange autoZoomRange;

var autoZoomRange: UIFloatRange { get set }

cameraView

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

Objective-C
Swift

@property (nonatomic, assign) DSCameraView * cameraView;

```
var cameraView: CameraView { get set }
```