DynamsoftCameraEnhancer Class

The main class of DynamsoftCameraEnhancer. It contains APIs that enable user to:

• Implement basic camera control like open, close, change resolution, etc.
• Get frames from the video streaming.
• Enable advanced features including:
  • Frame filtering by sharpness
  • Frame filtering by sensor
  • Enhanced focus
  • Frame cropping
  • Auto zoom
  • Smart torch control

• Objective-C
• Swift

1. @interface DynamsoftCameraEnhancer:NSObject<ImageSource>
   

2. class DynamsoftCameraEnhancer : NSObject, ImageSource
   

Initialization Methods Summary

Basic Camera Control Methods Summary

Frame Acquiring Methods Summary

Enhanced Features Methods Summary

Advanced Camera Control Methods Summary

Initialization Methods Details

initWithView

Initialize the camera enhancer with the DCECameraView.

• Objective-C
• Swift

1. - (instancetype)initWithView:(DCECameraView *)view;
   

2. init(view: DCECameraView) -> DynamsoftCameraEnhancer
   

Return Value

The instance of DynamsoftCameraEnhancer.

Code Snippet

• Objective-C
• Swift

1. _dce = [[DynamsoftCameraEnhancer alloc] initWithView:_dceView];
   

2. let dce = DynamsoftCameraEnhancer.init(view: dceCameraView)
   

getVersion

Get the SDK version of Dynamsoft Camera Enhancer.

• Objective-C
• Swift

1. + (NSString*)getVersion;
   

2. class func getVersion() -> String
   

Return Value

A string value that indicates the version of DynamsoftCameraEnhancer SDK.

Code Snippet

• Objective-C
• Swift

1. NSString* version = [DynamsoftCameraEnhancer getVersion];
   

2. let version = DynamsoftCameraEnhancer.getVersion()
   

cameraView

Bind a DCECameraView to the camera enhancer.

• Objective-C
• Swift

1. @property (strong, nonatomic) DCECameraView *dceCameraView; 
   

2. var dceCameraView: DCECameraView { get set }
   

Code Snippet

• Objective-C
• Swift

1. _dceView = [[DCECameraView alloc] initWithFrame:self.view.bounds]
   [_dce setCameraView:_dceView];
   

2. let dceView = DCECameraView.init(frame self.view.bounds)
   dce.cameraView = dceView
   

Basic Camera Control Methods Details

getAllCameras

Get the IDs of all available cameras.

• Objective-C
• Swift

1. - (NSArray*)getAllCameras;
   

2. func getAllCameras() -> [String]
   

Return Value

An NSArray that includes all available cameras. Users can clearly read whether the camera is front-facing, back-facing, or external from the cameraID.

Code Snippet

• Objective-C
• Swift

1. NSArray<NSString*>* allCameras = [_dce getAllCameras];
   

2. let allCameraList = dce.getAllCameras()
   

selectCameraWithPosition

Select the camera position (front-facing or back-facing).

• Objective-C
• Swift

1. - (void)selectCameraWithPosition:(EnumCameraPosition)position error:(NSError * _Nullable * _Nullable)error;
   

2. func selectCameraWithPosition(_ position: EnumCameraPosition) throws
   

Parameters

cameraPosition: An EnumCameraPosition value that indicates front-facing or back-facing camera.

Code Snippet

• Objective-C
• Swift

1. [_dce selectCameraWithPosition:EnumCameraPositionBack error: &error];
   

2. do{
      try dce.selectCameraWithPosition(EnumCameraPosition.back)
   }catch{
      // Add your code to deal with the exceptions.
   }
   

getCameraPosition

Returns whether the front-facing camera or back-facing camera is selected.

• Objective-C
• Swift

1. - (EnumCameraPosition) getCameraPosition;
   

2. func getCameraPosition() -> EnumCameraPosition
   

Return Value

An EnumCameraPosition value that indicates front-facing or back-facing camera.

Code Snippet

• Objective-C
• Swift

1. EnumCameraPosition cameraPosition = [_dce getCameraPosition];
   

2. let cameraPosition = dce.getCameraPosition()
   

selectCamera

Select camera by cameraID. The camera will be selected and further camera control settings will be applied to this camera. When the selected camera is changed via this method, the settings will be inherited by the newly selected camera.

• Objective-C
• Swift

1. - (void)selectCamera:(NSString*)cameraId error:(NSError * _Nullable * _Nullable)error;
   

