e1n.h

Go to the documentation of this file.

/*
 * This software was developed at the National Institute of Standards and
 * Technology (NIST) by employees of the Federal Government in the course
 * of their official duties. Pursuant to title 17 Section 105 of the
 * United States Code, this software is not subject to copyright protection
 * and is in the public domain. NIST assumes no responsibility whatsoever for
 * its use by other parties, and makes no guarantees, expressed or implied,
 * about its quality, reliability, or any other characteristic.
 */
 
#ifndef FRIF_EVALUATIONS_E1N_H_
#define FRIF_EVALUATIONS_E1N_H_
 
#include <cstddef>
#include <cstdint>
#include <filesystem>
#include <memory>
#include <optional>
#include <set>
#include <string>
#include <tuple>
#include <vector>
 
#include <frif/frif.h>
 
namespace FRIF::Evaluations::Exemplar1N
{
        LibraryIdentifier
        getLibraryIdentifier();
 
        class ExtractionInterface
        {
        public:
                struct Compatibility
                {
                        bool supportsTemplateIntrospection{};
 
                        std::set<uint16_t> probeTemplateVersions{};
 
                        std::set<uint16_t> referenceTemplateVersions{};
 
                        std::set<uint16_t> referenceDatabaseVersions{};
                };
 
                virtual
                std::tuple<ReturnStatus, std::optional<CreateTemplateResult>>
                createTemplate(
                    const TemplateType templateType,
                    const std::string &identifier,
                    const std::vector<Sample> &samples)
                    const = 0;
 
                virtual
                std::optional<std::tuple<ReturnStatus,
                    std::vector<TemplateData>>>
                extractTemplateData(
                    const TemplateType templateType,
                    const CreateTemplateResult &templateResult)
                    const = 0;
 
                virtual
                ReturnStatus
                createReferenceDatabase(
                    const TemplateArchive &referenceTemplates,
                    const std::filesystem::path &databaseDirectory,
                    const uint64_t maxSize)
                    const = 0;
 
                /**************************************************************/
 
                static
                std::shared_ptr<ExtractionInterface>
                getImplementation(
                    const std::filesystem::path &configurationDirectory);
 
                static
                std::optional<ProductIdentifier>
                getProductIdentifier();
 
                static
                Compatibility
                getCompatibility();
 
                ExtractionInterface(const ExtractionInterface&) = delete;
                ExtractionInterface& operator=(const ExtractionInterface&) =
                    delete;
                ExtractionInterface();
                virtual ~ExtractionInterface();
        };
 
        class SearchInterface
        {
        public:
                struct Compatibility
                {
                        bool supportsCorrespondence{};
 
                        std::set<uint16_t> probeTemplateVersions{};
 
                        std::set<uint16_t> referenceDatabaseVersions{};
                };
 
                virtual
                ReturnStatus
                load(
                    const uint64_t maxSize) = 0;
 
                /**************************************************************/
 
                virtual
                std::tuple<ReturnStatus, std::optional<SearchResult>>
                search(
                    const std::vector<std::byte> &probeTemplate,
                    const uint16_t maxCandidates)
                    const = 0;
 
                virtual
                std::optional<CandidateListCorrespondence>
                extractCorrespondence(
                    const std::vector<std::byte> &probeTemplate,
                    const SearchResult &searchResult)
                    const = 0;
 
                /**************************************************************/
 
                static
                std::shared_ptr<SearchInterface>
                getImplementation(
                    const std::filesystem::path &configurationDirectory,
                    const std::filesystem::path &databaseDirectory);
 
                static
                std::optional<ProductIdentifier>
                getProductIdentifier();
 
                static
                Compatibility
                getCompatibility();
 
                SearchInterface(const SearchInterface&) = delete;
                SearchInterface& operator=(const SearchInterface&) = delete;
                SearchInterface();
                virtual ~SearchInterface();
        };
 
        /*
         * API versioning.
         *
         * NIST code will extern the version number symbols. Participant code
         * shall compile them into their core library.
         */
        #ifdef NIST_EXTERN_FRIF_E1N_API_VERSION
        extern uint16_t API_MAJOR_VERSION;
        extern uint16_t API_MINOR_VERSION;
        extern uint16_t API_PATCH_VERSION;
        #else /* NIST_EXTERN_FRIF_E1N_API_VERSION */
        uint16_t API_MAJOR_VERSION{0};
        uint16_t API_MINOR_VERSION{0};
        uint16_t API_PATCH_VERSION{1};
        #endif /* NIST_EXTERN_FRIF_E1N_API_VERSION */
}
 
#endif /* FRIF_EVALUATIONS_E1N_H_ */