refman.net

FaceVACS-SDK .NET Reference ManualVersion 8.1.0

Copyright by Cognitec GmbH

Generated 17 Feb 2010

Contents

1 Face Recognition SDK Overview 1

2 FaceVACS-SDK .NET Manual 3

3 User guide - .NET user guide 5

4 User Guide - Creating Applications with FaceVACS-SDK .NET 7

4.1 Build Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.2 Run-Time Environment for FaceVACS-SDK .NET Applications . . . 8

4.3 Redistribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.4 Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.5 Differences to the C++ SDK . . . . . . . . . . . . . . . . . . . . . . 10

5 Tutorial - Overview 11

6 .Net Tutorial - Finding faces 13

7 Tutorial - Locating eyes and Analyze 17

8 Tutorial - Making set enrollments 23

9 Namespace Index 27

9.1 Package List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

10 Class Index 29

10.1 Class Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

11 Class Index 31

11.1 Class List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

ii CONTENTS

12 Namespace Documentation 33

12.1 Package Cognitec.FRsdk . . . . . . . . . . . . . . . . . . . . . . . . 33

12.2 Package Cognitec.FRsdk.Enrollment . . . . . . . . . . . . . . . . . . 37

12.3 Package Cognitec.FRsdk.Eyes . . . . . . . . . . . . . . . . . . . . . 38

12.4 Package Cognitec.FRsdk.Face . . . . . . . . . . . . . . . . . . . . . 39

12.5 Package Cognitec.FRsdk.Identification . . . . . . . . . . . . . . . . . 40

12.6 Package Cognitec.FRsdk.ImageIO . . . . . . . . . . . . . . . . . . . 41

12.7 Package Cognitec.FRsdk.ISO 19794 5 . . . . . . . . . . . . . . . . . 42

12.8 Package Cognitec.FRsdk.ISO 19794 5.FullFrontal . . . . . . . . . . 43

12.9 Package Cognitec.FRsdk.ISO 19794 5.TokenFace . . . . . . . . . . 44

12.10Package Cognitec.FRsdk.Portrait . . . . . . . . . . . . . . . . . . . . 45

12.11Package Cognitec.FRsdk.Portrait.Feature . . . . . . . . . . . . . . . 46

12.12Package Cognitec.FRsdk.Verification . . . . . . . . . . . . . . . . . 47

13 Class Documentation 49

13.1 Analyzer Class Reference . . . . . . . . . . . . . . . . . . . . . . . . 49

13.2 AnnotatedImage Struct Reference . . . . . . . . . . . . . . . . . . . 50

13.3 Bmp Struct Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 51

13.4 CaptureDevice Interface Reference . . . . . . . . . . . . . . . . . . . 53

13.5 Characteristics Class Reference . . . . . . . . . . . . . . . . . . . . . 54

13.6 Compliance Class Reference . . . . . . . . . . . . . . . . . . . . . . 62

13.7 Configuration Class Reference . . . . . . . . . . . . . . . . . . . . . 68

13.8 Configuration.ProtectedItem Struct Reference . . . . . . . . . . . . . 70

13.9 Creator Class Reference . . . . . . . . . . . . . . . . . . . . . . . . 71

13.10Exception Struct Reference . . . . . . . . . . . . . . . . . . . . . . . 72

13.11FacialMatchingEngine Class Reference . . . . . . . . . . . . . . . . 73

13.12FeatureDisabled Struct Reference . . . . . . . . . . . . . . . . . . . 75

13.13Feedback Interface Reference . . . . . . . . . . . . . . . . . . . . . . 76



13.16Finder Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . 84

13.17Finder Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . 86

13.18FIR Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 87

13.19FIRBuilder Class Reference . . . . . . . . . . . . . . . . . . . . . . 89

Copyright c 2009 by Cognitec Systems GmbH

CONTENTS iii

13.20Image Interface Reference . . . . . . . . . . . . . . . . . . . . . . . 91

13.21ImageManipulation Struct Reference . . . . . . . . . . . . . . . . . . 93

13.22ImagePropertiesFeedback Class Reference . . . . . . . . . . . . . . . 94

13.23Jpeg Struct Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 95

13.24Jpeg2000 Struct Reference . . . . . . . . . . . . . . . . . . . . . . . 97

13.25Jpeg.Properties Struct Reference . . . . . . . . . . . . . . . . . . . . 98

13.26LenseDistortionCorrector Class Reference . . . . . . . . . . . . . . . 99

13.27LicenseSignatureMismatch Struct Reference . . . . . . . . . . . . . . 100

13.28LimitExceeded Struct Reference . . . . . . . . . . . . . . . . . . . . 101

13.29Location Struct Reference . . . . . . . . . . . . . . . . . . . . . . . 102

13.30Location Struct Reference . . . . . . . . . . . . . . . . . . . . . . . 104

13.31Match Struct Reference . . . . . . . . . . . . . . . . . . . . . . . . . 106

13.32Pgm Struct Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 107

13.33Png Struct Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 108

13.34Population Class Reference . . . . . . . . . . . . . . . . . . . . . . . 109

13.35Position Struct Reference . . . . . . . . . . . . . . . . . . . . . . . . 110

13.36Processor Class Reference . . . . . . . . . . . . . . . . . . . . . . . 111



13.39Rgb Struct Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 117

13.40Sample Struct Reference . . . . . . . . . . . . . . . . . . . . . . . . 118

13.41SampleEvaluator Class Reference . . . . . . . . . . . . . . . . . . . 120

13.42SampleQuality Struct Reference . . . . . . . . . . . . . . . . . . . . 121

13.43Score Struct Reference . . . . . . . . . . . . . . . . . . . . . . . . . 123

13.44ScoreMappings Class Reference . . . . . . . . . . . . . . . . . . . . 124

13.45Set Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

13.46Shape Struct Reference . . . . . . . . . . . . . . . . . . . . . . . . . 128

13.47ShapeImage Interface Reference . . . . . . . . . . . . . . . . . . . . 129

13.48Test Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 131

13.49Test Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 132

13.50Tracker Class Reference . . . . . . . . . . . . . . . . . . . . . . . . 133

13.51TrackerLocation Struct Reference . . . . . . . . . . . . . . . . . . . 135

13.52WinCaptureDevice Class Reference . . . . . . . . . . . . . . . . . . 136

13.53WinCaptureDevice.VideoFormat Class Reference . . . . . . . . . . . 138


iv CONTENTS

14 Example Documentation 139

14.1 acquisition.cs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

14.2 enroll.cs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

14.3 eyesfind.cs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

14.4 facefind.cs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

14.5 identify.cs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

14.6 tracklife.cs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

14.7 trackrec.cs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

14.8 verify.cs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158


Chapter 1

Face Recognition SDKOverview

2 Face Recognition SDK Overview


Chapter 2

FaceVACS-SDK .NET Manual

This is the documentation for the .NET FaceVACS-SDK.This documentation does onlycover .NET specific issues. For an understanding of how to use the FaceVACS-SDKthe more complete FaceVACS-SDK C++ documentation should be used.

The FaceVACS-SDK Manual consists of the following main parts which are accessibleover the header of each page:

FaceVACS-SDK .NET Userguide describes .NET specific concepts and redistribution,

FaceVACS-SDK .NET Tutorial explains step by step the use cases covered by FaceVACS-SDK.

FaceVACS-SDK .NET Examples However the .NET API Reference and some examples are provided in the

C# programming language.

4 FaceVACS-SDK .NET Manual


Chapter 3

User guide - .NET user guide

6 User guide - .NET user guide

This user guide gives information which are specific for the developing .NET applica-tions.

For an overall introduction to the FaceVACS-SDK please consult the C++Userguide which covers all topics in depth.

The user guide is divided into the following chapter with sections:

Creating Applications with FaceVACS-SDK Build environment Run-Time requirements for FaceVACS-SDK applications Redistribution Exception Handling Differences to the C++ API


Chapter 4

User Guide - CreatingApplications withFaceVACS-SDK .NET

8 User Guide - Creating Applications with FaceVACS-SDK .NET

4.1 Build Environment

For the developing of .NET applications the following parts of the directory tree of theinstalled FaceVACS-SDK distribution are relevant:

- ... the root directory of the FaceVACS-SDK installation||+- examples ... location for the examples| || +- cs ... C# sources, solution and project files| || +- x86_32 ... 32 bit binaries, together with noipp runtime lib|+- lib ... the location of FaceVACS-SDK libraries