2. func selectCamera(_ cameraId: String) throws
   

Parameters

cameraID: A String value that listed in the cameraIDList returned by getAllCameras. The method will have no effects if the input value does not exist in the cameraIDList.

Code Snippet

• Objective-C
• Swift

1. [_dce selectCamera:@"BACK_FACING_CAMERA" error: &error];
   

2. do{
      try  dce.selectCamera("BACK_FACING_CAMERA")
   }catch{
      // Add your code to deal with the exceptions.
   }
   

Remarks

• There is always a back-facing camera be defined as a default camera. If the user doesn’t select any camera via selectCamera, the default camera will be considered as the selected camera.
• If there is no opened camera, the method selectCamera will not open any camera.
• If there is an opened camera and the opened camera’s ID exactly equals the input ID, the method selectCamera will make no changes.
• If there is an opened camera and the opened camera’s ID is different from the input ID, the method selectCamera will close the currently opened camera and then open a new camera by the input ID.

getSelectedCamera

Get the ID of the currently selected camera.

• Objective-C
• Swift

1. - (NSString*)getSelectedCamera;
   

2. func getSelectedCamera() -> String
   

Return Value

The ID of the current selected camera.

Code Snippet

• Objective-C
• Swift

1. NSString* cameraID = [_dce getSelectedCamera];
   

2. let selectedCamera = dce.getSelectedCamera()
   

getCameraState

Get the state of the currently selected camera.

• Objective-C
• Swift

1. - (EnumCameraState*)getCameraState;
   

2. func getCameraState() -> EnumCameraState
   

Return Value

One of the preset camera state in Enumeration EnumCameraState.

Code Snippet

• Objective-C
• Swift

1. EnumCameraState state = [_dce getCameraState];
   

2. let cameraState = dce.getCameraState()
   

open

• Turn on the selected camera if a camera has been selected via selectCamera.
• Turn on the default camera if no camera is selected via selectCamera.

• Objective-C
• Swift

1. - (void)open;
   

2. func open()
   

Code Snippet

• Objective-C
• Swift

1. [_dce open];
   

2. dce.open()
   

close

• Turn off the selected camera if a camera has been selected via selectCamera.
• Turn off the default camera if no camera is selected via selectCamera.

• Objective-C
• Swift

1. - (void)close;
   

2. func close()
   

Code Snippet

• Objective-C
• Swift

1. [_dce close];
   

2. dce.close()
   

turnOnTorch

Turn on the torch (if the torch of the mobile device is available).

• Objective-C
• Swift

1. - (void)turnOnTorch;
   

2. func turnOnTorch()
   

Code Snippet

• Objective-C
• Swift

1. [_dce turnOnTorch];
   

2. dce.turnOnTorch()
   

turnOffTorch

Turn off the torch.

• Objective-C
• Swift

1. - (void)turnOffTorch;
   

2. func turnOffTorch()
   

Code Snippet

• Objective-C
• Swift

1. [_dce turnOffTorch];
   

2. dce.turnOffTorch()
   

getFrameRate

Get the current frame rate.

• Objective-C
• Swift

1. - (NSInteger)getFrameRate;
   

2. func getFrameRate() -> Int32
   

Return Value

The current frame rate.

Code Snippet

• Objective-C
• Swift

1. NSInteger frameRate = [_dce getFrameRate];
   

2. let frameRate = dce.getFrameRate()
   

setResolution

Input one of the preset resolution value in Enumeration Resolution. The camera enhancer will try to set the resolution to the target value or the closest available value below the target value.

• Objective-C
• Swift

1. - (void)setResolution:(EnumResolution)resolution;
   

2. func setResolution(_ resolution: EnumResolution)
   

Parameters

resolution: One of the int value that preset in Enumeration EnumResolution.

Code Snippet

• Objective-C
• Swift

1. [_dce setResolution:EnumRESOLUTION_1080P];
   

2. dce.setResolution(EnumResolution.EnumRESOLUTION_1080P)
   

getResolution

Get the current resolution.

• Objective-C
• Swift

1. - (NSString*)getResolution;
   

2. func getResolution() -> String
   

Return Value

The size of the current resolution.

Code Snippet

• Objective-C
• Swift

1. NSString* resolution = [_dce getResolution];
   

2. let resolution = dce.getResolution()
   

setZoom

Set the zoom factor. Once setZoom is triggered and approved, the zoom factor of the activated camera will immediately become the input value.

• Objective-C
• Swift

1. - (void)setZoom:(CGFloat)factor
   

2. func setZoom(_ factor: CGFloat)
   

Parameters

factor: The target zoom factor.

Code Snippet

• Objective-C
• Swift

1. [_dce setZoom:3.0f];
   

2. dce.setZoom(3.0)
   

autoZoomRange

The property for getting/setting the range of auto zoom.

• Objective-C
• Swift

1. @property (nonatomic, assign) UIFloatRange autoZoomRange;
   

2. var autoZoomRange: UIFloatRange { get set }
   

Code Snippet

• Objective-C
• Swift

1. [_dce setAutoZoomRange:UIFloatRangeMake(1.5,4)];
   UIFloatRange currentZoomRange = [_dce autoZoomRange];
   

2. dce.autoZoomRange = UIFloatRange(minimum:1.5, maximum: 4)
   let currentZoomRange = dce.autoZoomRange()
   

getMaxZoomFactor

Get the maximum available zoom factor.

• Objective-C
• Swift

1. - (CGFloat)getMaxZoomFactor;
   

2. func getMaxZoomFactor() -> CGFloat
   

Return Value

A CGFloat value that indicates the maximum available zoom factor of the device.

Code Snippet

• Objective-C
• Swift

1. CGFloat maxZoomFactor = [_dce getMaxZoomFactor];
   

2. let maxZoomFactor = dce.getMaxZoomFactor()
   

setFocus

Set the focus position (value range from 0.0f to 1.0f) and trigger a focus at the configured position.

• Objective-C
• Swift

1. - (void)setFocus:(CGPoint)point;
   

2. func setFocus(_ point: CGPoint)
   

Parameters

focusPosition: A CGPoint that stores the x and y coordinate of the targeting focus position.

Code Snippet

• Objective-C
• Swift

1. CGPoint focusPoint = {0.4, 0.5};
   [_dce setFocus:focusPoint];
   

2. let focusPoint = CGPoint(x:0.4, y:0.5)
   dce.setFocus(focusPoint)
   

setFocus(subsequentFocusMode)

Trigger a focus at the targeting point and set the subsequent focus mode after focused.

• Objective-C
• Swift

1. - (void)setFocus:(CGPoint)focusPoint subsequentFocusMode:(EnumFocusMode)subsequentFocusMode; 
   

2. func setFocus(_ focusPoint: CGPoint, focusMode subsequentFocusMode: EnumFocusMode)
   

Parameters

[in] focusPosition: A CGPoint indicates the interest area. [in] subsequentFocusMode: If you set the focus mode to FM_LOCKED, the focallength will be lock after the focus. Otherwise, the continuous auto focus that control by the hardware is still enabled.

Code Snippet

• Objective-C
• Swift

1. CGPoint focusPoint = {0.4, 0.5};
   [_dce setFocus:focusPoint subsequentFocusMode:EnumFocusMode.FM_LOCKED];
   

2. let focusPoint = CGPoint(x:0.4, y:0.5)
   dce.setFocus(focusPoint, subsequentFocusMode:EnumFocusMode.FM_LOCKEDD)
   

setScanRegion

Specify the scanRegion. The DCEFrames will be cropped according to the scanRegion before they are stored in the video buffer.

• Objective-C
• Swift

1. - (void)setScanRegion:(RegionDefinition)scanRegion error:(NSError * _Nullable)error;
   

2. func setScanRegion(_ scanRegion: iRegionDefinition?) throws
   

Parameters

scanRegion: Use a iRegionDefinition value to specify the scan region. The parameter will be optimized to the maximum or minimum available value if the input parameter is out of range. For more information, please view iRegionDefinition.

Code Snippet

• Objective-C
• Swift

1. iRegionDefinition* scanRegion = [[iRegionDefinition alloc] init];
   scanRegion.regionTop = 25;
   scanRegion.regionBottom = 75;
   scanRegion.regionLeft = 25;
   scanRegion.regionRight = 75;
   scanRegion.regionMeasuredByPercentage = 1
   [_dce setScanRegion:scanRegion error: &error];
   

2. let scanRegion = iRegionDefinition()
   scanRegion.regionTop = 25
   scanRegion.regionBottom = 75
   scanRegion.regionLeft = 25
   scanRegion.regionRight = 75
   scanRegion.regionMeasuredByPercentage = 1
   do{
      try  dce.setScanRegion(scanRegion)
   }catch{
      // Add your code to deal with the exceptions.
   }
   

