CameraEnhancer Class

The main class of CameraEnhancer library. 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

class com.dynamsoft.dce.CameraEnhancer

Initialization Methods Summary

Basic Camera Control Methods Summary

Frame Acquiring Methods Summary

Enhanced Features Methods Summary

Camera UI Methods Summary

Advanced Camera Control Methods Summary

Initialization Methods Details

CameraEnhancer

Initialize the CameraEnhancer Object.

CameraEnhancer(Activity activity)

Parameters

activity: An instance of android.app.Activity.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

initLicense

Set product key and activate the SDK.

static void initLicense(String license, DCELicenseVerificationListener listener)

Parameters

license: The product key.
listener: The listener that handles callback when the license server returns. See also DCELicenseVerificationListener.

Code Snippet

CameraEnhancer.initLicense("Put your license here", new DCELicenseVerificationListener(){
    @Override
    public void DCELicenseVerificationCallback(boolean b, Exception e) {
        if (!b && e != null) {
            e.printStackTrace();
        }
    }
});

getVersion

Get the SDK version of Dynamsoft Camera Enhancer.

String getVersion()

Return Value

A string value that stands for the camera enhancer SDK version.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
String DCEVersion = cameraEnhancer.getVersion();

Basic Camera Control Methods Details

getAllCameras

Get the IDs of all available cameras.

String[] getAllCameras()

Return Value

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

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
String[] cameraIds = cameraEnhancer.getAllCameras();

selectCamera(EnumCameraPosition)

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

void selectCamera(EnumCameraPosition cameraPosition) throws CameraEnhancerException

Parameters

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

Exception

An exception thrown to indicate an error has occurred when switching the camera.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
cameraEnhancer.selectCamera(EnumCameraPosition.CP_BACK);

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

EnumCameraPosition camera = mCameraEnhancer.getCameraPosition();

selectCamera(String)

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 by selecting another camera via this method, the settings applied to this camera will be inherited by the newly selected camera.

void selectCamera(String cameraID) throws CameraEnhancerException

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.

Exception

An exception thrown to indicate an error has occurred when switching the camera.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
cameraEnhancer.selectCamera("BACK_FACING_CAMERA_0");

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.

String getSelectedCamera()

Return Value

The ID of the current selected camera.

CodeSnippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
String selectedCameraID = cameraEnhancer.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

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this);
int cameraState = cameraEnhancer.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() throws CameraEnhancerException

Exception

An exception thrown to indicate an error has occurred when the device is opening the camera.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
cameraEnhancer.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() throws CameraEnhancerException

Exception

An exception thrown to indicate an error has occurred when the device is closing the camera.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
cameraEnhancer.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() throws CameraEnhancerException

Exception

An exception thrown to indicate an error has occurred when the device is pausing the camera.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
cameraEnhancer.pause();

Remarks

If the pause method is triggered:

• The camera UI will be stopped on the last captured frame 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() throws CameraEnhancerException

Exception

An exception thrown to indicate an error has occurred when the device is resuming the camera.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
cameraEnhancer.resume();

turnOnTorch

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

void turnOnTorch() throws CameraEnhancerException

Exception

An exception thrown to indicate an error has occurred when the device is turning on the torch.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
cameraEnhancer.turnOnTorch();

turnOffTorch

Turn off the torch.

void turnOffTorch() throws CameraEnhancerException

Exception

An exception thrown to indicate an error has occurred when the device is turning off the torch.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
cameraEnhancer.turnOffTorch();

getFrameRate

Get the current frame rate.

int getFrameRate()

Return Value

The current frame rate.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

int frameRate = cameraEnhancer.getFrameRate();

getResolutionList

Check the available resolutions of the current device.

List<Size> getResolutionList()

Return Value

A list that contains all available resolutions.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

List<Size> resolutionList = cameraEnhancer.getResolutionList();

setResolution

Input a 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(EnumResolution resolution) throws CameraEnhancerException

Parameters

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

Exception

An exception thrown to indicate an error has occurred when trying to change the resolution.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

cameraEnhancer.setResolution(EnumResolution.RESOLUTION_2K);

getResolution

Get the current resolution.

Size getResolution()

Return Value

The size of the current resolution.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

Size currentResolution = cameraEnhancer.getResolution();

setZoom

Set the zoom factor. The camera will zoom in/out immediately after this method is triggered.

void setZoom(float factor) throws CameraEnhancerException

Parameters

factor: The target zoom factor.

Exception

An exception thrown to indicate an error has occurred when trying to zoom-in or zoom-out.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

