The interface to the implementations. More...

#include <n2n.h>

Public Member Functions
virtual void	getIDs (std::string &identifier, uint32_t &revision, std::string &email)=0
	Obtain identifying information about the software under test. More...

virtual ReturnStatus	initMakeEnrollmentTemplate (const std::string &configurationDirectory)=0
	Prepare for calls to makeEnrollmentTemplate(). More...

virtual ReturnStatus	makeEnrollmentTemplate (const std::vector< FingerImage > &standardImages, const std::vector< BiometricEvaluation::Memory::uint8Array > &proprietaryImages, BiometricEvaluation::Memory::uint8Array &enrollmentTemplate)=0
	Create an enrollment template for one subject. More...

virtual ReturnStatus	finalizeEnrollment (const std::string &configurationDirectory, const std::string &enrollmentDirectory, const uint8_t nodeCount, const uint64_t nodeMemory, BiometricEvaluation::IO::RecordStore &enrollmentTemplates)=0
	Form an enrollment set from one or more enrollment templates. More...

virtual ReturnStatus	initMakeSearchTemplate (const std::string &configurationDirectory, const InputType &inputType)=0
	Prepare for calls to makeSearchTemplate(). More...

virtual ReturnStatus	makeSearchTemplate (const std::vector< FingerImage > &standardImages, const std::vector< BiometricEvaluation::Memory::uint8Array > &proprietaryImages, BiometricEvaluation::Memory::uint8Array &searchTemplate)=0
	Create a search template for one subject. More...

virtual ReturnStatus	initIdentificationStageOne (const std::string &configurationDirectory, const std::string &enrollmentDirectory, const InputType &inputType, const uint8_t nodeNumber)=0
	Prepare for calls to identifyTemplateStageOne(). More...

virtual ReturnStatus	identifyTemplateStageOne (const std::string &searchID, const BiometricEvaluation::Memory::uint8Array &searchTemplate, const std::string &stageOneDataDirectory)=0
	Search a template against the partial enrollment set. More...

virtual ReturnStatus	initIdentificationStageTwo (const std::string &configurationDirectory, const std::string &enrollmentDirectory, const InputType &inputType)=0
	Prepare for calls to identifyTemplateStageTwo(). More...

virtual ReturnStatus	identifyTemplateStageTwo (const std::string &searchID, const std::string &stageOneDataDirectory, std::vector< Candidate > &candidates)=0
	Produce a candidate list from the results of all calls to identifyTemplateStageOne() for a particular search ID. More...

virtual	~Interface ()=default
	Destructor.

Static Public Member Functions
static std::shared_ptr< Interface >	getImplementation ()
	Obtain a managed pointer to an implementation of this interface. More...

Detailed Description

The interface to the implementations.

The implementation under test will implement this interface by subclassing this class and implementing each method.

Member Function Documentation

◆ finalizeEnrollment()

virtual ReturnStatus N2N::Interface::finalizeEnrollment	(	const std::string &	configurationDirectory,
		const std::string &	enrollmentDirectory,
		const uint8_t	nodeCount,
		const uint64_t	nodeMemory,
		BiometricEvaluation::IO::RecordStore &	enrollmentTemplates
	)

pure virtual

Form an enrollment set from one or more enrollment templates.

This finalization step will prepare the enrolled templates to be distributed across multiple nodes. The enrollment directory will then be read-only throughout the duration of the identification process.

Parameters

[in]	configurationDirectory	A read-only directory containing vendor-supplied configuration parameters or run-time data files.
[in]	enrollmentDirectory	The top-level directory in which all enrollment data will reside. Access permission will be read-write and the application can populate this directory as needed. The directory is initially empty. After this method returns, the directory and its contents will become read-only.
[in]	nodeCount	The number of nodes the enrollment set will be spread across. It is up to the implementation to determine how best to spread the enrolled templates across the blades in order to get best performance. If `nodeCount` is not enough nodes, StatusCode::InsufficientResources should be returned.
[in]	nodeMemory	Amount of memory available to this process on each node, in kibibytes.
[in]	enrollmentTemplates	A read-only RecordStore of enrollment templates, as returned by makeEnrollmentTemplate().

Returns: Completion status of the operation.

Exceptions

BiometricEvaluation::Error::Exception There was an error processing this request, and the exception string may contain additional information.

Note: All implementations must be capable of performing searches using >= 5 nodes. A larger value may be provided for speed, or a smaller value provided to conserve resources. If a smaller value is not feasible, StatusCode::InsufficientResources should be returned. Implementations that do not return successfully for values >= 5 will be disqualified.; The file system does not perform well with the creation of millions of small files, so the application should consolidate templates into some sort of database file within enrollmentDirectory.; This method must return within 90 minutes per 1-million subjects (e.g., if 5-million enrollment templates are provided, this method must return within 7.5 hours).; Reasonable multithreading is permitted. This method will only be called once.

◆ getIDs()

virtual void N2N::Interface::getIDs	(	std::string &	identifier,
		uint32_t &	revision,
		std::string &	email
	)

pure virtual

Obtain identifying information about the software under test.

Participants will receive an identifier from the project sponsor, and use this method to hard-code the identifier into the submission. The information obtained by this method must form the name of the submitted library, in the form libN2N_<identifier>_<revision>.so.

Parameters

[out]	identifier	The identifier provided to you by the project sponsor.
[out]	revision	A unique revision number for this submission. No two submission revision numbers may be the same, and subsequent submissions should only ever increase this value.
[out]	email	Point of contact email address.

Note: This method must return immediately.

◆ getImplementation()

static std::shared_ptr< Interface > N2N::Interface::getImplementation ( )

static

Obtain a managed pointer to an implementation of this interface.

Returns: A managed pointer to the Interface subclass implementation.

◆ identifyTemplateStageOne()

virtual ReturnStatus N2N::Interface::identifyTemplateStageOne	(	const std::string &	searchID,
		const BiometricEvaluation::Memory::uint8Array &	searchTemplate,
		const std::string &	stageOneDataDirectory
	)

pure virtual

Search a template against the partial enrollment set.

Parameters

[in]	searchID	The ID of the search template. This ID does not identify subject, but is merely an identifier used to distinguish different searches performed by the system. It will be used as the input to identifyTemplateStageTwo().
[in]	searchTemplate	A template from makeSearchTemplate().
[in]	stageOneDataDirectory	This directory will have read-write access. The output information from identifyTemplateStageOne() that is needed in identifyTemplateStageTwo() is written in this directory. This directory will be unique for each search performed.

Returns: Completion status of the operation.

Exceptions

BiometricEvaluation::Error::Exception There was an error processing this request, and the exception string may contain additional information.

Note: All calls to combined identification functions (identifyTemplateStageOne() + identifyTemplateStageTwo()) for a single searchID must return within 60 seconds for InputType::Capture and 300 seconds for InputType::Latent. If identifyTemplateStageOne() takes 55 seconds for searchID XYZ (InputType::Capture), identifyTemplateStageTwo() must complete within 5 seconds for the same search ID. stageOneDataDir will reside on a RAM disk to reduce the effects of I/O operations on this time requirement.

Attention: Multithreading and other multiprocessing techniques are absolutely not permitted. The testing application will be calling this method from multiple processes on the same node.; Unique filenames are required for all data written to stageOneDataDirectory for each searchID. This can be accomplished by appending nodeNumber (from initIdentificationStageOne()) to the filename of any file written within stageOneDataDirectory.

◆ identifyTemplateStageTwo()

virtual ReturnStatus N2N::Interface::identifyTemplateStageTwo	(	const std::string &	searchID,
		const std::string &	stageOneDataDirectory,
		std::vector< Candidate > &	candidates
	)

pure virtual

Produce a candidate list from the results of all calls to identifyTemplateStageOne() for a particular search ID.

identifyTemplateStageOne() with searchID was called >= 1 times on separate nodes, ideally searching different subsets of the full enrolled set. In this method, the implementation should parse the results of the first search stage to form a final candidate list. This method will only be called once per searchID and only on a single node.

Parameters

[in]	searchID	The ID of the search template. This ID does not identify subject, but is merely an identifier used to distinguish different searches performed by the system.
[in]	stageOneDataDirectory	A read-only version of the data generated by identifyTemplateStageOne().
[out]	candidates	The candidate list.

Returns: Completion status of the operation.

Exceptions

BiometricEvaluation::Error::Exception There was an error processing this request, and the exception string may contain additional information.

Note: All calls to combined identification functions (identifyTemplateStageOne() + identifyTemplateStageTwo()) for a single searchID must return within 60 seconds for InputType::Capture and 300 seconds for InputType::Latent. If identifyTemplateStageOne() takes 55 seconds for searchID XYZ (InputType::Capture), identifyTemplateStageTwo() must complete within 5 seconds for the same search ID.; candidates will have reserve() called prior to calling this method.; There shall be [0,100] objects in candidates after the successful return of this method.; candidates shall be sorted by descending similarity score before returning.

Attention: Multithreading and other multiprocessing techniques are absolutely not permitted. The testing application will be calling this method from multiple processes on the same node.

◆ initIdentificationStageOne()

virtual ReturnStatus N2N::Interface::initIdentificationStageOne	(	const std::string &	configurationDirectory,
		const std::string &	enrollmentDirectory,
		const InputType &	inputType,
		const uint8_t	nodeNumber
	)

pure virtual

Prepare for calls to identifyTemplateStageOne().

The function will be called to initialize each node that will contain a portion of the enrolled templates. The number of nodes will be the same as provided in finalizeEnrollment().

Parameters

[in]	configurationDirectory	A read-only directory containing vendor-supplied configuration parameters or run-time data files.
[in]	enrollmentDirectory	The top-level read-only directory in which all finalized enrollment data resides. The contents of this directory is identical to the enrollmentDirectory parameter from finalizeEnrollment(), but the path may not be the same.
[in]	inputType	The types of images that will be provided during all subsequent calls to identifyTemplateStageOne().
[in]	nodeNumber	Node number from nodes in finalizeEnrollment() that is being initialized. This parameter lets the callee know which piece of the enrolled templates to load into memory. Nodes are numbered 0 to (N - 1).

Returns: Completion status of the operation.

Exceptions

BiometricEvaluation::Error::Exception There was an error processing this request, and the exception string may contain additional information.

Note: This method must complete with 5 minutes. Reasonable multithreading is permitted.

◆ initIdentificationStageTwo()

virtual ReturnStatus N2N::Interface::initIdentificationStageTwo	(	const std::string &	configurationDirectory,
		const std::string &	enrollmentDirectory,
		const InputType &	inputType
	)

pure virtual

Prepare for calls to identifyTemplateStageTwo().

This second stage of identification uses the results from identifyTemplateStageOne() to produce a candidate list for the search subject.

Parameters

[in]	configurationDirectory	A read-only directory containing vendor-supplied configuration parameters or run-time data files.
[in]	enrollmentDirectory	The top-level directory in which all finalized enrolled data resides. The directory will have read-only access.
[in]	inputType	The types of images that will be provided during all subsequent calls to identifyTemplateStageTwo().

Returns: Completion status of the operation.

Exceptions

BiometricEvaluation::Error::Exception There was an error processing this request, and the exception string may contain additional information.

Note: This method must complete with 5 minutes. Reasonable multithreading is permitted.

◆ initMakeEnrollmentTemplate()

virtual ReturnStatus N2N::Interface::initMakeEnrollmentTemplate ( const std::string & configurationDirectory )

pure virtual

Prepare for calls to makeEnrollmentTemplate().

The function is called once by the testing application before N >= 1 calls to makeEnrollmentTemplate() on the current node. The implementation must tolerate execution of this initialization function and other N >= 1 calls to makeEnrollmentTemplate() running simultaneously and independently on the same and/or multiple machines.

Parameters

[in] configurationDirectory A read-only directory containing vendor-supplied configuration parameters or run-time data files.

Returns: Completion status of the operation.

Exceptions

BiometricEvaluation::Error::Exception There was an error processing this request, and the exception string may contain additional information.

Note: This method must complete with 5 minutes. Reasonable multithreading is permitted.

◆ initMakeSearchTemplate()

virtual ReturnStatus N2N::Interface::initMakeSearchTemplate	(	const std::string &	configurationDirectory,
		const InputType &	inputType
	)

pure virtual

Prepare for calls to makeSearchTemplate().

The function is called once by the testing application before N >= 1 calls to makeSearchTemplate() on the current node. The implementation must tolerate execution of this initialization function and other N >= 1 calls to makeSearchTemplate() running simultaneously and independently on the same and/or multiple machines.

Parameters

[in]	configurationDirectory	A read-only directory containing vendor-supplied configuration parameters or run-time data files.
[in]	inputType	The types of images that will be provided during all subsequent calls to makeSearchTemplate().

Returns: Completion status of the operation.

Exceptions

BiometricEvaluation::Error::Exception There was an error processing this request, and the exception string may contain additional information.

Note: This method must complete with 5 minutes. Reasonable multithreading is permitted.

◆ makeEnrollmentTemplate()

virtual ReturnStatus N2N::Interface::makeEnrollmentTemplate	(	const std::vector< FingerImage > &	standardImages,
		const std::vector< BiometricEvaluation::Memory::uint8Array > &	proprietaryImages,
		BiometricEvaluation::Memory::uint8Array &	enrollmentTemplate
	)

pure virtual

Create an enrollment template for one subject.

This method provides one or more fingerprints from a subject and tasks the implementation with creating and returning an object that can represent this subject in an enrollment set.

Parameters

[in]	standardImages	One or more finger images from a single subject.
[in]	proprietaryImages	One or more proprietary representations of fingers, as returned from the participant's sensor.
[out]	enrollmentTemplate	A non-regulated representation of fingers for an enrollment set.

Returns: Completion status of the operation.

Exceptions

BiometricEvaluation::Error::Exception There was an error processing this request, and the exception string may contain additional information.

Note: This method should call BiometricEvaluation::Memory::uint8Array::resize() before any writes to enrollmentTemplate to ensure it is large enough to contain the write. This method should also call BiometricEvaluation::Memory::uint8Array::resize() before returning so that enrollmentTemplate is the exact required size. All BiometricEvaluation::Memory::uint8Array::size() bytes of enrollmentTemplate will be provided to the N2N::Interface implementation during finalizeEnrollment().; 90% of calls to this method must return in three seconds or less.

Attention: Multithreading and other multiprocessing techniques are absolutely not permitted. The testing application will be calling this method from multiple processes on the same node.

◆ makeSearchTemplate()

virtual ReturnStatus N2N::Interface::makeSearchTemplate	(	const std::vector< FingerImage > &	standardImages,
		const std::vector< BiometricEvaluation::Memory::uint8Array > &	proprietaryImages,
		BiometricEvaluation::Memory::uint8Array &	searchTemplate
	)

pure virtual

Create a search template for one subject.

This method provides one or more fingerprints from a subject and tasks the implementation with creating and returning an object that can represent this subject as a search initiator.

Parameters

[in]	standardImages	One or more finger images from a single subject.
[in]	proprietaryImages	One or more proprietary representations of fingers, as returned from the participant's sensor.
[out]	searchTemplate	A non-regulated representation of fingers used to initiate a search.

Returns: Completion status of the operation.

Exceptions

BiometricEvaluation::Error::Exception There was an error processing this request, and the exception string may contain additional information.

Note: This method should call BiometricEvaluation::Memory::uint8Array::resize() before any writes to searchTemplate to ensure it is large enough to contain the write. This method should also call BiometricEvaluation::Memory::uint8Array::resize() before returning so that searchTemplate is the exact required size. All BiometricEvaluation::Memory::uint8Array::size() bytes of enrollmentTemplate will be provided to the N2N::Interface implementation during finalizeEnrollment().; 90% of calls to this method must return in three seconds or less.

Attention: Multithreading and other multiprocessing techniques are absolutely not permitted. The testing application will be calling this method from multiple processes on the same node.

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ finalizeEnrollment()

◆ getIDs()

◆ getImplementation()

◆ identifyTemplateStageOne()

◆ identifyTemplateStageTwo()

◆ initIdentificationStageOne()

◆ initIdentificationStageTwo()

◆ initMakeEnrollmentTemplate()

◆ initMakeSearchTemplate()

◆ makeEnrollmentTemplate()

◆ makeSearchTemplate()