elft.h

Go to the documentation of this file.

 
#ifndef ELFT_H_
#define ELFT_H_
 
#include <cstddef>
#include <cstdint>
#include <filesystem>
#include <memory>
#include <optional>
#include <string>
#include <tuple>
#include <vector>
 
namespace ELFT
{
        enum class Impression
        {
                PlainContact = 0,
                RolledContact = 1,
                Latent = 4,
                LiveScanSwipe = 8,
                PlainContactlessStationary = 24,
                RolledContactlessStationary = 25,
                Other = 28,
                Unknown = 29,
                RolledContactlessMoving = 41,
                PlainContactlessMoving = 42
        };
 
        enum class FrictionRidgeCaptureTechnology
        {
                Unknown = 0,
                ScannedInkOnPaper = 2,
                OpticalTIRBright = 3,
                OpticalDirect = 5,
                Capacitive = 9,
                Electroluminescent = 11,
 
                LatentImpression = 18,
                LatentLift = 22
        };
 
        enum class FrictionRidgeGeneralizedPosition
        {
                UnknownFinger = 0,
                RightThumb = 1,
                RightIndex = 2,
                RightMiddle = 3,
                RightRing = 4,
                RightLittle = 5,
                LeftThumb = 6,
                LeftIndex = 7,
                LeftMiddle = 8,
                LeftRing = 9,
                LeftLittle = 10,
                RightExtraDigit = 16,
                LeftExtraDigit = 17,
 
                RightFour = 13,
                LeftFour = 14,
                RightAndLeftThumbs = 15,
 
                UnknownPalm = 20,
                RightFullPalm = 21,
                RightWritersPalm = 22,
                LeftFullPalm = 23,
                LeftWritersPalm = 24,
                RightLowerPalm = 25,
                RightUpperPalm = 26,
                LeftLowerPalm = 27,
                LeftUpperPalm = 28,
                RightPalmOther = 29,
                LeftPalmOther = 30,
                RightInterdigital = 31,
                RightThenar = 32,
                RightHypothenar = 33,
                LeftInterdigital = 34,
                LeftThenar = 35,
                LeftHypothenar = 36,
                RightGrasp = 37,
                LeftGrasp = 38,
                RightCarpalDeltaArea = 81,
                LeftCarpalDeltaArea = 82,
                RightFullPalmAndWritersPalm = 83,
                LeftFullPalmAndWritersPalm = 84,
                RightWristBracelet = 85,
                LeftWristBracelet = 86,
 
                UnknownFrictionRidge = 18,
                EJIOrTip = 19
        };
 
        enum class ProcessingMethod
        {
                Indanedione,
                BlackPowder,
                Other,
                Cyanoacrylate,
                Laser,
                RUVIS,
                StickysidePowder,
                Visual,
                WhitePowder
        };
 
        enum class PatternClassification
        {
                Arch,
                Whorl,
                RightLoop,
                LeftLoop,
                Amputation,
                UnableToPrint,
                Unclassifiable,
                Scar,
                DissociatedRidges
        };
 
        enum class ValueAssessment
        {
                Value,
                Limited,
                NoValue
        };
 
        enum class Substrate
        {
                Paper,
                PorousOther,
 
                Plastic,
                Glass,
                MetalPainted,
                MetalUnpainted,
                TapeAdhesiveSide,
                NonporousOther,
 
                PaperGlossy,
                SemiporousOther,
 
                Other,
                Unknown
        };
 
        struct ReturnStatus
        {
                enum class Result
                {
                        Success = 0,
                        Failure
                };
 
                Result result{};
                std::optional<std::string> message{};
 
                explicit operator bool()
                    const
                    noexcept;
        };
 
        struct Image
        {
                Image();
 
                Image(
                    const uint8_t identifier,
                    const uint16_t width,
                    const uint16_t height,
                    const uint16_t ppi,
                    const uint8_t bpc,
                    const uint8_t bpp,
                    const std::vector<std::byte> &pixels);
 
                uint8_t identifier{};
                uint16_t width{};
                uint16_t height{};
                uint16_t ppi{};
                uint8_t bpc{};
                uint8_t bpp{};
                std::vector<std::byte> pixels{};
        };
 
        struct Coordinate
        {
                uint32_t x{};
                uint32_t y{};
 
                Coordinate(
                    const uint32_t x = {},
                    const uint32_t y = {});
 
