SOAP Method Quality Check
Performs a rigorous quality check, which is crucial for enrollment, verification or identification.
[OperationContract] [FaultContract(typeof(BioIDWebServiceFault)] bool QualityCheck(Sample [] samples, out Sample [] processedSamples, out string messages, TestFlags flags, string issuer);
Parameters
| samples | The array of Samples to check. The array may contain samples of different traits. |
|---|---|
| processedSamples | Returns the array of processed samples. If an element from the samples array has been checked successfully, a normalized version of the sample is added to this output array, otherwise this array will contain an empty sample at this position. |
| messages | Returns an XML-string containing information about the checked samples (see BWSMessages). |
| flags | A combination of available TestFlags. |
| issuer | The quality checks of face images can be performed according to document-issuer specific settings defined by this parameter. Currently supported issuers are:ICAO (the default settings as specified by ICAO), BioID (similar to ICAO but with a bigger token image) and various ISO 3166-1 alpha-2 country codes specifying the document issuing country:AT (Austria), BR (Brazil), FI (Finland), DE (Germany), GR (Greece), HK (Hong Kong), IN (India), LT (Lithuania), MV (Maldives), NL (Netherlands), RU (Russia), CH (Switzerland), TR (Turkey), GB (United Kingdom), US (United States).The following country codes are currently defined, but they use the default ICAO parameter set: AU (Australia), BE (Belgium), BA (Bosnia and Herzegovina), BG (Bulgaria), HR (Croatia), CZ (Czech Republic), DK (Denmark), FR (France), IE (Ireland), IT (Italy), JP (Japan), LI (Liechtenstein), MA (Morocco), NZ (New Zealand), NO (Norway), PL (Poland), SI (Slovenia), TW (Taiwan). |
Returns true when the quality check has been performed on all samples, although some samples might have been refused; false when a quality check was not possible, see messages for details.
Remarks
The quality checks of face images are performed according to ICAO requirements. ICAO (International Civil Aviation Organization) is the leading organization in creating standards for machine readable travel documents (MRTDs). This includes a standard for the digital image quality of facial images, defining requirements for photographic and digital characteristics.
Quality checks of voice samples can be performed as well. These are just some generic tests to find out, whether we can use the samples for biometric operations or not. The flags and issuer parameters are ignored for voice samples.
References: ISO/IEC 19794-5:2011 and ISO/IEC 29794-5:2010 (see also ICAO Document 9303)
This API has a fault contract of type BioIDWebServiceFault, which is used for fatal errors like invalid arguments or missing service, etc. Messages, even error messages, generated by the quality check procedure are reported via the messages output value, which contains an XML string according to the BWSMessages schema namespace.
The checks performed
The following list gives an overview of the tests performed and the errors they might generate in case the corresponding condition is not fulfilled. For face image checks, the list shows the conditions for three of the most commonly used configurations: checks according to the ICAO specifications for travel documents (ICAO document mode), checks according to the ICAO specifications for token images (ICAO token mode) and checks typically performed internally (BioID token mode) to generate the token images as used with the other biometric tasks.
Face-finding: BioID's patented, outstanding face-detection algorithm in high accuracy mode.
Condition: exactly one face found
Reported errors: NoFaceFound or MultipleFacesFound
Iris-finding: BioID's patented iris-detection algorithm (only performed in ICAO document mode).
Condition: both irides have to be found
Reported error: IrisNotFound
Image geometric format (crop-image): based on the found eye- and/or iris-position the following settings are used to calculate the cropped face image position and size. The image must contain the complete head.
- Image-width relative to head-width: 1.7
- Image-width to image-height ratio (aspect ratio): 3 / 4
- Aspect ratio in ICAO document mode: 7 / 9
- Eye-position: offset from the top of the image: 0.45%
Reported error: CannotCropImage
Eye-distance: the found head within the image must be big enough so that the distance from eye center to eye center is at least:
240 pixel for ICAO documents, 60 pixel in all other (i.e. token) modes.
Reported error: ImageTooSmall
Photo resolution: the calculated crop-image must have a minimum size (only performed in ICAO document mode).
Condition: minimun cropped image size of 876 x 1063 pixel
Reported error: ImageTooSmall
Gaze direction: the person should look straight ahead into the camera (only performed in ICAO document mode).
Condition: maximum deviation (in any direction) is 9%
Reported error: WrongViewingDirection
Head rotation: the person should not tilt its head too far (only performed in ICAO document mode).
Condition: maximum head tilt is 8°
Reported error: HeadRotatedTooFar
Lightning and pose symmetry: to find out, whether the head is frontal in front of the camera and it is illuminated equally, we calculate an asymmetry value (only performed in ICAO document mode).
Condition: asymmetry shall not exceed 65
Reported error: FaceAsymmetry
Image creation time: there are various tags (e.g. EXIF-tags) that can be associated with images to indicate when an image was taken (only performed in ICAO document mode).
Condition: the image shall not be older than a half year
Reported error: ImageTooOld
Blurring: the image is too blurry, i.e. is it not sharp enough, if the blurring factor (average width of edges) is too big.
Condition: blurring factor shall not be greater than 9.0
Reported error: ImageTooBlurry
Contrast: the variance of the intensity (gray-scale) values within the image must be within a specific range.
Condition: the variance of the intensity values shall be in the range 20 - 90
Reported errors: FaceContrastTooLow or FaceContrastTooHigh
Exposure: the image is over-exposed/under-exposed if the relative amount of very light/dark pixels is to high.
Condition: the amount of very light/dark pixels exceeds 1.5%
Reported errors: ImageOverExposure or ImageUnderExposure
Brightness: an image has an improper brightness, if the calculated brightness distribution (Kurtosis) is not in a specific range.
Condition: the Kurtosis shall be in the range 2 - 10
Reported error: BadFaceBrightness
Illumination intensity: an image has an improper illumination, if the center of mass of the intensity-histogram is not in a specific range.
Condition: the center of mass shall be in the range 20 - 215
Reported errors: FaceTooDark or FaceTooBright
Gray scale density: an image needs to have at least a minimum number of gray scale values in the intensity-histogram.
Condition: the number of gray scale values exceeds 128
Reported error: BadGrayscaleDensity
Extract the facial image: rotates and cuts out the facial region according to the found eye- and/or iris-coordinates to obtain a token image. Not applied in ICAO document mode (in this case the image must not be modified).
Creates a token image of size 240 x 320 pixels in ICAO token mode and of size 360 x 480 pixels in BioID token mode.
Image size: the uploaded image must have a minimum size.
Condition: the image must have a size of at least 240 x 320 pixels
Reported error: ImageWayTooSmall
Blurring: the image is too blurry, i.e. is it not sharp enough, if the blurring factor (average width of edges) is too big.
Condition: blurring factor shall not be greater than 9.0
Reported error: ImageTooBlurry
Contrast: the variance of the intensity (gray-scale) values within the image must be within a specific range.
Condition: the variance of the intensity values shall be in the range 20 - 90
Reported errors: ImageContrastTooLow or ImageContrastTooHigh
Exposure: the image is over-exposed/under-exposed if the relative amount of very light/dark pixels is to high.
Condition: the amount of very light/dark pixels exceeds 1.5%
Reported errors: ImageOverExposure or ImageUnderExposure
Brightness: an image has an improper brightness, if the calculated brightness distribution (Kurtosis) is not in a specific range.
Condition: the Kurtosis shall be in the range -2 - 2
Reported error: BadImageBrightness
Illumination intensity: an image has an improper illumination, if the center of mass of the intensity-histogram is not in a specific range.
Condition: the center of mass shall be in the range 20 - 210
Reported errors: ImageTooDark or ImageTooBright
File Format: the audio signal must be a WAVE (RIFF-based waveform audio file format), PCM encoded with 8 or 16 bits per sample, mono or stereo.
Reported error: CouldNotReadWave
Sampling Frequency: the audio signal should have a sample rate of 22050 Hz. Higher ones will be downsampled, lower ones rejected.
Reported error: AudioSamplingFrequencyTooLow
Audio Segmentation: there must be a non-empty signal given.
Reported error: BadVoiceSignal
Audio Segmentation: the audio segmentation algorithm needs some pause before and after the spoken utterance. If those pauses are missing, or if there is no utterance in-between, it cannot segment the utterance.
Reported error: AudioSegmentationFailure
Audio Segmentation: the utterance in the audio signal must have higher energy than the noise of the signal. If this signal-noise ratio is too low, the signal will be rejected.
Reported error: BadSignalQuality
Audio Segmentation: the segmented audio utterance must be at least 0.3 seconds long.
Reported error: AudioSignalTooShort
Audio Segmentation: the segmented audio utterance may not be longer than 5 seconds.
Reported error: AudioSignalTooLong
Audio Segmentation: the audio segmentation will find voice utterance boundaries. There may only be one such utterance segment.
Reported error: MultipleUtterancesFound
Faults
| InvalidArgument | No samples have been transmitted. |
|---|---|
| AccessDenied | Access to the requested service operation has been denied. Please ensure that you use a valid client authentication certificate and that this certificate has been announced to BioID GmbH as your client certificate. |
| InternalError | For some reason BioID is not running or not configured correctly on this BWS deployment. |
Operation Error-codes
The messages output XML string might contain operation specific errors as follows:
| ExecutionOfJobTimedOut | The service could not process the requested task in a reasonable amount of time. |
|---|---|
| IssuerNotFound | A parameter set for the specified issuer was not found. The default ICAO parameter set is used instead. |
Sample Error-codes
The messages output XML string contains errors for each individual sample representing the results of the quality checks in case a check failed. Some of the listed errors mark the sample as unsuitable, others are only informative:
| SampleNotOfExpectedType | Parameter is not valid: the sample does not contain a valid image or wave format. The sample is therefore not suitable and was not checked. |
|---|---|
| TraitNotSupported | A sample for a trait has been submitted that is not (yet) supported by the service. The sample is not suitable and was not checked. |
Face Sample Error-codes
| NoFaceFound | No face was found in the face sample. The sample is not suitable. |
|---|---|
| MultipleFacesFound | Multiple faces were found in the face sample. The sample is not suitable. |
The following error-codes result from checks that are performed only if a face has been found within a given face-sample. They typically do not mark the sample as unsuitable:
| CannotCropImage | The image does not contain enough space around the found face and therefore can not be cropped in a way that the head is positioned in the correct manner. |
|---|---|
| IrisNotFound | A face was found, however, at least one iris could not be localized. |
| ImageTooSmall | The part of the image containing the found face is too small. |
| WrongViewingDirection | It seems that the found person does not look straight ahead into the camera. |
| HeadRotatedTooFar | It seems that the head of the found person is rotated too much. |
| FaceAsymmetry | It seems that the face of the found person is somehow asymmetric, maybe due to bad illumination and/or due to a wrong pose. |
| ImageTooBlurry | The image is too blurry, i.e. it is not sharp enough. Note that compression artefacts might be the reason for this fuzziness as they reduce the objective sharpness more than the subjective sharpness. |
| BadFaceBrightness | The face area within the image has an improper brightness distribution. |
| FaceContrastTooHigh | The face area within the image has too much contrast. |
| FaceContrastTooLow | The face area within the image has too little contrast. |
| ImageOverExposure | The image is overexposed, i.e. it has too many very light pixels. |
| ImageUnderExposure | The image is underexposed, i.e. it has too many very dark pixels. |
| FaceTooDark | The face area within the image is too dark. |
| FaceTooBright | The face area within the image is too bright. |
| BadGrayscaleDensity | The color intensity of the face area within the image does not have enough variation. The image needs to be lighter or darker so that the grayscale density is distributed a bit better over the face. |
| ImageTooOld | The image has a tag attached that indicates that it was taken too many days ago. |
| MissingTimeStamp | The image does not have any tag attached that could be used to find out when it was taken. |
The following error-codes result from checks that are performed only if a face could not be found within a given face-sample:
| ImageWayTooSmall | The input image is far too small to be used for face recognition. |
|---|---|
| ImageTooBlurry | The image is too blurry, i.e. it is not sharp enough. Note that compression artefacts might be the reason for this fuzziness as they reduce the objective sharpness more than the subjective sharpness. |
| BadImageBrightness | The image has an improper brightness distribution. |
| ImageContrastTooHigh | The image has too much contrast. |
| ImageContrastTooLow | The image has too little contrast. |
| ImageOverExposure | The image is overexposed, i.e. it has too many very light pixels. |
| ImageUnderExposure | The image is underexposed, i.e. it has too many very dark pixels. |
| ImageTooDark | The image is too dark. |
| ImageTooBright | The image is too bright. |
Voice Sample Error-codes
The following error-codes result from checks that are performed only with voice-samples. With all of these errors the voice sample is marked as unsuitable:
| MultipleUtterancesFound | Multiple voice utterances were found in the audio sample, this is unsupported. |
|---|---|
| CouldNotReadWave | The wave format is not supported. |
| AudioSamplingFrequencyTooLow | The sampling frequency of the wave signal is too low. |
| BadSignalQuality | The quality of the audio signal is not sufficient. |
| AudioSignalTooShort | The audio signal is too short. |
| AudioSignalTooLong | The audio signal is too long. |
| AudioSegmentationFailure | The segmentation of the audio signal failed. (This is typically an internal error.) |
| BadVoiceSignal | The format of the audio signal is not recognized. (This is typically an internal error.) |