Einsatz CIB Module unter Android technischer Leitfaden (DE)

1. Lieferumfang

Die CIB Module werden für Android als AAR (Android Archive) geliefert.

2. Einführung

Die vorliegende Bibliothekssammlung für den Einsatz unter Android beinhaltet alle CIB Module die erforderlich sind um Bilder und PDFs auf mobilen Endgeräten zu bearbeiten. Die verfügbaren Wrapper erleichtern den Einsatz der mächtigen CIB Module auf der jeweiligen Plattform.

Die Größe und der Umfang des Bibliotheksmoduls kann auf Anfrage angepasst werden.

3. SDK

3.1. Anforderungen

Das minimal unterstützte API Level ist 21 (Android 5).

Unterstützte Architekturen sind:

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

3.2. Integration

Allgemein

Die CIB Modulen werden für Android als AAR geliefert. Das AAR kann wie folgt in eine bestehende Android-Anwendung integriert werden. Dabei wird auf Android Studio als Entwicklungsumgebung gesetzt.

Die im Lieferumfang enthaltene Beispielintegration („Showcase“) kann ebenfalls als Vorlage für die Integration genutzt werden.

1. In Android Studio, wählen Sie „File“ ➔ „New“ ➔ „Module“.
2. Im Dialog wählen Sie „Import .JAR/.AAR Package“ und klicken „Next“.
3. Wählen Sie den Pfad zum AAR mit den CIB Modulen aus und klicken Sie „Finish“.
4. Klicken Sie anschließend in der Werkzeugleiste auf „Sync Project with Gradle Files“.

Setzen der Lizenz

Die Lizenz besteht jeweils aus Ihrem Kundennamen („Company“) und einem Schlüssel („Key“). Diese müssen Sie über eine Ressourcendatei in Ihrem existierenden Projekt, wie z.B. eine „strings.xml“, als Strings gesetzt werden. Fügen Sie dazu folgende Zeilen in eine bestehende „strings.xml“ ein.

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

Als Werte setzten Sie die separat ausgehändigten Lizenzschlüsselpaare. Die Werte müssen exakt so gesetzt werden, wie Sie sie von uns erhalten haben.

Prüfen der Lizen

Hinweis:
Eine Lizenz kann bestimmte Funktionen ein- oder ausschließen. Um sicher zu gehen ob ein Lizenzproblem vorliegt, muss das Tracefile geprüft werden. Dazu gehen Sie wie folgt vor.

1. Stellen Sie sicher, dass bei Ihrem Aufruf an das jeweilige CIB Modul die Property „TraceFilename“ mit einem validen Dateipfad gesetzt ist.
2. Starten Sie ihren Job.
3. Nachdem der Job beendet ist, öffnen Sie auf dem Gerät den unter „TraceFilename“ angegebenen Dateipfad. Hier befindet sich der Trace des Jobs.
4. Öffnen Sie das Tracefile. Wenn die Lizenz gültig ist, sollte u.a. folgende Zeile darin zu finden sein:

LICENSE: Valid license.

Ist dies nicht der Fall, prüfen Sie Ihre Lizenz. Falls das Problem weiter besteht, kontaktieren Sie den CIB Support.

3.3. Ansteuerung

Allgemein

Bei den CIB Modulen  handelt es sich um native C++-Bibliotheken. Dies bringt gewisse technische Erfordernisse mit sich, die hier beschrieben werden.

Prinzipiell folgt der Aufruf aller CIB Module einem festen Ablauf. Er kann durch Wrapper implizit ausgeführt werden. Lediglich beim Direktzugriff auf die CIB Module wird der hier beschriebene Ablauf explizit offensichtlich:

1. Laden der Bibliothek und aller Abhängigkeiten.
• Muss lediglich einmalig je Laufzeit vorgenommen werden.
2. Erstellen eines Jobs.
3. Setzen von Properties für diesen Job.
4. Ausführung des Jobs.
5. Abholen der Ergebnisse.
6. Freigeben des Jobs.

Für die Fehleranalyse gibt jeder Aufruf eines Jobs einen Fehlercode zurück. In den jeweiligen technischen Leitfäden finden sich Listen mit der jeweiligen Bedeutung.

Für jeden Aufruf eines Jobs kann darüber hinaus ein Tracefile geschrieben werden, welches für die weitere Fehleranalyse erforderlich ist. Es wird nur geschrieben, wenn für die Property „TraceFilename“ ein gültiger Pfad gesetzt ist.

Für die CIB Module sind im AAR Wrapper-Klassen enthalten, welche die Handhabung für typische Anwendungsfälle deutlich vereinfachen. Jedoch sind nur übliche Anwendungsfälle abgedeckt.

Darüber hinaus sind auch Klassen für den Direktzugriff vorhanden. Diese mappen 1:1 die nativen Schnittstellen der CIB Module über JNI auf Java-Methoden. Somit können die CIB Module ganz individuell genutzt und die volle Funktionalität ausgereizt werden. Die jeweiligen Property-Namen und mögliche Werte finden Sie für jedes CIB Modul in dem entsprechenden technischen Leitfaden.

In jedem Fall wird empfohlen zunächst einen Blick auf den Showcase zu werfen, der bereits typische Anwendungsfälle beinhaltet, auf die eigene aufgebaut werden können.

CIB pdf toolbox

Klassen für Direktzugriff

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

Beispiele für die einzelnen Schritte:

1. Laden der Bibliothek und aller Abhängigkeiten.
• Mindestens erforderliche Bibliotheken, die geladen werden müssen.

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

• Soll ein PDF in eine Grafik gerendert werden, muss zusätzlich folgende Bibliothek geladen werden.

System.loadLibrary("cibrendererux64");

• Um hochkomprimierte Schwarz/Weiß-PDFs mit JBig2 zu erstellen, muss zusätzlich folgende Bibliothek geladen werden.

System.loadLibrary("cibjbig2ux64");

• Um hochkomprimierte Farb-PDFs mit MRC zu erstellen, müssen lediglich folgende Bibliotheken geladen werden.

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

2. Erstellen eines Jobs.

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

3. Setzen von Properties für diesen Job.
• Namen und Werte für die meisten Properties finden Sie in der Klasse „CibPdfContants“. Eine vollständige Liste mit Dokumentation finde Sie im technischen Leitfaden der CIB pdf toolbox.

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

4. Ausführung des Jobs.

CibPdf.CibPdfJobJoin(handle[0]);

5. Abholen der Ergebnisse.
• Wenn die Property „OutputFilename“ gesetzt wurde, kann im dort angegebenen Pfad die Ausgabedatei gefunden werden.
• Abholen von Get-Properties ist nur für bestimmte Properties über Methoden-Aufrufe möglich:

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

• Fehlercodes und Meldungen sind hier zu finden:

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. Freigeben des Jobs.

   CibPdf.CibPdfJobFree(handle);

Wrapper-Klassen

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

Beispiele für die einzelnen Schritte:

1.     Laden der Bibliothek und aller Abhängigkeiten.

• Mindestens erforderliche Bibliotheken, die geladen werden müssen.

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

• Soll ein PDF in eine Grafik gerendert werden, muss zusätzlich folgende Bibliothek geladen werden.

PdfToolbox.Library.TOOLBOX_RENDERER

• Um hochkomprimierte Schwarz/Weiß-PDFs mit JBig2 zu erstellen, muss zusätzlich folgende Bibliothek geladen werden.

PdfToolbox.Library.JBIG2

• Um hochkomprimierte Farb-PDFs mit MRC zu erstellen, müssen lediglich folgende Bibliotheken geladen werden.

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

2.     Erstellen eines Jobs.

• Wird implizit vorgenommen.

3.     Setzen von Properties für diesen Job.

• Properties werden implizit durch Methodenaufrufe gesetzt.

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

4.     Ausführung des Jobs.

PdfToolbox
toolbox = builder.build();

5.     Abholen der Ergebnisse.

• Wenn die Property „OutputFilename“ gesetzt wurde, kann im dort angegebenen Pfad die Ausgabedatei gefunden werden.
• Abholen von Get-Properties ist nur für bestimmte Properties über Methoden-Aufrufe möglich:

int pageCount = toolbox.getPageCount()

• Sollten anderen Get-Properties benötigt werden, verwenden Sie bitte die Klassen für den Direktzugriff oder kontaktieren Sie uns.
• Fehlercodes und Meldungen sind hier zu finden:

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

6.     Freigeben des Jobs.

toolbox.close();

CIB pdfModule

Klassen für Direktzugriff

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

Beispiele für die einzelnen Schritte:

1.     Laden der Bibliothek und aller Abhängigkeiten.

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

2.     Erstellen eines Jobs.

CibPdfModuleJobInterface job = new CibPdfModuleJobInterface();

3.     Setzen von Properties für diesen Job.

• Namen und Werte für die meisten Properties finden Sie in der Klasse „CibPdfContants“. Eine vollständige Liste mit Dokumentation finde Sie im technischen Leitfaden der CIB pdf toolbox.

job.setProperty(name, value);

• Android Bitmaps können als Input wie folgt direkt übergeben werden. Dies ist für die Konvertierung von Bild zu PDF hilfreich.

job.addInputImage(bitmap);

4.     Ausführung des Jobs.

long resultCode = job.execute();

5.     Abholen der Ergebnisse.

• Wenn die Property „OutputFilename“ gesetzt wurde, kann im dort angegebenen Pfad die Ausgabedatei gefunden werden.
• Abholen von Get-Properties mit folgendem Aufruf:

String result = job.getProperty(name);

• Für Fehlercodes prüfen Sie bitte den Rückgabewert des „execute()“-Aufrufs.

6.     Freigeben des Jobs.

job.delete();

Wrapper-Klassen

de.cib.pdf.module.CibPdfModule

Beispiele für die einzelnen Schritte:

1.     Laden der Bibliothek und aller Abhängigkeiten.

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

2.     Erstellen eines Jobs.

• Wird implizit vorgenommen.

3.     Setzen von Properties für diesen Job.

• Properties werden implizit durch Methodenaufrufe gesetzt.

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

• Android Bitmaps können als Input wie folgt direkt übergeben werden. Dies ist für die Konvertierung von Bild zu PDF hilfreich.

builder.addInputImage(bitmap)

4.     Ausführung des Jobs.

CibPdfModule module = builder.build();

5.     Abholen der Ergebnisse.

• Wenn die Property „OutputFilename“ gesetzt wurde, kann im dort angegebenen Pfad die Ausgabedatei gefunden werden.
• Abholen von Get-Properties mit folgendem Aufruf:

String result = job.getProperty(name);

• Aktuell ist nur eine Prüfung möglich, ob der Aufruf erfolgreich war. Details finden Tracefile, das im Debug-Modus immer ins App-Cache-Verzeichnis geschrieben wird.

boolean success = module.isSuccessful();

6.     Freigeben des Jobs.

module.close();

CIB image toolbox

Klassen für Direktzugriff

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

Beispiele für die einzelnen Schritte:

1.     Laden der Bibliothek und aller Abhängigkeiten.

• Folgende Bibliotheken müssen geladen werden.

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

2.     Erstellen eines Jobs.

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

3.     Setzen von Properties für diesen Job.

• Namen und Werte für die meisten Properties finden Sie in der Klasse „CibImageProcessingLibraryConstants“. Eine vollständige Liste mit Dokumentation finde Sie im technischen Leitfaden der CIB image toolbox.

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

• Android Bitmaps können als Input wie folgt direkt übergeben werden.

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

4.     Ausführung des Jobs.

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

5.     Abholen der Ergebnisse.

• Wenn die Property „OutputFilename“ gesetzt wurde, kann im dort angegebenen Pfad die Ausgabedatei gefunden werden.
• Abholen von Get-Properties mit folgendem Aufruf:

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

• Falls das Ergebnis wiederum eine Bitmap ist, kann diese wie folgt abgeholt werden.

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

• Fehlercodes und Meldungen sind hier zu finden:

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.     Freigeben des Jobs.

IPLJob.CibImageProcessingJobFree(handle);

Wrapper-Klassen

• de.cib.imageprocessing.CibIpl

Beispiele für die einzelnen Schritte mit CibIpl:

Hierbei handelt es sich um eine Klasse mit statischen Methoden. Sie decken Anwendungsfälle zur Bildbearbeitung ab wie das Anwenden von Filtern, Erkennung von Dokumenten oder das Drehen von Bildern. Innerhalb der Methoden sind alle Schritte berücksichtigt, womit sich der Einsatz als sehr einfach darstellt.

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

CIB ocr

Klassen für Direktzugriff

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

Beispiel:

// 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-Klassen

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

Die Wrapper-Klassen ermöglichen die Ausführung einer Texterkennung auf mehrere Seiten oder Dokumente. Über Callbacks werden Fortschritt und Abschluss der Vorgänge mitgeteilt.

Beispiel:

Bitte werfen Sie hierfür einen Blick in das Beispiel „testImage2Hocr“ im Showcase.

CIB aiModule

Hinweis:
CIB aiModule ist aktuell nur für ARM 64 bit und x86 64 bit verfügbar. Bitte fragen Sie bei Bedarf weitere Architekturen bei uns an.

Dieses Modul wird nicht direkt angesteuert. Es wird durch CIB image toolbox gekapselt und wird für die Kantenerkennung auf KI-Basis benötigt. Am einfachsten ist ein Aufruf über die Wrapper-Klasse „CibIpl“ mit der Methode findLargestRectangle() indem der zweite Parameter auf „Ai“ gesetzt wird. Dies setzt direkt die Property „InfoGetBoundaries/Algorithm“ in CIB image toolbox. Weitere mögliche Werte und Informationen finden Sie im Technischen Leitfaden von CIB image toolbox, wenn Sie nach „InfoGetBoundaries“ suchen.

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

3.4. Empfehlung zur Texterkennung

Die Ergebnisse der Texterkennung lassen sich mit geeigneter Vorverarbeitung der Bilddaten deutlich verbessern.

Aufnahme des Bildes

Das Dokument möglichst eben aufgenommen sein. Unebenheiten des Dokuments erschweren die Erkennung.

Reinigen des Bildes

Entweder mit einem Schwarz-Weiß-Filter wie:

CibIpl.localOtsuBinarizer(Bitmap src, float threshold)

oder mit dem folgenden Filter, der auch für Farbdokumente geeignet ist:

CibIpl.whiteboard(Bitmap src, boolean reflectionMode)

Ausrichten des Bildes

Die Ausrichtung des Dokuments und des darin enthaltenen Textes ist wichtig. Der Text sollte möglichst waagerecht ausgerichtet sein. Die Ausrichtung wird gleichzeitig mit dem Zuschnitt durch folgende Funktion angepasst:

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

Zusätzlich kann eine automatische Ausrichtung mit:

CibIpl.deskew(Bitmap src)

noch Verbesserungen in der Texterkennung bringen.

4. Showcase

Bei dem mitgelieferten Showcase handelt es sich um ein Projekt für Android Studio.

4.1. Öffnen und Starten

Entpacken Sie den mitgelieferten Showcase für Android in ein lokales Verzeichnis.

Starten Sie Android Studio und klicken auf „File“ ➔ „Open“.

Wählen Sie das lokale Verzeichnis im Dialog aus und klicken Sie „Ok“.

In der „Project“-Ansicht finden Sie nun „showcase“ und „sdk“.

Bei „sdk“ handelt es sich um das als AAR gelieferte SDK der CIB Module.

„showcase“ beinhaltet Beispielcode in Form von Tests.

Öffnen Sie „showcase“ ➔ „java“ ➔ „de.cib.android.showcase“ und die darin enthaltenen Dateien. Sie enthalten typische Anwendungsfälle zu den jeweiligen Themenbereichen.

Öffnen Sie mit einem Rechtsklick auf eine der Dateien (außer „BaseTests“) das Kontextmenü und wählen „Run <Dateiname>‘“.

Die Beispiele der jeweiligen Datei werden nun als Tests ausgeführt.

4.2. Setzen der Lizenz

Hinweis:
Die Lizenz wurde im Showcase bereits von uns für Sie gesetzt.

Sofern noch keine Lizenz von uns gesetzt wurde, gehen Sie wie folgt vor.

1. Öffnen Sie das Modul „showcase“.
2. Klappen Sie den Ordner „res“ auf.
3. Öffnen Sie die Datei „strings.xml“.
4. Sie sehen nun die String-Variablen mit den Namen:
• cibOcrLicenseCompany
• cibOcrLicenseKey
• cibPdfToolboxLicenseCompany
• cibPdfToolboxLicenseKey
5. Setzen Sie als Wert die von uns zur Verfügung gestellten Lizenzen.
6. Möchten Sie darüber hinaus unsere servergebundene Texterkennung mit DeepER testen, müssen auch die Werte für folgende String-Variablen gesetzt werden:
• cibOcrDeeperUrlProduction
• cibOcrDeeperProductionAuthentication

4.3. Prüfen der Lizenz

Siehe Abschnitt „Prüfen der Lizenz“ im Abschnitt „SDK“.

4.4. Ausgabedateien

Die Ausgaben werden in im externen Cache-Verzeichnis der Showcase-App abgelegt. Dies befindet sich üblicherweise auf dem Gerät unter:

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

Im gleichen Ordner sind auch die Eingabedateien zu finden.

Der Ordner lässt sich entweder auf dem verwendeten Android-Gerät über einen Dateiexplorer öffnen oder über Android Studios „Device File Explorer“ direkt am Entwickler-Rechner.