diff --git a/common.yml b/common.yml old mode 100755 new mode 100644 index 698d918..d3dac6f --- a/common.yml +++ b/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 diff --git a/detect.yml b/detect.yml index aa899a0..46cc0ba 100644 --- a/detect.yml +++ b/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,22 +148,22 @@ 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" @@ -144,12 +171,12 @@ components: 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" diff --git a/match_and_search.yml b/match_and_search.yml index f2e30d0..2d1dd2d 100644 --- a/match_and_search.yml +++ b/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: diff --git a/matching.yml b/matching.yml index db5140f..1c530f7 100755 --- a/matching.yml +++ b/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: