Einsatz CIB Module unter Android technischer Leitfaden (DE)

3. SDK

3.3. Ansteuerung

Allgemein
 CIB pdf toolbox
 CIB pdfModule
 CIB image toolbox
 CIB ocr
 CIB aiModule
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.
    3. 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.
    5. 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");