Menu ▾ ▴

Basic_HRTF_post_processing

Sergejs

Saving HRTF SOFA files

WARNING:
This Tutorial is valid ONLY for Mesh2HRTF files from 2022-06-23. Update for the 1.0 version will be made closer to the release.

The post-processing generates the final HRTF and HRIR .sofa files out of hundreds of individual raw simulation result files.

------------------------------------------------------------ Part of the the Complete Beginner’s tutorial ------------------------------------------------------------
Previous <<< The HRTF Simulation \\\ Express tutorial /// The Last part. (Extra Application notes)

Video version of this tutorial:

Background

Post processing for Mesh2HRTF has several parts, but for most users who just need to create their HRTF everything comes down to running a single file: "finalize_HRTF_simulation.py".

For reference:

  1. The official post-processing code of the Mesh2HRTF project that is responsible for converting raw simulation results into SOFA files is: "output_to_hrtf.py" that runs in Python and requires installation of mesh2hrtf Python package.

    • To launch the Python post-processing each Blender generated project folder has a script called "Output2HRTF.py".
    • The Python post-processing has a number of extra functions that can be accessed from Python - see Mesh2HRTF Python API
    • This post processing has a possibility to join Left and Right side projects into a complete HRTF. "merge_sofa_files" function is accessible using Python API commands (it requires some Python scripting).

  2. There is an alternative post-processing code of the Mesh2HRTF project which requires commercial Matlab software to run - "Output2HRTF_Main.m". Matlab post-processing has very similar functionality to the Python post-processing and is recommended only for advanced Matlab users.

    • To launch the Matlab post processing each Blender generated project folder has a script called "Output2HRTF.m".
    • NOTE: currently this post processing handles just 1 project and that means that it can not automatically produce complete HRTF if the simulation contains 2 project folders.
    • NOTE: even if Mesh2HRTF is used in "Both ears" mode to simulate both ears in one project, the Matlab post-processing produces SOFA files that may not be compatible with for example SPARTA Binauralizer.

  3. The “finalize_hrtf_simulation.py” script is made to compliment the main Python post-processing of the Mesh2HRTF. This script is currently not part of the Mesh2HRTF project, but it implements a few useful features, all from a single "double-click":

    1. Executes "Output2HRTF.py" files inside both Left and Right side project folders.
    2. Joins Left and Right halves of the HRTF into a complete HRTF.
    3. Produces multi_samplingrate_hrirs - in addition to the maximum possible sampling rate defined by "Max. frequency" project setting, the "finalize_hrtf_simulation.py" will produce extra HRIR.sofa files at all possible common sampling rates using naming convention as described here. Typically this is used to generate 44.1kHz and 48kHz sofa files from a single Mesh2HRTF simulation that uses 150 of 75 Hz frequency step setting.
    4. Plots the SOFA HRIR data for both ears to give graphical confirmation that the simulation produced valid results.
    5. Has some extra data quality checks and user feedback features to make post-processing more intuitive and help in troubleshooting.

Generate HRTF SOFA file

The "finalize_HRTF_simulation.py" script is optimized for beginners and executes the complete post-processing in a couple of simple steps:

  1. Move both Mesh2HRTF project folders into the folder that contains “finalize_hrtf_simulation.py” (one project folder for the left side and one folder for the right side). If you followed all tutorial recommendations then the correct /Finalize_HRTF_simulation/ should be right next to your 2 project folders, so a simple drag-and-drop in the Windows Explorer should do the trick.

  2. Run: "finalize_hrtf_simulation.py" in the correct Python environment (environment where you installed “mesh2hrtf” package).

    • On Windows, launching can be as easy as double click the "finalize_hrtf_simulation.py" file. This works in case of Direct Python installation (here the "pip install -e ." part of installation is required). In some Python installations, if double-click does not work - use "Open with" ==> "Python 3.x".

    • For Linux, Mac, Windows Anaconda installations or any other Python environment cases it is always possible to write python finalize_hrtf_simulation.py(or possibly "python3 finalize_hrtf_simulation.py") in the command line of the environment where "mesh2hrtf" Python package was installed.

    • Be careful on Windows: do not click inside the Python window. If you see a “white square cursor” – the running script will be paused and it will not do anything. To escape the problem: press “Esc” key until “white square cursor” disappears.

    • In case you need to re-run the "finalize_hrtf_simulation.py" - just delete the folder with the merged SOFA files that it creates and it is possible to run again.

  3. Done. The final HRTF and HRIR sofa files will be saved next to the input project folders (path is visible in the printouts of the "finalize_hrtf_simulation.py" script). the typical final output from Mesh2HRTF simulation after the "finalize_hrtf_simulation.py" for each Evaluation Grid (in this example "ARI") will be:

    • HRIR_ARI_48000.sofa - main "HRTF" file to use if sound card is used at 48kHz sampling rate ("the DVD sampling rate" - common in video files).
    • HRIR_ARI_44100.sofa - main "HRTF" file to use if sound card is used at 44.1kHz sampling rate ("the CD sampling rate" - common among music files).
    • any additional HRIR sampling rates - if the simulation "Max frequency" was higher than 24kHz, then there will be additional HRIR.sofa files. Note, while it is technically possible to simulate 96kHz, 192kHz and other extended frequency range sampling rates, there is almost no practical reason in doing so.
    • HRTF_ARI_48000.sofa - frequency domain HRTF file. (contains practically the same information as HRIR file).
    • HRIR_ARI_48000.png - image file with a plot of the HRIR.sofa data for quick visual inspection that SOFA files look similar to known examples.
    • HRXX_ARI_xxxxx_2D.pdf - one more plot of the HRIR/HRTF.sofa data generated by standard Mesh2HRTF function inspect_sofa_files.
    • HRXX_ARI_xxxxx_3D.jpeg - one more plot of the HRIR/HRTF.sofa data generated by standard Mesh2HRTF function inspect_sofa_files.
    • Info.txt - a simple copy of the project Info file generated by Blender. Can be useful for keeping track of the origin of the SOFA files.

