Morpho Identix

SDK Guide

Rev. B
© 2017 IDEMIA, All rights reserved | www.idemia.com
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 y our own
custom applications.

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

Windows 7 PC
Application

Document Identix DocAuth Document

Class Reviewer
C# API (WinForm)

Configuration
(XML File)
Identix DocAuth Transaction
Logging
Process Logging Transaction Controller (SQL Server)
(Text File)

Identix DocAuth
Common Tests Identix DocAuth authentication engine(s)
Test Matrix

B5000
events &
authentication
Image-based results
Authent ication
PENTA M500
File
events and event s and
Images
images images
iA-thenticate
(authentication engine)

DESKO M500 Files

B5000
PENTA

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.

Operators

Windows PC

Standard Custom UI Transaction

Identix DocAuth UI or interface Repository
(SQL Server)

Identix DocAuth Identix DocAuth

C# API Reporting

Local or hosted Identix DocAuth

Identix DocAuth Core transaction repository and web
reporting portal
(dedicated per application)

DESKO M500 Files

B5000
PENTA

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.

Operators

Windows PC

Custom UI or interface Local or hosted Identix DocAuth

provides image analysis and
authentication
Identix DocAuth
Identix DocAuth Core
C# API

Other Platforms

Transaction
Repository
(SQL Server)
Files,
Images,
Cameras,
Identix DocAuth
... Reporting
Local or hosted Identix DocAuth
transaction repository and web
reporting portal
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 FieldSource FieldSource.Unknown;

public enum FieldSource
{
Document,
Personal,
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 TestType DocumentTestType.Unknown
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,
Type Name Default
DLParserMSR,
DocXCheck,
MRZQuality,
LegalAge,
NDLVIS,
OCRBFont,
OCRXCheck,
ReverseSide,
VizMatch,
Unknown
}
TestResult Result TestResult.Unknown
public enum TestResult
{
Failed = 0,
Caution = 1,
Attention = 2,
Indeterminate = 3,
Overridden = 4,
Unknown = 5,
Passed = 6,
Ignore = 7
}
object Value Null
Type ValueType typeof(object)
float RiskFactor 0
DocumentSide Side DocumentSide.Unknown
public enum DocumentSide
{
Front,
Back,
None,
Unknown
}
Image
Type Name Default

DocumentImageType ImageType DocumentImageType.Unknown

public enum DocumentImageType
{
Visible,
IR,
UV,
Seal,
Tamper,
Photo,
Unknown
}
byte[] Bitmap Null

DocumentSide DocSide DocumentSide.Unknown

public enum DocumentSide
{
Front,
Back,
None,
Unknown
}
float Rotation 0.0F
DocumentImageSource Source
public enum DocumentImageSource
{
Document,
Barcode,
Smartcard
}
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 string m_Device; The platform status

PlatformStatusEventHandler(PlatformStat PlatformStatus m_OldStatus; event fires when
usEventArgs e); PlatformStatus m_NewStatus; there is a change of
public enum PlatformStatus status of a device.

{
Ready,
Starting,
Stopped,
Stopping,
Busy,
Error,
Unknown
}

public delegate void string m_Device; The platform error

PlatformErrorEventHandler(PlatformError Exception m_Error; event fires when a
EventArgs e);
bool m_PlatformTerminated device error occurs.

public delegate void string m_Device; The device status

DeviceStatusEventHandler(DeviceStatusEv DeviceStatus m_Status; event fires when a
entArgs e);
public enum DeviceStatus device goes online or
{ offline.

Online,
Offline
}

public delegate void string m_Device; The document status

DocumentStatusEventHandler(DocumentStat DocumentFlowStatus m_Status; event fires when the
usEventArgs e);
FlowNextStep m_Next; status of the
public enum DocumentFlowStatus document being
Event Data Comment
{ captured has
DocumentInserted, changed.
BarcodeMissing,
BcOrMsScanFailed, When the
BcOrMsInvalid, DocumentAuthenticat
FrontScanned, ed or the
PrematureDocumentRemoval, DocumentComplete
DocumentCanBeRemoved, status is reported, the
application can
DocumentRemoved,
reference the
DocumentAuthenticated,
Document object
DocumentComplete,
through the Identix
SelectJurisdiction, Document
DocumentCancelled, Authentication SDK.
IdParseFailed,
Unknown
}

public delegate void string m_Device; The document scan

DocumentScanRequestEventHandler(Documen DocumentScanSide m_ScanSide; request event fires
tScanRequestEventArgs e);
public enum DocumentScanSide when user action is
{ required and the
operator must be
Front,
notified.
Barcode,
Magstripe
}

public delegate void string m_Device; The image event fires

ImageEventHandler(ImageEventArgs e); DocumentImage m_Image; when each image
DocumentImageType m_ImageType = becomes available.
DocumentImageType.Unknown;
byte[] m_Bitmap = null;
DocumentSide m_DocSide =
DocumentSide.Unknown;
float m_Rotation = 0.0F;
DocumentImageSource m_Source;
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);
}
}