CameraEnhancer 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
@interface DynamsoftCameraEnhancer:NSObject
Initialization Methods Summary
Method | Description |
---|---|
initWithView |
Initialize the camera enhancer with the camera view |
initLicense |
Set product key and activate the SDK. |
getVersion |
Get the SDK version. |
Basic Camera Control Methods Summary
Method | Description |
---|---|
getAllCameras |
Get all available cameras. This method returns a list of available camera IDs. |
selectCameraWithPosition |
Select whether to use front-facing camera or back-facing camera. |
getCameraPosition |
Returns whether the front-facing camera or back-facing camera is selected. |
selectCamera |
Select a camera from the camera list with the camera ID. |
getSelectedCamera |
Get the camera ID of the current selected camera. |
getCameraState |
Get the state of the current selected camera. |
open |
Turn on the current selected camera. |
close |
Turn off the current selected camera. |
pause |
Pause the current selected camera. |
resume |
Resume the current selected camera. |
turnOnTorch |
Turn on the torch. |
turnOffTorch |
Turn off the torch. |
getFrameRate |
Get the current frame rate. |
setResolution |
Set the resolution to the input value (if the input value is available for the device). |
getResolution |
Get the current resolution. |
setZoom |
Set the zoom factor. Once setZoom is triggered and approved, the zoom factor of the activated camera will immediately become the input value. |
setFocus |
Set the focus position (value range from 0.0f to 1.0f) and trigger a focus at the configured position. |
setScanRegion |
Set the scanRegion with a iRegionDefinition value. The frame will be cropped according to the scan region. |
getScanRegion |
Get the scan region. |
scanRegionVisible |
Set whether to display the scanRegion on the UI. |
setFrameRate |
Deprecated, will be removed in v3.0. Set the frame rate to the input value (if the input value is available for the device). |
Frame Acquiring Methods Summary
Method | Description |
---|---|
getFrameFromBuffer |
Get the latest frame from the buffer. The boolean value determines whether the fetched frame will be removed from the buffer. |
addListener |
Add a listener to the camera enhancer instance. |
removeListener |
Remove a previously added listener from the camera enhancer instance. |
Enhanced Features Methods Summary
Method | Description |
---|---|
enableFeatures |
Enable camera enhancer features by inputting EnumEnhancerFeatures values. |
disableFeatures |
Disable camera enhancer features by inputting EnumEnhancerFeatures values. |
isFeatureEnabled |
Check whether the input features are enabled. |
Advanced Camera Control Methods Summary
Method | Description |
---|---|
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. |
updateAdvancedSettingsFromString |
Update the advanced camera controlling and video streaming processing parameters. This method enables you to update settings via a JSON string. |
Initialization Methods Details
initWithView
Initialize the camera enhancer with the DCECameraView
.
- (instancetype)initWithView:(DCECameraView *)view;
Return Value
The instance of DynamsoftCameraEnhancer.
Code Snippet
- Objective-C
- Swift
_dce = [[DynamsoftCameraEnhancer alloc] initWithView:_dceView];
let dce = DynamsoftCameraEnhancer.init(view: dceCameraView)
initLicense
Set product key and activate the SDK. It is recommended to initialize the license in AppDelegate.m
.
+(void)initLicense:(NSString*)license verificationListener:(id) verificationListener;
Parameters
[in] license
: The product key.
[in out] verificationListener
: The listener that handles callback when the license server returns. See also DCELicenseVerificationListener
.
Code Snippet
- Objective-C
- Swift
[DynamsoftCameraEnhancer initLicense:@"Put your license here" verificationDelegate: self]; - (void)DCELicenseVerificationCallback:(bool)isSuccess error:(NSError *)error{ }
DynamsoftCameraEnhancer.initLicense("Put your license here", verificationDelegate: self) func dceLicenseVerificationCallback(_ isSuccess: Bool, error: Error?) { }
getVersion
Get the SDK version of Dynamsoft Camera Enhancer.
- (NSString*)getVersion;
Return Value
A string value that stands for the Camera Enhancer SDK version.
Code Snippet
- Objective-C
- Swift
NSString* version = [_dce getVersion];
let version = dce.getVersion()
cameraView
Bind a DCECameraView
to the camera enhancer.
@property (strong, nonatomic) DCECameraView cameraView;
Code Snippet
- Objective-C
- Swift
_dceView = [[DCECameraView alloc] initWithFrame:self.view.bounds] [_dce setCameraView:_dceView];
let dceView = DCECameraView.init(frame self.view.bounds) dce.cameraView = dceView
Basic Camera Control Methods Details
getAllCameras
Get the IDs of all available cameras.
- (NSArray*)getAllCameras;
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
NSArray<NSString*>* allCameras = [_dce getAllCameras];
let allCameraList = dce.getAllCameras()
selectCameraWithPosition
Select the camera position (front-facing or back-facing).
- (void)selectCameraWithPosition:(EnumCameraPosition)position error:(NSError * _Nullable * _Nullable)error;
Parameters
[in] cameraPosition
An EnumCameraPosition
value that indicates front-facing or back-facing camera.
[in out] error
The error occurs when the input value is invalid. You may specify nil for this parameter if you do not want the error information.
Code Snippet
- Objective-C
- Swift
[_dce selectCameraWithPosition:EnumCameraPositionBack error: &error];
dce.selectCamera(with: EnumCameraPosition.back, error: nil)
getCameraPosition
Returns whether the front-facing camera or back-facing camera is selected.
- (EnumCameraPosition) getCameraPosition;
Return Value
An EnumCameraPosition
value that indicates front-facing or back-facing camera.
Code Snippet
- Objective-C
- Swift
EnumCameraPosition cameraPosition = [_dce getCameraPosition];
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.
- (void)selectCamera:(NSString*)cameraId error:(NSError * _Nullable * _Nullable)error;
Parameters
[in] 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
.
[in out] error
The error occurs when the input value is invalid. You may specify nil for this parameter if you do not want the error information.
Code Snippet
- Objective-C
- Swift
[_dce selectCamera:@"BACK_FACING_CAMERA" error: &error];
dce.selectCamera("BACK_FACING_CAMERA", error: &error)
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.
- (NSString*)getSelectedCamera;
Return Value
The ID of the current selected camera.
Code Snippet
- Objective-C
- Swift
NSString* cameraID = [_dce getSelectedCamera];
let selectedCamera = dce.getSelectedCamera()
getCameraState
Get the state of the currently selected camera.
- (EnumCameraState*)getCameraState;
Return Value
One of the preset camera state in Enumeration EnumCameraState
.
Code Snippet
- Objective-C
- Swift
EnumCameraState state = [_dce getCameraState];
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
.
- (void)open;
Code Snippet
- Objective-C
- Swift
[_dce open];
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
.
- (void)close;
Code Snippet
- Objective-C
- Swift
[_dce close];
dce.close()
pause
- Pause the selected camera if a camera has been selected via
selectCamera
. - Pause the default camera if no camera is selected via
selectCamera
.
- (void)pause;
Code Snippet
- Objective-C
- Swift
[_dce pause];
dce.pause()
Remarks
If the pause
method is triggered:
- The camera UI will be stopped on the last frame captured before you
pause
the camera. - The camera is still open.
- The video streaming input is not stopped.
- DCE video buffer will continue appending frames.
resume
- Resume the selected camera if a camera has been selected via
selectCamera
. - Resume the default camera if no camera is selected via
selectCamera
.
- (void)resume;
Code Snippet
- Objective-C
- Swift
[_dce resume];
dce.resume()
turnOnTorch
Turn on the torch (if the torch of the mobile device is available).
- (void)turnOnTorch;
Code Snippet
- Objective-C
- Swift
[_dce turnOnTorch];
dce.turnOnTorch()
turnOffTorch
Turn off the torch.
- (void)turnOffTorch;
Code Snippet
- Objective-C
- Swift
[_dce turnOffTorch];
dce.turnOffTorch()
getFrameRate
Get the current frame rate.
- (NSInteger)getFrameRate;
Return Value
The current frame rate.
Code Snippet
- Objective-C
- Swift
NSInteger frameRate = [_dce getFrameRate];
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.
- (Void)setResolution:(Resolution)resolution;
Parameters
[in] resolution
One of the int value that preset in Enumeration EnumResolution
.
Code Snippet
- Objective-C
- Swift
[_dce setResolution:EnumRESOLUTION_1080P];
dce.setResolution(EnumResolution.EnumRESOLUTION_1080P)
getResolution
Get the current resolution.
- (NSString*)getResolution;
Return Value
The size of the current resolution.
Code Snippet
- Objective-C
- Swift
NSString* resolution = [_dce getResolution];
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.
- (Void)setZoom:(CGFloat)factor
Parameters
[in] factor
The target zoom factor.
Code Snippet
- Objective-C
- Swift
[_dce setZoom:3.0f];
dce.setZoom(3.0)
setFocus
Set the focus position (value range from 0.0f to 1.0f) and trigger a focus at the configured position.
- (Void)setFocus:(CGPoint)focusPosition;
Parameters
[in] focusPosition
A CGPoint that stores the x and y coordinate of the targeting focus position.
Code Snippet
- Objective-C
- Swift
CGPoint focusPoint = {0.4, 0.5}; [_dce setFocus:focusPoint];
let focusPoint = CGPoint(x:0.4, y:0.5) dce.setFocus(focusPoint)
setScanRegion
Specify the scanRegion
. The DCEFrames will be cropped according to the scanRegion
before they are stored in the video buffer.
- (void)setScanRegion:(RegionDefinition)scanRegion error:(NSError * _Nullable)error;
Parameters
[in] 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
.
[in out] error
The error occurs when the region parameters are invalid. You may specify nil for this parameter if you do not want the error information.
How to set scan region
Code Snippet
- Objective-C
- Swift
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];
let scanRegion = iRegionDefinition() scanRegion.regionTop = 25 scanRegion.regionBottom = 75 scanRegion.regionLeft = 25 scanRegion.regionRight = 75 scanRegion.regionMeasuredByPercentage = 1 dce.setScanRegion(scanRegion, error: &error)
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.
- The
- When you trigger
setScanRegion
, the enhancer featureEF_FAST_MODE
will be disabled. - You will still get the original
DCEFrame
fromFrameOutputCallback
and croppedDCEFrame
fromgetFrameFromBuffer
. ThecropRegion
ofDCEFrame
will be configured based on the scanRegion whensetScanRegion
is triggered. - When you trigger
setScanRegion
, thescanRegionVisible
will be set to true automatically. If you don’t want to display the scanRegion on the UI, please set thescanRegionVisible
to false manually.
getScanRegion
- (iRegionDefinition) getScanRegion
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
iRegionDefinition* myScanRegion = [[iRegionDefinition alloc] init]; myScanRegion = [_dce getScanRegion];
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
@property (assign, nonatomic) BOOL scanRegionVisible;
setFrameRate
Note: The method is deprecated in v9.0.2 and will be removed in v10.0 release.
Set the frame rate to the input value (if the input value is available for the device).
- (void)setFrameRate:(NSInteger)frameRate;
Parameters
[in] frameRate
An int value that refers to the target frame rate.
Code Snippet
- Objective-C
- Swift
[_dce setFrameRate:15];
dce.setFrameRate(15)
Remarks
The available frame rate setting threshold is always intermittent, which means the input value might not match any available frame rate threshold. If the input value is below the lowest available threshold, the frame rate will be set to the lowest available threshold. If the input value is above the lowest available threshold but still does not match any threshold, the frame rate will be set to the highest available threshold below the input value.
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.
- (DCEFrame*)getFrameFromBuffer:(BOOL)keep;
Parameters
[in] 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
dceFrame = [_dce getFrameFromBuffer:true];
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.
- (void)addListener:(nonnull id<DCEFrameListener>)listener;
Parameters
[in] 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
[_dce addListener:self];
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.
- (void)removeListener:(nonnull id<DCEFrameListener>)listener;
Parameters
[in] listener
The input listener will be removed from the Camera Enhancer instance.
Code Snippet
- Objective-C
- Swift
[_dce removeListener:self];
dce.removeListener(self)
Enhanced Features Methods Details
enableFeatures
Enable camera enhancer features by inputting EnumEnhancerFeatures
value. When the license verification is failed, the enabled features will be recorded but not actived. Once a valid license is verified, the features you enabled will be recovered.
- (void)enableFeatures:(EnumEnhancerFeatures)features error:(NSError * _Nullable * _Nullable)error;
Parameters
[in] enhancerFeatures
The combined value of EnumEnhancerFeatures
.
[in out] error
The error occurs when the license is invalid. You may specify nil for this parameter if you do not want the error information.
Code Snippet
- Objective-C
- Swift
[_dce enableFeatures:EnumFRAME_FILTER error: &error];
dce.enableFeatures(EnumEnhancerFeature.EnumFRAME_FILTER.rawValue, error: &error)
Remarks
The EnumEnhancerFeatures
members:
Members | Value |
---|---|
EnumFRAME_FILTER |
0x01 |
EnumSENSOR_CONTROL |
0x02 |
EnumENHANCED_FOCUS |
0x04 |
EnumFAST_MODE |
0x08 |
EnumAUTO_ZOOM |
0x10 |
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.
- (void)disableFeatures:(EnumEnhancerFeatures)features;
Parameters
[in] enhancerFeatures
The combined value of EnumEnhancerFeatures
.
Code Snippet
- Objective-C
- Swift
[_dce disableFeatures:EnumFRAME_FILTER];
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.
- (BOOL)isFeatureEnabled:(EnumEnhancerFeatures)features;
Parameters
[in] 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
BOOL featureEnabled = [_dce isFeatureEnabled:EnumFRAME_FILTER];
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.
- (void)updateAdvancedSettings:(NSString*)filePath error:(NSError * _Nullable * _Nullable)error;
Parameters
[in] filePath
The file path of the JSON file.
[in out] error
The error occurs when the JSON data is invalid. You may specify nil for this parameter if you do not want the error information.
Code Snippet
- Objective-C
- Swift
[_dce updateAdvancedSettingsFromFile:@"Put your JSON file path here." error: &error];
dce.updateAdvancedSettings(fromFile: "Put your JSON file path here.", error: &error)
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.
- (void)updateAdvancedSettings:(NSString*)params error:(NSError * _Nullable * _Nullable)error;
Parameters
[in] jsonString
A stringified JSON data.
[in out] error
The error occurs when the JSON data is invalid. You may specify nil for this parameter if you do not want the error information.
Code Snippet
- Objective-C
- Swift
[_dce updateAdvancedSettingsFromString:@"Put your stringified JSON data here." error: &error];
dce.updateAdvancedSettings(from: "Put your stringified JSON data here.", error: &error)
The advanced settings are as follow:
Parameter Name | Type | Description |
---|---|---|
focalLength |
float | Set the fixed focal length. |
autoFocusInterval |
int | Set the time interval of the auto focus. |
autoFocusTerminateTime |
int | Set the minimum terminate time of auto focus. |
sensorControlSensitivity |
int | Set the sensitivity of the mobile sensor. |
FastMode |
JSON data | Set a group of crop regions. |
focalLength
Set the fixed focal length with a float value. When this parameter is configured, the other focus methods and parameters will be disbaled and the focal length will be fixed. Users can reset the focalLength to -1 to disable the fixed focus settings. The closer to the 0, the further the focalLength will be.
Value Type | Value Range | Default Value |
---|---|---|
int | [0,1] | -1 |
autoFocusInterval
Set the time interval of the auto-focus with an int value.
Value Type | Value Range | Default Value |
---|---|---|
int | [0,0x7fffffff] | 3000(ms) |
autoFocusTerminateTime
The minimum termination time of the auto-focus with an int value.
Value Type | Value Range | Default Value |
---|---|---|
int | [0,0x7fffffff] | 500(ms) |
sensorControlSensitivity
Set the sensitivity of the mobile sensor with an int value. A lower input value results in a higher sensitivity.
Value Type | Value Range | Default Value |
---|---|---|
int | [0,0x7fffffff] | 50 |
FastMode
The fast-mode parameters store four groups of frame cropping parameters. The cropping parameters will be implemented periodically when the fast mode is enabled. You can use the default cropping region settings or update your personalized crop regions via a JSON string or file.
Example:
"FastMode": {
"cropRegions": [{
"top": 0,
"right": 100,
"bottom": 100,
"left": 0
},
{
"top": 25,
"right": 100,
"bottom": 75,
"left": 0
},
{
"top": 25,
"right": 75,
"bottom": 75,
"left": 25
},
{
"top": 25,
"right": 75,
"bottom": 75,
"left": 25
}]
}