Usage of CIB modules on Android Technical Guide (EN)

1. Lieferumfang

The CIB modules are delivered for Android as AAR (Android Archive).

2. Introduction

This library collection for the use on Android contains all CIB modules which are necessary to process images and PDFs on mobile devices. The available wrappers facilitate the use of the powerful CIB modules on the respective platform.

The size and scope of the library module can be customized on request.

3. SDK

3.1. Requirements

The minimum supported API level is 21 (Android 5).

• ARM-v7a (32 bit)*
• ARM-v8a (64 bit)
• x86 (64 bit)

3.2. Integration

General

The CIB modules are delivered for Android as AAR. The AAR can be integrated into an existing Android application as follows. Android Studio is used as development environment.

The sample integration ("showcase") included in the delivery can also be used as a template for the integration.

1. In Android Studio, choose „File“ ➔ „New“ ➔ „Module“.
2. Select „Import .JAR/.AAR Package“ and click „Next“.
3. Select the path to the AAR with the CIB modules and click "Finish
4. Afterwards, click on „Sync Project with Gradle Files“ in the toolbar.

Setting the licence

The license consists of your customer name (“Company”) and a key (“Key”). These must be set as strings via a resource file in your existing project, such as a “strings.xml”. To do this, add the following lines to an existing “strings.xml”.

<item name="cibPdfToolboxLicenseCompany" format="string" type="string" 
translatable="false">REQUEST FROM CIB SUPPORT</item>
<item name="cibPdfToolboxLicenseKey" format="string" type="string" 
translatable="false">REQUEST FROM CIB SUPPORT</item>
<item name="cibOcrLicenseCompany" format="string" type="string" 
translatable="false">REQUEST FROM CIB SUPPORT</item>
<item name="cibOcrLicenseKey" format="string" type="string" 
translatable="false">REQUEST FROM CIB SUPPORT</item>    

Set the separately handed out license key pairs as values. The values must be set exactly as you received them from us.

Check the license

Note:
A license can include or exclude certain functions. To be sure whether there is a license problem, the trace file must be checked. Proceed as follow.

1. Make sure that the property "TraceFilename" is set with a valid file path when you call the respective CIB module.
2. Start your Job.
3. After the job is finished, open the file path specified under "TraceFilename" on the device. This is where the trace of the job is located.
4. Open the trace file. If the license is valid, it should contain the following line, among others:

LICENSE: Valid license.

If this is not the case, check your license. If the problem persists, please contact the CIB Support.

3.3. Usage

General

The CIB modules are native C++ libraries. This entails certain technical requirements, which are described here.

In principle the call of all CIB modules follows a fixed sequence. It can be executed implicitly by wrappers. Only with direct access to the CIB modules the procedure described here is explicitly obvious:

1. Load the library and all dependencies.
• Must only be done once per runtime.
2. Create a job.
3. Set properties for this job.
4. Execute the job.
5. Collect the results.
6. Release of the job.

For error analysis, each call to a job returns an error code. The respective technical guides contain lists with the respective meaning.

In addition, a trace file can be written for each job call, which is required for further error analysis. It is only written if a valid path is set for the property "TraceFilename".

For the CIB modules, the AAR contains wrapper classes that simplify the handling of typical applications. However, only common use cases are covered.

Additionally, classes for a direct access are available. These map 1:1 the native interfaces of the CIB modules via JNI to Java methods. Thus, the CIB modules can be used individually and the full functionality can be exploited. The respective property names and possible values can be found for each CIB module in the corresponding technical guide.

CIB pdf toolbox

Classes for direct access

• de.cib.pdf.toolbox.swig.CibPdf
• de.cib.pdf.toolbox.swig.CibPdfConstants

Examples for the individual steps:

1. Load the library and all dependencies.
• Minimum required libraries that must be loaded.

System.loadLibrary("c++_shared");
    System.loadLibrary("cibpdfux64");
    System.loadLibrary("cibxalanux64");

• If a PDF is to be rendered into a graphic, the following library must also be loaded.

System.loadLibrary("cibrendererux64");

• To create highly compressed black/white PDFs with JBig2, the following additional library must be loaded.

System.loadLibrary("cibjbig2ux64");

• To create highly compressed colour PDFs with MRC, only the following libraries must be loaded.

System.loadLibrary("c++_shared");
System.loadLibrary("cibpdfux64");
System.loadLibrary("cibpdfmodule64");

2. Create a Job.

final long[] handle = { 0 };
CibPdf.CibPdfJobCreate(handle, null);

3. Set the properties for this job.
• Names and values for most properties are found in the "CibPdfContants" class. A complete list with documentation can be found in the CIB pdf toolbox technical guide.

CibPdf.CibPdfJobSetProperty(handle[0], name, value, value.length());

4. Execute the job.

CibPdf.CibPdfJobJoin(handle[0]);

5. Collect the results.
• If the property "OutputFilename" is set, the output file can be found in the path specified there.
• Retrieval of Get-Properties is only possible for certain properties via method calls:

byte[] inputbuf = new byte[length];
CibPdf.CibPdfJobGetProperty(handle, name, inputbuf);
String result = new String(inputbuf, 0, length);

• Error codes and messages can be found here:

int[] errorCode = {0};
CibPdf.CibPdfJobGetError(handlerId, errorCode);
int code = errorCode[0];

final byte[] errorText = new byte[length];
CibPdf.CibPdfJobGetErrorText(handlerId, errorTextBuf);
String message = new String(errorText, 0, length);

6. Release the job.

   CibPdf.CibPdfJobFree(handle);

Wrapper-classes

• de.cib.android.common.manager.PdfToolbox

Examples for the individual steps:

1.     Load the library and all dependencies.

• Minimum required libraries that must be loaded.

PdfToolbox.Builder builder = PdfToolbox.createBuilder()
        .load(PdfToolbox.Library.STL, 
              PdfToolbox.Library.TOOLBOX, 
              PdfToolbox.Library.TOOLBOX_PARSER);

• If a PDF is to be rendered into a graphic, the following library must also be loaded.

PdfToolbox.Library.TOOLBOX_RENDERER

• To create highly compressed black/white PDFs with JBig2, the following additional library must be loaded.

PdfToolbox.Library.JBIG2

• To create highly compressed colour PDFs with MRC, only the following libraries must be loaded.

PdfToolbox.Builder builder = PdfToolbox.createBuilder()
        .load(PdfToolbox.Library.STL, 
              PdfToolbox.Library.TOOLBOX, 
              PdfToolbox.Library.PDF_MODULE);

2.     Create a job.

• This is done implicitly.

3.     Set properties for this job.

• Properties are set implicitly by method calls.

builder.inputFilePath(inputPath);
builder.outputFilePath(outputPath);

4.     Execute the job.

PdfToolbox
toolbox = builder.build();

5.     Collect the results.

• If the property "OutputFilename" is set, the output file can be found in the path specified there.
• Retrieval of Get-Properties is only possible for certain properties via method calls:

int pageCount = toolbox.getPageCount()

• If other Get-Properties are needed, please use the classes for direct access or contact us.
• Error codes and messages can be found here:

boolean success = toolbox.isSuccessful();
int code = toolbox.getErrorCode());
String message = toolbox.getErrorMessage();

6.     Release the job.

toolbox.close();

CIB pdfModule

Classes for direct access

swig.jni.de.cib.pdf.CibPdfModuleJobInterface
de.cib.pdf.toolbox.swig.CibPdfConstants

Examples for the individual steps:

1.     Load the library and all dependencies.

System.loadLibrary("c++_shared");
System.loadLibrary("cibpdfmodule64");

2.     Create a job.

CibPdfModuleJobInterface job = new CibPdfModuleJobInterface();

3.    Set properties for this job.

• Names and values for most properties are found in the CibPdfContants class. A complete list with documentation can be found in the CIB pdf toolbox technical guide.

job.setProperty(name, value);

• Android bitmaps can be passed directly as input as follows. This is useful for converting from image to PDF.

job.addInputImage(bitmap);

4.     Execute the job.

long resultCode = job.execute();

5.    Collect the results.

• If the property "OutputFilename" is set, the output file can be found in the path specified there.
• Fetch Get-Properties with the following call:

String result = job.getProperty(name);

• For error codes please check the return value of the "execute()" call.

6.     Release the job.

job.delete();

Wrapper-classes

de.cib.pdf.module.CibPdfModule

Examples for the individual steps:

1.     Load the library and all dependencies.

CibPdfModule.Builder builder = CibPdfModule.createBuilder()
        .load(CibPdfModule.Library.STL, 
              CibPdfModule.Library.PDF_MODULE);

2.     Create a job.

• This is done implicitly.

3.     Set properties for this job.

• Properties are set implicitly by method calls.

builder.inputFilePath(inputPath);
builder.outputFilePath(outputPath);

• Android bitmaps can be passed directly as input as follows This is useful for converting from image to PDF.

builder.addInputImage(bitmap)

4.     Execute the job.

CibPdfModule module = builder.build();

5.     Collect the results.

• If the property "OutputFilename" is set, the output file can be found in the path specified there.
• Fetch Get-Properties with the following call

String result = job.getProperty(name);

• Currently, only a check is possible whether the call was successful. Details can be found in the trace file, which is always written to the app cache directory in debug mode.

boolean success = module.isSuccessful();

6.    Release the job.

module.close();

CIB image toolbox

Classes for direct access

• swig.jni.de.cib.ipl.IPLJob
• de.cib.imageprocessing.swig.CibImageProcessingLibraryConstants

Examples for the individual steps:

1.     Load the library and all dependencies.

• Following libraries must be loaded.

System.loadLibrary("c++_shared");
System.loadLibrary("cibipltux64");

2.     Create a job.

final long[] handle = { 0 };
IPLJob.CibImageProcessingJobCreate(handle);

3.     Set properties for this job.

• Names and values for most properties are found in the CibImageProcessingLibraryConstants class. A complete list with documentation can be found in the CIB image toolbox technical guide.

IPLJob.CibImageProcessingJobSetProperty (handle[0], name, value);

• Android bitmaps can be passed directly as input as follows.

IPLJob.CibImageProcessingJobAddInputImage(handle[0], bitmap);

4.     Execute the job.

long errorCode = IPLJob.CibImageProcessingJobRun(handle[0]);

5.     Collect the results.

• If the property "OutputFilename" is set, the output file can be found in the path specified there.
• Fetch Get-Properties with the following call:

byte[] inputbuf = new byte[length];
IPLJob.CibImageProcessingJobGetProperty(handle[0], name, inputbuf);
String result = new String(inputbuf, 0, length);

• If the result is again a bitmap, it can be retrieved as follows.

IPLJob.CibImageProcessingJobGetOutputImage(handle[0], 0L, Bitmap.Config.RGB_565);

• Error codes and messages can be found here:

int[] errorCode = {0};
IPLJob.CibImageProcessingJobGetError(handlerId, errorCode);
int code = errorCode[0];
 
final byte[] errorText = new byte[length];
IPLJob.CibImageProcessingJobGetErrorText (handlerId, errorTextBuf);
String message = new String(errorText, 0, length);

6.     Release the job.

IPLJob.CibImageProcessingJobFree(handle);

Wrapper-classes

• de.cib.imageprocessing.CibIpl

Examples for the individual steps with CibIpl:

This is a class with static methods. They cover use cases for image processing such as applying filters, recognizing documents, or rotating images. Within the methods, all steps are considered, which makes them very easy to use.

CibIpl.load();
Bitmap outputBitmap = CibIpl.boostContrast(inputBitmap, 1.5f);

CIB ocr

Classes for direct access

• de.cib.ocr.CibOcrImpl
• de.cib.ocr.swig.CibOcrConstants

Example:

// load initially the libraries
CibOcrImpl.loadStl();
CibOcrImpl.loadOcr();

// create a job handle
long handle = CibOcrImpl.CreateJob();

// set properties for this job
CibOcrImpl.SetProperty(handle, CibOcrConstants.COMOD_PROP_LICENSE_COMPANY, licenseCompany);