example of good simulated HRIR data plotted and saved by "finalize_hrtf_simulation.py" v1.2 for graphical comparison

Troubleshooting

Normally the post-processing itself should be very quick and mostly automatic, but different issues can still get detected during post-processing:

  1. The final SOFA file does not work in a program "X" - even though SOFA format is a standardized by AES (AES69-2020) there is no guarantee that specific software will support all variants of the SOFA format and there simply can be bugs.

    • First try a known working SOFA file in your application. The de-facto reference SOFA file format that is likely supported by majority of software is the format used in ARI HRTF database. The most up-to-date files from ARI database can be downloaded here: http://sofacoustics.org/data/database/ari/ . For example you can download and try dtf_nh15.sofa file. Note that files produced by "finalize_hrtf_simulation.py" follow almost exactly the same format as the reference ARI database SOFA files.

    • Try another software. The files produced by "finalize_hrtf_simulation.py" should work in examples described in SOFA application notes.

  2. Various "ERROR" and "PROBLEM" printouts from "finalize_hrtf_simulation.py" usually are symptoms of issues encountered during simulation - please go to Simulation Troubleshooting for more guidance.

    • Additional details and statistics on the simulation are saved by "output_to_hrtf.py" in each project folder under sub-folder /Output2HRTF/. For example "report_source_X.csv" file contains most of the stats.

  3. Crash of "finalize_hrtf_simulation.py" - this is most likely a bug - seek support by opening support issue and providing the error information. It is important to read the error printouts.

    • If the script is executed by double-clicking, the "finalize_hrtf_simulation.py" window will close itself in case of code errors. In such case it is necessary to launch the "finalize_hrtf_simulation.py" from command line. Write python finalize_hrtf_simulation.py(or possibly "python3 finalize_hrtf_simulation.py") in the command line of the environment where "mesh2hrtf" Python package was installed (For Direct Python installation on Windows a suitable command line is just "cmd.exe" in the folder where "finalize_hrtf_simulation.py" is located).

      • As "finalize_hrtf_simulation.py" calls "Output2HRTF.py" in each project folder, which in turn runs "output_to_hrtf.py" it may be useful to identify which project causes a problem in the Python post-processing by running python Output2HRTF.pydirectly in each project folder.

Advanced post-processing

  • "finalize_hrtf_simulation.py" has additional command line arguments which can be useful for advanced use (open the script itself for details).
  • In case “finalize_hrtf_simulation.py" script is too limiting for your simulation needs, advanced users should study the methods and functions in Mesh2HRTF Python API to access all available features through Python scripting or make their own scripts just like “finalize_hrtf_simulation.py".

Tips on use of HRTF SOFA files

The main scope of Mesh2HRTF and this tutorial stops at delivering the sofa files. Here is some additional information that can help in practical use of the HRTF files generated by Mesh2HRTF:

  • Most software that supports .sofa files actually expects the "HRIR.sofa" files even if it may be referred to as "HRTF".

  • The resulting sofa files assume completely flat headphone response on input. To use these files, at least a basic "diffuse field" equalization needs to be applied (such as available in SPARTA Binauralizer) or use even more sophisticated headphone EQs. Individual equalization of headphones for use with HRTFs is a topic for a separate tutorial with many alternative approaches.

  • See (partial) list of software with SOFA support on the sofaconventions.org to find more tools and applications for SOFA files.

  • See SOFA application notes for more tutorials.

The Last part. (Extra Application notes)

Related

Wiki: Basic_HRTF_NumCalc_Simulation
Wiki: Basic_HRTF_tutorial
Wiki: Express_Basic_HRTF_tutorial