Usage of CIB modules on Android Technical Guide (EN)

3. SDK

3.3. Usage

General
CIB pdf toolbox
CIB pdfModule
CIB image toolbox
CIB ocr
CIB aiModule

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:

Load the library and all dependencies.

Must only be done once per runtime.

Create a job.
Set properties for this job.
Execute the job.
Collect the results.
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.

In any case, it is recommended to first have a look at the Showcase, which already contains typical use cases on which you can build your own.

CIB pdf toolbox

Classes for direct access

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

Examples for the individual steps:

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");

Create a Job.

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

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());

Execute the job.

CibPdf.CibPdfJobJoin(handle[0]);

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);

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");