CibOcrImpl.SetProperty(handle, CibOcrConstants.
CibOcrImpl.SetProperty(handle, CibOcrConstants.COMOD_PROP_LICENSE_KEY, licenseKey);

CibOcrImpl.SetProperty(handle, CibOcrConstants.
CibOcrImpl.SetProperty(handle, CibOcrConstants.COMOD_PROP_OUTPUT_FORMAT, CibOcrConstants.COMOD_OPT_FORMAT_TEXT);

CibOcrImpl.SetProperty(handle, CibOcrConstants.
CibOcrImpl.SetProperty(handle, CibOcrConstants.CIBOCR2_PROP_DICTIONARY_WORKSPACE, pathToTessData);

CibOcrImpl.SetProperty(handle, CibOcrConstants.
CibOcrImpl.SetProperty(handle, CibOcrConstants.CIBOCR2_PROP_LANGUAGE, "eng");

CibOcrImpl.SetProperty(handle, CibOcrConstants.
CibOcrImpl.SetProperty(handle, CibOcrConstants.CIBOCR_PROP_INPUT_FILENAME, inputFilePath);

CibOcrImpl.SetProperty(handle, CibOcrConstants.
CibOcrImpl.SetProperty(handle, CibOcrConstants.CIBOCR_PROP_OUTPUT_FILENAME, outputFilePath);
 
// start job execution
boolean result = CibOcrImpl.Start(handle);
 
// free job memory
CibOcrImpl.FreeJob(handle);

Wrapper-classes

• de.cib.android.common.manager.OcrManager
• de.cib.android.common.operation.OcrTask
• de.cib.android.common.operation.OcrTaskBundle

The wrapper classes allow the execution of text recognition on multiple pages or documents. Callbacks are used to communicate the progress and completion of the process.

Example:

Please have a look at the example "testImage2Hocr" in the showcase.

CIB aiModule

Note:
CIB aiModule is currently available for ARM 64 bit and x86 64 bit, only. Please ask us for other architectures if required.

This module is not directly called. It is encapsulated by CIB image toolbox and is required for edge detection on AI basis. The easiest way to call it via the wrapper class "CibIpl" with the method findLargestRectangle() is to set the second parameter to "Ai". This directly sets the property "InfoGetBoundaries/Algorithm" in CIB image toolbox. More possible values and information can be found in the Technical guide CIB image toolbox when searching for "InfoGetBoundaries".

CibIpl.load();
BorderDetectionResult
result = CibIpl.findLargestRectangle(bitmap, "Ai");

3.4. Recommadation for text recognition

The results of text recognition can be significantly improved with suitable pre-processing of the image data.

Taking the picture

The document should be recorded as flat as possible. Unevenness of the document makes recognition more difficult.

Cleaning the image

Either with a black and white filter like::

CibIpl.localOtsuBinarizer(Bitmap src, float threshold)

or with the following filter, which is also suitable for colour documents:

CibIpl.whiteboard(Bitmap src, boolean reflectionMode)

Aligning the image

The alignment of the document and the text it contains is important. The text should be aligned as horizontally as possible. The alignment is adjusted at the same time as the cut is made by the following function:

CibIpl.warpCrop(Bitmap src, int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3, boolean resize)

In addition, an automatic alignment with:

CibIpl.deskew(Bitmap src)

can bring improvements in text recognition.

4. Showcase

The included showcase is a project for Android Studio.

4.1. Open and start

1. Unpack the included Showcase for Android into a local directory.
2. Start Android Studio and click on „File“ à „Open“.
3. Select the local directory in the dialog and click "Ok".
4. In the "Project" view you will now find "showcase" and "sdk".
• „sdk" is the SDK of the CIB modules delivered as AAR.
• „showcase“ contains sample code in the form of tests.
5. Open „showcase“➔ „java“➔ „de.cib.android.showcase“ and the files it contains. They contain typical use cases for the respective subject areas.
6. Open the context menu with a right click on one of the files (except "BaseTests") and select "Run <Filename>”.
7. The examples of the respective file are now executed as tests.

4.2. Setting the licence

Hint:
The license was already set for you in the showcase by us.

If no license has been set by us, please proceed as follows:

1. Open the module „showcase“.
2. Open the "res" folder.
3. Open the file „strings.xml“.
4. You now see the string variables with the names:
• cibOcrLicenseCompany
• cibOcrLicenseKey
• cibPdfToolboxLicenseCompany
• cibPdfToolboxLicenseKey
5. Set as value the licenses provided by us.
6. If you also want to test our server-bound text recognition with DeepER, the values for the following string variables must also be set:
• cibOcrDeeperUrlProduction
• cibOcrDeeperProductionAuthentication

4.3. Checking the licence

See section "Checking the license" in the "SDK" section.

4.4. Output files

The output is stored in the external cache directory of the showcase app. This is usually located on the device under:

/sdcard/Android/data/de.cib.android.showcase

In the same folder you can also find the input files.

The folder can either be opened on the Android device used via a file explorer or via Android Studio's "Device File Explorer" directly on the developer computer.