Using the Scanner¶

Start the image capture¶

The image capturing is started with a single class method call on the GiniVision class. The document capturing then displays its own UI and your application’s UI is dismissed during the capturing process. The arguments to this method call are:

The currently displayed view controller. Usually, this is the same view controller as the view controller which started the image capturing.
An instance of an object that implements the GiniVisionDelegate protocol. This delegate is called during several steps of the image capturing and gets the results of the image capturing.
(optional) A GiniConfiguration object to customize the look and behavior of the Gini Vision Library.

The following example implements a callback for a touch event on a UIButton. In this callback, the image capturing is started.

//
// MyViewController.m
//

#import <GiniVision/GiniVision.h>

@interface MyViewController () <GiniVisionDelegate>
@end

@implementation MyViewController

- (IBAction) scanDocument:(UIButton *)sender {
    [GiniVision captureImageWithViewController:self delegate:self];
}

@end

//
// Bridging-Header.h
//

#import <GiniVision/GiniVision.h>


//
// MyViewController.swift
//

class MyViewController: UIViewController, GiniVisionDelegate {

    @IBAction
    func scanDocument(sender: AnyObject) {
        GiniVision.captureImageWithViewController(self, delegate: self)
    }

}

Warning

You really have to call this method with the view controller that is currently displayed. If the given view controller isn’t displayed currently, the framework throws an error and your application will crash.

To switch back to your application’s UI use the GINIVisionUploadDelegate as described below.

Implement and use the `GiniVisionDelegate`¶

As mentioned above, the image capturing comes with a built-in UI and your application does not need to implement anything regarding the image capturing. However, you are usually interested in the results of the image capturing. The results of the image capturing process are given to your app via the GiniVisionDelegate. Therefore, you need to pass an object that implements this delegate to the image capture call (see the method call in the example above).

`didScan:(UIImage ) documentJPEGData:(NSData ) documentType:(GINIDocumentType) uploadDelegate:(id<GINIUploadDelegate>)`¶

Will be called after a document has been captured with the document (cropped and enhanced) as argument. The given documentType argument describes the type of the scanned document. The receiver should upload the document and inform the given upload delegate so the UI is updated accordingly. In documentJPEGData the cropped and enhanced document is contained including meta information about the image. This argument will be nil when createJPEGDocumentWithMetaData is set to false. Read below to find out which meta information is used.

The first parameter is a UIImage instance containing the scanned document. The second argument is an NSData instance containing the scanned document as JPEG data and meta information about the image. The third argument is an enum that informs you which document type the user scanned. This can either be

GINIDocumentTypeInvoice: An invoice, usually in the DIN A4 format.
GINIDocumentTypeRemittance: A German remittance slip in the DIN A6 format
GINIDocumentTypeIntegratedRemittance: A document in the A4 format which contains a remittance slip.

Note

The delegate method didScan:documentType:uploadDelegate: was deprecated. You should move the method body to didScan:documentData:documentType:uploadDelegate: and leave the old one empty.

`(void)didScanOriginal:(UIImage *)`¶

Will be called after a document has been captured with the original (that means not enhanced and not cropped) image as argument. Handy for debugging or analysis. It is not recommended to use this feature in production.

`(void)didFinishCapturing:(BOOL)`¶

Called after the image capturing UI has been dismissed. The given argument success indicates whether the user has captured a document or has canceled the document capturing.

`(void)didCancelUpload`¶

Called when the user cancels the upload process.

Meta Information Tags¶

In order to improve our service we would like to receive meta information about the circumstances in which the document was photographed. Therefore we use a subset of all available exif tags.

Only the following exif tags are kept in the jpeg file. No personal, geographical or otherwise sensitive information is stored.