                bool
                operator==(
                    const Coordinate &rhs)
                    const;
 
                bool
                operator!=(
                    const Coordinate &rhs)
                    const;
 
                bool
                operator<(
                    const Coordinate &rhs)
                    const;
 
                bool
                operator<=(
                    const Coordinate &rhs)
                    const;
 
                bool
                operator>(
                    const Coordinate &rhs)
                    const;
 
                bool
                operator>=(
                    const Coordinate &rhs)
                    const;
        };
 
        enum class MinutiaType
        {
                RidgeEnding,
                Bifurcation,
                Other,
                Unknown
        };
 
        struct Minutia
        {
                Coordinate coordinate{};
                uint16_t theta{};
                MinutiaType type{MinutiaType::Unknown};
 
                Minutia(
                    const Coordinate &coordinate = {},
                    const uint16_t theta = {},
                    const MinutiaType type = MinutiaType::Unknown);
        };
 
        struct Core
        {
                Coordinate coordinate{};
                std::optional<uint16_t> direction{};
 
                Core(
                    const Coordinate &coordinate = {},
                    const std::optional<uint16_t> &direction = {});
        };
 
        struct Delta
        {
                Coordinate coordinate{};
                std::optional<std::tuple<std::optional<uint16_t>,
                    std::optional<uint16_t>, std::optional<uint16_t>>>
                    direction{};
 
                Delta(
                    const Coordinate &coordinate = {},
                    const std::optional<std::tuple<std::optional<uint16_t>,
                        std::optional<uint16_t>, std::optional<uint16_t>>>
                        &direction = {});
        };
 
        enum class CorrespondenceType
        {
                Definite,
                Possible,
                DoesNotExist,
                OutOfRegion,
                UnclearArea
        };
 
        struct Correspondence
        {
                CorrespondenceType type{};
 
                std::string probeIdentifier{};
                uint8_t probeInputIdentifier{};
                Minutia probeMinutia{};
 
                std::string referenceIdentifier{};
                uint8_t referenceInputIdentifier{};
                Minutia referenceMinutia{};
 
                Correspondence(
                    const CorrespondenceType type = {},
                    const std::string &probeIdentifier = {},
                    const uint8_t probeInputIdentifier = {},
                    const Minutia &probeMinutia = {},
                    const std::string &referenceIdentifier = {},
                    const uint8_t referenceInputIdentifier = {},
                    const Minutia &referenceMinutia = {});
        };
 
        struct CorrespondenceResult
        {
                struct Data
                {
                        std::vector<std::vector<Correspondence>>
                            correspondence{};
 
                        std::optional<bool> complex{};
 
                };
 
                ReturnStatus status{};
                Data data{};
        };
 
        enum class RidgeQuality
        {
                Background = 0,
                DebatableRidgeFlow = 1,
                DebatableMinutiae = 2,
                DefinitiveMinutiae = 3,
                DefinitiveRidgeEdges = 4,
                DefinitivePores = 5
        };
 
        struct RidgeQualityRegion
        {
                std::vector<Coordinate> region{};
                RidgeQuality quality{RidgeQuality::Background};
        };
 
        struct EFS
        {
                uint8_t identifier{};
 
                uint16_t ppi{};
 
                Impression imp{Impression::Unknown};
                FrictionRidgeCaptureTechnology frct{
                    FrictionRidgeCaptureTechnology::Unknown};
                FrictionRidgeGeneralizedPosition frgp{
                    FrictionRidgeGeneralizedPosition::UnknownFrictionRidge};
 
                std::optional<int16_t> orientation{};
                std::optional<std::vector<ProcessingMethod>> lpm{};
                std::optional<ValueAssessment> valueAssessment{};
                std::optional<Substrate> lsb{};
                std::optional<PatternClassification> pat{};
 
                std::optional<bool> plr{};
                std::optional<bool> trv{};
 
                std::optional<std::vector<Core>> cores{};
                std::optional<std::vector<Delta>> deltas{};
                std::optional<std::vector<Minutia>> minutiae{};
                std::optional<std::vector<Coordinate>> roi{};
 
                std::optional<std::vector<RidgeQualityRegion>> rqm{};
 
                std::optional<bool> complex{};
        };
 
        struct TemplateData
        {
                std::string candidateIdentifier{};
 
                uint8_t inputIdentifier{};
 
                std::optional<EFS> efs{};
 
                std::optional<uint8_t> imageQuality{};
        };
 
        struct CreateTemplateResult
        {
                ReturnStatus status{};
                std::vector<std::byte> data{};
 
                std::optional<std::vector<TemplateData>> extractedData{};
        };
 
        struct Candidate
        {
                std::string identifier{};
                FrictionRidgeGeneralizedPosition frgp{};
                double similarity{};
 
                Candidate(
                    const std::string &identifier = {},
                    const FrictionRidgeGeneralizedPosition frgp = {},
                    const double similarity = {});
 
                bool
                operator==(
                    const Candidate &rhs)
                    const;
 
                bool
                operator!=(
                    const Candidate &rhs)
                    const;
 
                bool
                operator<(
                    const Candidate &rhs)
                    const;
 
                bool
                operator<=(
                    const Candidate &rhs)
                    const;
 
                bool
                operator>(
                    const Candidate &rhs)
                    const;
 
                bool
                operator>=(
                    const Candidate &rhs)
                    const;
        };
 
        struct SearchResult
        {
                ReturnStatus status{};
                bool decision{};
                std::vector<Candidate> candidateList{};
 
                std::optional<CorrespondenceResult::Data> correspondence{};
        };
 
        enum class TemplateType
        {
                Probe,
                Reference
        };
 
        struct TemplateArchive
        {
                std::filesystem::path archive{};
                std::filesystem::path manifest{};
        };
 
        struct ProductIdentifier
        {
                struct CBEFFIdentifier
                {
                        uint16_t owner{};
                        std::optional<uint16_t> algorithm{};
                };
 
                std::optional<std::string> marketing{};
                std::optional<CBEFFIdentifier> cbeff{};
        };
 
        class ExtractionInterface
        {
        public:
                struct SubmissionIdentification
                {
                        SubmissionIdentification();
 
                        SubmissionIdentification(
                            const uint16_t versionNumber,
                            const std::string &libraryIdentifier,
                            const std::optional<ProductIdentifier>
                                &exemplarAlgorithmIdentifier = {},
                            const std::optional<ProductIdentifier>
                                &latentAlgorithmIdentifier = {});
 
                        uint16_t versionNumber{};
                        std::string libraryIdentifier{};
 
                        std::optional<ProductIdentifier>
                            exemplarAlgorithmIdentifier{};
                        std::optional<ProductIdentifier>
                            latentAlgorithmIdentifier{};
                };
 
                virtual
                SubmissionIdentification
                getIdentification()
                    const = 0;
 
                virtual
                CreateTemplateResult
                createTemplate(
                    const TemplateType templateType,
                    const std::string &identifier,
                    const std::vector<std::tuple<
                        std::optional<Image>, std::optional<EFS>>> &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);
 
                ExtractionInterface(const ExtractionInterface&) = delete;
                ExtractionInterface& operator=(const ExtractionInterface&) =
                    delete;
                ExtractionInterface();
                virtual ~ExtractionInterface();
        };
 
        class SearchInterface
        {
        public:
                virtual
                std::optional<ProductIdentifier>
                getIdentification()
                    const = 0;
 
                virtual
                ReturnStatus
                load(
                    const uint64_t maxSize) = 0;
 
                /**************************************************************/
 
                virtual
                SearchResult
                search(
                    const std::vector<std::byte> &probeTemplate,
                    const uint16_t maxCandidates)
                    const = 0;
 
                virtual
                std::optional<CorrespondenceResult>
                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);
 
                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_API_VERSION
        extern uint16_t API_MAJOR_VERSION;
        extern uint16_t API_MINOR_VERSION;
        extern uint16_t API_PATCH_VERSION;
        #else /* NIST_EXTERN_API_VERSION */
        uint16_t API_MAJOR_VERSION{1};
        uint16_t API_MINOR_VERSION{2};
        uint16_t API_PATCH_VERSION{1};
        #endif /* NIST_EXTERN_API_VERSION */
 
        /*
         * Ensure that std::byte is exactly 8 bits, such that reinterpret_casts
         * may be safely used.
         */
        static_assert(std::is_same_v<std::underlying_type_t<std::byte>,
            uint8_t>, "std::byte not represented as unsigned 8 bit type");
}
 
#endif /* ELFT_H_ */