apply markdown formatting on the readme text

   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.

-->

# Modeling tool for All IVAS binaural renderer

# Allows to convert sofa file(s) to rom tables files (*.c|h) or binaural binary file(s)

# Modeling tool for all IVAS binaural renderer

# Allows to convert SOFA file(s) to rom tables files (*.c|h) or binaural binary file(s)

## Requirements

- MATLAB >= R2020b

- Signal Processing Toolbox

- Python 3.9.* with pip

- ./scripts/pyaudio3dtools packages

- Numpy (pip install numpy)

- H5py (pip install h5py)

- Scipy (pip install scipy) for ./scripts/pyaudio3dtools packages

- [`../../scripts/pyaudio3dtools`](../../scripts/pyaudio3dtools) packages

- NumPy (`pip install numpy`)

- H5py (`pip install h5py`)

- SciPy (`pip install scipy`) for [`../../scripts/pyaudio3dtools`](../../scripts/pyaudio3dtools) packages

- C/C++ compiler 

   - linux (ubuntu) :

      - sudo apt-get update

      - sudo apt-get install build-essential

   - windows

      - install visual studio community or other : https://visualstudio.microsoft.com/fr/vs/community/

- cmake version > 3.5

   - Linux (Ubuntu) :

     ```shell

     sudo apt-get update

     sudo apt-get install build-essential

     ```

   - Windows

      - Install Visual Studio Community Edition or other: https://visualstudio.microsoft.com/fr/vs/community/

- CMake version > 3.5

### Build generate_crend_ivas_tables

   - open a command line terminal

   - goto /scripts/binauralRenderer_interface folder 

   - mkdir build

   - cd build

   - cmake ..

   - cmake --build .

   - cd .. 

   - generate_crend_ivas_tables executable shall be in this folder

   - SofaReader.py file must be in the same folder as the executable generate_crend_ivas_tables

   - run python3 run.py -> no error message shall appear

      - using pip and PYTHONPATH. Add pip packages folder (ex : C:\Users\username\AppData\Local\Programs\Python\Python311\Lib\site-packages) to environment variable PYTHONPATH. It can be necessary also to add to PYTHONPATH ./scripts/pyaudio3dtools folder.  

   - for more details on generate_crend_ivas_tables see mixer_conv_sofa_to_rom_table_converter_readme.txt

### Build `generate_crend_ivas_tables`

   - Open a command line terminal

   - Execute

     ```shell

     cd ../../scripts/binauralRenderer_interface

     mkdir build

     cd build

     cmake ..

     cmake --build .

     cd ..

     ```

   - `generate_crend_ivas_tables` executable shall be in folder [`../../scripts/binauralRenderer_interface`](../../scripts/binauralRenderer_interface)

   - `SofaReader.py` file must be in the same folder as the executable `generate_crend_ivas_tables`

   - Run

     ```shell 

     python3 run.py

     ``` 

     → No error message shall appear

      - Using `pip` and `PYTHONPATH`. Add `pip` packages folder (e.g., [`C:\Users\username\AppData\Local\Programs\Python\Python311\Lib\site-packages`](C:\Users\username\AppData\Local\Programs\Python\Python311\Lib\site-packages)) to environment variable `PYTHONPATH`. It can be necessary also to add folder [`../../scripts/pyaudio3dtools`](../../scripts/pyaudio3dtools) to `PYTHONPATH`.  

   - For more details on `generate_crend_ivas_tables` see [`mixer_conv_sofa_to_rom_table_converter_readme.txt`](mixer_conv_sofa_to_rom_table_converter_readme.txt).

### Build tables_format_converter in release or relWithDebugInfo. debug configuration do not work calling numpy

   - open a command line terminal

   - goto /scripts/binauralRenderer_interface/Table_Format_Converter folder

   - mkdir build

   - cd build

   - cmake ..

   - cmake --build .

   - cd .. 

   - tables_format_converter executable shall be in this folder

### Build `tables_format_converter` in `Release` or `RelWithDebugInfo` configuration. `Debug` configuration does not work calling NumPy

   - Open a command line terminal

   - Goto  folder

   - Execute

     ```shell

     cd ../../scripts/binauralRenderer_interface/Table_Format_Converter

     mkdir build

     cd build

     cmake ..

     cmake --build .

     cd ..

     ```

   - `tables_format_converter` executable shall be in the folder [`../../scripts/binauralRenderer_interface/Table_Format_Converter/`](../../scripts/binauralRenderer_interface/Table_Format_Converter)

### matlab scripts from :

 -/scripts/binauralRenderer_interface/matlab_hrir_generation_scripts

   see readme in the folder. Convert dense set of HRIRs into HOA to binaural filters in time domain or in CLDFB domain.

   Required by generate_crend_ivas_tables, parim_bin and fastconv.     

 -/scripts/binauralRenderer_interface/param_bin  

   see readme in the folder. Generate part of rom file ivas_rom_binauralRenderer.c and/or parametric renderer binary file. To generate complete ivas_rom_binauralRenderer.c rom file see example in generate_ivas_binauralizer_tables_from_sofa.m 

 -/scripts/binauralRenderer_interface/fastconv

   see readme in the folder. Generate part of rom file ivas_rom_binauralRenderer.c and/or fastconv renderer binary file. To generate complete ivas_rom_binauralRenderer.c rom file see example in generate_ivas_binauralizer_tables_from_sofa.m . Warning the computed values for late reverberation depend on matlab OS version used. IVAS tests still BE.

 -/scripts/td_object_renderer

    see readme in the folder. Generate part of rom files ivas_rom_TdBinauralRenderer.c ivas_rom_TdBinauralRenderer.c and TD renderer binary file. Warning the computed values depend on matlab OS version used. IVAS tests still BE.  

### MATLAB scripts from

 - [`binauralRenderer_interface/matlab_hrir_generation_scripts`](../../scripts/binauralRenderer_interface/matlab_hrir_generation_scripts)

   - See  [`README.md`](../../scripts/binauralRenderer_interface/matlab_hrir_generation_scripts/README.md) in the folder. 

   - Convert dense set of HRIRs into HOA to binaural filters in time domain or in CLDFB domain.

   - Required by `generate_crend_ivas_tables`, ParamBin, and FastConv.     

 - [`binauralRenderer_interface/param_bin`](../../scripts/binauralRenderer_interface/param_bin)  

    - Generate part of ROM file [`ivas_rom_binauralRenderer.c`](../../lib_rend/ivas_rom_binauralRenderer.c) and/or parametric renderer binary file. 

    - To generate complete [`ivas_rom_binauralRenderer.c`](../../lib_rend/ivas_rom_binauralRenderer.c) ROM file see example in [`generate_ivas_binauralizer_tables_from_sofa.m`](generate_ivas_binauralizer_tables_from_sofa.m)

 - [`binauralRenderer_interface/fastconv`](../../scripts/binauralRenderer_interface/fastconv)

    - See [`README.txt`](../../scripts/binauralRenderer_interface/fastconv/README.txt) in the folder. 

    - Generate part of ROM file [`ivas_rom_binauralRenderer.c`](../../lib_rend/ivas_rom_binauralRenderer.c) and/or FastConv renderer binary file. 

    - To generate complete [`ivas_rom_binauralRenderer.c`](../../lib_rend/ivas_rom_binauralRenderer.c) file see example in [`generate_ivas_binauralizer_tables_from_sofa.m`](generate_ivas_binauralizer_tables_from_sofa.m). 

    - **Warning**: The computed values for late reverberation depend on MATLAB and OS versions used. IVAS tests are still BE.

 - [`td_object_renderer`](../../scripts/td_object_renderer)

    - See [`README.md`](../../scripts/td_object_renderer/modeling_tool/README.md) in the folder. 

    - Generate part of the ROM files [`ivas_rom_TdBinauralRenderer.h`](../../lib_rend/ivas_rom_TdBinauralRenderer.h), [`ivas_rom_TdBinauralRenderer.c`](../../lib_rend/ivas_rom_TdBinauralRenderer.c), and TD renderer binary file. 

    - **Warning**: The computed values depend on MATLAB and OS versions used. IVAS tests are still BE.  

### SOFA files:

   - HRIRs sofa files for testing are stored in ./HRIRs_sofa folder

   - BRIRs sofa files for testing are stored in ./BRIRs_sofa folder

   The current scripts have not been tested with other SOFA files. For other SOFA files some adaptations of the scripts may be required. Current scripts are provided as example.

   - HRIRs sofa files for testing are stored in [`HRIRs_sofa`](HRIRs_sofa)  folder

   - BRIRs sofa files for testing are stored in [`BRIRs_sofa`](BRIRs_sofa) folder

   - The current scripts have not been tested with other SOFA files. For other SOFA files some adaptations of the scripts may be required. Current scripts are provided as an example.

See /scripts/ThirdPartyLegalNotices for related information.

See [`scripts/ThirdPartyLegalNotices`](../../scripts/ThirdPartyLegalNotices) for related information.

## Usage