| libfrsdk-.{lib|dll} and libfrsdknet-.dll|+- x86_32 ... for 32 bit platforms| || +- msc_7.1_crtdll and Visual C++ 7.1 (Visual C++ .NET 2003, .Net Framework 1.1)| || +- msc_8.0_crtdll and Visual C++ 8.0 (Visual C++ .NET 2005, .Net Framework 2.0)|+- x86_64 ... for 64 bit platforms

|+- msc_8.0_crtdll and Visual C++ 8.0 (Visual C++ .NET 2005, .Net Framework 2.0)

To compile applications referencing the FaceVACS-SDK.NET assembly one have togive the location for e.g.:

cd \examples\cscsc /reference:..\..\lib\x86_32\msc_8.0_crtdll\libfrsdknet-.dll /out:enroll.exe enroll.cs

Additionally one can use the provided solution/project files together with the MicrosoftVisual Studio .NET environment. The bin directory contains the precompiled examplebinaries together with a FaceVACS-SDK runtime lib (noipp). To run the example ap-plication call them simple from the bin directory. If no command line parameters aregiven a short help description explains the usage.

4.2 Run-Time Environment for FaceVACS-SDK .NETApplications

Applications build with an assembly reference have to resolve this reference at run-time. The .NET framework offers two different solutions: either Private Assembly orShared Assembly. Independent which form will be used, the delivered FaceVACS-SDK.NET assembly libfrsdknet-.dll references a FaceVACS-SDK librarybuild for Visual C++ 7.1 and .Net Framework version 1.1 or Visual C++ 8.0 and .NetFramework 2.0. This referenced library has to be available in the search path or in thesame directory where the FaceVACS-SDK.NET assembly was installed. See the C++Userguide for the available types of this library (debug/nodebug/ipp/noipp..).


4.3 Redistribution 9

4.2.1 Private Assembly

An private assembly has to be located in the same directory or an subdirectory of theapplication. You may copy the FaceVACS-SDK.NET assembly in your applicationdirectory to get the reference resolved.

4.2.2 Shared Assembly

To make the assembly globally available they have to be placed into the global assem-bly cache. Example using gacutil:

cd \lib\dotnet\msc_8.0_crtdllgacutil /i libfrsdknet.dll

4.3 Redistribution

For a complete description what to deploy see the Redistribution/Run-Time Environ-ment section of the C++ Userguide.

- ... the root directory of the application| installation+- frsdk.cfg (can reside anywhere, or compiled in)|+- bin| +-| +-| +-|+- etc

+- portrait| +- *.dat|+- cara| +- *.dat|+- cmp| +- *.dat|+- ojo

+- *.dat

Additional the libfrsdknet-.dll assembly has to be copied to the bin loca-tion of the distributed application directory tree. This directory must contain also thedependent runtime libraries.

4.4 Exception Handling

Potentially on all operations on library objects ( creation, member function calls)Cognitec.FRsdk.Exception objects might be thrown. This object is of type Sys-tem.Exception and thus provides the properties Message and StackTrace. The messagestring may give an hint about the reason of the exception.


10 User Guide - Creating Applications with FaceVACS-SDK .NET

If the cause of the exception was related to an licensing issue then an Cog-nitec.FRsdk.LicenseSignatureMismatch exception will be thrown which itselfs is anCognitec.FRsdk.Exception. In case of accessing a disabled FaceVACS-SDK featurea Cognitec.FRsdk.FeatureDisabled exception may be thrown. If some set limit ofFaceVACS-SDK was exceeded a Cognitec.FRsdk.LimitExceeded exception may bethrown.

4.5 Differences to the C++ SDK

Here is a brief listing of the main differences between the .NET and the C++ API.

4.5.1 standard template library types

std.string is mapped to string std.list is mapped to arrys of T[]. std.pair is replaced by struct { T1 t1; T2 t2}; all std.exception C++ exceptions are converted to Cognitec.FRsdk.Exception

.NET exceptions

4.5.2 Refrence counting and Body/Handle idiom

The Reference counting used by the C++ SDK is not necessary in the .NET librarybecause .NET manages the lifetime of its objects themselfs.


Chapter 5

Tutorial - Overview

12 Tutorial - Overview

Currently there is no dedicated tutorial available for .NET.

Due to the fact, that the interfaces are completely similar to the C++ ones just refer tothe C++ tutorial .


Chapter 6

Namespace Index

6.1 Package List

Here are the packages with brief descriptions (if available):

Cognitec.FRsdk (FaceVACS-SDK.NET ) . . . . . . . . . . . . . . . . . . . 33Cognitec.FRsdk.Enrollment (Namespace for the enrollment facility ) . . . . . 37Cognitec.FRsdk.Eyes (The eyes finding facility ) . . . . . . . . . . . . . . . 38Cognitec.FRsdk.Face (The face finding facility ) . . . . . . . . . . . . . . . . 39Cognitec.FRsdk.Identification (Namespace for the identification facility ) . . 40Cognitec.FRsdk.ImageIO (Additinal image properties, Image I/O support ) . . 41Cognitec.FRsdk.ISO 19794 5 (Support for image formats defined by

ISO/IEC 19794-5:2005 ) . . . . . . . . . . . . . . . . . . . . . . . 42Cognitec.FRsdk.ISO 19794 5.FullFrontal (Compliance with ISO 19794 5

Full Frontal Image type ) . . . . . . . . . . . . . . . . . . . . . . . 43Cognitec.FRsdk.ISO 19794 5.TokenFace (Support for Token Face Image

type as defined in ISO 19794 5 9.2 ) . . . . . . . . . . . . . . . . . 44Cognitec.FRsdk.Portrait (Portrait characteristics and feature tests ) . . . . . . 45Cognitec.FRsdk.Portrait.Feature (Test for features in the portrait ) . . . . . . 46Cognitec.FRsdk.Verification (Namespace for the verification facility ) . . . . 47

14 Namespace Index


Chapter 7

Class Index

7.1 Class Hierarchy

This inheritance list is sorted roughly, but not completely, alphabetically:

Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49AnnotatedImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Bmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51CaptureDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

WinCaptureDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Configuration.ProtectedItem . . . . . . . . . . . . . . . . . . . . . . . . . . 70Creator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

FeatureDisabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75LicenseSignatureMismatch . . . . . . . . . . . . . . . . . . . . . . . . . 100LimitExceeded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

FacialMatchingEngine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86FIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87FIRBuilder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91ImageManipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93ImagePropertiesFeedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Jpeg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Jpeg2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Jpeg.Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98LenseDistortionCorrector . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

16 Class Index

Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Pgm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Png . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Population . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Rgb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118SampleEvaluator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120SampleQuality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Score . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123ScoreMappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128ShapeImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Tracker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133TrackerLocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135WinCaptureDevice.VideoFormat . . . . . . . . . . . . . . . . . . . . . . . . 138


Chapter 8

Class Index

8.1 Class List

Here are the classes, structs, unions and interfaces with brief descriptions:

Analyzer (Portrait Characteristics Analyzer, create Portrait characteristicsfrom annotated images ) . . . . . . . . . . . . . . . . . . . . . . . 49

