IREX 10
API Specification for the IREX 10 Identification Track
Interface Class Referenceabstract

Submitted libraries must override these functions. More...

Public Member Functions

virtual ReturnStatus initializeTemplateCreation (const string &configDirectory, const TemplateType type)=0
 Initialization function, called once prior to one or more calls to createTemplate(). More...
 
virtual ReturnStatus createTemplate (std::vector< IrisImage > &irides, std::vector< uint8_t > &templateData)=0
 Generates a template from a vector of iris images. More...
 
virtual ReturnStatus createDatabase (const string &enrollmentDirectory, const string &configDirectory, const std::vector< DatabaseEntry > &templates)=0
 Function to create an enrollment database to search against. More...
 
virtual ReturnStatus initializeIdentification (const string &enrollmentDirectory, const string &configDirectory)=0
 Initialization function, to be called once prior to one or more calls to identify(). More...
 
virtual ReturnStatus identify (const std::vector< uint8_t > &searchTemplate, const uint32_t numCandidates, std::vector< Candidate > &candidates)=0
 Searches a template against the enrollment database and returns a list of candidates. More...
 

Static Public Member Functions

static std::shared_ptr< InterfacegetImplementation ()
 Return an instance of the implementation.
 

Detailed Description

Submitted libraries must override these functions.

For an example of how to do this, see this dummy implementation.

Definition at line 50 of file irex.h.

Member Function Documentation

◆ initializeTemplateCreation()

virtual ReturnStatus initializeTemplateCreation ( const string &  configDirectory,
const TemplateType  type 
)
pure virtual

Initialization function, called once prior to one or more calls to createTemplate().

The implementation shall tolerate execution of multiple calls to this function from different processes running on the same machine. If participants wish to use the optional configDirectory parameter, they must say so in documentation accompanying their submission. NIST will debug if a call to this function returns a non-zero value, contacting the participant if necessary.

Parameters
[in]typeAbout to create enrollment or search templates.
[in]configDirectoryA directory containing read-only configuration files and/or runtime data files.
Returns
An object of type Irex::ReturnStatus.

◆ createTemplate()

virtual ReturnStatus createTemplate ( std::vector< IrisImage > &  irides,
std::vector< uint8_t > &  templateData 
)
pure virtual

Generates a template from a vector of iris images.

The implementation must be able to handle iris images having arbitrary pixel dimensions, although primary NIST tests are expected to only operate over images that are 640x480 or 640x512. If a return value of 100 or greater is returned, NIST will attempt to debug, contacting the participant if necessary.

Each IrisImage has an optional quality field that participants are encouraged to fill in. As per ISO/IEC 29794-6: Biometric Sample Quality, values should be between 0 and 100 with higher values indicating better quality, or 255 indicating an inability to provide a quality score. Implementations are not required to fill in this parameter but it would be appreciated by NIST.

When specified, the iris boundary variables provide estimates of the limbus center (limbusCenterX, limbusCenterY) and pupil (pupilRadius) and limbus (limbusRadius) radii. The estimates should be accurate to within a few pixels. When left unspecified, the participant is encouraged to fill in these values, as it can assist with debugging, but doing so is optional.

Each IrisImage in irides represents a single iris image (left or right). Implementations must support the following scenarios:

  1. irides contains a single iris image.
  2. irides contains one left and one right iris.
  3. irides contains several images of the same iris.
  4. irides contains N images of the left iris and N images of the right iris.

For scenarios 2-4 the eye parameter for each IrisImage in irides will always be set to either 1 (left) or 2 (right) and never 0 (unknown / undefined). Scenario 2 represents the most common operational use case and is likely to be the most tested.

Parameters
[in]iridesThe iris images from which to create the template.
[out]templateDataTemplate generated from the iris samples. The template's format is proprietary and NIST will not access any part of it other to pass it to createDatabase() and possibly store it temporarily.
Returns
An object of type Irex::ReturnStatus.

◆ createDatabase()

virtual ReturnStatus createDatabase ( const string &  enrollmentDirectory,
const string &  configDirectory,
const std::vector< DatabaseEntry > &  templates 
)
pure virtual

Function to create an enrollment database to search against.

Enrollment database creation shall be performed after all enrollment processes are complete. It should populate the contents of the enrollment directory with everything that is necessary to perform searches against it. This function allows post-enrollment book-keeping, normalization, and other statistical processing of the generated templates. It should tolerate being called multiple times, altough subsequent calls should probably not do anything.

NIST will debug if a call to this function returns a non-zero value. The NIST test harness will never knowingly enroll the same iris under two different identifiers.

Parameters
[in]enrollmentDirectoryAn absolute path to the top-level directory in which the enrollment database will reside. The implementation will have read and write access to this directory.
[in]configDirectoryA directory containing read-only configuration files and/or runtime data files.
[in]templatesThe vector of enrollment templates that should comprise the enrollment database. The implementation should store these templates in the enrollment directory.
Returns
An object of type Irex::ReturnStatus.

◆ initializeIdentification()

virtual ReturnStatus initializeIdentification ( const string &  enrollmentDirectory,
const string &  configDirectory 
)
pure virtual

Initialization function, to be called once prior to one or more calls to identify().

The function may use this function to read data (e.g. templates) from the enrollment directory and load it into memory. NIST will debug if a call to this function returns a non-zero value, contacting the participant if necessary.

Parameters
[in]enrollmentDirectoryThe top-level directory in which the enrollment data was placed when finalizeEnrollment() was called.
[in]configDirectoryA directory containing read-only configuration files and/or runtime data files.
Returns
An object of type Irex::ReturnStatus.

◆ identify()

virtual ReturnStatus identify ( const std::vector< uint8_t > &  searchTemplate,
const uint32_t  numCandidates,
std::vector< Candidate > &  candidates 
)
pure virtual

Searches a template against the enrollment database and returns a list of candidates.

NIST will typically set the candidate list length to operationally feasible values (e.g. 20), but may decide to extend it to values that approach the size of the enrollment database.

Parameters
[in]searchTemplateA search template generated by a call to createTemplate().
[in]numCandidatesThe length of the candidate list array to output.
[out]candidatesAn array (of length numCandidates) of candidates. Each candidate shall be populated by the implementation and shall be sorted in ascending order of distance score (i. e. the most similar entry shall appear first).
Returns
An object of type Irex::ReturnStatus.

The documentation for this class was generated from the following file: