Quality
=======

.. _quality_schema:

Schema for describing different types of quality metrics and associated wrappers.

.. note::

   The following top-level properties are **required**: ``metrics``, ``bd-adjusted-metrics``, ``weighted-metrics``, ``wrappers``.


Properties
----------

.. _quality_schema_metrics:


[Required] ``metrics``
~~~~~~~~~~~~~~~~~~~~~~

*Path:* ``Quality > metrics``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``array``
   * - **Required**
     - Yes

List of the available quality metrics that are computed by third-party tools.


Items of ``metrics``
~~~~~~~~~~~~~~~~~~~~

.. _quality_schema_metrics_items_name:


[Required] ``name``
^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > metrics > items > name``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

Human-readable name of the metric (e.g., 'PSNR Y', 'SSIM').

**Example(s):**

.. code-block:: json

   "PSNR Y"

.. code-block:: json

   "SSIM"

.. code-block:: json

   "VMAF"

.. _quality_schema_metrics_items_label:


[Required] ``label``
^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > metrics > items > label``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

Short identifier used in reports and file names (e.g., 'PSNR_Y').

**Example(s):**

.. code-block:: json

   "PSNR_Y"

.. code-block:: json

   "SSIM"

.. code-block:: json

   "VMAF"

.. _quality_schema_metrics_items_tex_label:


[Required] ``tex_label``
^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > metrics > items > tex_label``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

LaTeX formatted label for use in plots and documents.

**Example(s):**

.. code-block:: json

   "$\\text{PSNR}_\\text{Y}$"

.. code-block:: json

   "$\\text{SSIM}$"

.. code-block:: json

   "$\\text{VMAF}$"

.. _quality_schema_metrics_items_description:


[Optional] ``description``
^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > metrics > items > description``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - No

Detailed explanation of what the metric measures.

**Example(s):**

.. code-block:: json

   "Peak Signal-to-Noise Ratio of the Y channel."

.. _quality_schema_metrics_items_unit:


[Optional] ``unit``
^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > metrics > items > unit``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - No

Measurement unit for the metric values (e.g., 'dB').

**Example(s):**

.. code-block:: json

   "dB"

.. code-block:: json

   ""

.. _quality_schema_metrics_items_quality_wrapper:


[Required] ``quality-wrapper``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > metrics > items > quality-wrapper``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

Reference to the wrapper that implements this metric calculation.

**Example(s):**

.. code-block:: json

   "vmaf_tool"

.. code-block:: json

   "compare_tool"

.. _quality_schema_metrics_items_convert_log:


[Optional] ``convert-log``
^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > metrics > items > convert-log``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``boolean``
   * - **Required**
     - No

Whether the metric requires logarithmic conversion before analysis.

**Example(s):**

.. code-block:: json

   false

.. _quality_schema_bd_adjusted_metrics:


[Required] ``bd-adjusted-metrics``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Path:* ``Quality > bd-adjusted-metrics``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``array``
   * - **Required**
     - Yes

List of metrics adjusted for Bjontegaard-Delta (BD) rate calculations.


Items of ``bd-adjusted-metrics``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _quality_schema_bd_adjusted_metrics_items_name:


[Required] ``name``
^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > bd-adjusted-metrics > items > name``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

**Example(s):**

.. code-block:: json

   "SSIM dB"

.. code-block:: json

   "VMAF dB"

.. _quality_schema_bd_adjusted_metrics_items_label:


[Required] ``label``
^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > bd-adjusted-metrics > items > label``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

Mathematical expression showing the BD adjustment formula.

**Example(s):**

.. code-block:: json

   "-10{\\times}log_{10}(1-SSIM)"

.. code-block:: json

   "-10{\\times}log_{10}(1-\\frac{VMAF}{100})"

.. _quality_schema_bd_adjusted_metrics_items_tex_label:


[Required] ``tex_label``
^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > bd-adjusted-metrics > items > tex_label``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

LaTeX formatted label for the BD-adjusted metric.

**Example(s):**

.. code-block:: json

   "$\\text{SSIM}_\\text{dB}"

.. code-block:: json

   "$\\text{VMAF}_\\text{dB}"

.. _quality_schema_bd_adjusted_metrics_items_unit:


[Optional] ``unit``
^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > bd-adjusted-metrics > items > unit``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - No

Measurement unit for the adjusted values (typically 'dB').

**Example(s):**

.. code-block:: json

   "dB"

.. _quality_schema_bd_adjusted_metrics_items_quality_wrapper:


[Required] ``quality-wrapper``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > bd-adjusted-metrics > items > quality-wrapper``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

**Example(s):**

.. code-block:: json

   "vmaf_tool"

.. _quality_schema_bd_adjusted_metrics_items_convert_log:


[Optional] ``convert-log``
^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > bd-adjusted-metrics > items > convert-log``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``boolean``
   * - **Required**
     - No

.. _quality_schema_bd_adjusted_metrics_items_origin:


[Required] ``origin``
^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > bd-adjusted-metrics > items > origin``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

Identifier of the original metric before BD adjustment.

**Example(s):**

.. code-block:: json

   "float_ssim"

.. code-block:: json

   "vmaf"

.. _quality_schema_bd_adjusted_metrics_items_adjustment_for_bd:


[Required] ``adjustment_for_bd``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > bd-adjusted-metrics > items > adjustment_for_bd``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

Function name that performs the BD-specific adjustment.

**Example(s):**

.. code-block:: json

   "ssim_adjustment_for_bd"

.. code-block:: json

   "vmaf_adjustment_for_bd"

.. _quality_schema_bd_adjusted_metrics_items_pooling_first:


[Optional] ``pooling-first``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > bd-adjusted-metrics > items > pooling-first``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``boolean``
   * - **Required**
     - No

Whether to pool frame-level metrics before BD adjustment.

**Example(s):**

.. code-block:: json

   true

.. _quality_schema_weighted_metrics:


[Required] ``weighted-metrics``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Path:* ``Quality > weighted-metrics``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``array``
   * - **Required**
     - Yes

List of composite metrics calculated as weighted combinations of other metrics.


Items of ``weighted-metrics``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _quality_schema_weighted_metrics_items_name:


[Required] ``name``
^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > weighted-metrics > items > name``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

**Example(s):**

.. code-block:: json

   "PSNR YUV"

.. _quality_schema_weighted_metrics_items_label:


[Required] ``label``
^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > weighted-metrics > items > label``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

**Example(s):**

.. code-block:: json

   "\\frac{6{\\times}PSNR_Y+PSNR_U+PSNR_V}{8}"

.. _quality_schema_weighted_metrics_items_tex_label:


[Required] ``tex_label``
^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > weighted-metrics > items > tex_label``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

LaTeX formatted label for the weighted metric.

**Example(s):**

.. code-block:: json

   "$\\text{PSNR}_\\text{YCbCr}$"

.. _quality_schema_weighted_metrics_items_unit:


[Required] ``unit``
^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > weighted-metrics > items > unit``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

**Example(s):**

.. code-block:: json

   "dB"

.. _quality_schema_weighted_metrics_items_metrics:


[Required] ``metrics``
^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > weighted-metrics > items > metrics``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``array of string``
   * - **Required**
     - Yes

**Example(s):**

.. code-block:: json

   [
       "psnr_y",
       "psnr_cb",
       "psnr_cr"
   ]

.. _quality_schema_weighted_metrics_items_weights:


[Optional] ``weights``
^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > weighted-metrics > items > weights``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``object``
   * - **Required**
     - No

Optional weights for each component metric.

**Example(s):**

.. code-block:: json

   {
       "psnr_y": 4,
       "psnr_cb": 1,
       "psnr_cr": 1
   }

.. _quality_schema_wrappers:


[Required] ``wrappers``
~~~~~~~~~~~~~~~~~~~~~~~

*Path:* ``Quality > wrappers``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``array``
   * - **Required**
     - Yes

List of quality metric calculation implementations.


Items of ``wrappers``
~~~~~~~~~~~~~~~~~~~~~

.. _quality_schema_wrappers_items_wrapper_id:


[Required] ``wrapper_id``
^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > wrappers > items > wrapper_id``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

**Example(s):**

.. code-block:: json

   "vmaf_tool"

.. code-block:: json

   "compare_tool"

.. _quality_schema_wrappers_items_wrapper_file:


[Required] ``wrapper_file``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > wrappers > items > wrapper_file``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

**Example(s):**

.. code-block:: json

   "vmaf_tool_wrapper"

.. code-block:: json

   "compare_tool_wrapper"

.. _quality_schema_wrappers_items_wrapper_name:


[Required] ``wrapper_name``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > wrappers > items > wrapper_name``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

**Example(s):**

.. code-block:: json

   "VMAFMetrics"

.. code-block:: json

   "CompareMetrics"

.. _quality_schema_wrappers_items_short_name:


[Required] ``short_name``
^^^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > wrappers > items > short_name``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

**Example(s):**

.. code-block:: json

   "vmaf"

.. code-block:: json

   "compare"

.. _quality_schema_wrappers_items_raw_type:


[Required] ``raw_type``
^^^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > wrappers > items > raw_type``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``string``
   * - **Required**
     - Yes

**Example(s):**

.. code-block:: json

   "yuv"

.. code-block:: json

   "ppm"

.. _quality_schema_wrappers_items_kwargs:


[Optional] ``kwargs``
^^^^^^^^^^^^^^^^^^^^^

*Path:* ``Quality > wrappers > items > kwargs``

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - **Type**
     - ``object``
   * - **Required**
     - No

**Example(s):**

.. code-block:: json

   {
       "vmaf_executable_path": "${base-path}/../temporary/vmaf_tool"
   }