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 = 54,  
        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,                       
        HDV_PRECISE_V5 = 115,                       
        HDV_REGULAR_V5 = 116                        
    };

    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;
    };

} // namespace fsdk