cameraEnhancer.setZoom(2.5)

getMaxZoomFactor

Get the maximum available zoom factor.

float getMaxZoomFactor()

Return Value

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

Code Snippet

float maxZoomFactor = cameraEnhancer.getMaxZoomFactor();

setAutoZoomRange

Set the range of auto zoom.

void setAutoZoomRange(android.util.Range zoomRange)

Parameters

[in] zoomRange: A UIFloatRange value that defines the range of auto zoom.

Code Snippet

cameraEnhancer.setAutoZoomRange(new Range(1.5,4));

getAutoZoomRange

Get the range of auto zoom.

Range getAutoZoomRange()

Return Value

A UIFloatRange value that defines the range of auto zoom.

Code Snippet

Range range = cameraEnhancer.getAutoZoomRange();

setFocus

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

void setFocus(float x, float y) throws CameraEnhancerException

Parameters

x: The x-coordinate of the targeting focus position.
y: The y-coordinate of the targeting focus position.

Exception

An exception thrown to indicate an error has occurred when trying to trigger a focus.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

cameraEnhancer.setFocus(0.5,0.4);

setFocus(subsequentFocusMode)

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

void setFocus(android.graphics.PointF focusPoint, EnumFocusMode subsequentFocusMode) throws CameraEnhancerException

Parameters

[in] focusPosition: An android.graphics.PointF object 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.

Exception

An exception thrown to indicate an error has occurred when trying to trigger a focus.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

cameraEnhancer.setFocus(new PointF(0.5f,0.5f), EnumFocusMode.FM_LOCKED);

setScanRegion

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

void setScanRegion(RegionDefinition scanRegion) throws CameraEnhancerException

Parameters

scanRegion: Use a RegionDefinition 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 RegionDefinition class.

Exception

An exception thrown to indicate the region parameter is invalid.

Code Snippet

com.dynamsoft.dce.RegionDefinition scanRegion = new RegionDefinition();
scanRegion.regionTop = 25;
scanRegion.regionBottom = 75;
scanRegion.regionLeft = 25;
scanRegion.regionRight = 75;
scanRegion.regionMeasuredByPercentage = 1;

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this);
try {
    cameraEnhancer.setScanRegion(scanRegion);;
} catch (CameraEnhancerException e) {
    e.printStackTrace();
}

Remarks

• The region definition defines the region on the camera view. For each value of the class RegionDefinition:
  • 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 scanRegion will be displayed on the UI automatically. If you don’t want to display the scanRegion on the UI, please set the scanRegionVisible to false manually.

getScanRegion

Get the scan region configurations. You will get a null value if the scan region is not set.

RegionDefinition 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

com.dynamsoft.dce.RegionDefinition myScanRegion = new RegionDefinition();

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this);
myScanRegion = cameraEnhancer.getScanRegion(scanRegion);

setCameraStateListener

Add a DCECameraStateListener to receive notification when the camera state changes.

void setCameraStateListener (DCECameraStateListener listener)

Parameters

[in] listener: A DCECameraStateListener object.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

cameraEnhancer.setCameraStateListener(new DCECameraStateListener(){
    @Override
    public void stateChangeCallback(EnumCameraState currentState) {
        // Add your code to do when camera state changes.
    }
});

setScanRegionVisible

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

void setScanRegionVisible(boolean scanRegionVisible)

Parameters

scanRegionVisible: When the value is set to true, the scanRegion will be displayed on the UI. Otherwise, the scanRegion will not be displayed.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

cameraEnhancer.setScanRegionVisible(true);

getScanRegionVisible

Get whether the scanRegion will be displayed on the UI.

boolean getScanRegionVisible()

Return Value

When the return value is true, the scanRegion will be displayed. Otherwise, the scanRegion will not be displayed.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

boolean scanRegionVisible = cameraEnhancer.getScanRegionVisible();

setFrameRate

Note: The method is deprecated in v2.1.4 and will be removed in v3.0 release.

Camera Enhancer will try to set the frame rate around the input value.

void setFrameRate(int frameRate) throws CameraEnhancerException

Parameters

frameRate: An int value that refers to the target frame rate.

Exception

An exception thrown to indicate the an error has occurred when trying to change the frame rate.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

cameraEnhancer.setFrameRate(25);

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 video buffer.

DCEFrame getFrameFromBuffer(boolean isKeep)

Parameters

isKeep: 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

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
DCEFrame frame = cameraEnhancer.getFrameFromBuffer(false);

addListener

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

