Simple ECM Image Processing SDK for Android

Screenshot

Features

Provides a wizard view that will handle the document capture flow for you. It includes:
- Image dewarping (crop image using a 4 points that form a quadrangle and straighten the resulting image)
- Brightness and contrast adjustment
- Clockwise and counter-clockwise rotation
- Persistent storage
- Notifies of user interaction events
Provides access to convert an image to black and white, or grayscale
Export as PDF, JPG and PNG

Quick Setup

1. Include the required dependencies:

In the SDK library project

In your application project

Add the SDK library to your project

2. Verify your license

In the onCreate method of your Application class, load your license and hash (*.signed) and pass them and the application name (that was used to generate your license) to SECMLicense.verifyLicense:

			
SECMLicense.verifyLicense(
		"AppName",
		getResources().openRawResource(R.raw.license),
		getResources().openRawResource(R.raw.hash)
	);

Note: If you don't verify the license, the SDK won't apply any of the operations to the images

Using the Wizard

1. Modify your Android Manifest

Add the activities and permissions that the wizard requires to your AndroidManifest file.

			
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    ... >

    <!-- Need this permission to open device's camera -->
    <uses-permission android:name="android.permission.CAMERA" />
    <!-- Need this permission to read photos from gallery -->
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    ...

    <application
        ... >
        ...
        <activity android:name="com.simpleecm.imageprocessing.activities.CaptureDocumentActivity"
            android:label="@string/optionsTitle"/>
        <activity android:name="com.simpleecm.imageprocessing.activities.CaptureListActivity"
            android:label="@string/documentTitle"/>
        <activity android:name="com.simpleecm.imageprocessing.activities.CameraActivity"
            android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
            android:label="@string/cameraTitle"/>
        <activity android:name="com.simpleecm.imageprocessing.activities.DewarpActivity"
            android:label="@string/cropTitle"/>
        <activity android:name="com.simpleecm.imageprocessing.activities.EnhanceActivity"
            android:label="@string/enhanceTitle"/>
    </application>
</manifest>

2. Create an SECMCaptureDocumentWizardBuilder instance

You need an instance of SECMCaptureDocumentWizardBuilder to start using the Wizard.

			
SECMCaptureDocumentWizardBuilder mWizardBuilder = SECMCaptureDocumentWizardBuilder.getInstance(this);

3. Configure the wizard builder

You can customize different display options in the wizard. To do so, just set the different properties with the setters provide in the SECMCaptureDocumentWizardBuilder instance. If you don't set a property, it will be ignored and the wizard will use its default values
For example, by setting the following property, you can modify the wizard's Action Bar color.

			
mWizardBuilder.setActionBarBackgroundColorResource(R.color.blue);

For more information about wizard customization, go to the SECMCaptureDocumentWizardBuilder section in SDK Javadocs

4. Set the builder's listener

The wizard will notify its listener whenever it is closed or the capture operation is finished.


public class MainActivity extends Activity implements OnWizardFinishListener {

	private SECMCaptureDocumentWizardBuilder mWizardBuilder;
	...
	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		...
		mWizardBuilder.setOnWizardFinishListener(this);
		...
	}
	
	@Override
	public void onWizardSucceed(SECMDocumentBuilder builder) {
		
	}
	
	@Override
	public void onWizardCanceled(SECMDocumentBuilder builder, boolean isDocumentDeleted) {
		
	}
}

5. Present the wizard


mWizardBuilder.start();

Implementing the OnWizardFinishListener

There are two ways to close the wizard, to cancel the capture process and to complete it successfully.

When the user cancel the capture process, the wizard will notify its listener using the onWizardCanceled(SECMDocumentBuilder builder, boolean wantToDelete) method. The wantToDelete flag will specify if the user wants to delete the document. You can do so using the method SECMDocumentBuilder.deleteAll()

When the user complete the capture process, the wizard will notify its listener using the onWizardSucceed(SECMDocumentBuilder builder) method.
You can obtain the captured images by using the SECMDocumentBuilder's methods:

void buildPDFDocument(OnExportPDFListener listener)
void buildImagesDocument(SECMImageExportOperation.ExportFormat imageFormat, OnExportImagesListener listener)
int getImagesCount()

Using the Core SDK functions

If something different from what wizard provides is required, the Core SDK functions can be used instead. To do so, create a SECMImage object with a Bitmap object.

		
SECMImage mSECMImage = new SECMImage(mBitmap);

To apply an operation to the image, use these methods:

void rotate(float degrees)
void rotateFixed(SECMImageRotation rotation)
void adjustBrightnessContrast(float brightness, float contrast)
void convertToBlackAndWhite()
void convertToGrayScale()
void dewarpWithQuadrangle(SECMQuadrangle quadrangle)
void findEdges(SECMQuadrangle quadrangle)

For more information about Core SDK functions, go to the SECMImage section in SDK Javadocs

The SECMImage object is mutable, and applying the image operations will change it.

Once the operations have been applied to the SECMImage, one can obtain a Bitmap from it using SECMImage.getBitmap() method. One can also use the SECMImageExporter to export a bitmap to a PDF, PNG or JPEG file.

Multithreading

The SDK provides Runnables (SECMImageOperation and its subclasses) for each operation. All the operations have a setOnImageOperationListener(OnImageOperationListener listener) method to register a callback the operation.
Once the operations are completed, they notify it through the OnImageOperationListener.onFinished() method.

To execute more than one operation in a row, the SECMContext class might helps. It provides control of 2 SECMImage objects, one for source image and another for the resulting image of any operation. So, you can perform any number of this kind of operations to the source image with the applyOperations(OnImageOperationListener listener, SECMImageOperation... operations) method and get the resulting image from the SECMContext object through a unique OnImageOperationListener.onFinished() callback that is invoked when all the operations are done.

Also, the SDK provides the SECMEdgeDetectionOperation class to find a quadrangle in the given image. It has a OnEdgeDetectionListener.onEdgesDetected(SECMQuadrangle quadrangle) callback to be invoke when the quadrangle is found and returned as a parameter. This quadrangle has a certainty factor, a float number between 0 and 1, that can be accessed by the getCertainty() method.

Furthermore, the SDK provides the SECMImageExportOperation class to perform the exporting task as asynchronous operations. One can register 2 different callbacks to it in order to notify that the export operation is finished:

OnExportPDFListener which is set through the setOnExportPDFListener(OnExportPDFListener listener).
This listener notify the operation finished through the OnExportPDFListener.onExportFinish(File file) method which gives access to the single exported PDF file that have all the images exported.
OnExportImagesListener which is set through the setOnExportImagesListener(OnExportImagesListener listener).
This listener notify the operation finished through the OnExportImagesListener.onExportFinish(List<File> files) method which gives access to all the exported images files.