Einsatz CIB Module unter iOS technischer Leitfaden (DE)

1. Lieferumfang

Die CIB Module werden für iOS als Framework geliefert.

2. Einführung

Das vorliegende Bibliotheksmodul für den Einsatz unter iOS 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

Minimal wird iOS 9.3 unterstützt.

Unterstützte Architekturen sind:

• ARM64 (64 bit)
• x86 (64 bit)

3.2. Integration

Allgemein

Die CIB Module werden für iOS als xcframework geliefert. Das xcframework kann wie folgt in eine bestehende iOS-Anwendung integriert werden. Dabei wird auf Xcode als Entwicklungsumgebung gesetzt.

Die im Lieferumfang enthaltene Beispielintegration („Showcase“) kann ebenfalls als Vorlage genutzt werden.

1. In Xcode, markieren Sie ihr App-Projekt im „Project Navigator“.
2. Unter „Targets“ wählen Sie Ihr App Target und öffnen die Seite „General“.
3. Im Bereich „Linked Frameworks and Libraries” klicken Sie auf das „+“.
4. Wählen Sie den Pfad zum xcframework mit den CIB Modulen und klicken Sie „Add“.

Setzen der Lizenz

Die Lizenz besteht jeweils aus Ihrem Kundennamen („Company“) und einem Schlüssel („Key“). Diese müssen Sie über Properties bei jedem Aufruf gesetzt werden.

Beispiel für CIB pdfToolbox und CIB ocr:

#define ocrLicenseCompany @"REQUEST FROM CIB SUPPORT
#define ocrLicenseKey @"REQUEST FROM CIB SUPPORT
#define pdfToolboxLicenseCompany @"REQUEST FROM CIB SUPPORT
#define pdfToolboxLicenseKey @"REQUEST FROM CIB SUPPORT
…
DXOCRJob *ocrJob = [[DXOCRJob alloc] init];
[ocrJob setValue:ocrLicenseCompany forProperty:COMOD_PROP_LICENSE_COMPANY];
[ocrJob setValue:ocrLicenseKey forProperty:COMOD_PROP_LICENSE_KEY];
…
DXPDFToolboxJob *pdfToolboxJob = [[DXPDFToolboxJob alloc] init];
[pdfToolboxJob setValue:pdfToolboxLicenseCompany forProperty:COMOD_PROP_LICENSE_COMPANY];
[pdfToolboxJob setValue:pdfToolboxLicenseKey forProperty:COMOD_PROP_LICENSE_KEY];

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

• doXisafeBase/DXPDFToolboxJob
• doXisafeBase/COMod

Beispiele für die einzelnen Schritte:

1. Laden der Bibliothek und aller Abhängigkeiten.
• Wird implizit durch das System vorgenommen.
2. Erstellen eines Jobs.

DXPDFToolboxJob *job = [[DXPDFToolboxJob alloc] init];

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

[job setValue:value forProperty:name];

4. Ausführung des Jobs.

BOOL success = [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:

NSString *result = [job valueForProperty:name];

6. Fehlercodes und Meldungen sind hier zu finden:

job.error.code;
job.error.userInfo;

7. Freigeben des Jobs.
• Wird implizit vorgenommen.

CIB pdfModule

• doXisafeBase/DXPDFModuleJob
• doXisafeBase/COMod

Beispiele für die einzelnen Schritte:

1. Laden der Bibliothek und aller Abhängigkeiten.
• Wird implizit durch das System vorgenommen.
2. Erstellen eines Jobs.

DXPDFToolboxJob *job = [[DXPDFModuleJob alloc] init];

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

[job setValue:value forProperty:name];

4. Ausführung des Jobs.

BOOL success = [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)

6. Fehlercodes und Meldungen sind hier zu finden:

job.error.code;
job.error.userInfo;

7. Freigeben des Jobs.
• Wird implizit vorgenommen.

CIB image toolbox

• doXisafeBase/DXIPLProcessingJob
• doXisafeBase/COMod

Beispiele für die einzelnen Schritte:

1. Laden der Bibliothek und aller Abhängigkeiten.
• Wird implizit durch das System vorgenommen.
2. Erstellen eines Jobs.

DXIPLProcessingJob *job = [[DXIPLProcessingJob alloc] init];

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

[job setValue:value forProperty:name];

• „UIImages“ können als Input wie folgt übergeben werden.

UIImage *uiImage = [UIImage imageNamed:pathFile];
[job addInputUiImage: uiImage];

4. Ausführung des Jobs.

BOOL success = [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:

NSString *result = [job valueForProperty:name];

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

  UIImage *uiImageResult = [job getOutputUiImage];

6. Fehlercodes und Meldungen sind hier zu finden:

   job.error.code;
   job.error.userInfo;

7. Freigeben des Jobs.
• Wird implizit vorgenommen.

Wrapper-Klassen

• doXisafeBase/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.

UIImage *uiImageResult = [[CibIpl alloc] boostContrast:uiImage contrast:1.5f];

CIB ocr

• doXisafeBase/DXOCRJob
• doXisafeBase/COMod

Beispiele für die einzelnen Schritte:

1. Laden der Bibliothek und aller Abhängigkeiten.
• Wird implizit durch das System vorgenommen.
2. Erstellen eines Jobs.

DXOCRJob *job = [[DXOCRJob alloc] init];

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

[job setValue:value forProperty:name];

4. Ausführung des Jobs.

BOOL success = [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:

NSString *result = [job valueForProperty:name];

6. Fehlercodes und Meldungen sind hier zu finden:

job.error.code;
job.error.userInfo;

7. Freigeben des Jobs.
• Wird implizit vorgenommen.

CIB aiModule

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

DXPointsRecord record = [[CibIpl alloc] findLargestRectangle:&cibImageProcessingImage 
orientation:UIInterfaceOrientationPortrait algorithm:@"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 alloc] localOtsuBinarizer:&cibImageProcessingImage threshold:1]

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

[[CibIpl alloc] whiteboard:&cibImageProcessingImage reflectionMode:NO]

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 alloc] warpCrop:&cibImageProcessingImage points:mPoints resize:NO]

Zusätzlich kann eine automatische Ausrichtung mit:

[[CibIpl alloc] deskew:&cibImageProcessingImage]

noch Verbesserungen in der Texterkennung bringen.

4. Showcase

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

4.1. Öffnen und Starten

Hinweis:
Im Showcase sind zwei SDKs im Auslieferungszustand enthalten. Das SDK für die Build-Konfiguration „Debug“ ist nur mit Simulatoren kompatibel. Das SDK für die Build-Konfiguration „Release“ ist nur mit echten Geräten kompatibel.
Wenn Sie den Code in einer Konfiguration anderweitig ausführen möchten, tauschen Sie das SDK im Showcase bitte aus der entsprechenden Framework-Datei.

1. Entpacken Sie den mitgelieferten Showcase für iOS in ein lokales Verzeichnis.
2. Öffnen Sie mit einem Doppelklick auf „sdk-showCase.xcodeproj“ das Projekt in Xcode.
3. In der Projektnavigation finden sie nun „sdk-showCase“.
• Darunter finden Sie in „Frameworks“ das SDK unter der Bezeichnung „doXisafeBase.framework“.
• Im Ordner „sdk-showCase“ finden Sie den Beispielcode.
4. Öffnen Sie „sdk-showCase“ ➔ „Classes“ und die darin enthaltenen Dateien „ImageFilterTests.mm“, „PdfTests.mm“ und „TestRecognitionTests.mm“. Sie enthalten typische Anwendungsfälle zu den jeweiligen Themenbereichen.
• In „ViewController.m“ können einzelne Beispiele ein- und auskommentiert werden, die ausgeführt werden sollen.
5. Mit einem Klick auf „Build and Run“ in Xcode werden die 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 Module „sdk-showcase“.
2. Öffnen Sie den Ordner „sdk-showcase“.
3. Öffnen Sie den Ordner „Classes“.
4. Öffnen Sie die Dateien PdfTests.mm, TextRecognitionTests.mm, InMemoryTests.mm und TextRecognitionWithDeepErTests.mm.
• Setzen Sie als Wert die von uns zur Verfügung gestellten Lizenzen für CIB pdf toolbox und CIB ocr wie in „Setzen der Lizenz“ im Abschnitt SDK beschrieben.
5. Sofern Sie DeepER verwenden möchten, setzten Sie auch folgenden Variablen in TextRecognitionWithDeepErTests.mm auf die Ihnen zur Verfügung gestellten Werte.

    #define cibOcrDeeperUrlProduction @"REQUEST FROM CIB SUPPORT"
    #define cibOcrDeeperProductionAuthentication @"REQUEST FROM CIB SUPPORT"

4.3. Prüfen der Lizenz

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

4.4. Ausgabedateien

Der Pfad der Ausgaben wird in der Ausgabe von Xcode ausgegeben.