Evaluation of Latent Friction Ridge Technology
API for participating in NIST's evaluation of latent friction ridge identification algorithms.
Public Member Functions | Static Public Member Functions | List of all members
ELFT::SearchInterface Class Referenceabstract

Interface for database search implemented by participant. More...

#include <elft.h>

Public Member Functions

virtual std::optional< ProductIdentifiergetIdentification () const =0
 Obtain identification and version information for the search portion of this submission. More...
 
virtual ReturnStatus load (const uint64_t maxSize)=0
 Load reference database into memory. More...
 
virtual SearchResult search (const std::vector< std::byte > &probeTemplate, const uint16_t maxCandidates) const =0
 Search the reference database for the samples represented in probeTemplate. More...
 
virtual std::optional< CorrespondenceResultextractCorrespondence (const std::vector< std::byte > &probeTemplate, const SearchResult &searchResult) const =0
 Extract pairs of corresponding Minutia between TemplateType::Probe and TemplateType::Reference templates. More...
 
 SearchInterface ()
 
virtual ~SearchInterface ()
 

Static Public Member Functions

static std::shared_ptr< SearchInterfacegetImplementation (const std::filesystem::path &configurationDirectory, const std::filesystem::path &databaseDirectory)
 Obtain a managed pointer to an object implementing SearchInterface. More...
 

Detailed Description

Interface for database search implemented by participant.

Definition at line 1263 of file elft.h.

Constructor & Destructor Documentation

◆ SearchInterface()

ELFT::SearchInterface::SearchInterface ( )
default

◆ ~SearchInterface()

ELFT::SearchInterface::~SearchInterface ( )
virtualdefault

Member Function Documentation

◆ getIdentification()

virtual std::optional< ProductIdentifier > ELFT::SearchInterface::getIdentification ( ) const
pure virtual

Obtain identification and version information for the search portion of this submission.

Returns
ProductIdentifier populated with information used to identify the search algorithm in reports.
Note
The reference database may be stored on a read-only file system when this method is called. Do not attempt to modify the reference database here.
This method shall return instantly.

◆ load()

virtual ReturnStatus ELFT::SearchInterface::load ( const uint64_t  maxSize)
pure virtual

Load reference database into memory.

Parameters
maxSizeSuggested maximum number of bytes of memory to consume in support of searching the reference database faster.
Returns
Information about the result of executing the method.
Warning
This method will be called after construction and should not be called from an implementation's constructor. This allows calling getIdentification() without wasting resources.
DO NOT MODIFY the contents of your database in memory after this method returns! After calling this method, the test application may fork(), allowing calls to search() to share the contents of memory using copy-on-write semantics.
DO NOT MODIFY the contents of the database on disk at any time! The databaseDirectory provided to getImplementation() may be stored on a read-only file system and may be destroyed and restored before calls to search().
Note
maxSize will not be the full amount of memory available on the system, but it is the maximum amount of memory the reference database should consume. The test application may fork() after calls to this method, during which, this implementation and the test application are free to perform dynamic memory allocations. While there is no penalty for exceeding this memory limit with the reference database, it is a near certainty that implementations will run out of memory if they do.
This method is guaranteed to be called at least once before calls to any SearchInterface method, except for calls to getIdentification().
If the reference database is already loaded when this method is called, this method shall return immediately.
This method need not be threadsafe. It may use more than one thread.
This method shall return in <= 1 millisecond * the number of identifiers in the reference database.

◆ search()

virtual SearchResult ELFT::SearchInterface::search ( const std::vector< std::byte > &  probeTemplate,
const uint16_t  maxCandidates 
) const
pure virtual

Search the reference database for the samples represented in probeTemplate.

Parameters
probeTemplateObject returned from createTemplate() with templateType of TemplateType::Probe.
maxCandidatesThe maximum number of Candidate to return.
Returns
A SearchResult object containing information on if this task was able to be completed and a list of less than or equal to maxCandidates Candidate.
Warning
DO NOT MODIFY the database loaded with load() either in memory or on disk. This method will be called after calling load() and most likely from a fork()ed process, allowing the read-only database in memory to be shared using fork()'s copy-on-write semantics while not requiring this method to be threadsafe. Modifying the database will at best cause an out of memory error and at worst cause undefined behavior for the many running search processes.
Note
SearchResult.candidateList will be sorted by descending Candidate.similarity upon return from this method using std::stable_sort().
If provided a probe template that contains images from multiple regions of the same candidate, Candidate.frgp will be ignored in analysis.
Candidate.frgp shall be the most localized region where the correspondence was noted to be considered as correct as possible. See the test plan for more information.
This method must return in <= 10 * number of database identifiers milliseconds, on average, as measured on a fixed subset of data.

◆ extractCorrespondence()

virtual std::optional< CorrespondenceResult > ELFT::SearchInterface::extractCorrespondence ( const std::vector< std::byte > &  probeTemplate,
const SearchResult searchResult 
) const
pure virtual

Extract pairs of corresponding Minutia between TemplateType::Probe and TemplateType::Reference templates.

Parameters
probeTemplateProbe template sent to searchReferences().
searchResultObject returned from searchReferences().
Returns
An optional with no value if not implemented, or a collection of information containing corresponding features otherwise.
Note
ELFT::Minutia must align with minutiae returned from ExtractionInterface::extractTemplateData() for the given identifier + position pair.
You must implement this method to compile, but providing the requested information is optional. If provided, information may help in debugging, as well as informing future NIST analysis.
searchResult is not guaranteed to be the identical object returned from search(). Specifically, ordering of SearchResult.candidateList may have changed (e.g., sorted by descending similarity) and the ReturnStatus member is not guaranteed to populated with ReturnStatus::message.
The reference database will be stored on a read-only file system when this method is called. Do not attempt to modify the reference database here.
This method shall return in <= 5 seconds.

◆ getImplementation()

static std::shared_ptr< SearchInterface > ELFT::SearchInterface::getImplementation ( const std::filesystem::path &  configurationDirectory,
const std::filesystem::path &  databaseDirectory 
)
static

Obtain a managed pointer to an object implementing SearchInterface.

Parameters
configurationDirectoryRead-only directory populated with configuration files provided in validation.
databaseDirectoryRead-only directory populated with files written in ExtractionInterface::createReferenceDatabase().
Returns
Shared pointer to an instance of SearchInterface containing the participant's code to perform search operations.
Warning
Do not load your reference database into memory on construction. Instead, wait for a call to load().
Note
A possible implementation might be: return (std::make_shared<SearchImplementation>( configurationDirectory, databaseDirectory));
This method shall return in <= 5 seconds.

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