void addListener(DCEFrameListener listener)

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

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

DCEFrameListener listener = new DCEFrameListener(){
    @Override
    public void frameOutputCallback(DCEFrame frame, long timeStamp) {
        //perform custom action on generated frame
    }
};
cameraEnhancer.addListener(listener);

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(DCEFrameListener listener)

Parameters

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

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

DCEFrameListener listener = new DCEFrameListener(){
    @Override
    public void frameOutputCallback(DCEFrame frame, long timeStamp) {
        //perform custom action on generated frame
    }
};
cameraEnhancer.addListener(listener);
// ......
cameraEnhancer.removeListener(listener);

takePhoto

Take a photo from the camera and save the image in the memory. The photo will be captured and users can receive the captured photo via photoOutputCallback.

void takePhoto(DCEPhotoListener listener)

Parameters

listener: An instance of DCEPhotoListener.

Code Snippet

// Create an instance of DCEPhotoListener
DCEPhotoListener photoListener = new DCEPhotoListener() {
    @Override
    public void photoOutputCallback(byte[] bytes) {
        // Add your code to execute when photo is captured.
    }
};
mCameraEnhancer.takePhoto(photoListener);

Enhanced Features Methods Details

enableFeatures

Enable camera enhancer features by inputting EnumEnhancerFeatures value.

void enableFeatures(int enhancerFeatures) throws CameraEnhancerException

Parameters

enhancerFeatures: The combined value of EnumEnhancerFeatures.

Exception

An exception thrown to indicate an error has occurred when trying to access the sensor.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

cameraEnhancer.enableFeatures(EnumEnhancerFeatures.FRAME_FILTER | EnumEnhancerFeatures.SENSOR_CONTROL);

Remarks

The EnumEnhancerFeatures members:

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(int enhancerFeatures)

Parameters

enhancerFeatures: The combined value of EnumEnhancerFeatures.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

cameraEnhancer.disableFeatures(EnumEnhancerFeatures.FRAME_FILTER | EnumEnhancerFeatures.SENSOR_CONTROL);

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

Returns a boolean value that means whether the feature(s) you input is (are) enabled.

boolean isFeatureEnabled(int enhancerFeatures)

Parameters

enhancerFeatures: The combined value of EnumEnhancerFeatures.

Return Value

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

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

boolean isEnabled = cameraEnhancer.isFeatureEnabled(EnumEnhancerFeatures.FRAME_FILTER | EnumEnhancerFeatures.SENSOR_CONTROL);

Remarks

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

Camera UI Methods Details

setCameraView

Set a DCECameraView object as the main UI view.

void setCameraView(DCECameraView cameraView)

Parameters

cameraView: The main UI view. See also DCECameraView.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

DCECameraView cameraView = findViewById(R.id.cameraView);
cameraEnhancer.setCameraView(cameraView);

getCameraView

Get the DCECameraView object of the current UI view.

DCECameraView getCameraView()

Return Value

The current UI view. See also DCECameraView.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

DCECameraView cameraView =  cameraEnhancer.getCameraView();

Advanced Camera Control Methods Details

updateAdvancedSettingsFromFile

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

void updateAdvancedSettingsFromFile(String filePath) throws CameraEnhancerException

Parameters

filePath: The file path of the JSON file.

Exception

An exception thrown to indicate the JSON data is invalid.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 
// Replace the filePath with your target filePath
cameraEnhancer.updateAdvancedSettingsFromFile("/storage/emulated/0/1.json")

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 updateAdvancedSettingsFromString(String jsonString) throws CameraEnhancerException

Parameters

jsonString: A stringified JSON data.

Code Snippet

CameraEnhancer cameraEnhancer = new CameraEnhancer(MainActivity.this); 

cameraEnhancer.updateAdvancedSettingsFromString("{'sensorvalue':3,'graydiffthreshold':30,'conversioncountthreshold':30,'sharpnessthreshold':0.2,'sharpnessthresholdlarge':0.4,'abssharpnessthreshold':200,'absgraythreshold':35,'claritythreshold':0.1}");

The advanced settings are as follow:

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.

autoFocusInterval

Set the time interval of the auto-focus with an int value.

autoFocusTerminateTime

The minimum termination time of the auto-focus with an int value.

sensorControlSensitivity

Set the sensitivity of the mobile sensor with an int value. A lower input value results in a higher sensitivity.

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
    }]
}

ISO & ExposureTime

Set the ISO and exposure time of the camera.

Example:

{
    "androidExposureTime": 2,
    "iso":30
}