Remarks

• The region definition defines the region on the camera view. For each value of the class iRegionDefinition:
  • The regionTop is the distance between the top of the scan region and the top of the video frame.
  • The regionBottom is the distance between the bottom of the scan region and the top of the video frame.
  • The regionLeft is the distance between the left of the scan region and the left of the video frame.
  • The regionRight is the distance between the right of the scan region and the left of the video frame.
• When you trigger setScanRegion, the enhancer feature EF_FAST_MODE will be disabled.
• You will still get the original DCEFrame from FrameOutputCallback and cropped DCEFrame from getFrameFromBuffer. The cropRegion of DCEFrame will be configured based on the scanRegion when setScanRegion is triggered.
• When you trigger setScanRegion, the scanRegionVisible will be set to true automatically. If you don’t want to display the scanRegion on the UI, please set the scanRegionVisible to false manually.

getScanRegion

Get the current scan region settings.

• Objective-C
• Swift

1. - (iRegionDefinition) getScanRegion
   

2. func getScanRegion() -> iRegionDefinition?
   

Return Value

The return value of getScanRegion is always the actual parameter of the scanRegion, which might be different from the user input parameter. If scanRegion is not configured or the method setScanRegion is not approved, the return value will be null.

Code Snippet

• Objective-C
• Swift

1. iRegionDefinition* myScanRegion = [[iRegionDefinition alloc] init];
   myScanRegion = [_dce getScanRegion];
   

2. let scanRegion = iRegionDefinition()
   scanRegion = dce.getScanRegion()
   

scanRegionVisible

Set whether to display the scanRegion on the UI. The default value of the property is false. When the property value is set to true, the scan region will be drawn on the UI. The scanRegion will not be displayed if its value is null.

• Objective-C
• Swift

1. @property (assign, nonatomic) BOOL scanRegionVisible;
   

2. var scanRegionVisible: Bool { get set }
   

setCameraStateListener

Set a DCECameraStateListener to receive notifications when the camera state changes.

• Objective-C
• Swift

1. - (void) setCameraStateListener:(nonnull id<DCECameraStateListener>)listener;
   

2. func setCameraStateListener(_ listener: DCECameraStateListener?)
   

Parameters

[in] listener: A DCECameraStateListener object.

Code Snippet

• Objective-C
• Swift

1. @interface ViewController ()<DCECameraStateListener>
   - (void)configurationDCE{
      [_dce setCameraStateListener:self];
   }
   - (void)stateChangeCallback:(EnumCameraState)state{
      // Add your code to do when camera state changes.
   }
   

2. class ViewController: UIViewController,DCECameraStateListener{
      func configurationDCE(){
         dce.setCameraStateListener(self)
      }
      func stateChangeCallback(EnumCameraState currentState){
         // Add your code to do when camera state changes.
      }
   }
   

Frame Acquiring Methods Details

getFrameFromBuffer

Get the latest frame from the buffer. The boolean value determines whether the fetched frame will be removed from the buffer.

• Objective-C
• Swift

1. - (DCEFrame*)getFrameFromBuffer:(BOOL)keep;
   

2. func getFrameFromBuffer(_ iskeep: Bool) -> DCEFrame
   

Parameters

Keep: If set to true, the frame will be kept in the video buffer. Otherwise, it will be removed from the video buffer.

Return Value

The latest frame in the video buffer.

Code Snippet

• Objective-C
• Swift

1. dceFrame = [_dce getFrameFromBuffer:true];
   

2. let dceFrame = dce.getFrameFromBuffer()
   

addListener

Add a listener to the CameraEnhancer instance. This method will have no effect if the same listener is already added.

• Objective-C
• Swift

1. - (void)addListener:(nonnull id<DCEFrameListener>)listener;
   

2. func addListener(_ listener: DCEFrameListener)
   

Parameters

listener: An object of DCEFrameListener. Its callback method frameOutputCallback will be available for users to make further operations on the captured video frame.

Code Snippet

• Objective-C
• Swift

1. [_dce addListener:self];
   

2. dce.addListener(self)
   

removeListener

Remove a previously added listener from the CameraEnhancer instance. This method will have no effect if there is no listener exists in CameraEnhancer instance.

• Objective-C
• Swift

1. - (void)removeListener:(nonnull id<DCEFrameListener>)listener;
   

2. func removeListener(_ listener: DCEFrameListener)
   

Parameters

