Skip to content

Basic_HRTF_post_processing

Jump to bottom
Sergejs edited this page Aug 31, 2022 · 4 revisions

Saving HRTF SOFA files

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 last updated in 2022-08-31 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. This tutorial explains the simplest post-processing approach, using “finalize_hrtf_simulation.py” script. It is made to perform the complete post-processing with zero coding using a single "double-click" or a console command:

    1. Executes the normal "output2hrtf" Python post processing that converts raw simulation results into SOFA files.
    2. Joins Left and Right halves of the HRTF into a single SOFA file.
    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.

  2. The main post-processing code of the Mesh2HRTF project is: "output2hrtf" function in the Mesh2HRTF Python API - see the corresponding tutorial to learn the scripting commands to use it directly.

  3. For advanced Matlab users, there is also an alternative Matlab post-processing code of the Mesh2HRTF project - "output2hrtf.m".

    • NOTE: there is no guarantee that Matlab and Python functions have the same functionality or produce equivalent output.

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. 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.
    • Paraview vtk files - folders with files for visualizing HRTF using Paraview (can be deleted if not needed).
    • parameters.json - 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 "output2hrtf.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 "output2hrtf.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 (run python finalize_hrtf_simulation.py -h from the system command line 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)

Clone this wiki locally