- Run the following MATLAB script: [`generate_ivas_binauralizer_tables_from_sofa.m`](generate_ivas_binauralizer_tables_from_sofa.m)

  - It will generate ROM files that can be used to compile IVAS decoder or renderer. By default the result is BE. 

  - It will also generate binary files that can be used with `-hrtf` flag in IVAS decoder or renderer command line. 

  - Using IVAS decoder or renderer with default binary files will generate BE output compare to the same command line without `-hrtf` flag. 

  - To test different SOFA files input you need to modify the script in the section `%% Set input files`. Other SOFA files are available in [`HRIRs_sofa`](HRIRs_sofa) folder. 

  - **Warning**: The script will overwrite the tables in [`lib_rend`](../../lib_rend/)

Run the following matlab script : generate_ivas_binauralizer_tables_from_sofa.m

It will generate rom files that can be used to compile IVAS decoder or renderer. By default the result it BE. I will also generate binary files that can be used with -hrtf flag in IVAS decoder or renderer command line. Using IVAS decoder or renderer with default binary files will generate BE output compare to the same command line without -hrtf flag. To test different sofa files input you need to modify the script in the section "%% Set input files". Other sofa files are available in ./HRIRs_sofa folder. Generated files are in folder ./binaural_renderers_hrtf_data.

 Generated files :

 - ivas_binaural_*kHz.bin : file containing all tables values for all IVAS binaural renderers for one sample rate.

 - ivas_binaural_td_*kHz.bin : file containing tables values for IVAS td binaural renderer for one sample rate.

 - ivas_binaural_reverb_*kHz.bin : file containing tables values for IVAS td reverberation process for one sample rate.

 - ivas_binaural_fastconv_*kHz.bin : file containing tables values for IVAS fastconv binaural renderers. All    sample rate files are the same.

- ivas_binaural_parambin_*kHz.bin : file containing tables values for IVAS prametric binaural renderers. All    sample rate files are the same.

 - ivas_binaural_td_*kHz.bin : file containing tables values for IVAS td binaural renderers for one sample rate.

 - ivas_binaural_mixconv_hrir_*kHz.bin : file containing tables values for IVAS mixer conv binaural renderer for HRIR for one sample rate.

 - ivas_binaural_mixconv_brir_*kHz.bin : file containing tables values for IVAS mixer conv binaural renderer for BRIR for one sample rate.

→ Generated files are in folder [`binaural_renderers_hrtf_data`](binaural_renderers_hrtf_data)

- Generated files :

 - `ivas_binaural_*kHz.bin`: file containing all tables values for all IVAS binaural renderers for one sample rate.

 - `ivas_binaural_td_*kHz.bin`: file containing tables values for IVAS td binaural renderer for one sample rate.

 - `ivas_binaural_reverb_*kHz.bin`: file containing tables values for IVAS td reverberation process for one sample rate.

 - `ivas_binaural_fastconv_*kHz.bin`: file containing tables values for IVAS fastconv binaural renderers. Files for all sampling rate files are the same.

 - `ivas_binaural_parambin_*kHz.bin`: file containing tables values for IVAS prametric binaural renderers. Files for all sampling rate files are the same.

 - `ivas_binaural_td_*kHz.bin`: file containing tables values for IVAS td binaural renderers for one sample rate.

 - `ivas_binaural_mixconv_hrir_*kHz.bin`: file containing tables values for IVAS mixer conv binaural renderer for HRIR for one sample rate.

 - `ivas_binaural_mixconv_brir_*kHz.bin`: file containing tables values for IVAS mixer conv binaural renderer for BRIR for one sample rate.

 Without matlab only binary files for mixer conv renderer BRIR can be generated.

   - run for example to use IVAS renderer as a BRIR convolver run successively :

- Without MATLAB only binary files for mixer conv renderer BRIR can be generated.

   - Run, for example, to use IVAS renderer as a BRIR convolver run successively:

  ```shell

  ./generate_crend_ivas_tables -lib_rend_path ./ -brir_optim_config_path ./brir_no_optim.cfg -binary_files_path ./binaural_renderers_hrtf_data  -binary_common_file_name IIS_BRIR_officialMPEG_Combined_no_optim 5 ./BRIRs_sofa/IIS_BRIR_officialMPEG_Combined.sofa 

  ./tables_format_converter -output_file_path ../binaural_renderers_hrtf_data -output_file_name brir_no_optim -input_mixerconv_brir_file_path  ../binaural_renderers_hrtf_data -input_mixerconv_brir_file_name   IIS_BRIR_officialMPEG_Combined_no_optim 

      - IVAS_rend -hrtf ./scripts/binaurelRenderer_interface/binaural_renderers_hrtf_data/brir_no_optim_48kHz.bin ... command line to complete

  ```

  and then to complete, the `IVAS_rend` command line

  ```shell

  IVAS_rend -hrtf ./scripts/binaurelRenderer_interface/binaural_renderers_hrtf_data/brir_no_optim_48kHz.bin ... 

  ```