Updating Detect (#98)

* Updating Detect

* SP-9396: Add attributes detect details (#99)

* added descriptions

* fixed descriprions + remaned timer to elapsedTime

* Removed originalRect

* adjusted descriptions + added AttributesAll member to FaceQualityScenarios enum

* https://app.clickup.com/t/4535044/SP-17852

* minor fix

* fixes according to review https://app.clickup.com/t/4535044/SP-9396

* adjusted scenarion description in the request and elapsedTime descriptions

* adjusted links to docs

* minor fix

---------

Co-authored-by: Alexander Gubin <aliaksandr.hubin@regula.us>
Co-authored-by: Kiryl Kovaliov <kkirusha@gmail.com>

Author: 3 people

common.yml

@@ -51,13 +51,13 @@ components:
         onlyCentralFace:
           type: boolean
           description: "Whether to process only the central face in the image. If set to `false`, all the faces are processed."
-          example: false
+          example: true
         outputImageParams:
           $ref: "#/components/schemas/OutputImageParams"
         quality:
           $ref: "#/components/schemas/QualityRequest"
         attributes:
-          description: "If set, the selected attributes, such as age or emotions, are evaluated."
+          description: "If set, the selected attributes, such as age or emotions, are evaluated. To check all the available attributes, you can set the `AttributesAll` scenario in `processParam.scenario`."
           type: object
           properties:
             config:
@@ -75,7 +75,7 @@ components:
 
     QualityRequest:
       type: object
-      description: "If set, the face image quality check is performed according to the set scenario or characteristics."
+      description: "If set, the face image quality check is performed according to the given list of [characteristics](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/face-image-quality-check/) in `quality.config`."
       properties:
         backgroundMatchColor:
           description: "The RGB value for the background color: the silhouette of a person is cut out and the background is filled with this color."
@@ -85,7 +85,7 @@ components:
 
     Crop:
       type: object
-      description: "Whether to return a Base64-encoded image of an aligned and cropped portrait in the `crop` field. Alignment is performed according to `type`; if a head on the original image is tilted, for the returned portrait it is aligned in a straight vertical line. If there are more than one face in the photo, all the faces are detected and processed, and separate portraits for each face are returned. So, if there are five people in the photo, you'll get five processed portraits. Each portrait can be downloaded."
+      description: "Whether to return a Base64-encoded image of each aligned and cropped portrait in the `crop` field. Faces are aligned to a straight vertical line based on the value in the `crop.type` field, correcting any tilt present in the original image. If the image contains multiple faces, the system will detect and process each face separately, returning individual portraits. For example, if there are five people in the photo, five processed portraits will be returned. Each portrait is available for download."
       properties:
         type:
           $ref: "#/components/schemas/FaceImageQualityAlignType"
@@ -102,10 +102,6 @@ components:
           maxItems: 2
           description: "The resize value in case `type` matches this value. If it doesn't, no resize is performed."
           example: [300, 400]
-        returnOriginalRect:
-          type: boolean
-          description: "Whether to return the coordinates of the rectangle with the face in the original image prepared for the face crop."
-          example: true
 
     QualityConfigList:
       type: array
@@ -128,7 +124,7 @@ components:
             format: float
           minItems: 2
           maxItems: 2
-          description: "The range of applicable values for this characteristic. If the returned in the response value fits this range, the characteristic is identified as compliant with the requirements."
+          description: "The range of applicable values for this characteristic. If the returned in the response value fits this range, the characteristic is identified as compliant with the requirements. For recommended ranges, see [Face Image Quality Assessment](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/face-image-quality-check/)."
           example: [x, y]
 
     AttributeConfigList:
@@ -177,7 +173,7 @@ components:
           example: "Roll"
         range:
           type: array
-          description: "The range of set values for this characteristic."
+          description: "The range of set values for this characteristic, see the [Recommended range column](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/face-image-quality-check/)."
           items:
             type: number
             format: float
@@ -191,7 +187,7 @@ components:
         value:
           type: number
           format: float
-          description: "The assessed value for the characteristic, returned in the set units."
+          description: "The result value for the characteristic, returned in set units."
           example: 0.0
 
     RGB:
@@ -205,7 +201,7 @@ components:
 
     FaceImageQualityStatus:
       type: integer
-      description: "The processing status returned for each assessed quality characteristic." 
+      description: "The processing status returned for each quality characteristic, see the [FaceImageQualityStatus enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-status/)." 
       enum:
         - 0
         - 1
@@ -217,13 +213,8 @@ components:
 
     FaceQualityScenarios:
       type: string
-      description: "Face detection scenario. If applied and the scenario is found, the parameters are set automatically and any other parameters mentioned in the request are ignored.
-      
-
-      If not set, left empty, or the name is not found, the processing is performed according to the set parameters.
-
-
-      You can find detailed descriptions of available scenarios on the [Scenarios page](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/scenarios/)."
+      description: "Face detection scenario. If set and the scenario is found, it automatically applies the relevant parameters, overriding any other parameters specified in the request. If the scenario is not set, is empty, or the name is not recognized, processing will follow the parameters directly set in the request. For detailed descriptions of available scenarios, refer to the [Scenarios page](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/scenarios/)."
+      example: "QualityICAO"
       enum:
         - "OldMode"
         - "QualityFull"
@@ -233,6 +224,7 @@ components:
         - "CropCentralFace"
         - "CropAllFaces"
         - "Thumbnail"
+        - "AttributesAll"
         - ""
       x-enum-varnames:
         - OLD_MODE
@@ -243,11 +235,12 @@ components:
         - CROP_CENTRAL_FACE
         - CROP_ALL_FACES
         - THUMBNAIL
+        - ATTRIBUTES_ALL
         - EMPTY
 
     FaceImageQualityGroups:
       type: integer
-      description: "Face image quality group types for face image quality assessment."
+      description: "The group ID of the characteristic, see the [FaceImageQualityGroups enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-groups/) for details."
       enum:
         - 1
         - 2
@@ -268,7 +261,7 @@ components:
         - BACKGROUND
     FaceImageQualityGroupsStrings:
       type: string
-      description: "Face image quality group types for face image quality assessment."
+      description: "Face image quality assessment group name, see [FaceImageQualityGroups](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-groups/)."
       enum:
         - "ImageCharacteristics"
         - "HeadSizeAndPosition"
@@ -290,7 +283,7 @@ components:
 
     FaceQualityConfigName:
       type: string
-      description: "The name of the quality check characteristic. For definitions, see the [FaceQualityConfigName enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-quality-config-name/)."
+      description: "The name of the characteristic. For definitions, see the [FaceQualityConfigName enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-quality-config-name/)."
       enum:
         - "ImageWidth"
         - "ImageHeight"
@@ -399,7 +392,7 @@ components:
           $ref: "#/components/schemas/FaceSDKResultCode"
 
     ImageData:
-      description: "Base64-encoded image."
+      description: "Thumbnail: Base64-encoded image."
       type: string
       format: byte
 

detect.yml

@@ -10,18 +10,18 @@ paths:
       description: "Use the POST `api/detect` endpoint to analyze images, recognize faces in them, and return cropped and aligned portraits of the detected people. 
       
       
-      The Face Detection feature lets you:
+      The Face Detection feature lets you additionally:
 
-      - **Check face image quality**: Assess whether a portrait meets certain standards, for example, ICAO, Schengen visa, USA visa. To perform image quality check, use the `processParam.quality` field.
+      - **Check face image quality**: Assess whether a portrait meets certain standards, for example, ICAO, Schengen visa, USA visa. To perform image quality check, use the `processParam.quality` field. For the list of assessed characteristics, see the [Face Image Quality Characteristics page](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/face-image-quality-check/).
 
-      - **Evaluate face attributes**: Estimate the age range of a person; check whether the eyes are occluded, closed, or open; detect a facial expression or smile; see if there are glasses, sunglasses, head coverage, medical mask, etc. To evaluate attributes, add the `processParam.attributes` field.
+      - **Evaluate face attributes**: Estimate the age range of a person; check whether the eyes are occluded, closed, or open; detect a facial expression or smile; see if there are glasses, sunglasses, head coverage, medical mask, etc. To evaluate attributes, add the `processParam.attributes` field. For the list of assessed attributes, see the [Attributes List page](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/attributes-detection/).
 
       
       You can perform Face Detection in two ways:
 
-      - By adding parameters manually. In this case, the configuration is not saved and can not be automatically repeated.
+      - By adding parameters manually. In this case, the configuration is not saved and you will need to add all the necessary parameters to each request.
       
-      - By a processing `scenario` that includes certain parameters. You can use predefined scenarios or add custom ones."      
+      - By a processing `scenario` that includes certain parameters. You can use predefined scenarios or add custom ones. For detailed information about scenarios, refer to the [Scenarios page](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/scenarios/)."      
       operationId: detect
       requestBody:
         required: true
@@ -51,11 +51,6 @@ components:
           $ref: "./common.yml#/components/schemas/ProcessParam"
         image:
           $ref: "./common.yml#/components/schemas/ImageData"
-        thumbnails:
-          description: "Use `processParam.outputImageParams.crop` instead."
-          deprecated: true
-          type: boolean
-          default: false
 
     DetectResponse:
       allOf:
@@ -67,11 +62,13 @@ components:
 
     DetectResult:
       type: object
+      description: "The detection results."
       required:
         - detections
       properties:
         detections:
           type: array
+          description: "The array of performed checks."
           items:
             $ref: "#/components/schemas/Detection"
         detectorType:
@@ -81,14 +78,39 @@ components:
           description: "Internal."
           type: integer
         scenario:
-          description: "Scenario from Request processParam."
-          $ref: "./common.yml#/components/schemas/FaceQualityScenarios"
-        timer:
+          description: "The face detection scenario that was set in the `processParam.scenario` field of the request."
+          type: string
+        elapsedTime:
           type: number
           format: float
-          description: "The total time taken for the detection."
+          description: "Server processing time, ms. Does not include the time taken to receive the request or deliver the response."
           example: 0.84793560000000001
 
+    DetectAttributesDetails:
+      type: object
+      properties:
+        name:
+          type: string
+          description: "The name of the attribute."
+        value:
+          type: array
+          description: "The estimated value for the attribute, see the [Returned values column](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/attributes-detection/)."
+          items:
+            type: integer
+
+    DetectDetailsMeta:
+      type: object
+      properties:
+        confidence:
+          type: number
+          description: "The confidence in the estimated value, `1.0` is for 100% confidence."
+          format: float
+        value:
+          type: string
+          description: "The estimated value for the attribute, see the [Returned values column](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/attributes-detection/)."
+        name:
+          type: string
+          description: "The name of the attribute."
     Detection:
       type: object
       required:
@@ -100,17 +122,22 @@ components:
           $ref: "./common.yml#/components/schemas/ImageData"
         attributes:
           type: object
+          description: "The evaluated attributes, see the [Attributes List](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/attributes-detection/) for details."
           properties:
             details:
               type: array
+              description: "Attributes assessment details. Returns `DetectDetailsMeta` or `DetectAttributesDetails`."
               items:
-                type: object
-                additionalProperties: true
+                items:
+                  anyOf:
+                    - $ref: '#/components/schemas/DetectAttributesDetails'
+                    - $ref: '#/components/schemas/DetectDetailsMeta'
+
             elapsedTime:
               type: number
-              description: "The elapsed time for attribute detection."
+              description: "Server processing time for attribute detection, ms."
         landmarks:
-          description: "Absolute coordinates (x,y) of five points of each detected face: left eye, right eye, nose, left point of lips, right point of lips."
+          description: "Absolute coordinates (X,Y) of five points of each detected face: left eye, right eye, nose, left point of lips, right point of lips."
           type: array
           items:
             description: "Cartesian points. First element - X-axis coordinate. Second element - Y-axis coordinate."
@@ -121,35 +148,35 @@ components:
           example: [ [ x, y ] ]
         quality:
           type: object
-          description: "Field for checking the portrait quality. If it is not mentioned, no quality check is performed."
+          description: "The portrait quality assessment results, see [Face Image Quality Characteristics](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/face-image-quality-check/). If not set in request, no quality check is performed."
           properties:
             nonCompliant:
               type: array
-              description: "The array of all the non-compliant assessment characteristics."
+              description: "Non-compliant assessment characteristics."
               items:
                 $ref: "./common.yml#/components/schemas/FaceQualityConfigName"
               example: ["ImageWidthToHeight", "Yaw"]
             detailsGroups:
-              description: "The array of the assessment results for each group of characteristics."
+              description: "Assessment results for each [group of characteristics](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-groups/)."
               type: array
               items:
                 $ref: "./common.yml#/components/schemas/QualityDetailsGroups"
             details:
               type: array
-              description: "The array of the assessment characteristics that were set in the request."
+              description: "Assessment characteristics that were set in the request."
               items:
                 $ref: "./common.yml#/components/schemas/QualityDetail"
 
             score:
               type: number
               format: float
               description: "Returns the estimated portrait quality assessment result,
-               a number from 0 to 1, where 1 is for absolute compliance."
+               a number from `0` to `1`, where `1` is for absolute compliance."
               example: -1.0
-            timer:
+            elapsedTime:
               type: number
               format: float
-              description: "The total time the quality assessment has taken."
+              description: "Server processing time for quality assessment, ms."
               example: 0.42036411166191101
         roi:
           $ref: "./common.yml#/components/schemas/FaceRectangular"

match_and_search.yml

@@ -62,7 +62,7 @@ components:
                 $ref: './matching.yml#/components/schemas/MatchImageResult'
             elapsedTime:
               type: number
-              description: "Time the processing has taken, ms."
+              description: "Server processing time, ms. Does not include the time taken to receive the request or deliver the response."
               format: float
               example: 1.317137987
             metadata:

matching.yml

@@ -52,10 +52,7 @@ components:
         tag:
           type: string
           description: "Session identificator, should be unique for each session."
-        thumbnails:
-          description: "Use `outputImageParams.crop` instead."
-          deprecated: true
-        images:
+        images: 
           type: array
           description: "All images included in the comparison."
           items: