include/fsdk/IDescriptor.h

Go to the documentation of this file.

#pragma once

#include <fsdk/IObject.h>
#include <fsdk/IDetector.h>
#include <fsdk/FSDKError.h>
#include <fsdk/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 DescriptorType {
        DT_FACE,        
        DT_HUMAN        
    };
    
    enum DescriptorVersion : uint32_t {
        DV_MIN_FACE_DESCRIPTOR_VERSION  = 46,       
        DV_MIN_HUMAN_DESCRIPTOR_VERSION = 102       
    };

    enum HumanDescriptorVersion : uint32_t {
        HDV_TRACKER_HUMAN_DESCRIPTOR_VERSION = 102,     
        HDV_PRECISE_HUMAN_DESCRIPTOR_VERSION = 103,     
        HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION = 104,     
        HDV_TRACKER_V2 = 105,                           
        HDV_PRECISE_V2 = 106,                           
        HDV_REGULAR_V2 = 107,                           
        HDV_TRACKER_V3 = 108,                           
        HDV_PRECISE_V3 = 109,                           
        HDV_REGULAR_V3 = 110,                           
        HDV_PRECISE_V4 = 112,                           
        HDV_REGULAR_V4 = 113                            
    };
    
    struct IDescriptor : IDataStorageObject {
        virtual uint32_t getModelVersion() const noexcept = 0;
        
        virtual DescriptorType 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(uint32_t index) noexcept = 0;

        virtual Result<Error> removeSlow(uint32_t 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 DescriptorType getDescriptorType() const noexcept = 0;

        virtual uint32_t getDescriptorLength() const noexcept = 0;

        virtual ResultValue<FSDKError, IDescriptorPtr> getDescriptorSlow(uint32_t index) const noexcept = 0;

        virtual ResultValue<FSDKError, IDescriptorPtr> 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>
        extractFromWarpedImage(
            const Image& warp,
            IDescriptor* descriptor) const noexcept = 0;

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

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

        virtual Result<FSDKError>
        validate(
            Span<const Image> warps,
            Span<Result<FSDKError>> errors) const noexcept = 0;

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

         using FutureResult = vlc::future<float>;

        virtual FutureResult extractFromWarpedImageBatchAsync(
            Span<const Image> warps,
            IDescriptorBatch* descriptorBatch,
            IDescriptor* aggregation,
            Span<float> garbageScoreBatch) const = 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,
            Span<MatchingResult> results) noexcept = 0;

        virtual uint32_t getModelVersion() const noexcept = 0;

        virtual Result<FSDKError> calcSimilarity(Span<MatchingResult> distances) const noexcept = 0;

        virtual Result<FSDKError> calcDistance(Span<MatchingResult> similarities) const noexcept = 0;
    };
}