> For the complete documentation index, see [llms.txt](https://docs.saas.haut.ai/haut.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saas.haut.ai/haut.ai/developers/saas-api-overview/api-for-face-metrics-2.0/technical-algorithms-results/image-quality.md).

# Image Quality Result Scheme

How the image quality algorithm scores a selfie, and the quality properties, problems, and feedback fields it returns.

## **Description**

The algorithm analyzes the overall quality of an input image for the consequent skin analysis, which is done through an API. The algorithm returns the evaluation of quality properties and human-readable feedback with an explanation of why an image is of high or low quality.

You can select the result of this algorithm by selecting:

```json
"algorithm_tech_name": "quality"
```

## **`main_metric`**

The main metric is an overall score that indicates the quality of a selfie image.

```json
"main_metric": {
    "value": 78,
    "widget_type": "bad_good_line",
    "name": "Image Quality Score",
    "tech_name": "image_quality_score",
    "widget_meta": null,
    "units": null
},
```

* **`value`** the image quality score ranges from `[0,100]`. *The higher the value, the better the image quality*
* **`"widget_type": "bad_good_line"`** this indicates that a higher value is better
* **`name`** metric name (<mark style="background-color:orange;">may change</mark>)
* **`tech_name`** metric technical name (<mark style="background-color:green;">does not change</mark>)
* **`widget_meta`** empty, ignore
* **`units`** empty, ignore

## `sub_metrics`

Sub-metrics are a set of features that define an image's quality. There are 2 types of sub-metrics:

* **scores**: sub-metrics with `"tech_name"` property ending with `"_score"`
* **raw metrics**: other sub-metrics

```json
"sub_metrics": [
    < here is an example of a "score" sub-metric >
    {
        "value": 0, 
        "widget_type": 
        "bad_good_line", 
        "name": "rotation_score", 
        "tech_name": "rotation_score", 
        "widget_meta": null, 
        "units": null
    }, 
    ...
    < here is an example of "raw metrics" sub-metric >
    {
        "value": -41, 
        "widget_type": "numeric", 
        "name": "angles_yaw_angle_degree", 
        "tech_name": "angles_yaw_angle_degree", 
        "widget_meta": null, 
        "units": null
    },
    ...
]
```

### Scores

#### Structure

* **`value`** the image quality score ranges from `[0,100]`. *The higher the value, the better the image quality*
* **`"widget_type": "bad_good_line"`** this indicates that a higher value is better
* **`name`** metric name (<mark style="background-color:orange;">may change</mark>)
* **`tech_name`** metric technical name (<mark style="background-color:green;">does not change</mark>)
* **`widget_meta`** empty, ignore
* **`units`** empty, ignore

#### Meaning

<table><thead><tr><th width="181.33333333333331">tech_name</th><th width="223">description</th><th>interpretation</th></tr></thead><tbody><tr><td>full_face_score</td><td>This parameter describes the degree of face presence on image, necessary for analysis</td><td><p>A higher value is better.</p><ul><li>0: at least one face skin area is not present fully on the image</li><li>100: the face is fully present on the image</li></ul><p>We suggest using 50 as a threshold to separate high- and low-quality images</p></td></tr><tr><td>rotation_score</td><td>This parameter describes the deviation of a head position from looking straight into the camera.</td><td><p>A higher value is better.</p><ul><li>0 value: the head is significantly rotated (more than<span class="math">45^{o}</span>along any or both axes)</li><li>100: the head has a perfect position with the face looking straight into the camera</li></ul><p>We suggest using 50 as a threshold to separate high- and low-quality images.</p></td></tr><tr><td>occlusion_score</td><td>This parameter describes the degree of face skin areas occlusion by a non-skin objects</td><td><p>A higher value is better.</p><ul><li>0: one or several large skin areas (forehead, cheeks, chin) are not visible because of occlusion by an object or significantly high-contrast light</li><li>100: all face skin areas relevant for analysis are visible on the image</li></ul><p>We suggest using 50 as a threshold to separate high- and low-quality images</p></td></tr><tr><td>resolution_score</td><td>This parameter describes the sufficiency of resolution of a part of an image related to the detected face</td><td><p>A higher value is better.</p><ul><li>0: the image resolution and/or face size in the image is too low</li><li>100: the face resolution is good enough for further image analysis</li></ul><p>We suggest using 50 as a threshold to separate high- and low-quality images</p></td></tr><tr><td>focus_score</td><td>This parameter describes the degree of image distortions similar to motion/misfocus blur that usually prevent correct small-feature extraction.</td><td><p>A higher value is better.</p><ul><li>0: the image has severe distortions</li><li>100: the image has no detectable distortions or the distortions are negligible for further analysis</li></ul><p>We suggest using 50 as a threshold to separate bad and good quality images</p></td></tr><tr><td>lightness_score</td><td>This parameter describes the sufficiency of face illumination (exposition)</td><td><p>A higher value is better.</p><p>Interpretation:</p><ul><li>0: the face illumination is poor due to global over-exposure or under-exposure</li><li>100: the face illumination is sufficient enough for further image analysis</li></ul><p>We suggest using 50 as a threshold to separate high- and low-quality images</p></td></tr><tr><td>shadows_score</td><td>This parameter describes the degree of side illumination as a uniformness of face illumination</td><td><p>A higher value is better.</p><ul><li>0: the face illumination is poor due to significant shadows caused by side illumination</li><li>100: the face illumination is uniform enough for further image analysis</li></ul><p>We suggest using 50 as a threshold to separate high- and low-quality images</p></td></tr><tr><td>colortone_score</td><td>This parameter describes the degree of color tone of the face illumination.</td><td><p>A higher value is better.</p><ul><li>0: the face illumination is poor due to significantly incorrect white balance (color tone of light)</li><li>100: the face illumination is illuminated with neutral white light</li></ul><p>We suggest using 50 as a threshold to separate high- and low-quality images</p></td></tr></tbody></table>

### Raw Metrics

#### Structure

* **`value`** float or int value
* **`"widget_type":`** different types, describing the exact logic of value reading. The most common are:
  * `"numeric"` - just a number
  * `"bad_good_line"` - indicates that a higher value is better
* **`name`** metric name (<mark style="background-color:orange;">may change</mark>)
* **`tech_name`** metric technical name (<mark style="background-color:green;">does not change</mark>)
* **`widget_meta`** empty, ignore
* **`units`** empty, ignore

## `problems`

**`problems`** is a list of all detected issues with image quality, returned as a short codenames. The list can contain from 0 (no problems) to N (several problems):

```json
"problems": ["wrong_angle", "low_resolution", "misfocus_or_distortion"]
```

#### Meaning

Every codename reflect exact case, described in a table below:

<table><thead><tr><th width="219">codename</th><th>description</th></tr></thead><tbody><tr><td>no_detection</td><td>No face detected</td></tr><tr><td>out_of_frame</td><td>Face is not fully visible</td></tr><tr><td>far_from_camera</td><td>Face is too far from camera</td></tr><tr><td>wrong_angle</td><td>Head is rotated at the wrong angle</td></tr><tr><td>skin_occlusion</td><td>Skin is partially not visible</td></tr><tr><td>low_resolution</td><td>Low face resolution</td></tr><tr><td>misfocus_or_distortion</td><td>Image is distorted or blurred</td></tr><tr><td>compression_artifacts</td><td>Image compression artifacts are visible</td></tr><tr><td>noise</td><td>Noisy image</td></tr><tr><td>too_dark</td><td>Image is too dark</td></tr><tr><td>too_bright</td><td>Image is too bright</td></tr><tr><td>strong_shadows</td><td>Front facing light required</td></tr><tr><td>colored_illumination</td><td>Incorrect white balance</td></tr></tbody></table>

## :warning: \[DEPRECATED] `feedback`

{% hint style="danger" %}
This field will be removed in the nearest update. Use **`problems`** instead
{% endhint %}

**`feedback`** is a message with information about the image quality in form of 2 objects:

* overlay - short summary
* tooltip - more verbose list of issues, split to critical / warning / good condition

```javascript
"feedback": {
        "overlay": "Low quality image",
        "tooltip": {
            "positive": [
                "Good face resolution"
            ],
            "warn": [],
            "negative": [
                "Unacceptable face illumination"
            ]
        }
```

* **`overlay`** is an informal message about the overall image quality. It returns an informal rating of the image quality:
  * `"Good quality image"` - image quality is suitable for skin analysis
  * `"Low-quality image"` - image quality is low for skin analysis
  * `"No face detected"` - face is not detected. Image can't be processed by skin assessment algorithms
  * `"Not full face"`- image is not fully presented in the image. Image is not suitable for skin analysis
  * `"Face is rotated"` - face is extremely rotated in the image. Image is not suitable for skin analysis
* **`tooltip`** is an informal message about image quality and warnings
  * `positive` possible feedback values are:
    * `Good face resolution`
    * `Good face illumination`
  * `warn` possible feedback values are:
    * `Poor face resolution`
    * `Poor face illumination`
  * `negative` possible feedback values are:
    * `Face is not detected`
    * `Face is not fully presented`
    * `Face is rotated`
    * `Misfocus or distortion`
    * `Noisy image`
    * `Unacceptable face resolution`
    * `Unacceptable face illumination`

## **Example (JSON)**

{% file src="/files/6c7RSqExjmvTKY6bOUQA" %}
quality.json
{% endfile %}

***

{% hint style="warning" %}
Not a Haut.AI client yet?
{% endhint %}

<a href="https://haut.ai/book-a-demo?utm_source=referral&#x26;utm_medium=saas_docs&#x26;utm_campaign=Docs_SaaS_HautAI" class="button primary" data-icon="user-vneck">Book a demo</a> <a href="https://haut.ai/product/ai-skin-analysis?utm_source=referral&#x26;utm_medium=saas_docs&#x26;utm_campaign=Docs_SaaS_HautAI" class="button secondary" data-icon="external-link">Platform overview on haut.ai</a>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.saas.haut.ai/haut.ai/developers/saas-api-overview/api-for-face-metrics-2.0/technical-algorithms-results/image-quality.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.