listener: The input listener will be removed from the Camera Enhancer instance.

Code Snippet

• Objective-C
• Swift

1. [_dce removeListener:self];
   

2. dce.removeListener(self)
   

Enhanced Features Methods Details

enableFeatures

Enable camera enhancer features by inputting EnumEnhancerFeatures value.

The EnumEnhancerFeatures members:

• Objective-C
• Swift

1. - (void)enableFeatures:(EnumEnhancerFeatures)features  error:(NSError * _Nullable * _Nullable)error;
   

2. func enableFeatures(_ enumEnhancerFeatures: Int) throws
   

Parameters

enhancerFeatures: The combined value of EnumEnhancerFeatures.

Code Snippet

• Objective-C
• Swift

1. [_dce enableFeatures:EnumFRAME_FILTER error: &error];
   

2. do{
      try  dce.enableFeatures(EnumEnhancerFeature.EnumFRAME_FILTER.rawValue)
   }catch{
      // Add your code to deal with the exceptions.
   }
   

Remarks

The enable action will not be approved if the license is invalid. If your input values include the features that have been already enabled, these features will keep the enabled status.

disableFeatures

Disable camera enhancer features by inputting EnumEnhancerFeatures values.

• Objective-C
• Swift

1. - (void)disableFeatures:(EnumEnhancerFeatures)features;
   

2. func disableFeatures(_ enumEnhancerFeatures: Int)
   

Parameters

enhancerFeatures: The combined value of EnumEnhancerFeatures.

Code Snippet

• Objective-C
• Swift

1. [_dce disableFeatures:EnumFRAME_FILTER];
   

2. dce.disableFeatures(EnumEnhancerFeature.EnumFRAME_FILTER.rawValue)
   

Remarks

You can still disable the features even if the license is invalid. If your input values include the features that are not enabled, these features will keep the disabled status.

isFeatureEnabled

Check whether the input features are enabled.

• Objective-C
• Swift

1. - (BOOL)isFeatureEnabled:(EnumEnhancerFeatures)features;
   

2. func isFeatureEnabled(_ enumEnhancerFeatures: Int) -> Bool
   

Parameters

enhancerFeatures: The combined value of EnumEnhancerFeatures.

Return Value

A BOOL value refers to whether all the features you input are enabled.

• True: All the features you input are enabled.
• False: There is at least one feature is not enabled among your input values.

Code Snippet

• Objective-C
• Swift

1. BOOL featureEnabled = [_dce isFeatureEnabled:EnumFRAME_FILTER];
   

2. let featureEnabled = dce.isFeatureEnabled(EnumEnhancerFeature.EnumFRAME_FILTER.rawValue)
   

Remarks

If the features you input are all enabled but don’t cover all the enabled features, this method will still return true.

Advanced Camera Control Methods Details

updateAdvancedSettingsFromFile

Update the advanced camera controlling and video streaming processing parameters. This method enables you to update settings via a JSON file from the storage.

• Objective-C
• Swift

1. - (BOOL)updateAdvancedSettingsFromFile:(NSString*)filePath error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(updateAdvancedSettingsFromFile(_:));
   

2. func updateAdvancedSettingsFromFile(_ filePath: String) throws
   

Parameters

filePath: The file path of the JSON file.

Code Snippet

• Objective-C
• Swift

1. [_dce updateAdvancedSettingsFromFile:@"Put your JSON file path here." error: &error];
   

2. do{
      try  dce.updateAdvancedSettingsFromFile("Put your JSON file path here.")
   }catch{
      // Add your code to deal with the exceptions.
   }
   

Remarks

You might need permission authority to enable the Camera Enhancer to read the file in your mobile storage.

updateAdvancedSettingsFromString

Update the advanced camera controlling and video streaming processing parameters. This method enables you to update settings via a JSON string.

• Objective-C
• Swift

1. - (BOOL)updateAdvancedSettingsFromString:(NSString*)JsonString error:(NSError * _Nullable * _Nullable)error;
   

2. func updateAdvancedSettingsFromString(_ JsonString: String) throws
   

Parameters

jsonString: A stringified JSON data.

Code Snippet

• Objective-C
• Swift

1. [_dce updateAdvancedSettingsFromString:@"Put your stringified JSON data here." error: &error];
   

2. do{
      try  dce.updateAdvancedSettingsFromString("Put your stringified JSON data here.")
   }catch{
      // Add your code to deal with the exceptions.
   }