// Copyright 2026 BioID GmbH.
// Definition of the BWS 3 FaceImageQuality API.

syntax = "proto3";

package bioid.services.v1;

option java_package = "com.bioid.services";
option csharp_namespace = "BioID.Services";
import "bwsmessages.proto";

// BioID Face Image Quality Service definition.
service FaceImageQualityService {
    // Face image quality: enhanced quality measurements according to ISO/IEC 29794-5:2025, i.e. OFIQ
    rpc FaceImageQuality (FaceImageQualityRequest) returns (FaceImageQualityResponse);
}

// OFIQ request
message FaceImageQualityRequest {
    // The input face image.
    bytes image = 1;
}

// OFIQ response
message FaceImageQualityResponse {
    // The return-status of the processing job.
    JobStatus status = 1;
    // Any error messages collected during processing.
    repeated JobError errors = 2;
    // List of quality measurements performed.
    repeated QualityMeasurement quality_measurements = 3;
}

// A quality measure as calculated by the FaceImageQuality API.
message QualityMeasurement {
    // The quality measure performed.
    QualityMeasure measure = 1;
    // The raw score as computed by the quality measure implementation.
    double raw_value = 2;
    // A scalar value from the interval [0, 100] computed from the
    // raw score. Higher values mean higher quality.
    int32 scalar_score = 3;
}

// well known face image quality measures, which are identical
// to the registered quality assessment algorithm identifiers
enum QualityMeasure {
    Unspecified = 0;
    // general
    UnifiedQualityScore = 0x41;
    // capture related
    BackgroundUniformity = 0x42;
    IlluminationUniformity = 0x43;
    LuminanceMean = 0x44;
    LuminanceVariance = 0x45;
    UnderExposurePrevention = 0x46;
    OverExposurePrevention = 0x47;
    DynamicRange = 0x48;
    Sharpness = 0x49;
    CompressionArtifacts = 0x4a;
    NaturalColour = 0x4b;
    // subject related
    SingleFacePresent = 0x4c;
    EyesOpen = 0x4d;
    MouthClosed = 0x4e;
    EyesVisible = 0x4f;
    MouthOcclusionPrevention = 0x50;
    FaceOcclusionPrevention = 0x51;
    InterEyeDistance = 0x52;
    HeadSize = 0x53;
    LeftwardCropOfTheFaceImage = 0x54;
    RightwardCropOfTheFaceImage = 0x55;
    MarginAboveOfTheFaceImage = 0x56;
    MarginBelowOfTheFaceImage = 0x57;
    HeadPoseYaw = 0x58;
    HeadPosePitch = 0x59;
    HeadPoseRoll = 0x5a;
    ExpressionNeutrality = 0x5b;
    NoHeadCoverings = 0x5c;
    //ShoulderPresentation = 0x5d;
    //CameraSubjectDistance = 0x5e;
}