Rev. B

© 2017 IDEMIA, All rights reserved | www.idemia.com

Morpho Identix

SDK Guide

Table of contents

Chapter 1: Introduction ........................................................................................................ 3

Document history.............................................................................................................. 3

Chapter 2: Environment & licensing..................................................................................... 4

Development environment ................................................................................................. 4

Obtaining a license for the ESF capability ........................................................................... 4

Chapter 3: Getting started .................................................................................................... 5

Overview .......................................................................................................................... 7

Common Document Model .............................................................................................. 11

Document ...................................................................................................................... 11

Field .............................................................................................................................. 12

Test ............................................................................................................................... 16

Image ............................................................................................................................ 18

Identix Document Authentication API ............................................................................... 19

Document Authentication Controller Events ...................................................................... 20

Access Methods ............................................................................................................. 22

Flow Control Commands ................................................................................................. 23

Identix Document Authentication HOSTED API................................................................. 24

Chapter 1: Introduction

This document describes the Morpho Identix document authentication software development kit

(SDK).

The Morpho Identix SDK is comprised of authentication software and libraries that perform

identification, data extraction and authentication on scanned documents. The SDK supports multiple

hardware platforms. Sample code is included for custom development.

Document history

Date Revision Comments

01/27/2014 00 Initial Draft.

11/26/2014 01 Second Draft

02/09/2015 02 Minor edits to remove references to non-included concepts

02/18/2015 03 Changed part number to Agile PLM part number for release.

04/27/2016 A Rebranded Identix Document Authentication

03/10/2016 B Updates for Identix Document Authentication v.2.3.0, minor typographical

corrections, editorial improvements, and new format.

Chapter 2: Environment & licensing

Development environment

The Morpho Identix SDK has been developed and tested using the following environment:

Microsoft Windows 7 (64-bit) and Windows 10 (64-bit) operating systems

Microsoft Visual Studio

Obtaining a license for the ESF capability

The Morpho Identix SDK itself does not require a license. However, to take advantage of our

proprietary Enhanced Security Feature (ESF), you will need to obtain a license. Please contact your

Sales Representative.

Chapter 3: Getting started

As a first step, follow the Morpho Identix Software Installation Guide. Get the standard Morpho

Identix product running on your development computer with whatever you are using as a source

device (B5000 or DESKO’s PENTA scanner, or sample image files). Be sure that you can start up,

operate, close and restart the Morpho Identix standard application without issue.

Once you have the standard application configured and running on your development machine, copy

the ECAT_Sample directory to a convenient location on your system. Next, set the permissions for all

the files in the directory. The copies you just created are likely to have their permissions set to Read

Only; in the Properties dialog for the containing folder or for the files one at a time, uncheck the box

for Read Only.

In order to be sure that you’re starting development with the same environment that you now have

working, update your copy of the ECAT_Sample. Copy all of the files from:

C:\Program Files (x86)\MorphoTrust USA\Credential Authentication

to your copy of ECAT_Sample, to the \bin subdirectory – replacing the contents.

Using Visual Studio, open the ECAT_Sample.sln, then open your app.config in the editor, as shown

in the figure below.

Next, load your new copy of the standard Morpho Identix configuration, which you know is working,

from your \bin directory, as shown in the following figure:

NOTE: The screen shot is just an example, use the \bin directory under your ECAT_Sample copy.

Copy the sections from Controller through Logging from the

DocAuth.Applications.Authenticate.exe.config file, and paste them into your app.config file,

overwriting the corresponding lines.

Build, debug, and get familiar with the sample app. It should run similarly to how the standard Identix

Document Authentication product runs on your development system. Once you have the standard

and sample applications running on your machine, you should be ready to start developing your own

custom applications.

Overview

The following diagram shows the significant components of your application at run time.

Windows 7 PC

B5000

Process Logging(Text File)

Application

Configuration(XML File)

Identix DocAuthCommon Tests

Test Matrix

Transaction Logging

(SQL Server)

Identix DocAuthC# API

Identix DocAuthTransaction Controller

Identix DocAuth authentication engine(s)

Files

Document Reviewer(WinForm)

Document Class

M500

iA-thenticate(authentication engine)

PENTA

events and

images

Image-based

Authent ication

File

Images

M500

events and

images

B5000

events &

authent ication

results

DESKOPENTA

Identix Document Authentication is configured via its sections within your .NET application’s config file

and with help of the Identix Document Authentication configuration editor UI tool.

