Menu ▾ ▴

Basic_HRTF_post_processing

Sergejs
There is a newer version of this page. You can find it here.

Saving HRTF SOFA files

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

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

UNDER CONSTRUCTION!

  • Video tutorial for Windows - Coming soon.

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: "Output2HRTF_Main.py (github.com)" 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".
    • This post processing has a built-in function to join Left and Right side projects into a complete HRTF - exact steps to use this feature may be added at a later point.

  2. There is an alternative post-processing code of the Mesh2HRTF project which requires commercial Matlab software to run - "Output2HRTF_Main.m (github.com)". This code has very similar functionality to the Python post-processing and because it requires very expensive Matlab software to use - is not covered in this tutorial.

    • 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 basic post-processing produces SOFA files that are not compatible with for example SPARTA Binauralizer.

  3. “finalize_HRTF_simulation.py (sourceforge.net)” file is a script that 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 HRIR outputs - 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. If the project settings are supported, it allows to get at least 44.1kHz and 48kHz sofa files generated from a single Mesh2HRTF simulation.
    4. Ensures that the SOFA file uses the more common spherical coordinate system.
    5. Plots the SOFA HRIR data for both ears to give graphical confirmation that the simulation produced valid results.
    6. Checks for various simulation issues and excludes corrupt simulation data to produce usable results even if some instances failed to compute (this is especially useful when attempting to simulate frequencies higher than 24kHz).

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 (sourceforge.net)” (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".

      • It is normal that additional Python windows will open and close while "finalize_HRTF_simulation.py" is running.

    • 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.

    • example printouts from older version of "finalize_HRTF_simulation.py" running on Windows where some non-convergence issues were detected:

  3. Done. The final "HRTF.sofa" 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" will be:

    • HRIR_ARI_48000.sofa - the 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 - the 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 benefit in doing so.
    • HRTF_ARI_48000.sofa - the frequency domain HRTF file. Not as popular as HRIR files.
    • HRIR_ARI_48000.png - the image file with the plot of the HRIR.sofa data for quick graphical test that SOFA files look reasonable compared to other examples. (the plot is only generated if "pyfar" Python package is installed.)
    • 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 (sofacoustics.org) 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.

  3. Crash of "finalize_HRTF_simulation.py" - this is most likely a bug - seek support by opening issue and providing the error information. If it is not possible 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).
    • In case the crash happens in the pop-up command line from the "Output2HRTF_Main.py (github.com)" (it is called by the "finalize_HRTF_simulation.py"), then again it may be difficult to see the error messages. In this case it is necessary to call from command line python Output2HRTF.py from the specific project folder (folder that contains "Output2HRTF.py").

Advanced post-processing

In case “finalize_HRTF_simulation.py" script is too limiting for your simulation needs, advanced users should study the methods and function within the "Output2HRTF_Main.py (github.com)" to access all available features through Python scripting.

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. If there are no advanced headphone EQ options available, a simple 7-band parametric EQ should give enough controls to manually design your own headphone compensation EQ using some trusted speakers in direct-sound conditions (listening in nearfield and/or mostly room-reflection free conditions).

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

  • See SOFA application notes for more tutorials.

The Last part. (Extra Application notes)

MongoDB Logo MongoDB