Common_HRTF_conversion_and_analysis

Common features of HRTF conversion and analysis scripts

How to use the tools from https://sourceforge.net/p/mesh2hrtf-tools/code/ci/master/tree/convert_n_analyse_HRTF/ .

Currently the tools are:

1. • SOFA HRTF plotting tool - plot_sofa_hrtf.py
2. • HeSuVi to SOFA converter - hesuvi_to_sofa_converter.py
3. • SOFA to HeSuVi converter - sofa_to_hesuvi_ir_extractor.py (by direct IR data extraction)

Tutorial Status	Date Written	Date Last Updated
Complete	2022-11-27	2022-11-28

Example: plotting of any SOFA file by double-clicking "plot_sofa_hrtf.py":

---

• Common features of HRTF conversion and analysis scripts
  • Pre-requisites & Installation
  • Usage basics
  • How-To Examples
    • Convert SOFA to HeSuVi
    • Double check SOFA conversion quality
    • Plot all HeSuVi data and convert to SOFA format

Pre-requisites & Installation

The scripts are made for Python 3.8+ (tested in 3.10) and all dependency packages can be installed directly from pip install missing_package_name. Main dependencies are:

• pip install sofar and
• pip install pyfar (which also installs several necessary common packages).

If you need help installing Python itself check Mesh2HRTF Python installation tutorial. (Pip is included with Python).
If you do not want to risk your main Python installation. consider installing pyfar and sofar in a separate Python environment such as "python -m venv venv" in a specific folder (read more details here).

---

Usage basics

Good to know stuff:

1. All scripts can be used in 3 ways:

   1. "Double click" direct execution - if you just run the script in Python without any input arguments it will search for valid input files next to it and produce the default result (which is usually what is needed). Note, this works only if "sofar" is installed in the main Python environment.

   2. Command line with arguments - run from system command line using optional input arguments, for example try python sofa_to_hesuvi_ir_extractor.py --help or python sofa_to_hesuvi_ir_extractor.py --input_dir="TestFiles/Third.sofa" --diagnostic_plot="True"

   3. Python function - each script contains a function that can be called within Python code by for example: import plot_sofa_hrtf and then a usual function call plot_sofa_hrtf.main()

2. "input_1" is a flexible input parameter:

   1. input_1=False - default. Input files are searched next to this script.
   2. input_1=folder_path - SOFA file is searched inside Input folder. "
   3. input_1=path.file_extention - specific input file is used directly.

3. Scripts NEVER modify input data (there is no such option and it would be a major bug) - they can only produce additional new files.

4. By default "--overwrite = True" - script will overwrite any existing result-files with the same name (it should only fix old bugs, but not change the contents).

5. SOFA is the master format! it means that:

   • To plot HRTF from not-SOFA format - convert it to SOFA first and then use SOFA plotting tools. For example see hesuvi_to_sofa_converter.py.
   • Any converter script should convert from SOFA and back to SOFA to ensure compatibility with HRTF analysis and plotting tools.
   • SOFA format supports all metadata - so it is quite robust choice.

6. A typical chain of events is that when you run "SOFA to XYZ converter", it will also call "XYZ to SOFA converter" in order to plot XYZ data using standard "SOFA plotter" scripts. (Note that scripts that are sequentially called will use the result output folder as their input folder and will process any file that fits their input data criteria.)

7. You can copy/move the scripts to any folder where you wish to run them. It may be more convenient than moving the input data. Only remember that scripts often need one-another.

Example: plot of a Mesh2HRTF simulated individual SOFA file after level normalization ("plot_sofa_hrtf.py" v1.02):

---

Troubleshooting:

1. If you double-click a script and the window just closes - you have to run the script in system command line to find out why it happens (see example above^). Just remember that you must open command line / terminal in the folder where the scripts are to run them (or change directory in the command line).
2. most common problem is missing pre-requisites. just run pip install sofar and pip install pyfar.
3. second most common issue - outdated packages causing trouble. Use typical commands are: pip list --outdated and pip install --user --upgrade ThePackageYouNeed.
4. Be creative...
5. Ask for help - go to Discord or create Ticket.

---

For more specific How-To instructions:

1. Just try it! Most scripts are self-explanatory. They pick-up input data that lies next to them and print-out status information both about what they did and what went wrong.
2. Check out the following "How-To Examples".
3. Open script you are interested in text editor - they are quite easy to understand even if you don't know Python.
4. Search for tutorials using specific script name on this Wiki (or other places, like YouTube).

Have fun!

---

How-To Examples

Examples how these scripts can be used:

Convert SOFA to HeSuVi

Goal: Make any SOFA HRTF usable in HeSuVi by directly extracting impulse responses stored inside SOFA file
Same principle can be applied to other conversion scripts to other formats.

Example: output files from converting SOFA to HeSuVi by double-clicking the "sofa_to_hesuvi_ir_extractor.py" script:

Step by Step (assuming the basics are in place):

1. Convert your Mesh2HRTF SOFA file to HeSuVi using the direct IR extraction script:

   1. Place "yourFile.sofa" file next to the "sofa_to_hesuvi_ir_extractor.py" and
   2. Execute "sofa_to_hesuvi_ir_extractor.py" script (double click the script or simple command python sofa_to_hesuvi_ir_extractor.py in the correct Python environment)

   3. Note that new "output" folder will contain:

      • "yourFile_HeSuVi_direct.wav" - the HeSuVi output file.
      • Several ".png" and ".pdf" files with diagnostic plots of the "yourFile_HeSuVi_direct.wav" data.
      • a "yourFile_HeSuVi_direct_from_HeSuVi.sofa" file which was created by converting the HeSuVi file back into SOFA format in order to plot it using common "plot_sofa_hrtf.py" method.

2. Done.

   • Move the .wav file to your "C:\Program Files\EqualizerAPO\config\HeSuVi\hrir\" and select it in HeSuVi to listen.
   • Note: Typical HRTFs in SOFA format assume flat incoming sound and require extra equalization to be used with normal headphones - do not expect perfect tonal balance without additional EQ!.

Note, there are more-than 3 different methods to convert SOFA to HeSuVi. This "sofa_to_hesuvi_ir_extractor.py" method is the easiest and also 100% true to the SOFA file original.

---

Double check SOFA conversion quality

Goal: Double Check that "sofa_to_hesuvi_ir_extractor.py" script does not damage the source HRTF data
Same principle can be applied to other conversion scripts to other formats.

Step by Step (assuming the basics are in place):

1. Convert your Mesh2HRTF SOFA file to HeSuVi using the direct IR extraction script:

   1. Place "yourFile.sofa" file next to the "sofa_to_hesuvi_ir_extractor.py" and
   2. Execute "sofa_to_hesuvi_ir_extractor.py" script (double click the script or simple command python sofa_to_hesuvi_ir_extractor.py in the correct Python environment)

   3. Note that new "output" folder will contain:

      • "yourFile_HeSuVi_direct.wav" - the HeSuVi output file.
      • Several ".png" and ".pdf" files with diagnostic plots of the "yourFile_HeSuVi_direct.wav" data.
      • a "yourFile_HeSuVi_direct_from_HeSuVi.sofa" file which was created by converting the HeSuVi file back into SOFA format in order to plot it using common "plot_sofa_hrtf.py" method.

2. Re-Convert SOFA file created together with HeSuVi output file Again into HeSuVi file:

   1. go to the new "output" folder and copy the "yourFile_HeSuVi_direct_from_HeSuVi.sofa" file.
   2. Paste it back next to the "sofa_to_hesuvi_ir_extractor.py" and

   3. Execute "sofa_to_hesuvi_ir_extractor.py" script again. As a result:

      • script will report that there are now 2 input SOFA files and some of the existing result files will be overwritten (their contents will be the same as before overwriting).
      • notice "yourFile_HeSuVi_direct_from_HeSuVi_HeSuVi_direct_from_HeSuVi.sofa" file where the filename says that the data was 1st converted "_HeSuVi_direct" then "_from_HeSuVi" to SOFA then again "_HeSuVi_direct" and finally "_from_HeSuVi" back to SOFA so that it can be plotted & compared.

3. Confirm that the data is not degraded:

   1. visually compare the equivalent plots from converted and re-converted SOFA files. For example:

      • "yourFile_HeSuVi_direct_from_HeSuVi p1 Left speaker side.png" will be identical to
      • "yourFile_HeSuVi_direct_from_HeSuVi_HeSuVi_direct_from_HeSuVi p1 Left speaker side.png"

   2. Note, HeSuVi data can also be compared to the source SOFA file without any HeSuVi conversion:

      1. Execute "plot_sofa_hrtf.py" script and check the "output" folder:
      2. Plots with-out any "_HeSuVi_direct" in the name should look the same but NOT Normalized compared to the HeSuVi data plots. (because HeSuVi conversion requires to normalize impulse responses to max 0.985)

   3. Bonus numerical check in Python using "sofar" (optional):

      1. Start Python in a command line (preferably start in "output" folder)
      2. Run code to verify that two SOFA files are identical:
         import sofar as sf
converted_data = sf.read_sofa("yourFile_HeSuVi_direct_from_HeSuVi.sofa")
re_converted_data = sf.read_sofa("yourFile_HeSuVi_direct_from_HeSuVi_HeSuVi_direct_from_HeSuVi.sofa")
converted_data.GLOBAL_Title = "Making sure title is the same"
re_converted_data.GLOBAL_Title = "Making sure title is the same"
sf.equals(converted_data, re_converted_data)
# answer True means that the two files are identical in every way despite repeated conversions

Note, there are more-than 3 different methods to convert SOFA to HeSuVi. And then there are various options in the advanced methods. Using these plotting and conversion tools, it is possible to visually see how the methods differ from one another.

---

Plot all HeSuVi data and convert to SOFA format

Goal: Visually show the frequency response applied by HeSuVi processing using various HRTFs. Plus make all the HeSuVi profiles available in SOFA format.

Example: plot of OpenAL HRTF provided by HeSuVi:

1. Locate all HeSuVi .wav files in "C:\Program Files\EqualizerAPO\config\HeSuVi\hrir\"
2. Copy all "convert_n_analyse_HRTF" scripts to the HeSuVi "hrir" folder with .wav files (alternatively copy the .wav files into the "convert_n_analyse_HRTF" folder).
3. Execute "hesuvi_to_sofa_converter.py" script (beacause it will also do the plotting)

4. Newly created "output" folder will contain:

   • "<hesuvi_file>_from_HeSuVi.sofa" HeSuVi file converted to a valid SOFA HRTF file.</hesuvi_file>
   • ".png" and ".pdf" plots of every HeSuVi file. Note, plots are duplicated in 2 formats: .pdf is a vector format with infinite resolution while .png files are better for browsing on Windows and embedding.
   • Note some files have "_7ch" in the filename - it shows that this HeSuVi file only contained 7 channels instead of full-14-channel .wav file. These files are symmetrical on left and right side.