IDescriptor.h

Go to the documentation of this file.

#pragma once

#include "IObject.h"
#include "IDetector.h"
#include "FSDKError.h"
#include "Types.h"
#include <limits>

namespace fsdk {

#ifndef DOXYGEN_SHOULD_SKIP_THIS
    DECLARE_SMARTPTR(IDescriptor);
    DECLARE_SMARTPTR(IDescriptorBatch);
    DECLARE_SMARTPTR(IDescriptorMatcher);
    DECLARE_SMARTPTR(IDescriptorExtractor);
#endif
    
    struct MatchingResult {

        float distance;     
        float similarity;   

        MatchingResult(void) noexcept
            : distance(std::numeric_limits<float>::infinity())
            , similarity(0.f)
        {}

        MatchingResult(
            float distance,
            float similarity) noexcept
            : distance(distance)
            , similarity(similarity)
        {}
    };
    
    enum DesctiptorType {
        DT_FACE,        
        DT_HUMAN        
    };
    
    enum DescriptorVersion : uint32_t {
        DV_MIN_FACE_DESCRIPTOR_VERSION  = 46,       
        DV_MIN_HUMAN_DESCRIPTOR_VERSION = 101       
    };
    
    struct IDescriptor : IDataStorageObject {

        virtual uint32_t getModelVersion() const noexcept = 0;
        
        virtual DesctiptorType getDescriptorType() const noexcept = 0;

        virtual uint32_t getDescriptorLength() const noexcept = 0;

        virtual bool getDescriptor(uint8_t* buffer) const noexcept = 0;

        virtual void setDescriptor(const uint8_t* buffer) noexcept = 0;
    };

    struct IDescriptorBatch : IDataStorageObject {

        enum class Error : uint32_t {
            Ok,             
            InvalidInput,   
            BatchFull,      
            Incompatible,   
            Internal,       
            IoError,        
            OutOfRange,     
        };

        virtual Result<Error> add(IDescriptor* descriptor) noexcept = 0;

        virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset = 0) noexcept = 0;

        virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset, uint32_t count) noexcept = 0;

        virtual Result<Error> removeFast(int index) noexcept = 0;

        virtual Result<Error> removeSlow(int index) noexcept = 0;

        virtual Result<MultiError<ISerializableObject::Error,Error>> loadAndAdd(IArchive* archive) = 0;

        virtual uint32_t getMaxCount() const noexcept = 0;

        virtual uint32_t getCount() const noexcept = 0;

        virtual uint32_t getModelVersion() const noexcept = 0;
        
        virtual DesctiptorType getDescriptorType() const noexcept = 0;

        virtual uint32_t getDescriptorSize() const noexcept = 0;

        virtual IDescriptor* getDescriptorSlow(uint32_t index) const noexcept = 0;

        virtual IDescriptor* getDescriptorFast(uint32_t index) noexcept = 0;
    };

    template<>
    struct ErrorTraits<IDescriptorBatch::Error> {

        static bool isOk(IDescriptorBatch::Error error) noexcept {
            return error == IDescriptorBatch::Error::Ok;
        }

        static const char* toString (IDescriptorBatch::Error error) noexcept {
            switch(error) {
                case IDescriptorBatch::Error::Ok: return "Ok";
                case IDescriptorBatch::Error::IoError: return "Error during reading/writing";
                case IDescriptorBatch::Error::Internal: return "Internal error";
                case IDescriptorBatch::Error::BatchFull: return "Batch is full";
                case IDescriptorBatch::Error::OutOfRange: return "Descriptor out of range";
                case IDescriptorBatch::Error::Incompatible: return "Incompatible descriptor";
                case IDescriptorBatch::Error::InvalidInput: return "Invalid input";
                default: return "Unknown error";
            }
        }
    };
    
    struct IDescriptorExtractor : IRefCounted {
        virtual ResultValue<FSDKError, float>
        FSDK_DEPRECATED("IDescriptorExtractor::extract is deprecated. Use IDescriptorExtractor::extractFromWarpedImage method")
        extract(Image& image,
            const Detection& detection,
            const Landmarks5& landmarks,
            IDescriptor* descriptor) const noexcept = 0;

        virtual ResultValue<FSDKError, float>
        extractFromWarpedImage(
            const Image& image,
            IDescriptor* descriptor) const noexcept = 0;

        virtual ResultValue<FSDKError, float>
        extractFromWarpedImageBatch(
            const Image* warpsBatch,
            IDescriptorBatch* descriptorBatch,
            IDescriptor* aggregation,
            float* garbageScoreBatch,
            int batchSize) const noexcept = 0;

        virtual Result<FSDKError>
        extractFromWarpedImageBatch(
            const Image* warpsBatch,
            IDescriptorBatch* descriptorBatch,
            float* garbageScoreBatch,
            int batchSize) const noexcept = 0;

        virtual uint32_t getModelVersion() const noexcept = 0;
        
        virtual DesctiptorType getDescriptorType() const noexcept = 0;
    };

    struct IDescriptorMatcher : IRefCounted {

        virtual ResultValue<
                FSDKError,
                MatchingResult>
        match(
            const IDescriptor* first,
            const IDescriptor* second) noexcept = 0;

        virtual Result<FSDKError>
        match(
            const IDescriptor* reference,
            const IDescriptorBatch* candidates,
            MatchingResult* results) noexcept = 0;

        virtual uint32_t getModelVersion() const noexcept = 0;
    };
}