The Identix Document Authentication C# code in your application is fairly simple – create a controller

object, optionally handle some events, start it up and run.

The Identix Document Authentication Document class is used as a common model for communicating

information between Identix Document Authentication and the application. Each document object

contains credential information, images, authentication tests and data fields, either from a scan

transaction or loaded from files.

As your application handles Identix Document Authentication scanning events it can access and

process/display information in a Document object which gets populated throughout the scanning

transaction.

Your application can load its own Document object from files or scanner devices and pass it in to

Identix Document Authentication for analysis.

Once your application has an Identix Document Authentication authenticated Document object, this

object can be passed via the Identix Document Authentication API to the standard Identix Document

Authentication Document Reviewer interactive form. This allows the operator to examine the

document’s images, data and authentication tests.

Applications use Identix Document Authentication in two basic modes, scanning or analysis,

described in the following sections.

Scanning Mode – Application driven by Identix Document Authentication

hardware or software events

Identix Document Authentication’s C# API enables applications to get normalized data and

authentication results from supported document capture devices.

Windows PC

B5000

Standard

Identix DocAuth UITransactionRepository

(SQL Server)

Identix DocAuthC# API

Identix DocAuth Core(dedicated per application)

FilesM500

Identix DocAuthReporting

DESKOPENTA

Local or hosted Identix DocAuth transaction repository and web

reporting portal

Custom UI

or interface

Operators

Identix Document Authentication is event driven and notifies the application whenever changes occur

during the document capture cycle. A document object contains information about the scan, which

includes document data, test results and images.

A document authenticated event is fired when document authentication is complete and

visible image(s) are available. Document results can be displayed at this point.

A document completed event is fired when all images are available.

Flow control events indicate when user action is required (e.g. scan a barcode). Flow control

commands allow the application to direct Identix Document Authentication actions (e.g. skip

barcode capture).

Identix Document Authentication is device independent. All events and data are normalized

by Identix Document Authentication to the extent that they are supported by the device.

Authentication tests include those performed by the capture device as well as common tests

performed by Identix Document Authentication (e.g. age, expiration, watermark, etc).

Analysis Mode – Application drives Identix Document Authentication to

analyze image data

Identix Document Authentication’s C# API can be used in an active non-hardware, non-event driven

mode via the Analyze method call. The application can create a document object, populate it with one

or more credential images and pass it to the E_CAT API for analysis. The document object is returned

populated with document information, test records and data fields obtained by analyzing and

authenticating the provided images.

Identix Document Authentication’s Analyze API is available as a hosted web service. The Document

object is serializable and is used to communicate with services in the Identix Document Authentication

enterprise architecture.

Other Platforms

Windows PC

TransactionRepository

(SQL Server)

Identix DocAuthC# API

Files, Images,

Cameras,

...

Identix DocAuthReporting

Local or hosted Identix DocAuth transaction repository and web

reporting portal

Custom UI or interface

Operators

Identix DocAuth Core

Local or hosted Identix DocAuth provides image analysis and

authentication

Common Document Model

A compound class that contains:

Document attributes such as name, address, date of birth, issuer, expiration date, etc.

All images scanned from the credential.

A record for each authentication test performed, providing the test name, pass/fail, and risk

score (if available from the Identix Document Authentication platform).

All Identix Document Authentication components interact based on this common model for an

authenticated document. These elements are easily passed to UI controls, simplifying UI

development.

Document

Type Property Name Default Comment

Document information (prioritized – DWM, 2DBC, MS, MRZ):

Guid GUID Guid.Empty A unique ID assigned to the document transaction by Identix Document

Authentication

bool IsCancelled false Whether or not the document transaction was cancelled during processing

bool IsClassified false Whether or not the document was classified

string DocumentNumber A document number from the credential

DocumentStatus Status DocumentStatus.Unknown Pass or Fail authentication

string Name String.Empty; A name of the credential type

string Description string.Empty Description of the credential

DocumentType DocType DocumentType.Unknown document type

string DocTypeCode "" A doc type code

string CountryCode String.Empty Issuer Country code

string Country String.Empty Issuer Country

DateTime DocDate DateTime.MinValue Issue Date

string Issuer String.Empty Issuer

string IssuerCode String.Empty Issuer Code

string Issue String.Empty Document issue

string Series String.Empty Series

Type Property Name Default Comment

Nullable<DateTime> Expiration null Expiration date

Personal information (prioritized – DWM, 2DBC, MS, MRZ)

string FullName String.Empty Full name