AnnotatedImage (Annotated image ) . . . . . . . . . . . . . . . . . . . . . . 50Bmp (Bitmap (BMP) image implementation ) . . . . . . . . . . . . . . . . . 51CaptureDevice (Abstract image capturing device ) . . . . . . . . . . . . . . . 53Characteristics (Portrait Characteristics ) . . . . . . . . . . . . . . . . . . . . 54Compliance (Compliance assessment results ) . . . . . . . . . . . . . . . . . 62Configuration (Opaque configuration object of the FaceVACS SDK library ) . 68Configuration.ProtectedItem (Key value pair of a protected key ) . . . . . . . 70Creator (Extract a Full Frontal Image from the source image ) . . . . . . . . . 71Exception (An object of this type is thrown if exceptions in the library occure ) 72FacialMatchingEngine (Low level match facilities ) . . . . . . . . . . . . . . 73FeatureDisabled (An object of this type is thrown at any time if requesting or

accessing a disabled FaceVACS-SDK feature ) . . . . . . . . . . . . 75Feedback (The feedback from the verification process ) . . . . . . . . . . . . 76Feedback (The feedback for the identification process ) . . . . . . . . . . . . 79Feedback (The feedback for the enrollment procedure ) . . . . . . . . . . . . 81Finder (Face finder ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Finder (Eyes finder ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86FIR (FIR - Facial Identification Record ) . . . . . . . . . . . . . . . . . . . . 87FIRBuilder (Building FIRs from serialized representations Use Enroll-

ment.Processor to build FIRs from primary biometric data (faceimages) ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Image (Abstract image ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91ImageManipulation (Vignetting ) . . . . . . . . . . . . . . . . . . . . . . . . 93ImagePropertiesFeedback (Feedback for getting image properties on image

loading ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Jpeg (JPEG image support ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Jpeg2000 (JPEG 2000 image support ) . . . . . . . . . . . . . . . . . . . . . 97

18 Class Index

Jpeg.Properties (Properties of a JPEG image ) . . . . . . . . . . . . . . . . . 98LenseDistortionCorrector (Lens distorsion correction ) . . . . . . . . . . . . 99LicenseSignatureMismatch (License signature mismatch ) . . . . . . . . . . 100LimitExceeded (An object of this type is thrown at any time if a configured

limit of FaceVACS-SDK is exceeded ) . . . . . . . . . . . . . . . . 101Location (The Face.Location describes a image location where a face was

found ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Location (The Eyes.Location describes a location in the image where eyes

within a face have been found ) . . . . . . . . . . . . . . . . . . . . 104Match (Named score for a match of two FIRs ) . . . . . . . . . . . . . . . . 106Pgm (PGM/PPM image format support ) . . . . . . . . . . . . . . . . . . . . 107Png (PNG (Portable Network Graphics) image format support ) . . . . . . . . 108Population (An ordered (in the order of additions by add() ) set of named

FIRs which represents the population used for identifications ) . . . 109Position (Continuous two-dimensional coordinates ) . . . . . . . . . . . . . . 110Processor (This class represents the interface to the enrollment process ) . . . 111Processor (This class represents the interface to the verification process ) . . . 113Processor (This class represents the interface to the identification process ) . . 115Rgb (Rgb color model ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Sample (Sample A compound input data type containing an image and, op-

tionally, eyes annotation and/or shape data ) . . . . . . . . . . . . . 118SampleEvaluator (Evaluate the quality of a sample (image) ) . . . . . . . . . 120SampleQuality (A description of the biometric quality of a sample (image) ) . 121Score (This class represents a score for representing the comparison result

between a FIR and the biometric evidence ) . . . . . . . . . . . . . 123ScoreMappings (FAR - FRR Score mappings ) . . . . . . . . . . . . . . . . . 124Set (Feature assessment results ) . . . . . . . . . . . . . . . . . . . . . . . . 126Shape (Shape Image I/O support ) . . . . . . . . . . . . . . . . . . . . . . . 128ShapeImage (Abstract image ) . . . . . . . . . . . . . . . . . . . . . . . . . 129Test (Test for features in a portrait ) . . . . . . . . . . . . . . . . . . . . . . . 131Test (Compliance assessment ) . . . . . . . . . . . . . . . . . . . . . . . . . 132Tracker (The Face Tracker locates and tracks faces across a sequence of im-

ages in an efficient way by analyzing the spatial and temporal de-pendencies between faces in subsequent images ) . . . . . . . . . . 133

TrackerLocation (The location of a face being tracked by the face tracker ) . . 135WinCaptureDevice (Win32 DirectShow video capture device ) . . . . . . . . 136WinCaptureDevice.VideoFormat (Opaque type representing a video format

(resolution, bits per pixel, etc) ) . . . . . . . . . . . . . . . . . . . . 138


Chapter 9

Namespace Documentation

9.1 Package Cognitec.FRsdk

FaceVACS-SDK.NET.

Classes

struct ExceptionAn object of this type is thrown if exceptions in the library occure.

struct LicenseSignatureMismatchLicense signature mismatch.

struct FeatureDisabledAn object of this type is thrown at any time if requesting or accessing a disabledFaceVACS-SDK feature.

struct LimitExceededAn object of this type is thrown at any time if a configured limit of FaceVACS-SDK isexceeded.

class ConfigurationOpaque configuration object of the FaceVACS SDK library.

struct Rgbrgb color model

struct Positioncontinuous two-dimensional coordinates

interface Image

20 Namespace Documentation

Abstract image.

interface ShapeImageAbstract image.

struct JpegJPEG image support.

struct Jpeg2000JPEG 2000 image support.

struct PgmPGM/PPM image format support.

struct PngPNG (Portable Network Graphics) image format support.

struct BmpBitmap (BMP) image implementation.

struct ShapeShape Image I/O support.

struct ImageManipulationVignetting.

class LenseDistortionCorrectorLens distorsion correction.

interface CaptureDeviceAbstract image capturing device.

class WinCaptureDeviceWin32 DirectShow video capture device.

struct AnnotatedImageannotated image

struct SampleSample A compound input data type containing an image and, optionally, eyes anno-tation and/or shape data.

struct ScoreThis class represents a score for representing the comparison result between a FIRand the biometric evidence.

class ScoreMappings


9.1 Package Cognitec.FRsdk 21

FAR - FRR Score mappings.

struct SampleQualityA description of the biometric quality of a sample (image).

class SampleEvaluatorEvaluate the quality of a sample (image).

class FIRFIR - Facial Identification Record.

class FIRBuilderBuilding FIRs from serialized representations Use Enrollment.Processor to buildFIRs from primary biometric data (face images).

class PopulationAn ordered (in the order of additions by add() ) set of named FIRs which representsthe population used for identifications.

struct Matcha named score for a match of two FIRs

class FacialMatchingEngineLow level match facilities.

Packages

package ImageIOadditinal image properties, Image I/O support

package FaceThe face finding facility.

package EyesThe eyes finding facility.

package PortraitPortrait characteristics and feature tests.

package ISO 19794 5Support for image formats defined by ISO/IEC 19794-5:2005.

package Enrollmentthe namespace for the enrollment facility



package Verificationthe namespace for the verification facility

package Identificationthe namespace for the identification facility

9.1.1 Detailed Description

FaceVACS-SDK.NET.

Namespace for the .NET FaceVACS-SDK.


9.2 Package Cognitec.FRsdk.Enrollment 23

9.2 Package Cognitec.FRsdk.Enrollment

the namespace for the enrollment facility

Classes

interface FeedbackThe feedback for the enrollment procedure.

class Processorthis class represents the interface to the enrollment process


the namespace for the enrollment facility

Enrollment is the use case of constructing a FIR from a number of images of a humanface. One or more samples (face images) of the same person are captured and processedinto a FIR. The results of the enrollment are returned by a callback mechanism via theFeedback object.

The constraint to use images of one and the same person only is essentially. Due to thelimited capacity of a FIR and the properties of the clustering algorithm used, poorbiometric performance may be the result if combining images or merging FIRs fromdifferent persons is attempted.



9.3 Package Cognitec.FRsdk.Eyes

The eyes finding facility.

Classes

struct LocationThe Eyes.Location describes a location in the image where eyes within a face havebeen found.

class Findereyes finder


The eyes finding facility.


9.4 Package Cognitec.FRsdk.Face 25

9.4 Package Cognitec.FRsdk.Face

The face finding facility.

Classes

struct LocationThe Face.Location describes a image location where a face was found.

class Finderface finder

struct TrackerLocationThe location of a face being tracked by the face tracker.

class TrackerThe Face Tracker locates and tracks faces across a sequence of images in an efficientway by analyzing the spatial and temporal dependencies between faces in subsequentimages.


The face finding facility.



9.5 Package Cognitec.FRsdk.Identification

the namespace for the identification facility

Classes

interface FeedbackThe feedback for the identification process.

class Processorthis class represents the interface to the identification process


the namespace for the identification facility

Identification is the use case of identification of human faces. One or more samples(face images) are captured and processed into a FIR and matched against a set of FIRs.The result of the identification is a match set containing the matches ordered by score.This set is returned by callback mechanism using the Feedback object.


9.6 Package Cognitec.FRsdk.ImageIO 27

9.6 Package Cognitec.FRsdk.ImageIO

additinal image properties, Image I/O support

Classes

class ImagePropertiesFeedbackfeedback for getting image properties on image loading

Enumerations

enum ImageColorModeimage color modes


additinal image properties, Image I/O support

9.6.2 Enumeration Type Documentation

9.6.2.1 enum ImageColorMode

image color modes



9.7 Package Cognitec.FRsdk.ISO 19794 5

Support for image formats defined by ISO/IEC 19794-5:2005.

Packages

package FullFrontalCompliance with ISO 19794 5 Full Frontal Image type.

package TokenFaceSupport for Token Face Image type as defined in ISO 19794 5 9.2.


Support for image formats defined by ISO/IEC 19794-5:2005.

This namespace provides support for the face image formats defined by ISO/IEC19794-5:2005, Biometric Data Interchange Formats - Part 5: Face Image Data. Inthe documentation of the namespace members the term ISO 19794 5 refers to thestandard document ISO/IEC 19794-5:2005 final draft.

Use ISO 19794 5.FullFrontal.Test to determine compliance of a portrait with the ISO -19794 5 requirements for Full Frontal Images.

Use ISO 19794 5.TokenFace.Creator.extract or ISO 19794 -5.TokenFace.Creator.extractMinimal to produce images meeting the requirements ofthe ISO 19794 5 TokenFace Image type.

Use ISO 19794 5.TokenFace.IO.read and ISO 19794 5.TokenFace.IO.write for read-ing and writing Token Face Images from and to files.


9.8 Package Cognitec.FRsdk.ISO 19794 5.FullFrontal 29

9.8 Package Cognitec.FRsdk.ISO 19794 5.FullFrontal

Compliance with ISO 19794 5 Full Frontal Image type.

Classes

class CreatorExtract a Full Frontal Image from the source image.

class ComplianceCompliance assessment results.

class TestCompliance assessment.


Compliance with ISO 19794 5 Full Frontal Image type.

This namespace provides a framework for testing compliance with the ISO 19794 5Full Frontal Image requirements including the Best Practice recommendations for FullFrontal Images.



9.9 Package Cognitec.FRsdk.ISO 19794 5.TokenFace

Support for Token Face Image type as defined in ISO 19794 5 9.2.


Support for Token Face Image type as defined in ISO 19794 5 9.2.

According to ISO 19794 5 the Token Face Image is used to store the extracted faceinformation from any other image source.


9.10 Package Cognitec.FRsdk.Portrait 31

9.10 Package Cognitec.FRsdk.Portrait

Portrait characteristics and feature tests.

Classes

class CharacteristicsPortrait Characteristics.

class AnalyzerPortrait Characteristics Analyzer, create Portrait characteristics from annotated im-ages.

Packages

package FeatureTest for features in the portrait.


Portrait characteristics and feature tests.

This namespace provides support for measuring various face portrait characteristicsand testing for certain features in the portrait.

Use Portrait.Analyzer to produce Portrait.Characteristics of a portrait. The result of theanalysis can be used to determine compliance of a portrait with ISO 19794 5.

Use Portrait.Feature.Test to test for portrait features.



9.11 Package Cognitec.FRsdk.Portrait.Feature

Test for features in the portrait.

Classes

class SetFeature assessment results.

class TestTest for features in a portrait.

Enumerations

enum GenderGender.

enum EthnicityEthnicity.


Test for features in the portrait.

This namespace provides tests for features in a portrait. These features are not requiredby ISO 19794 5, although they might be of interest for other reasons.

9.11.2 Enumeration Type Documentation

9.11.2.1 enum Gender

Gender.

9.11.2.2 enum Ethnicity

Ethnicity.


9.12 Package Cognitec.FRsdk.Verification 33

9.12 Package Cognitec.FRsdk.Verification

the namespace for the verification facility

Classes

interface FeedbackThe feedback from the verification process.

class Processorthis class represents the interface to the verification process


the namespace for the verification facility

Verification is the use case of authenticating human faces. One or more samples (faceimages) are captured, processed into a FIR and then matched against an input (refer-ence) FIR. The results of the verification are returned via the Feedback object.


Chapter 10

Class Documentation

10.1 Analyzer Class Reference

Portrait Characteristics Analyzer, create Portrait characteristics from annotated images.

Public Member Functions

Characteristics analyze (AnnotatedImage a)Create portrait characteristics from the annotated image a.


Portrait Characteristics Analyzer, create Portrait characteristics from annotated images.

MT-safe It is safe to call the member functions concurrentlyfrom different threads.

10.1.2 Member Function Documentation

10.1.2.1 Characteristics analyze (AnnotatedImage a)

Create portrait characteristics from the annotated image a.

36 Class Documentation

10.2 AnnotatedImage Struct Reference

annotated image


AnnotatedImage (Image image , Eyes.Location annotation )Construct an annotated image from given Image and Eyes.Location.

Public Attributes

Image imagethe image

Eyes.Location annotationthe annotation


annotated image

An image with annotated eye positions

10.2.2 Constructor & Destructor Documentation

10.2.2.1 AnnotatedImage (Image image , Eyes.Location annotation )

Construct an annotated image from given Image and Eyes.Location.

10.2.3 Member Data Documentation

10.2.3.1 Image image

the image

10.2.3.2 Eyes.Location annotation

the annotation


10.3 Bmp Struct Reference 37

10.3 Bmp Struct Reference

Bitmap (BMP) image implementation.

Static Public Member Functions

static Image load (IntPtr bi, IntPtr img, string name)constructs a image representation from the specified bitmap image in memory.

static Image load (string filename)load the Bmp image from file; the image will get the name of the file

static Image load (System.IO.Stream s)load the Bmp image from a stream

static void save (Image i, string filename)saves the image as bmp to filename.

static uint getBitmapInfoSize (Image i)get the total size of bitmap info; returns sizeof( BITMAPINFOHEADER) +sizeof(color map)

static void writeBitmapInfo (Image i, IntPtr info)write bitmap info to buffer; buffer size has to be at least the size returned by get-BitmapInfoSize().


Bitmap (BMP) image implementation.

FaceVACS-SDK supports the following bitmap formats:

loading: 8, 16, 24, 32 bit pixel size, BI BITFIELD and BI RGB compression mode saving: 8 and 24 bit pixel size BI RGB compression mode

MT-safe It is safe to call the functions concurrentlyfrom different threads.




10.3.2.1 static Image load (IntPtr bi, IntPtr img, string name) [static]

constructs a image representation from the specified bitmap image in memory.

The bi pointer points to a BITMAPINFOHEARER followed by an optional color table.The existence of a colortable depends on the image type. The Byte pointer has to pointto bitmap data as described by the bitmap information. During construction of theBmpImage, BITMAPINFO and bitmap data is copied, so they can be safely discardedafterwards without corrupting the BmpImage.

10.3.2.2 static Image load (string filename) [static]

load the Bmp image from file; the image will get the name of the file

10.3.2.3 static Image load (System.IO.Stream s) [static]

load the Bmp image from a stream

10.3.2.4 static void save (Image i, string filename) [static]

saves the image as bmp to filename.

Note that the bitmap format of the file stored can differ from that used upon construc-tion.

10.3.2.5 static uint getBitmapInfoSize (Image i) [static]

get the total size of bitmap info; returns sizeof( BITMAPINFOHEADER) +sizeof(color map)

10.3.2.6 static void writeBitmapInfo (Image i, IntPtr info) [static]

write bitmap info to buffer; buffer size has to be at least the size returned by getBitmap-InfoSize().

Note that the bitmap format stored in info is the format of the FRsdk.Image colorrepresentation that can differ from that used when constructing an image from bitmapdata. To access bitmap data use img.colorRepresentation()


10.4 CaptureDevice Interface Reference 39

10.4 CaptureDevice Interface Reference

Abstract image capturing device.

Inheritance diagram for CaptureDevice::

CaptureDevice

WinCaptureDevice


Image capture ()returns the image to capture


Abstract image capturing device.


10.4.2.1 Image capture ()

returns the image to capture

Implemented in WinCaptureDevice.



10.5 Characteristics Class Reference

Portrait Characteristics.


uint width ()the width of the portrait image

uint height ()the height of the portrait image

Position eye0 ()Coordinate of Feature Point 12.2 (Right eye center).

Position eye1 ()Coordinate of Feature Point 12.1 (Left eye center).

float eyeDistance ()Get the eye distance in pixels.

Position faceCenter ()Coordinate of the center of the line connecting Feature Points 12.1 and 12.2 (Centerof left and right eye) See ISO standard 5.6.4.

uint numberOfFaces ()Try to detect all faces within the given image, ignores given position.

float eye0Open ()Returns the confidence for the persons eye0 beeing open.

float eye1Open ()Returns the confidence for the persons eye1 beeing open.

float eye0GazeFrontal ()Returns the confidence for the persons eye0 looking frontal to the camera.

float eye1GazeFrontal ()Returns the confidence for the persons eye1 looking frontal to the camera.

float eye0Tinted ()Returns a value how tinted the left eye and the environment is.

float eye1Tinted ()Returns a value how tinted the right eye and the environment is.


10.5 Characteristics Class Reference 41

float eye0Red ()Returns the redness of eyes pupils.

float eye1Red ()Returns the redness of eyes pupils.

float glasses ()Returns a measure for the probability of the person in the portrait to wear glasses SeeISO standard A.3.2.4.

float exposure ()Returns average gray value within facial region.

uint grayScaleDensity ()Gray scale density (number of different gray values) within facial region.

float naturalSkinColour ()Returns the natural colours ratio ( 0.0 - 1.0) within face region.

float hotSpots ()Returns the percentage of hot spot pixels ( 0.0 - 1.0) within face region.

float backgroundUniformity ()Background ist not nromativ according to ISO standard section 7.2.6, but accordingto A 2.4.3 the background uniformity is tested by this function.

float widthOfHead ()Horizontal distance between the points where the external ear connects the head inpixels.

float lengthOfHead ()Vertical distance between base of the chin and the crown in pixels.

float chin ()Returns the estimated distance (in pixel) of chin plane from the eyes plan.

float crown ()Returns the estimated distance (in pixel) of crown plane from the eyes plan.

float ear0 ()Returns the estimated distance (in pixel) between the center of the face and the leftbounding plane of the face reagion marked by the coordinate point 10.10 (left ear tohead connection, see ISO standard 5.6.3.

float ear1 ()Returns the estimated distance (in pixel) between the center of the face and the leftbounding plane of the face reagion marked by the coordinate point 10.10 (left ear tohead connection, see ISO standard 5.6.3.



float poseAngleRoll ()Returns the tangent of the Pose Angle - Roll.

float deviationFromFrontalPose ()Returns a measure for the deviation from frontal pose.

float isMale ()Returns a measure for the probability that the image contains a portrait of a maleperson.

float isChild ()Returns a measure for the probability that the image contains a portrait of a child(person in the age of 0 - 7 years).

float isToddler ()Returns a measure for the probability that the image of an child contains a portrait ofan toddler (person in the age of 0 - 4 years).

float isInfant ()Returns a measure for the probability that the image of an toddler contains a portraitof an infant (person in the age of 0 - 1 year).

float isBelow26 ()returns measurement for the probability that the given image is below 26 age

float isBelow36 ()returns measurement for the probability that the given image is below 36 age

float mouthClosed ()Returns a measure how open a mouth is.

float deviationFromUniformLighting ()Returns a measure for the deviation from uniform lighting in the face area.


Portrait Characteristics.

An instance of this class is produced by analyzing a face portrait using Por-trait.Analyzer. It provides various measures important for determining compliancewith ISO 19794 5.




10.5.2.1 uint width ()

the width of the portrait image

10.5.2.2 uint height ()

the height of the portrait image

10.5.2.3 Position eye0 ()

Coordinate of Feature Point 12.2 (Right eye center).

See ISO 19794 5 5.6.4.

10.5.2.4 Position eye1 ()

Coordinate of Feature Point 12.1 (Left eye center).

See ISO 19794 5 5.6.4.

10.5.2.5 float eyeDistance ()

Get the eye distance in pixels.

10.5.2.6 Position faceCenter ()

Coordinate of the center of the line connecting Feature Points 12.1 and 12.2 (Center ofleft and right eye) See ISO standard 5.6.4.

10.5.2.7 uint numberOfFaces ()

Try to detect all faces within the given image, ignores given position.

10.5.2.8 float eye0Open ()

Returns the confidence for the persons eye0 beeing open.

Higher values mean a higer confidence. See ISO standard 7.2.3.

10.5.2.9 float eye1Open ()

Returns the confidence for the persons eye1 beeing open.

Higher values mean a higer confidence. See ISO standard 7.2.3.



10.5.2.10 float eye0GazeFrontal ()

Returns the confidence for the persons eye0 looking frontal to the camera.

The higher the returned value is, the more frontal the gaze is. See ISO standard 7.2.3.

10.5.2.11 float eye1GazeFrontal ()

Returns the confidence for the persons eye1 looking frontal to the camera.

The higher the returned value is, the more frontal the gaze is. See ISO standard 7.2.3.

10.5.2.12 float eye0Tinted ()

Returns a value how tinted the left eye and the environment is.

Higher Value means mor tinted. See ISO standard 7.2.11.

10.5.2.13 float eye1Tinted ()

Returns a value how tinted the right eye and the environment is.

Higher Value means mor tinted. See ISO standard 7.2.11.

10.5.2.14 float eye0Red ()

Returns the redness of eyes pupils.

See ISO standard 7.3.4.

10.5.2.15 float eye1Red ()

Returns the redness of eyes pupils.


10.5.2.16 float glasses ()

Returns a measure for the probability of the person in the portrait to wear glasses SeeISO standard A.3.2.4.

10.5.2.17 float exposure ()

Returns average gray value within facial region.



10.5.2.18 uint grayScaleDensity ()

Gray scale density (number of different gray values) within facial region.

The facial region used is the area enclosed by the 2 semiellipses uniquely defined bycrown(), ear0(), ear1() and chin(), ear0(), ear1(), respectively. See ISO standard 7.4.2.1

10.5.2.19 float naturalSkinColour ()

Returns the natural colours ratio ( 0.0 - 1.0) within face region.

For details refer to ISO standard section 7.3.4.

10.5.2.20 float hotSpots ()

Returns the percentage of hot spot pixels ( 0.0 - 1.0) within face region.

For details refer to ISO standard section 7.2.10 and 7.2.11.

10.5.2.21 float backgroundUniformity ()

Background ist not nromativ according to ISO standard section 7.2.6, but according toA 2.4.3 the background uniformity is tested by this function.

10.5.2.22 float widthOfHead ()

Horizontal distance between the points where the external ear connects the head inpixels.

See ISO 19794 5 8.3.4.

10.5.2.23 float lengthOfHead ()

Vertical distance between base of the chin and the crown in pixels.

See ISO 19794 5 8.3.5.

10.5.2.24 float chin ()

Returns the estimated distance (in pixel) of chin plane from the eyes plan.

Chin is definded as the central forward portion of the lower jaw (see ISO standard 4.1.)In context of face recognition it is a part to determine the face region. So, chin can beseen as a lower limit plane of the face region. The eyes plane is defined by the eyesposition and the chin plane is parallel to the eyes plane.



10.5.2.25 float crown ()

Returns the estimated distance (in pixel) of crown plane from the eyes plan.

Crown is definded as the top head if it could be seen (see ISO standard 4.6.) In contextof face recognition it is a part to determine the face region. So, crown can be seen as aupper limit plane of the face region. The eyes plane is defined by the eyes position andthe crown plane is parallel to the eyes plane.

10.5.2.26 float ear0 ()

Returns the estimated distance (in pixel) between the center of the face and the leftbounding plane of the face reagion marked by the coordinate point 10.10 (left ear tohead connection, see ISO standard 5.6.3.

).

10.5.2.27 float ear1 ()

Returns the estimated distance (in pixel) between the center of the face and the leftbounding plane of the face reagion marked by the coordinate point 10.10 (left ear tohead connection, see ISO standard 5.6.3.

).

10.5.2.28 float poseAngleRoll ()

Returns the tangent of the Pose Angle - Roll.

This is the rotation about the horizontal axis from front to back. See ISO 19794 55.5.8.3 and 7.2.2.

10.5.2.29 float deviationFromFrontalPose ()

Returns a measure for the deviation from frontal pose.

Higher values mean larger deviation from frontal pose. See ISO standard 7.2.2.

10.5.2.30 float isMale ()

Returns a measure for the probability that the image contains a portrait of a male per-son.

10.5.2.31 float isChild ()

Returns a measure for the probability that the image contains a portrait of a child (per-son in the age of 0 - 7 years).



10.5.2.32 float isToddler ()

Returns a measure for the probability that the image of an child contains a portrait ofan toddler (person in the age of 0 - 4 years).

10.5.2.33 float isInfant ()

Returns a measure for the probability that the image of an toddler contains a portrait ofan infant (person in the age of 0 - 1 year).

10.5.2.34 float isBelow26 ()

returns measurement for the probability that the given image is below 26 age

10.5.2.35 float isBelow36 ()

returns measurement for the probability that the given image is below 36 age

10.5.2.36 float mouthClosed ()

Returns a measure how open a mouth is.

10.5.2.37 float deviationFromUniformLighting ()

Returns a measure for the deviation from uniform lighting in the face area.

Higher absolute values mean higher deviation. The implementation returns a valuewithin the range of [-1..1]. Negative values mean an darker left side and a brighterright side, positive values the opposite. See ISO standard 7.2.7



10.6 Compliance Class Reference

Compliance assessment results.


bool onlyOneFaceVisible ()Only one face has to be visible in the image according to ISO 19794 5 7.2.4.

bool goodVerticalFacePosition ()Test the vertical position of the face.

bool horizontallyCenteredFace ()Test whether the face is centered in the image.

bool widthOfHead ()Width of the head compared to image width.

bool widthOfHeadBestPractice ()According to section A 3.2.2 best practice is a range of image width to face widthratio betwee 1.4 and 2.0.

bool lengthOfHead ()Length of head is limited to the range of 60% to 90% of the image height.

bool lengthOfHeadBestPractice ()Best practice reduces the range of face length to 70% to 80% of the image hieght.

bool resolution ()Resolution of the full images shall be at least 18x0 pixels for the width of the head or90 pixels from eye center to eye center (see ISO standard 8.4.1).

bool resolutionBestPractice ()Best Practice recommendation are more strict.

bool imageWidthToHeightBestPractice ()Paragraph A3.2.1 of ISO standard describes a best practice of ratio between imageheight and width.

bool goodGrayScaleProfile ()Grayscale density 7 bit or 128 intensity values.

bool hasNaturalSkinColour ()Natural colours in face region Returns true if the face region has natural colors,otherwise false.


10.6 Compliance Class Reference 49

bool noHotSpots ()Hot Spots (bright areas of light reflected from the face).

bool isBackgroundUniformBestPractice ()background uniformity.

bool goodExposure ()See ISO 19794 5 7.3.2.

bool isFrontal ()The face is considered frontal if the rotation of the head is less than +/-5 degrees fromfrontal for yaw and pitch and if roll angle of head is less then +/-8 degrees.

bool isFrontalBestPractice ()The face is considered frontal if the rotation of the head is less than +/-5 degrees fromfrontal in every direction (roll, pitch and yaw).

bool isLightingUniform ()Returns true if lighting is equally distributed in the face area.

bool eyesOpenBestPractice ()Returns true if the persons eyes are open.

bool eyesGazeFrontalBestPractice ()Returns true if the persons eyes are looking frontal to the camera.

bool eyesNotRedBestPractice ()returns true if both eyes pupils are not detected as red.

bool noTintedGlasses ()according to 7.2.11 and best recommendations glasses should not be tinted.

bool isSharp ()returns true if the face area (from chin to crown and from left to right ear) fits thefocus and depth in field characteristics (see ISO 19794 5 section 7.3.3).

bool mouthClosedBestPractice ()returns true if mouth is closed according to ISO 19794 5 section 7.2.3

bool isCompliant ()Returns true if the images is compliant with the ISO 19794 5 requirements only.

bool isBestPractice ()The test contains is Compliant and additionally all checks according to best practicerepresented by function names of this class with BestPractice in name.




Compliance assessment results.

Instances of this class represent the compliance of portraits with the Full Frontal Imagerequirements. They can be produced using instances of FullFrontal.Test.


10.6.2.1 bool onlyOneFaceVisible ()

Only one face has to be visible in the image according to ISO 19794 5 7.2.4.

10.6.2.2 bool goodVerticalFacePosition ()

Test the vertical position of the face.

0.5 image height < eyes line < 0.7 image height. For children under 11 years: 0.4image height See ISO 19794 5 8.3.3.

10.6.2.3 bool horizontallyCenteredFace ()

Test whether the face is centered in the image.

See ISO 19794 5 8.3.2

10.6.2.4 bool widthOfHead ()

Width of the head compared to image width.

It should be between 50% and 75% of the image width. See ISO 19794 5 8.3.4.

10.6.2.5 bool widthOfHeadBestPractice ()

According to section A 3.2.2 best practice is a range of image width to face width ratiobetwee 1.4 and 2.0.

10.6.2.6 bool lengthOfHead ()

Length of head is limited to the range of 60% to 90% of the image height.

See ISO 19794 5 8.3.5.

10.6.2.7 bool lengthOfHeadBestPractice ()

Best practice reduces the range of face length to 70% to 80% of the image hieght.

See ISO 19794 5 A 3.2.3.



10.6.2.8 bool resolution ()

Resolution of the full images shall be at least 18x0 pixels for the width of the head or90 pixels from eye center to eye center (see ISO standard 8.4.1).

10.6.2.9 bool resolutionBestPractice ()

Best Practice recommendation are more strict.

A face should be 240 pixel in width (roughly 120 Pixel eye to eye distance, see ISOstandard A3.1.1).

10.6.2.10 bool imageWidthToHeightBestPractice ()

Paragraph A3.2.1 of ISO standard describes a best practice of ratio between imageheight and width.

It should be between 1.25 and 1.34.

10.6.2.11 bool goodGrayScaleProfile ()

Grayscale density 7 bit or 128 intensity values.

Color saturation See ISO standard 7.4.2.1 and 7.4.2.2.

10.6.2.12 bool hasNaturalSkinColour ()

Natural colours in face region Returns true if the face region has natural colors, other-wise false.

See ISO 19794 5 standard 7.3.4

10.6.2.13 bool noHotSpots ()

Hot Spots (bright areas of light reflected from the face).

Refer to ISO standard section 7.2.10 and 7.2.11.

10.6.2.14 bool isBackgroundUniformBestPractice ()

background uniformity.

returns true if the background is uniform. See ISO Standard A 2.4.3

10.6.2.15 bool goodExposure ()

See ISO 19794 5 7.3.2.



10.6.2.16 bool isFrontal ()

The face is considered frontal if the rotation of the head is less than +/-5 degrees fromfrontal for yaw and pitch and if roll angle of head is less then +/-8 degrees.

See ISO 19794 5 7.2.2.

10.6.2.17 bool isFrontalBestPractice ()

The face is considered frontal if the rotation of the head is less than +/-5 degrees fromfrontal in every direction (roll, pitch and yaw).

See ISO 19794 5 7.2.2 and A 2.2.

10.6.2.18 bool isLightingUniform ()

Returns true if lighting is equally distributed in the face area.

That means that there is no significant direction of the light from the point of view ofthe photographer. See ISO standard 7.2.7

10.6.2.19 bool eyesOpenBestPractice ()

Returns true if the persons eyes are open.


10.6.2.20 bool eyesGazeFrontalBestPractice ()

Returns true if the persons eyes are looking frontal to the camera.


10.6.2.21 bool eyesNotRedBestPractice ()

returns true if both eyes pupils are not detected as red.

Eyes are checkend independendly and the result is a logical AND of both single checks.See ISO standard 7.3.4.

10.6.2.22 bool noTintedGlasses ()

according to 7.2.11 and best recommendations glasses should not be tinted.

tintedGlasses() returns true if face wears glasses and glasses are tinted.



10.6.2.23 bool isSharp ()

returns true if the face area (from chin to crown and from left to right ear) fits the focusand depth in field characteristics (see ISO 19794 5 section 7.3.3).

10.6.2.24 bool mouthClosedBestPractice ()

returns true if mouth is closed according to ISO 19794 5 section 7.2.3

10.6.2.25 bool isCompliant ()

Returns true if the images is compliant with the ISO 19794 5 requirements only.

If it failes only member function without BestPractice in name must be checked inorder to get the reason why the test failes.

10.6.2.26 bool isBestPractice ()

The test contains is Compliant and additionally all checks according to best practicerepresented by function names of this class with BestPractice in name.

True is return incase of all checks are passed, else false is returned.



10.7 Configuration Class Reference

Opaque configuration object of the FaceVACS SDK library.


Configuration (string s)Construct Configuration object from given configuration file.

Configuration (System.IO.Stream s)Constructor for creating from given stream.

string licenseInformation ()returns a string which contains the license information

string getValue (string key)Configuration item value access, returns the string representation of the configurationitems value, the key has to be a valid configuration item name in dotted notation, e.g.

void setValue (string key, string value)Set configuration item to given value, the key has to be a valid configuration itemname, the value has to the string representation of the items value, e.g.

void resetToDefault (string key)Reset the configuration item to the default value.

ProtectedItem[ ] protectedItems ()returns a list of configuration items (key/value pairs) which are protected by the li-cense key.

Classes

struct ProtectedItemkey value pair of a protected key


Opaque configuration object of the FaceVACS SDK library.


10.7.2.1 Configuration (string s)

Construct Configuration object from given configuration file.


10.7 Configuration Class Reference 55

10.7.2.2 Configuration (System.IO.Stream s)

Constructor for creating from given stream.


10.7.3.1 string licenseInformation ()

returns a string which contains the license information

10.7.3.2 string getValue (string key)

Configuration item value access, returns the string representation of the configurationitems value, the key has to be a valid configuration item name in dotted notation, e.g.

FRSDK.ComparisonAlgorithm

10.7.3.3 void setValue (string key, string value)

Set configuration item to given value, the key has to be a valid configuration item name,the value has to the string representation of the items value, e.g.

B2ComparisonAlgorithm, 0.5 or 42. The changes will become persistent if theConfiguration object was created from a configFilename. Otherwise the changes willapply to the current object only. Note that most classes use the configuration at objectconstruction time only. In these cases later changes might have no effect.

10.7.3.4 void resetToDefault (string key)

Reset the configuration item to the default value.

The key has to be a valid configuration item name. The default values can be inspectedusing the configuration editor

10.7.3.5 ProtectedItem [ ] protectedItems ()

returns a list of configuration items (key/value pairs) which are protected by the licensekey.

Changing keys or values from that list in the FaceVACS-SDK configuration file willcause LicenseSignatureMismatch exceptions.



10.8 Configuration.ProtectedItem Struct Reference

key value pair of a protected key

Public Attributes

string keykey

string valuevalue


key value pair of a protected key

10.8.2 Member Data Documentation

10.8.2.1 string key

key

10.8.2.2 string value

value


10.9 Creator Class Reference 57

10.9 Creator Class Reference

Extract a Full Frontal Image from the source image.


AnnotatedImage extract (AnnotatedImage source)extract the Full frontal Image from an annotated image

AnnotatedImage extract (AnnotatedImage source, float headLengthToImage-HeightRatio, float verticalHeadToImagePositionRatio)

extract the Full frontal Image from an annotated image, headLengthToImageHeigh-tRatio and verticalHeadToImagePositionRatio can be given at runtime.


Extract a Full Frontal Image from the source image.

meeting the geometric requirements ISO 19794 5 8.3 and with respect to geometricalrecommendation of section A.3.2.3 Table 17. Resolution of the image (see section8.4.1) is not modified by the function. It means the input image should always fit therequirement of a full frontal image for resolution ( minimal resolution: 180 pixel headwidth or 90 pixel from eye center to eye center) tobe standard compliant.

There is a configuration key influencing the image height to width reatio of the targetimage. The default value is 45/35.


10.9.2.1 AnnotatedImage extract (AnnotatedImage source)

extract the Full frontal Image from an annotated image

10.9.2.2 AnnotatedImage extract (AnnotatedImage source,float headLengthToImageHeightRatio, floatverticalHeadToImagePositionRatio)

extract the Full frontal Image from an annotated image, headLengthToImageHeightRa-tio and verticalHeadToImagePositionRatio can be given at runtime.

It describes ratio of head to image dimension of the cropped area.



10.10 Exception Struct Reference

An object of this type is thrown if exceptions in the library occure.

Inheritance diagram for Exception::

Exception

FeatureDisabled LicenseSignatureMismatch LimitExceeded


An object of this type is thrown if exceptions in the library occure.

The Exception is of type System.Exception and thus provides all members of this baseclass.


10.11 FacialMatchingEngine Class Reference 59

10.11 FacialMatchingEngine Class Reference

Low level match facilities.


FacialMatchingEngine (Configuration c)Build FacialMatchingEngine from given Configuration.

Score compare (FIR firA, FIR firB)Calculate the score between firA and firB.

Score[ ] compare (FIR fir, Population population)Calculate the scores between fir and the FIRs in population (One-To-Many Match-ing).

Match[ ] bestMatches (FIR fir, Population population, Score threshold, uint max-Matches)

Calculates best matches of the comparison between fir and the FIRs in the popula-tion.


Low level match facilities.

This class contains interfaces to calculate low level comparisions between FIRs andFIRs or Populations.


10.11.2.1 FacialMatchingEngine (Configuration c)

Build FacialMatchingEngine from given Configuration.


10.11.3.1 Score compare (FIR firA, FIR firB)

Calculate the score between firA and firB.

MT-safeIt is safe to call this function concurrently from different threads.



10.11.3.2 Score [ ] compare (FIR fir, Population population)

Calculate the scores between fir and the FIRs in population (One-To-Many Matching).

Scores in the list returned have the same order as the FIRs within the Population.

MT-safeIt is safe to call this function concurrently from different threads. The populationhas to be kept unchanged during function execution.

10.11.3.3 Match [ ] bestMatches (FIR fir, Population population, Scorethreshold, uint maxMatches)

Calculates best matches of the comparison between fir and the FIRs in the population.

Matches returned are sorted by score value in descending order. Size of the match listreturned is controlled by both a score threshold and a maximum size.

MT-safeIt is safe to call this function concurrently from different threads. The populationhas to be kept unchanged during function execution.

Parameters:threshold threshold for match decisionmaxMatches the maximum size of the FRsdk.Matches to be returned in the feed-

back


10.12 FeatureDisabled Struct Reference 61

10.12 FeatureDisabled Struct Reference

An object of this type is thrown at any time if requesting or accessing a disabledFaceVACS-SDK feature.

Inheritance diagram for FeatureDisabled::

FeatureDisabled

Exception


An object of this type is thrown at any time if requesting or accessing a disabledFaceVACS-SDK feature.



10.13 Feedback Interface Reference

The feedback from the verification process.


void start ()Called at start of verification processing.

void processingImage (Image img)Called for each image when processed by the processor.

void eyesFound (Eyes.Location eyeLoc)Called if eyes have been found in the current image; the location l indicates the posi-tion they have been found at.

void eyesNotFound ()Called if no eyes have been found in the current image, may happen if the image doesnot contain a face.

void sampleQuality (float f)Informs about sample quality of the current image; will only be called if eyes couldbe found in the image.

void sampleQualityTooLow ()Called if the sample quality of the current image is too low for verification processing.

void match (Score s)Called if the current image could be compared with the given FIR.

void success ()Called if the verification was successful, i.e.

void failure ()Called if verification failed, i.e.

void end ()Called at the end of the verification procedure; this function will be called in any case.


The feedback from the verification process.

Abstract Verification feedback is used to transfer information from the verification pro-cess to the client.


10.13 Feedback Interface Reference 63


10.13.2.1 void start ()

Called at start of verification processing.

10.13.2.2 void processingImage (Image img)

Called for each image when processed by the processor.

10.13.2.3 void eyesFound (Eyes.Location eyeLoc)

Called if eyes have been found in the current image; the location l indicates the positionthey have been found at.

10.13.2.4 void eyesNotFound ()

Called if no eyes have been found in the current image, may happen if the image doesnot contain a face.

10.13.2.5 void sampleQuality (float f)

Informs about sample quality of the current image; will only be called if eyes could befound in the image.

10.13.2.6 void sampleQualityTooLow ()

Called if the sample quality of the current image is too low for verification processing.

10.13.2.7 void match (Score s)

Called if the current image could be compared with the given FIR.

Parameters:s the score obtained.

10.13.2.8 void success ()

Called if the verification was successful, i.e.

at least one of the input images has got a match result above the given threshold.



10.13.2.9 void failure ()

Called if verification failed, i.e.

no input image got a score above the given threshold.

10.13.2.10 void end ()

Called at the end of the verification procedure; this function will be called in any case.




The feedback for the identification process.


void start ()Called at the start of identification processing.


void eyesFound (Eyes.Location eyeLoc)Called if eyes have been found in the current image; the location l indicates the posi-tion they have been found at.

void eyesNotFound ()Called if no eyes have been found in the current image; this may happen if the imagedoes not contain a face.

void sampleQuality (float f)Informs about sample quality of the current image; will only be called if eyes couldbe found in the image.

void sampleQualityTooLow ()Called if the sample quality of the current image is too low for identification process-ing.

void matches (Match[ ] matches)Called if at least one of the input images matches with the given FIR population.

void end ()Called at the end of identification procedure.


The feedback for the identification process.


10.14.2.1 void start ()

Called at the start of identification processing.






Called if eyes have been found in the current image; the location l indicates the positionthey have been found at.


Called if no eyes have been found in the current image; this may happen if the imagedoes not contain a face.


Informs about sample quality of the current image; will only be called if eyes could befound in the image.


Called if the sample quality of the current image is too low for identification processing.

10.14.2.7 void matches (Match[ ] matches)

Called if at least one of the input images matches with the given FIR population.

The best match is the first one and the worst the last one. The FIRs are referenced bynames.

10.14.2.8 void end ()

Called at the end of identification procedure.

This function will be called in any case.




The feedback for the enrollment procedure.


void start ()Called at start of enrollment processing.


void eyesFound (Eyes.Location eyeLoc)Called if eyes have been found in the current image; the Eyes.Location indicates theposition they have been found at.

void eyesNotFound ()Called if no eyes have been found in the current image.

void sampleQuality (float f)Informs about sample quality of the current processing image.

void sampleQualityTooLow ()Called during stream enrollment if the sample quality of the current image is too lowfor enrollment processing.

void success (FIR)Called if the enrollment was successful; passes the FIR created.

void failure ()Called if the enrollment was not successful (due to failure conditions).

void end ()Called at the end of the enrollment procedure.


The feedback for the enrollment procedure.

The Feedback interface is used for interaction with the environment during the pro-cessing of the enrollment. The member functions of the feedback will be called duringthe enrollment as the processing proceeds. This make it possible to watch the status ofthe enrollment for instance for gui feedback.




10.15.2.1 void start ()

Called at start of enrollment processing.




Called if eyes have been found in the current image; the Eyes.Location indicates theposition they have been found at.


Called if no eyes have been found in the current image.

This may happen if the image does not contain a face.


Informs about sample quality of the current processing image.

Will only be called during stream enrollment and only if eyes could be found in theimage.


Called during stream enrollment if the sample quality of the current image is too lowfor enrollment processing.

10.15.2.7 void success (FIR)

Called if the enrollment was successful; passes the FIR created.

10.15.2.8 void failure ()

Called if the enrollment was not successful (due to failure conditions).

Possible failure conditions are:

the enrollment time exceeds the maximum configured (Stream enrollment only;default: 60 s)



there are less enrollable images than configured (default: 1) some error in final intensity image preprocessing or shape image processing, if

configured.

10.15.2.9 void end ()

Called at the end of the enrollment procedure.

This function will be called in any case.



10.16 Finder Class Reference

face finder


Finder (Configuration c)create an instance of class Finder

Location[ ] find (Image i) Location[ ] find (Image i, float minRelativeEyeDistance, float maxRela-

tiveEyeDistance, int x1, int y1, int x2, int y2)


face finder

This class represents a interface to the face finding procedure.


10.16.2.1 Finder (Configuration c)

create an instance of class Finder


10.16.3.1 Location [ ] find (Image i)

Returns:array of Face.Location for the faces found.

Searching is focused to faces in the eye distance range

minRelativeEyeDistance = 0.1, maxRelativeEyeDistance = 0.4 (relative to the image width) and within the given

search box

x1 = INT MIN / 2, y1 = INT MIN / 2, x2 = INT MAX / 2 - 1, y2 = INT MAX / 2 - 1, spanned by (x1, y1, x2, y2).

The search process can result in faces that are slightly smaller or bigger than suggestedby these numbers.


10.16 Finder Class Reference 71

10.16.3.2 Location [ ] find (Image i, float minRelativeEyeDistance, floatmaxRelativeEyeDistance, int x1, int y1, int x2, int y2)

Returns:array of Face.Location for the faces found.

Searching is focused to faces in the given eye distance range (relative to the imagewidth) and within the given search box spanned by (x1, y1, x2, y2). The givensearch box is clipped by the boundaries of the image, so the default settings for thesearch box denote that the entire image has to be used as search area. (See your com-pilers for INT MIN and INT MAX definitions.). Also note that minRel-ativeEyeDistance and maxRelativeEyeDistance are hints for the finding engine. Thesearch process can result in faces that are slightly smaller or bigger than suggested bythese numbers.



10.17 Finder Class Reference

eyes finder


Finder (Configuration c)create an instance of class Finder

Location[ ] find (Image i, Face.Location l)returns an array of Eyes.Location found within a face at the given Face.Location.


eyes finder

This class represents a interface to the eye finding procedure.

MT-safeIt is safe to call the find method concurrently from different threads.


10.17.2.1 Finder (Configuration c)

create an instance of class Finder


10.17.3.1 Location [ ] find (Image i, Face.Location l)

returns an array of Eyes.Location found within a face at the given Face.Location.


10.18 FIR Class Reference 73

10.18 FIR Class Reference

FIR - Facial Identification Record.


uint size ()returns the size of the FIR memory representation

string version ()returns the version id string

void serialize (IntPtr buf)write a serialized platform independent representation to a buffer which must be ableto hold at least FIR.size() bytes.

void serialize (System.IO.Stream o)Write a serialized platform independent representation to an ostream; the format ofthis representation is equal to that of the memory representation obtained with seri-alize( Byte).

void writeTo (ref IntPtr p)write a platform dependent representation to a buffer which must be able to hold atleast FIR.size() bytes.


FIR - Facial Identification Record.

The FIR is a serializable byte stream which encapsulates the transformed representationof a face which is often called feature set. Use Enrollment.Processor to create FIRsfrom primary facial data (images) or FIRBuilder to (re)create FIRs from serializedrepresentations.


10.18.2.1 uint size ()

returns the size of the FIR memory representation

10.18.2.2 string version ()

returns the version id string



10.18.2.3 void serialize (IntPtr buf)

write a serialized platform independent representation to a buffer which must be ableto hold at least FIR.size() bytes.

10.18.2.4 void serialize (System.IO.Stream o)

Write a serialized platform independent representation to an ostream; the format of thisrepresentation is equal to that of the memory representation obtained with serialize(Byte).

10.18.2.5 void writeTo (ref IntPtr p)

write a platform dependent representation to a buffer which must be able to hold atleast FIR.size() bytes.

After execution p points to the first byte after the FIRs data.


10.19 FIRBuilder Class Reference 75

10.19 FIRBuilder Class Reference

Building FIRs from serialized representations Use Enrollment.Processor to build FIRsfrom primary biometric data (face images).


FIRBuilder (Configuration c)Build a FIRBuilder from given Configuration.

FIR build (IntPtr buf, uint len)create a FIR from platform independent representation created with FIR.serialize()

FIR build (System.IO.Stream is)create a FIR from stream containing a platform independent representation createdwith FIR.serialize()

FIR build (ref IntPtr p)create a FIR from platform dependent representation created using FIR.writeTo, start-ing from p, the memory must be valid during the lifetime of the FIR object, after theconstruction p points to the first byte after the FIRs data.


Building FIRs from serialized representations Use Enrollment.Processor to build FIRsfrom primary biometric data (face images).


10.19.2.1 FIRBuilder (Configuration c)

Build a FIRBuilder from given Configuration.


10.19.3.1 FIR build (IntPtr buf, uint len)

create a FIR from platform independent representation created with FIR.serialize()

10.19.3.2 FIR build (System.IO.Stream is)

create a FIR from stream containing a platform independent representation created withFIR.serialize()



10.19.3.3 FIR build (ref IntPtr p)

create a FIR from platform dependent representation created using FIR.writeTo, start-ing from p, the memory must be valid during the lifetime of the FIR object, after theconstruction p points to the first byte after the FIRs data.


10.20 Image Interface Reference 77

10.20 Image Interface Reference

Abstract image.

Inherited by NetImage.


bool isColor ()returns true if image is based on color data.

uint width ()returns the width of the image in pixels

uint height ()returns the height of the image in pixels

IntPtr grayScaleRepresentation ()Returns a pointer to an array of size width() x height() x sizeof( byte) containing thegray scale representation of the image.

IntPtr colorRepresentation ()Returns a pointer to an array of size width() x height() x sizeof( uint) containing thecolor representation of the image.

string name ()returns the name of the image, or an empty string


Abstract image.


10.20.2.1 bool isColor ()

returns true if image is based on color data.

false will be returend if the images contains only intensity information

10.20.2.2 uint width ()

returns the width of the image in pixels



10.20.2.3 uint height ()

returns the height of the image in pixels

10.20.2.4 IntPtr grayScaleRepresentation ()

Returns a pointer to an array of size width() x height() x sizeof( byte) containing thegray scale representation of the image.

The pointer has to remain valid during the whole lifetime of the Image object.

10.20.2.5 IntPtr colorRepresentation ()

Returns a pointer to an array of size width() x height() x sizeof( uint) containing thecolor representation of the image.

The pointer has to remain valid during the whole lifetime of the Image object. Notethat the order of colors per pixel is BGRA (blue green red alpha) instead of RGB.

10.20.2.6 string name ()

returns the name of the image, or an empty string


10.21 ImageManipulation Struct Refer

refman.net

Documents

processor class reference

set class reference

finder class reference

configuration class

tracker class reference

analyzer class reference

population class reference

scoremappings class