Merge branch 'nokia/masa-diff-tool' into 'main'

#------------------------------------------------------------------------------------------------------------

# MASA conformance tools

# ----------------------------------

# (C) 2022-2026 IVAS codec Public Collaboration with portions copyright Dolby International AB, Ericsson AB,

# Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V., Huawei Technologies Co. LTD.,

# Koninklijke Philips N.V., Nippon Telegraph and Telephone Corporation, Nokia Technologies Oy, Orange,

# Panasonic Holdings Corporation, Qualcomm Technologies, Inc., VoiceAge Corporation, and other

# contributors to this repository. All Rights Reserved.

#

# This software is protected by copyright law and by international treaties.

# The IVAS codec Public Collaboration consisting of Dolby International AB, Ericsson AB,

# Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V., Huawei Technologies Co. LTD.,

# Koninklijke Philips N.V., Nippon Telegraph and Telephone Corporation, Nokia Technologies Oy, Orange,

# Panasonic Holdings Corporation, Qualcomm Technologies, Inc., VoiceAge Corporation, and other

# contributors to this repository retain full ownership rights in their respective contributions in

# the software. This notice grants no license of any kind, including but not limited to patent

# license, nor is any license granted by implication, estoppel or otherwise.

#

# Contributors are required to enter into the IVAS codec Public Collaboration agreement before making

# contributions.

#

# This software is provided "AS IS", without any express or implied warranties. The software is in the

# development stage. It is intended exclusively for experts who have experience with such software and

# solely for the purpose of inspection. All implied warranties of non-infringement, merchantability

# and fitness for a particular purpose are hereby disclaimed and excluded.

#

# Any dispute, controversy or claim arising under or in relation to providing this software shall be

# submitted to and settled by the final, binding jurisdiction of the courts of Munich, Germany in

# accordance with the laws of the Federal Republic of Germany excluding its conflict of law rules and

# the United Nations Convention on Contracts on the International Sales of Goods.

#

#------------------------------------------------------------------------------------------------------------

cmake_minimum_required(VERSION 3.10)

project(MasaDiffTool C)

set(MASA_DIFF_TOOL_NAME masaDiffTool)

set(CMAKE_C_STANDARD 99)

if(WIN32)

    add_definitions(

        -D_CRT_SECURE_NO_WARNINGS

        -Drestrict=__restrict

        /wd4028

        /wd4100

        /wd4244

        /wd4310

        /wd4996

        /MP

    )

endif()

set(MASA_DIFF_TOOL_SOURCES

        ivasParts.c

        masaDiffTool.c

        masa_file_reader.c

)

set(MASA_DIFF_TOOL_HEADERS

        ivasParts.h

        masa_file_reader.h

)

add_executable(${MASA_DIFF_TOOL_NAME} ${MASA_DIFF_TOOL_SOURCES} ${MASA_DIFF_TOOL_HEADERS})

if(NOT WIN32)

    target_link_libraries(${MASA_DIFF_TOOL_NAME} m)

endif()

# MASA-diff-tool

Version: 0.2.2

## Usage

```

Usage: masaDiffTool [options] refMetaFile cutMetaFile

Options:

--report <report.txt>, produces frame-by-frame results in text format, includes also details of descriptive metadata difference

--csv <report.csv>, produces most useful frame-by-frame results in csv format with header row and comma separation

```

## Output data

The tool provides always a summary of the differences to stdout at the end, and the return value is 0 only if the two

compared metadata files are identical. The summary contains:

- Overall status for metadata difference

- Total number of differing frames

- Status for descriptive metadata difference

- Overall status for spatial metadata difference

- Across all frames max ABS and mean difference values for spatial metadata

  - Overall max ABS diff in spatial direction (degrees)

  - Overall mean ABS diff in spatial direction (degrees)

  - Overall max ABS diff in direct-to-total ratio

  - Overall mean ABS diff in direct-to-total ratio

  - Overall max ABS diff in diffuse-to-total ratio

  - Overall mean ABS diff in diffuse-to-total ratio

  - Overall max ABS diff in remainder-to-total ratio

  - Overall mean ABS diff in remainder-to-total ratio

  - Overall max ABS diff in spread coherence ratio

  - Overall mean ABS diff in spread coherence ratio

  - Overall max ABS diff in surround coherence ratio

  - Overall mean ABS diff in surround coherence ratio

If a file contains format descriptor that is not `IVASMASA`, then the file is considered non-conformant and comparison

does not continue.

If a frame has differing number of directions in metadata, then spatial metadata comparison is not done and the frame is

considered to be completely different.

When option `--report` is given, then a frame-by-frame printout is generated into the text file. This lists main 

differences in spatial metadata and also detailed difference in descriptive metadata.

When option `--csv` is given, then a frame-by-frame results is constructed in comma-separated CSV-file with headers for:

- Frame index

- Diff in descriptive metadata

- Diff in number of directions

- Max ABS diff: Direction (degrees spatial angle)

- Mean ABS diff: Direction (degrees spatial angle)

- Max ABS diff: Direct-to-total ratio

- Mean ABS diff: Direct-to-total ratio

- Max ABS diff: Diffuse-to-total ratio

- Mean ABS diff: Diffuse-to-total ratio

- Max ABS diff: Remainder-to-total ratio

- Mean ABS diff: Remainder-to-total ratio

- Max ABS diff: Spread coherence

- Mean ABS diff: Spread coherence

- Max ABS diff: Surround coherence

- Mean ABS diff: Surround coherence

In the CSV-file, the spatial metadata diff values are considered invalid if "Diff in number of directions" is 1.

## Structure

The program code is structured as follows

- masaDiffTool.c, main application including comparison and reporting functions

- masa_file_reader.[c|h], MASA metadata reader from IVAS source code with minor changes

- ivasParts.[c|h], parts of code from several common IVAS headers and source files needed by MASA metadata reader 

## Notice

(C) 2022-2026 IVAS codec Public Collaboration with portions copyright Dolby International AB, Ericsson AB,

Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V., Huawei Technologies Co. LTD.,

Koninklijke Philips N.V., Nippon Telegraph and Telephone Corporation, Nokia Technologies Oy, Orange,

Panasonic Holdings Corporation, Qualcomm Technologies, Inc., VoiceAge Corporation, and other

contributors to this repository. All Rights Reserved.

This software is protected by copyright law and by international treaties.

The IVAS codec Public Collaboration consisting of Dolby International AB, Ericsson AB,

Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V., Huawei Technologies Co. LTD.,

Koninklijke Philips N.V., Nippon Telegraph and Telephone Corporation, Nokia Technologies Oy, Orange,

Panasonic Holdings Corporation, Qualcomm Technologies, Inc., VoiceAge Corporation, and other

contributors to this repository retain full ownership rights in their respective contributions in

the software. This notice grants no license of any kind, including but not limited to patent

license, nor is any license granted by implication, estoppel or otherwise.

Contributors are required to enter into the IVAS codec Public Collaboration agreement before making

contributions.

This software is provided "AS IS", without any express or implied warranties. The software is in the

development stage. It is intended exclusively for experts who have experience with such software and

solely for the purpose of inspection. All implied warranties of non-infringement, merchantability

and fitness for a particular purpose are hereby disclaimed and excluded.

Any dispute, controversy or claim arising under or in relation to providing this software shall be

submitted to and settled by the final, binding jurisdiction of the courts of Munich, Germany in

accordance with the laws of the Federal Republic of Germany excluding its conflict of law rules and

the United Nations Convention on Contracts on the International Sales of Goods.

/******************************************************************************************************

   (C) 2022-2026 IVAS codec Public Collaboration with portions copyright Dolby International AB, Ericsson AB,

   Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V., Huawei Technologies Co. LTD.,

   Koninklijke Philips N.V., Nippon Telegraph and Telephone Corporation, Nokia Technologies Oy, Orange,

   Panasonic Holdings Corporation, Qualcomm Technologies, Inc., VoiceAge Corporation, and other

   contributors to this repository. All Rights Reserved.

   This software is protected by copyright law and by international treaties.

   The IVAS codec Public Collaboration consisting of Dolby International AB, Ericsson AB,

   Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V., Huawei Technologies Co. LTD.,

   Koninklijke Philips N.V., Nippon Telegraph and Telephone Corporation, Nokia Technologies Oy, Orange,

   Panasonic Holdings Corporation, Qualcomm Technologies, Inc., VoiceAge Corporation, and other

   contributors to this repository retain full ownership rights in their respective contributions in

   the software. This notice grants no license of any kind, including but not limited to patent

   license, nor is any license granted by implication, estoppel or otherwise.

   Contributors are required to enter into the IVAS codec Public Collaboration agreement before making

   contributions.

   This software is provided "AS IS", without any express or implied warranties. The software is in the

   development stage. It is intended exclusively for experts who have experience with such software and

   solely for the purpose of inspection. All implied warranties of non-infringement, merchantability

   and fitness for a particular purpose are hereby disclaimed and excluded.

   Any dispute, controversy or claim arising under or in relation to providing this software shall be

   submitted to and settled by the final, binding jurisdiction of the courts of Munich, Germany in

   accordance with the laws of the Federal Republic of Germany excluding its conflict of law rules and

   the United Nations Convention on Contracts on the International Sales of Goods.

*******************************************************************************************************/

/******************************************************************************************************

   This file is adapted from IVAS source code files to support the specific task of this diff tool.

   The sources for this file are:

   - lib_com/ivas_masa_com.c

*******************************************************************************************************/

#include <math.h>

#include <assert.h>

#include "ivasParts.h"

/*---------------------------------------------------------------

 * generate_gridEq()

 *

 * generate Spherical grid

 *---------------------------------------------------------------*/

void generate_gridEq(

    SPHERICAL_GRID_DATA *data /* o  : data structure for grid  */

)

{

    int32_t cum_n, cum_n_prev;

    float theta;

    int16_t i;

    int16_t *n;

    n = data->no_phi;

    n[0] = MASA_NO_POINTS_EQUATOR;

    cum_n_prev = 0;

    for ( i = 1; i < MASA_NO_CIRCLES; i++ )

    {

        theta = MASA_ANGLE_AT_EQUATOR * (float) ( i + 0.5f );

        if ( i == 1 )

        {

            cum_n = 2 * (int32_t) ceilf( MASA_NTOT2_FAC * ( sinf( theta ) - MASA_ASIN_OFFSET ) );

        }

        else

        {

            cum_n = 2 * (int32_t) roundf( MASA_NTOT2_FAC * ( sinf( theta ) - MASA_ASIN_OFFSET ) );

        }

        n[i] = (int16_t) ( ( cum_n - cum_n_prev ) >> 1 );

        cum_n_prev = cum_n;

    }

    n[i] = 1;

    data->no_theta = i + 1;

    return;

}

/*-------------------------------------------------------------------------

 * deindex_sph_idx()

 *

 *  deindex the MASA metadata from the input metadata file

 *------------------------------------------------------------------------*/

void deindex_sph_idx(

    const uint16_t sphIndex,             /* i  : Spherical index            */

    const SPHERICAL_GRID_DATA *gridData, /* i  : Prepared spherical grid    */

    float *theta,                        /* o  : Elevation                  */

    float *phi                           /* o  : Azimuth                    */

)

{

    float ba_crt, del_crt, div_crt, a4_crt;

    float estim;

    int32_t base_low, base_up;

    int16_t n_crt;

    int16_t id_th;

    int16_t sign_theta;

    int16_t id_phi;

    int16_t no_th = gridData->no_theta;

    const int16_t *n = gridData->no_phi;

    const float ba[3] = { 2.137991118026424e+02f, 1.244854404591542e+02f, 1.228408647140870e+02f };

    const float del[3] = { 7.998262115303199e+05f, 1.300883976959332e+06f, 1.424072242426373e+06f };

    const float div[3] = { -0.237662341081474f, -0.100938185496887f, -0.092050209205032f };

    const float a4[3] = { -8.415300425381099f, -19.814106922515204f, -21.727272727270197f };

    const uint16_t limit_index1 = 64964, limit_index2 = 47870;

    if ( sphIndex >= limit_index1 )

    {

        ba_crt = ba[2];

        div_crt = div[2];

        a4_crt = a4[2];

        del_crt = del[2];

    }

    else if ( sphIndex >= limit_index2 )

    {

        ba_crt = ba[1];

        div_crt = div[1];

        a4_crt = a4[1];

        del_crt = del[1];

    }

    else

    {

        ba_crt = ba[0];

        div_crt = div[0];

        a4_crt = a4[0];

        del_crt = del[0];

    }

    estim = ba_crt + div_crt * sqrtf( del_crt + a4_crt * sphIndex );

    if ( estim > MASA_NO_CIRCLES )

    {

        estim = MASA_NO_CIRCLES;

    }

    assert( estim > 0 );

    id_th = (int16_t) roundf( estim ) - 1;

    if ( id_th < 0 )

    {

        id_th = 0;

    }

    if ( id_th == 0 )

    {

        base_low = 0;

        base_up = n[0];

    }

    else

    {

        estim = MASA_ANGLE_AT_EQUATOR * (float) ( id_th - 0.5f );

        base_low = n[0];

        if ( id_th >= 2 )

        {

            if ( id_th == 2 )

            {

                base_low += 2 * (int16_t) ceilf( MASA_NTOT2_FAC * ( sinf( estim ) - MASA_ASIN_OFFSET ) );

            }

            else

            {

                base_low += 2 * (int16_t) roundf( MASA_NTOT2_FAC * ( sinf( estim ) - MASA_ASIN_OFFSET ) );

            }

        }

        base_up = base_low + 2 * n[id_th];

    }

    sign_theta = 1;

    n_crt = n[id_th];

    if ( sphIndex < base_low )

    {

        id_th--;

        n_crt = n[id_th];

        if ( id_th == 0 )

        {

            base_low = 0;

            base_up = n_crt;

        }

        else

        {

            base_up = base_low;

            base_low -= 2 * n[id_th];

        }

        assert( sphIndex >= base_low );

    }

    else if ( sphIndex >= base_up )

    {

        id_th++;

        n_crt = n[id_th];

        base_low = base_up;

        base_up += 2 * n_crt;

        assert( sphIndex < base_up );

    }

    id_phi = (int16_t) ( sphIndex - base_low );

    if ( sphIndex - base_low >= n_crt )

    {

        id_phi -= n_crt;

        sign_theta = -1;

    }

    if ( id_th == 0 )

    {

        *theta = 0.f;

        *phi = (float) sphIndex * 360 / (float) n_crt - 180;

    }

    else

    {

        if ( id_th == no_th - 1 )

        {

            id_phi = 0;

            *phi = -180;

            *theta = 90 * (float) sign_theta;

        }

        else

        {

            *theta = id_th * MASA_ANGLE_AT_EQUATOR_DEG * (float) sign_theta;

            if ( id_th % 2 == 0 )

            {

                *phi = (float) id_phi * 360 / (float) n_crt - 180;

            }

            else

            {

                *phi = ( (float) id_phi + 0.5f ) * 360 / (float) n_crt - 180;

            }

        }

    }

    return;

}