string SurName String.Empty Sur Name

string GivenName String.Empty Given Name

string Sex String.Empty Sex/gender

string BirthDate String.Empty Date of birth

string Age String.Empty Age

string Address String.Empty Address

string City String.Empty City

string State String.Empty State

string PostalCode String.Empty Postal Code

string Weight String.Empty Weight

string Height String.Empty Height

string EyeColor String.Empty Eye Color

string HairColor String.Empty Hair Color

string PhoneNumber String.Empty Phone Number

Field information

DocumentFieldCollection Fields new DocumentFieldCollection() List of data field objects

List<FieldSource> DataSources new List<FieldSource>() List of field data sources

Test information

DocumentTestCollection Tests new DocumentTestCollection() List of authentication tests performed

DwmTestResults DWMTestResults Watermark test result object

DocBarcodeData BarcodeData Bar Code data object

DocMagstripeData MagstripeData Mag stripe data object

Image information

DocumentImageCollection Images new DocumentImageCollection() List of Images

Field

Type Name Default

string Name string.Empty

DocumentFieldType FieldType DocumentFieldType.Unknown

Type Name Default

public enum DocumentFieldType

{

// Examiner Document

CaptureNumber,

CaptureDate,

CaptureTime,

SystemName,

Operator,

HasReverse,

CountryCode,

Country,

Category,

DocType,

Series,

DocNumber,

DocStatus,

ExpirationDate,

IssueDate,

Nationality,

ImageSetDirectory,

ImageSetRootName,

ImageList,

ImageBoundaryROItop,

ImageBoundaryROIleft,

ImageBoundaryROIwidth,

ImageBoundaryROIheight,

PhotoBoundaryROItop,

PhotoBoundaryROIleft,

PhotoBoundaryROIwidth,

PhotoBoundaryROIheight,

PhotoRotation,

CreditCard,

Profile,

ClassificationStatus,

ClassificationDescription,

//Examiner Personal

LastName,

FirstName,

Sex,

BirthPlace,

Birthdate,

Age,

Type Name Default

Address,

City,

State,

PostalCode,

Height,

Weight,

HairColor,

EyeColor,

PhoneNumber,

SSN,

FlightNumber,

PassengerNumber,

UserField1,

UserField2,

UserField3,

// Examiner-Barcode/Magstripe

MiddleName,

StateCode,

PhotoFile,

// Examiner MRZ

MRZ1,

MRZ2,

MRZ3,

// SmartCard

Issuer,

OptionalData,

FingerprintFile,

FullName,

// OCR

DOE, //exp for Visa's

Unknown

}

FieldSource

public enum FieldSource

{

Document,

Personal,

FieldSource FieldSource.Unknown;

Type Name Default

MRZ,

Barcode1D,

Barcode2D,

MagStripe,

SmartCard,

OCR,

Viz,

Unknown

}

Test

Type Name Default

string Name string.Empty

string Desc String.Empty

string Actions String.Empty

DocumentTestType

public enum DocumentTestType

{

Classification,

BarcodeValid,

MagstripeValid,

Birthdate,

OverlayPattern,

IrPattern,

VisiblePattern,

UvPattern,

IrBrightness,

VisibleBrightness,

UvBrightness,

Expiration,

Portrait,

DWM,

UnderAge,

DLAlert1D,

DLAlert2D,

Identification,

DLAlertMS,

XCheck2D,

XCheckMagstripe,

XCheck2DMagstripe,

XCheck2D1D,

XCheck,

B900Ink,

SCardXCheck,

Misc,

SealPattern,

Custom,

WatermarkXCheck,

Watermark,

Checksum,

Smartcard,

Tamper,

DLParser2D,

TestType DocumentTestType.Unknown

Type Name Default

DLParserMSR,

DocXCheck,

MRZQuality,

LegalAge,

NDLVIS,

OCRBFont,

OCRXCheck,

ReverseSide,

VizMatch,

Unknown

}

TestResult

public enum TestResult

{

Failed = 0,

Caution = 1,

Attention = 2,

Indeterminate = 3,

Overridden = 4,

Unknown = 5,

Passed = 6,

Ignore = 7

}

Result TestResult.Unknown

object Value Null

Type ValueType typeof(object)

float RiskFactor 0

DocumentSide

public enum DocumentSide

{

Front,

Back,

None,

Unknown

}

Side DocumentSide.Unknown

Image

Type Name Default

DocumentImageType

public enum DocumentImageType

{

Visible,

IR,

UV,

Seal,

Tamper,

Photo,

Unknown

}

ImageType DocumentImageType.Unknown

byte[] Bitmap Null

DocumentSide

public enum DocumentSide

{

Front,

Back,

None,

Unknown

}

DocSide DocumentSide.Unknown

float Rotation 0.0F

DocumentImageSource

public enum DocumentImageSource

{

Document,

Barcode,

Smartcard

}

Source

Identix Document Authentication API

The application connects to and initializes the Identix Document Authentication platform, which in turn

initializes all devices. This includes the following steps:

Create a Identix Document Authentication controller object

Create Identix Document Authentication event handlers

Start Identix Document Authentication platform

// DADC (Document Authentication Device Controller) Interface

private DocAuth.Controller.Controller m_DADC;

// Initialize the DADC platform

try

{

m_DADC = new DocAuth.Controller.Controller();

m_DADC.PlatformError += new

DocAuth.Controller.Events.PlatformErrorEventHandler(m_DADC_PlatformError);

m_DADC.PlatformStatusChanged += new

DocAuth.Controller.Events.PlatformStatusEventHandler(m_DADC_PlatformStatusChang

ed);

m_DADC.DocumentScanRequest += new

DocAuth.Controller.Events.DocumentScanRequestEventHandler(m_DADC_DocumentScanRe

quest);

m_DADC.DocumentStatusChanged += new

DocAuth.Controller.Events.DocumentStatusEventHandler(m_DADC_DocumentStatusChang

ed);

m_DADC.DocumentEvent += new

DocAuth.Controller.Events.DocumentEventHandler(m_DADC_DocumentEvent);

m_DADC.ImageEvent += new

DocAuth.Controller.Events.ImageEventHandler(m_DADC_ImageEvent);

m_DADC.DeviceStatusChanged += new

DocAuth.Controller.Events.DeviceStatusEventHandler(m_DADC_DeviceStatusChanged);

m_DADC.BarcodeEvent += new

Controller.Events.BarcodeEventHandler(m_DADC_BarcodeEvent);

m_DADC.MagstripeEvent += new

Controller.Events.MagstripEventHandler(m_DADC_MagstripeEvent);

if (!m_DADC.Startup())

{

string sErr = m_DADC.Messages[0] != null ? m_DADC.Messages[0] :

"Error initializing the platform";

Logger.Error(mCaption, sErr);

Message(sErr, true);

this.Close();

return;

}

Logger.Information(mCaption, "DADC Initialized");

}

catch (Exception ex)

{

string sErr = "Error initializing the platform.";

Logger.Error(mCaption, sErr);

Message(sErr, true);

return;

}

Document Authentication Controller Events

Identix Document Authentication events notify the application of changes in the Identix Document

Authentication platform, a device or a document. In all of the events described below, the first data

field is “string m_Device”. This is the DAP (Document Authentication Platform) name where the event

came through. Current possibilities are B5000, PENTA, or ANALYZE.

Event Data Comment

Public delegate void

PlatformStatusEventHandler(PlatformStat

usEventArgs e);

string m_Device;

PlatformStatus m_OldStatus;

PlatformStatus m_NewStatus;

public enum PlatformStatus

{

Ready,

Starting,

Stopped,

Stopping,

Busy,

Error,

Unknown

}

The platform status

event fires when

there is a change of

status of a device.

public delegate void PlatformErrorEventHandler(PlatformErrorEventArgs e);

string m_Device;

Exception m_Error;

bool m_PlatformTerminated

The platform error

event fires when a

device error occurs.

public delegate void DeviceStatusEventHandler(DeviceStatusEventArgs e);

string m_Device;

DeviceStatus m_Status;

public enum DeviceStatus

{

Online,

Offline

}

The device status

event fires when a

device goes online or

offline.

public delegate void DocumentStatusEventHandler(DocumentStatusEventArgs e);

string m_Device;

DocumentFlowStatus m_Status;

FlowNextStep m_Next;

public enum DocumentFlowStatus

The document status

event fires when the

status of the

document being

Event Data Comment

{

DocumentInserted,

BarcodeMissing,

BcOrMsScanFailed,

BcOrMsInvalid,

FrontScanned,

PrematureDocumentRemoval,

DocumentCanBeRemoved,

DocumentRemoved,

DocumentAuthenticated,

DocumentComplete,

SelectJurisdiction,

DocumentCancelled,

IdParseFailed,

Unknown

}

captured has

changed.

When the

DocumentAuthenticat

ed or the

DocumentComplete

status is reported, the

application can

reference the

Document object

through the Identix

Document

Authentication SDK.

public delegate void DocumentScanRequestEventHandler(DocumentScanRequestEventArgs e);

string m_Device;

DocumentScanSide m_ScanSide;

public enum DocumentScanSide

{

Front,

Barcode,

Magstripe

}

The document scan

request event fires

when user action is

required and the

operator must be

notified.

public delegate void ImageEventHandler(ImageEventArgs e);

string m_Device;

DocumentImage m_Image;

DocumentImageType m_ImageType = DocumentImageType.Unknown;

byte[] m_Bitmap = null;

DocumentSide m_DocSide = DocumentSide.Unknown;

float m_Rotation = 0.0F;

DocumentImageSource m_Source;

The image event fires

when each image

becomes available.

Access Methods

Access methods to Identix Document Authentication data.

Command Comment

Document Document() The current Document object reference. This contains data, images

and tests related to the current transaction. The application can

reference this as soon as a DocumentAuthenticated status event is

posted by Identix Document Authentication.

List<DocServer> Platforms() The list of Document Authentication Platforms (DAP) that are

configured in the current Identix Document Authentication

installation.

SetPlatform(string platform) The application can set the active platform within Identix Document

Authentication to a particular DAP, typically for use with a

subsequent call to Analyze.

Analyze()

After setting up some image data within the current Identix Document

Authentication Document object and optionally setting the DAP

platform, the application can call the Analyze method. This will

initiate the DAP to perform authentication on the images within the

Document object. The call to Analyze returns asynchronously to the

application. The DocumentAuthenticated and DocumentComplete

events are generated back to the application as analysis completes

by the DAP. The application can then show the reviewer and/or post

process the Identix Document Authentication results. Not all DAPs

support this method.

ShowReview() After a DocumentComplete event has been generated by Identix

Document Authentication, the application can call ShowReview().

This will launch a Windows form allowing the user to review the

current transaction. Images can be examined. Information about

each test is shown. The detailed data fields are shown in a table.

Flow Control Commands

Flow control commands allow the application to direct Identix Document Authentication actions (e.g.

skip barcode capture).

Command Comment

CancelDocument() The currently active DAP is sent a cancel command.

AbortTransaction() The currently active DAP is sent an Abort Transaction command.

ClearResults() All Document results are cleared for a new transaction.

SkipScan() The active DAP is commanded to skip a scan, if it has requested action.

SkipReverse() The active DAP is commanded to skip a reverse side test, if it has requested

action.

DisableCapture() The DAPs are commanded to disable capture capability.

EnableCapture() The DAPs are commanded to enable capture capability.

Sample Processing Flow

Document StatusChanged event:

Case:

DocumentInserted Display “authenticating”

DocumentCanBeRemoved Display “document can be removed”

DocumentRemoved Display “processing”

SelectJurisdiction TBD

DocumentAuthenticated Authentication complete (document result, test results and visible

image(s) are available). Display document results.

DocumentComplete All images and data are available. Display document detail.

DocumentScanRequest event:

Front Prompt for front

Barcode Prompt for barcode (or send skip)

Magstripe Prompt for magstripe (or send skip)

Identix Document Authentication HOSTED API

private void PerformAnalysis() { // Analyze ... try { try { AnalyzeServiceReference.AnalyzeServiceClient iAnalyze = new AnalyzeServiceReference.AnalyzeServiceClient(); AnalyzeServiceReference.AnalyzeDocumentResponse iAnalyzeResponse = iAnalyze.AnalyzeDocument(mAnalyzeDocument); mDocument = iAnalyzeResponse.analyzedDocument; Logger.Information(mCaption, "Analyze Service status: [" + iAnalyzeResponse.status.ToString() + "] message: [" + iAnalyzeResponse.message + "] processing: [" + iAnalyzeResponse.processingTime.ToString() + "]"); } catch (Exception ex) { Logger.Error(mCaption, "ANALYZE THREAD: " + ex.Message); } if (mDocument != null) { // Merge back in the images foreach (DocumentImage docImage in mAnalyzeDocument.Images) { DocumentImage newImage = new DocumentImage(docImage); mDocument.Images.Add(newImage); } mAnalyzeDocument = null; // Complete TransactionAuthenticated(); CompleteTransaction(); } else { Reset(); } } catch (Exception ex) { Logger.Error(mCaption, ex.Message); } }