Interface for database search implemented by participant.
More...
#include <elft.h>
Interface for database search implemented by participant.
Definition at line 1265 of file elft.h.
◆ SearchInterface()
| ELFT::SearchInterface::SearchInterface |
( |
| ) |
|
|
default |
◆ ~SearchInterface()
| ELFT::SearchInterface::~SearchInterface |
( |
| ) |
|
|
virtualdefault |
◆ 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
-
| maxSize | Suggested 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
-
| probeTemplate | Object returned from createTemplate() with templateType of TemplateType::Probe. |
| maxCandidates | The 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
-
| probeTemplate | Probe template sent to searchReferences(). |
| searchResult | Object 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
-
- 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().
-
It is possible that
databaseDirectory does not exist when this function is called, but it will exist before load() is called. Do not emit errors based on the contents of databaseDirectory from this function. This is necessary to call getIdentification() prior to creating an enrollment database.
- 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:
