efs.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_EFS_H_
#define FRIF_EFS_H_
 
#include <unordered_map>
#include <variant>
 
#include <frifte/common.h>

namespace FRIF::EFS
{
        enum class Impression
        {
                PlainContact = 0,
                RolledContact = 1,
                Latent = 4,
                LiveScanSwipe = 8,
                PlainContactlessStationary = 24,
                RolledContactlessStationary = 25,
                Other = 28,
                Unknown = 29,
                Contactless = 43
        };

        using IMP = Impression;

        Impression
        toImpression(
            const std::underlying_type_t<Impression> i);

        enum class FrictionRidgeCaptureTechnology
        {
                Unknown = 0,
                ScannedInkOnPaper = 2,
                OpticalTIRBright = 3,
                OpticalDirect = 5,
                Capacitive = 9,
                Electroluminescent = 11,
 
                LatentImpression = 18,
                LatentLift = 22
        };

        using FCT = FrictionRidgeCaptureTechnology;

        FrictionRidgeCaptureTechnology
        toFrictionRidgeCaptureTechnology(
            const std::underlying_type_t<FrictionRidgeCaptureTechnology> i);

        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,
 
                PlainRightThumb = 11,
                PlainLeftThumb = 12,
 
                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
        };

        using FGP = FrictionRidgeGeneralizedPosition;

        FrictionRidgeGeneralizedPosition
        toFrictionRidgeGeneralizedPosition(
            const std::underlying_type_t<FrictionRidgeGeneralizedPosition> i);

        enum class ProcessingMethod
        {
                Indanedione,
                BlackPowder,
                Other,
                Cyanoacrylate,
                Laser,
                RUVIS,
                StickysidePowder,
                Visual,
                WhitePowder
        };

        using LPM = ProcessingMethod;

        ProcessingMethod
        toProcessingMethod(
            const std::underlying_type_t<ProcessingMethod> i);

        enum class PatternGeneralClassification
        {
                Arch,
                Whorl,
                RightLoop,
                LeftLoop,
                Amputation,
                UnableToPrint,
                Unclassifiable,
                Scar,
                DissociatedRidges
        };

        using GCF = PatternGeneralClassification;

        PatternGeneralClassification
        toPatternGeneralClassification(
            const std::underlying_type_t<PatternGeneralClassification> i);

        enum class ArchPatternSubclassification
        {
                PlainArch,
                TentedArch
        };

        ArchPatternSubclassification
        toArchPatternSubclassification(
            const std::underlying_type_t<ArchPatternSubclassification> i);

        enum class WhorlPatternSubclassification
        {
                PlainWhorl,
                CentralPocketLoop,
                DoubleLoop,
                AccidentalWhorl
        };

        WhorlPatternSubclassification
        toWhorlPatternSubclassification(
            const std::underlying_type_t<WhorlPatternSubclassification> i);

        using PatternSubclassification = std::variant<
            ArchPatternSubclassification, WhorlPatternSubclassification>;

        using SUB = PatternSubclassification;

        enum class WhorlDeltaRelationship
        {
                Inner,
                Outer,
                Meeting
        };

        WhorlDeltaRelationship
        toWhorlDeltaRelationship(
            const std::underlying_type_t<WhorlDeltaRelationship> i);

        using WDR = WhorlDeltaRelationship;

        class PatternClassification
        {
        public:
                PatternClassification(
                    const PatternGeneralClassification,
                    const std::optional<PatternSubclassification> = {},
                    const std::optional<WhorlDeltaRelationship> = {});

                void
                setPatternGeneralClassification(
                    const PatternGeneralClassification);

                void
                setPatternSubclassification(
                    const PatternSubclassification);

                void
                setWhorlDeltaRelationship(
                    const WhorlDeltaRelationship);

                PatternGeneralClassification
                getPatternGeneralClassification()
                    const;

                std::optional<PatternSubclassification>
                getPatternSubclassification()
                    const;

                std::optional<WhorlDeltaRelationship>
                getWhorlDeltaRelationship()
                    const;
 
        private:
                PatternGeneralClassification gcf{};
                std::optional<PatternSubclassification> sub{};
                std::optional<WhorlDeltaRelationship> wdr{};
        };

        enum class ValueAssessment
        {
                Value,
                Limited,
                NoValue,
                NonPrint
        };

        using EAA = ValueAssessment;

        ValueAssessment
        toValueAssessment(
            const std::underlying_type_t<ValueAssessment> i);

        enum class Substrate
        {
                Paper,
                PorousOther,
 
                Plastic,
                Glass,
                MetalPainted,
                MetalUnpainted,
                TapeAdhesiveSide,
                NonporousOther,
 
                PaperGlossy,
                SemiporousOther,
 
                Other,
                Unknown
        };

        Substrate
        toSubstrate(
            const std::underlying_type_t<Substrate> i);

        enum class MinutiaType
        {
                RidgeEnding,
                Bifurcation,
                Other,
                Unknown
        };

        MinutiaType
        toMinutiaType(
            const std::underlying_type_t<MinutiaType> i);

        struct Minutia
        {
                Coordinate coordinate{};
                std::optional<uint16_t> coordinateUncertainty{};

                uint16_t theta{};
                std::optional<uint8_t> thetaUncertainty{};

                MinutiaType type{MinutiaType::Unknown};

                Minutia(
                    const Coordinate &coordinate = {},
                    const uint16_t theta = {},
                    const MinutiaType type = MinutiaType::Unknown,
                    const std::optional<uint16_t> coordinateUncertainty = {},
                    const std::optional<uint8_t> thetaUncertainty = {});
        };

        struct Core
        {
                Coordinate coordinate{};
                std::optional<uint16_t> coordinateUncertainty{};

                std::optional<uint16_t> direction{};
                std::optional<uint8_t> directionUncertainty{};

                Core(
                    const Coordinate &coordinate = {},
                    const std::optional<uint16_t> &direction = {},
                    const std::optional<uint16_t> coordinateUncertainty = {},
                    const std::optional<uint8_t> directionUncertainty = {});
        };

        struct Delta
        {
                Coordinate coordinate{};
                std::optional<uint16_t> coordinateUncertainty{};

                std::optional<std::tuple<std::optional<uint16_t>,
                    std::optional<uint16_t>, std::optional<uint16_t>>>
                    direction{};
                std::optional<std::tuple<std::optional<uint8_t>,
                    std::optional<uint8_t>, std::optional<uint8_t>>>
                    directionUncertainty{};

                Delta(
                    const Coordinate &coordinate = {},
                    const std::optional<std::tuple<std::optional<uint16_t>,
                        std::optional<uint16_t>, std::optional<uint16_t>>>
                        &direction = {},
                    std::optional<uint16_t> coordinateUncertainty = {},
                    const std::optional<std::tuple<std::optional<uint8_t>,
                        std::optional<uint8_t>, std::optional<uint8_t>>>
                        &directionUncertainty = {});
        };

        struct Orientation
        {
                int16_t direction{0};
                std::optional<uint8_t> uncertainty{15};

                Orientation(
                    const int16_t direction = 0,
                    const std::optional<uint8_t> &uncertainty = 15);
        };

        enum class CorrespondenceType
        {
                Definite,
                Possible,
                DoesNotExist,
                OutOfRegion,
                UnclearArea
        };
        using TOC = CorrespondenceType;

        CorrespondenceType
        toCorrespondenceType(
            const std::underlying_type_t<CorrespondenceType> i);

        struct CorrespondenceRelationship
        {
                CorrespondenceType type{};

                std::string probeIdentifier{};
                FrictionRidgeGeneralizedPosition probeFGP{};
                uint8_t probeInputIdentifier{};
                Minutia probeMinutia{};

                std::string referenceIdentifier{};
                FrictionRidgeGeneralizedPosition referenceFGP{};
                uint8_t referenceInputIdentifier{};
                /**
                 * Location in the reference image of a probe image feature.
                 * @note
                 * This Minutia may be omitted if the #type indicates it.
                 */
                Minutia referenceMinutia{};


                CorrespondenceRelationship(
                    const CorrespondenceType type = {},
                    const std::string &probeIdentifier = {},
                    const FrictionRidgeGeneralizedPosition probeFGP = {},
                    const uint8_t probeInputIdentifier = {},
                    const Minutia &probeMinutia = {},
                    const std::string &referenceIdentifier = {},
                    const FrictionRidgeGeneralizedPosition referenceFGP = {},
                    const uint8_t referenceInputIdentifier = {},
                    const Minutia &referenceMinutia = {});
        };

        enum class RidgeQuality
        {
                Background = 0,
                DebatableRidgeFlow = 1,
                DebatableMinutiae = 2,
                DefinitiveMinutiae = 3,
                DefinitiveRidgeEdges = 4,
                DefinitivePores = 5
        };

        RidgeQuality
        toRidgeQuality(
            const std::underlying_type_t<RidgeQuality> i);

        struct RidgeQualityRegion
        {
                std::vector<Coordinate> region{};
                RidgeQuality quality{RidgeQuality::Background};
        };

        enum class FingerCrease
        {
                DistalInterphalangeal,
                ProximalInterphalangeal,
                ProximalDigital
        };

        FingerCrease
        toFingerCrease(
            const std::underlying_type_t<FingerCrease> i);

        enum class PalmCrease
        {
                DistalTransverse,
                Top = DistalTransverse,

                ProximalTransverse,
                Middle = ProximalTransverse,

                RadialLongitudinal,
                Bottom = RadialLongitudinal,

                Wrist,
                WristBracelet = Wrist
        };

        PalmCrease
        toPalmCrease(
            const std::underlying_type_t<PalmCrease> i);

        enum class LinearDiscontinuity
        {
                MinorCrease,
                Crack,
                Cut,
                NonPermanentScar,
                /*
                 * XXX: Considered a distinctive area in ANSI/NIST-ITL 1-2011
                 * Update:2015, requiring a polygon, not a segment.
                 */
//              PermanentScar,
                Other
        };

        LinearDiscontinuity
        toLinearDiscontinuity(
            const std::underlying_type_t<LinearDiscontinuity> i);

        using CreaseClassification = std::variant<FingerCrease, PalmCrease,
            LinearDiscontinuity>;

        class Crease
        {
        public:
                Crease(
                    const FrictionRidgeGeneralizedPosition fgp,
                    const CreaseClassification cld,
                    const std::vector<Segment> &segments);

                FrictionRidgeGeneralizedPosition
                getFrictionRidgeGeneralizedPosition()
                    const;

                void
                setFrictionRidgeGeneralizedPosition(
                    const FrictionRidgeGeneralizedPosition fgp);

                CreaseClassification
                getCreaseClassification()
                    const;

                void
                setCreaseClassification(
                    const CreaseClassification cld);

                std::vector<Segment>
                getSegments()
                    const;

                void
                addSegment(
                    const Segment &segment);

                void
                setSegments(
                    const std::vector<Segment> &segments);
 
        private:
                FrictionRidgeGeneralizedPosition fgp{};
                CreaseClassification cld{};
                std::vector<Segment> segments{};
        };

        class QualityMeasure
        {
        public:
                enum class Status : uint8_t
                {
                        Success = 0,

                        NotComputed = 254,
                        Error = 255
                };

                struct Description
                {
                        std::optional<ProductIdentifier> identifier{};
                        std::optional<std::string> version{};
                        std::optional<std::string> comment{};
                        std::optional<std::string> modelSHA256{};
 
                        std::strong_ordering
                        operator<=>(
                            const Description&)
                            const;
                        bool operator==(const Description&) const;
                };

                static const Description NFIQ2v23;

                struct DescriptionHash
                {
                        std::size_t
                        operator()(
                            const Description &d)
                            const;
                };
 
                QualityMeasure();

                QualityMeasure(
                    const double value);

                QualityMeasure(
                    const std::string &errorMessage);

                explicit operator bool()
                    const
                    noexcept;

                bool
                hasValue()
                    const
                    noexcept;

                double
                operator*()
                    const;

                double
                getValue()
                    const;
 
                Status
                getStatus()
                    const;

                void
                setError(
                    const std::string &errorMessage);
 
                std::optional<std::string>
                getMessage()
                    const;

                void
                setMessage(
                    const std::string &message);
 
        private:
                Status status{Status::NotComputed};

                std::optional<double> value{};

                std::optional<std::string> message{};
        };

        using QualityMeasureMap = std::unordered_map<
            QualityMeasure::Description, QualityMeasure,
            QualityMeasure::DescriptionHash>;

        struct Features
        {
                uint8_t identifier{};

                uint16_t ppi{};

                std::optional<QualityMeasureMap> quality{};

                Impression imp{Impression::Unknown};
                FrictionRidgeCaptureTechnology frct{
                    FrictionRidgeCaptureTechnology::Unknown};

                FrictionRidgeGeneralizedPosition frgp{
                    FrictionRidgeGeneralizedPosition::UnknownFrictionRidge};

                std::optional<Orientation> 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<Crease>> creases{};
                std::optional<std::vector<Coordinate>> roi{};

                std::optional<std::vector<RidgeQualityRegion>> rqm{};

                std::optional<bool> complex{};
        };
}
 
#endif /* FRIF_EFS_H_ */