liveness_pipeline.h

Go to the documentation of this file.

/* Copyright 2021 ID R&D Inc. All Rights Reserved. */

#pragma once

#include <string>
#include <memory>
#include <ostream>
#include <utility>
#include <vector>
#include <unordered_map>

#include "config.h"
#include "image.h"

namespace docsdk {

struct LivenessPipelineResult {
    enum class ValidationStatusCode {
        kOk,                       
        kDocumentTooCloseToCamera, 
        kDocumentTooCloseToBorder, 
        kDocumentCropped,          
        kDocumentNotFound,         
        kDocumentTooSmall,         
        kTooManyDocuments,         
        kDocumentIsColorless,      
        kDocumentPhotoNotFound     
    };

    enum class ImageQualityWarning {
        kRelativeDocumentSizeLowerThan10Percent, 
        kDocumentBordersOutsideOfFrame,          
        kMultipleDocumentsInFrame,               
        kDocumentTooCloseToBorder,               
        kImageTooBlurry,                         
        kImageTooCompressed,                     
        kPoorImageExposure,                      
        kGlareOnImage,                           
    };

    struct Value {
        float liveness_probability; 
        float liveness_score;       
        float quality_score = 0;

        std::vector<ImageQualityWarning> image_quality_warnings; 
        Value() = default;
        Value(float liveness_probability, float liveness_score, float quality_score,
              std::vector<ImageQualityWarning> image_quality_warnings = {})
            : liveness_probability(liveness_probability),
              liveness_score(liveness_score),
              quality_score(quality_score),
              image_quality_warnings(std::move(image_quality_warnings)) {}

        friend std::ostream& operator<<(std::ostream& os, const Value& result) {
            os << "LivenessPipelineResult::Value["
               << " liveness_probability: " << result.liveness_probability
               << ", liveness_score: " << result.liveness_score << ", quality_score: " << result.quality_score
               << ", image_quality_warnings: [ ";
            for (size_t idx = 0; idx < result.image_quality_warnings.size(); ++idx) {
                if (idx != 0) {
                    os << ", ";
                }
                os << static_cast<int>(result.image_quality_warnings[idx]);
            }
            os << " ]";
            return os;
        }
    };

    LivenessPipelineResult() = default;
    explicit LivenessPipelineResult(ValidationStatusCode status_code) : status_code(status_code) {}
    explicit LivenessPipelineResult(Value value) : value(std::move(value)), status_code(ValidationStatusCode::kOk) {}

    const Value& GetValue() const {
        if (Ok()) {
            return value;
        } else {
            throw std::runtime_error("LivenessPipelineResult: value is not available, because status code is not kOk");
        }
    }

    const ValidationStatusCode& GetStatusCode() const noexcept {
        return status_code;
    }

    bool Ok() const noexcept {
        return status_code == ValidationStatusCode::kOk;
    }

    friend std::ostream& operator<<(std::ostream& os, const LivenessPipelineResult& result) {
        os << "LivenessPipelineResult[ status: " << static_cast<int>(result.status_code) << ", value: ";
        if (result.Ok()) {
            os << result.value;
        } else {
            os << "unavailable";
        }
        os << " ]";
        return os;
    }

 private:
    Value value{};
    ValidationStatusCode status_code = ValidationStatusCode::kOk;
};

struct LivenessCheckOptions {
    enum class Calibration {
        kRegular, 
        kSoft,    
        kHard     
    };

    std::vector<LivenessPipelineResult::ValidationStatusCode> errors_to_ignore;

    Calibration calibration = Calibration::kRegular;

    friend std::ostream& operator<<(std::ostream& os, const LivenessCheckOptions& options) {
        os << "LivenessCheckOptions[ calibration: " << static_cast<int>(options.calibration) << " ]";
        return os;
    }
};

class DOCSDK_API LivenessPipeline {
 public:
    using Ptr = std::shared_ptr<LivenessPipeline>;

    static Ptr Create(const std::string& path_to_config);

    virtual LivenessPipelineResult CheckLiveness(Image::Ptr image, const LivenessCheckOptions& options = {}) const = 0;

    virtual LivenessPipelineResult CheckLivenessSequence(const std::vector<Image::Ptr>& images,
                                                         const LivenessCheckOptions& options = {}) const = 0;

    virtual ~LivenessPipeline() noexcept = default;
};

class DOCSDK_API LivenessPipelineComposition {
 public:
    using Ptr = std::shared_ptr<LivenessPipelineComposition>;

    static Ptr Create(const std::vector<std::string>& paths_to_configs);

    virtual std::unordered_map<std::string, LivenessPipelineResult> CheckLiveness(
            Image::Ptr image, const std::unordered_map<std::string, LivenessCheckOptions>& options = {}) const = 0;

    virtual ~LivenessPipelineComposition() noexcept = default;
};

}  // namespace docsdk