Make: The manufacturer of the device.
LensMake: Should be the same as Make.
Model: The model name or model number of the device.
LensModel: Like Model but gives more detailed information about the lens used.
Software: The software used by the capturing device, this should be some version of iOS ex. “9.1”.
ISO: The ISO speed of the camera.
Exposure Time: Exposure time, given in seconds.
Aperture: The lens aperture. The unit is the APEX value.
Flash: Status of flash when the image was taken.
Compressed Bits Per Pixel: The compression mode used for a compressed image is indicated in unit bits per pixel.
Orientation: The image orientation derived from the device orientation.
Platform: The name of the os in this case “iOS”.
OS Version: Should be the same as Software.
GiniVision Version: GiniVision SDK version.

Use the `GINIVisionUploadDelegate` to upload files and update the UI¶

Your application is responsible for uploading the captured document, for example with the help of the Gini SDK for iOS. Nevertheless, the Gini Vision Library displays an optimized and user-tested UI during the upload. When your application gets informed that a document is captured, it gets also an instance of the upload delegate. You can call several methods on this delegate in order to update the UI to reflect the current update status.

`(void)didProgress:(float)totalProgress`¶

Call this method during the upload of the document to update the activity indicator of the upload UI accordingly. The parameter represents the progress in the upload process of the document on a scale from 0 to 1.

`(void)didProgressWithMessage:(NSString *)message`¶

Call this method during the upload of the document to update the hub with a custom message. The message will be presented in the navigation bar therefore use short and concise messages.

`(void)didEndUpload`¶

Call this method after the upload of a document has been finished. It will make the photo capturing UI disappear and return to the screen of your UI from which the image capturing was started. After that, the didFinish: method of your application’s GiniVisionDelegate will be called.

Example¶

The following example is based on the example above and shows how to use the GINIVisionUploadDelegate after a document has been captured and enhanced.

//
// MyViewController.m
//

@implementation MyViewController

// Start image capturing and set delegate as seen above
- (IBAction) scanDocument:(UIButton *)sender {
    [GiniVision captureImageWithViewController:self delegate:self];
}

// MARK: GiniVisionDelegate method
- (void)didScan:(UIImage *)document documentType:(GINIDocumentType)docType uploadDelegate:(id<GINIVisionUploadDelegate>)delegate {

    /* Implement the Gini SDK for iOS or your custom upload to send the scanned and enhanced document to be processed. */

    // Inform the delegate about the progress of the uploading process, so the UI gets updated properly.
    [delegate didProgressWithMessage:@"Analyzing document"];

    // Inform the delegate that the upload ended, the UI is then switched back to your application's UI.
    [delegate didEndUpload];
}

@end

//
// MyViewController.swift
//

class MyViewController: UIViewController, GiniVisionDelegate {

    // Start image capturing and set delegate as seen above
    @IBAction
    func scanDocument(sender: AnyObject) {
        GiniVision.captureImageWithViewController(self, delegate: self)
    }

    // MARK: GiniVisionDelegate method
    func didScan(document: UIImage!, documentType docType: GINIDocumentType, uploadDelegate delegate: GINIVisionUploadDelegate!) {

        /* Implement the Gini SDK for iOS or your custom upload to send the scanned and enhanced document to be processed. */

        // Inform the delegate about the progress of the uploading process, so the UI gets updated properly.
        delegate.didProgressWithMessage("Analyzing document")

        // Inform the delegate that the upload ended, the UI is then switched back to your application's UI.
        delegate.didEndUpload()
    }

}

Next: Customize the UI¶

After you have successfully integrated the Gini Vision Library with the Gini SDK you can customize your UI according to your CI. Learn next how to style the module.

Using the Scanner¶

Start the image capture¶

Implement and use the GiniVisionDelegate¶

didScan:(UIImage *) documentJPEGData:(NSData *) documentType:(GINIDocumentType) uploadDelegate:(id<GINIUploadDelegate>)¶

(void)didScanOriginal:(UIImage *)¶

(void)didFinishCapturing:(BOOL)¶

(void)didCancelUpload¶