Installation

Installation instructions

Download the latest version of Mesh2HRTF from github by clicking on Code -> Download ZIP and unpacking the zip file.
Alternatively, clone the git repository with the command git clone https://github.com/Any2HRTF/Mesh2HRTF.git.

Note: The following instructions cover Unix based operating systems. Most tools can be used under MacOS and Windows as well. However, we do not test nor support Mesh2HRTF for MacOS and Windows.

Mesh2Input

These steps are required to export Mesh2HRTF projects from Blender.

Install Blender (version 2.80 or newer)
(Note: If you are running Ubuntu, you can run it without installing, just by extracting the archive and running the command ./blender inside the directory.)

• Open the file path/to/your/mesh2hrtf-git/mesh2hrtf/Mesh2Input/exportMesh2HRTF.py in any text editor.
• Change the default value of the variable programPath to the absolute path of the mesh2hrtf folder by changing the linedefault=r"/path/to/mesh2hrtf",. The folder that you enter should contain the sub-folders Mesh2Input, NumCalc, and Output2HRTF
• Start Blender
• Open Blender, and go to Edit -> Preferences -> Add-ons in the menu.
  
• Press Install..., navigate to path/to/your/mesh2hrtf-git/mesh2hrtf/Mesh2Input/exportMesh2HRTF.py and press Install add-on.
• Tick the checkbox to enable the add-on
  
• If you go to File -> Export you should now see an option Mesh2HRTF

NumCalc

These steps are required to numerically simulate HRTFs with NumCalc and are executed in the terminal.

• Install the C++ build essentials by running sudo apt-get install build-essential
• Go into the NumCalc directory by running cd path/to/your/mesh2hrtf-git/mesh2hrtf/NumCalc/Source
• Compile NumCalc by running make
• Copy NumCalc to a folder in your program path: in the same directory run sudo cp NumCalc /usr/local/bin/
• Now NumCalc can be used by running NumCalc (don't do this yet).

Output2HRTF

Using mesh2HRTF with Python

The Mesh2HRTF Python API is required for processing and inspecting HRTFs. It needs to installed in the terminal, before it can be used.

Environment
It is recommended to create an environment for mesh2hrtf. This can for example be done with conda or Anaconda in a terminal or the Anaconda Prompt.
conda create --name mesh2hrtf python
conda activate mesh2hrtf

Install mesh2hrtf package
To make mesh2HRTF available in Python, go to your mesh2HRTF directory (the one containing setup.py) by running
cd your/path/to/mesh2hrtf-git
Then install mesh2HRTF using pip
pip install -e .
Note that the -e option will make changes in mesh2HRTF immediately available. This is helpful if you adapt parts of the code to your needs. If you do not want this, omit this option.

You can now use mesh2HRTF by importing it in your Python code, e.g.
import mesh2hrtf as m2h

Testing
If you want to develop or test mesh2HRTF make sure to also install the requirements listed in setup.py under test_requirements, e.g.
pip install -r requirements_python.txt
Don't forget to
pip install ipykernel
in case you want to interactively debug your changes.

Using mesh2HRTF with Matlab

These steps are required to save HRTFs as SOFA files using Matlab.

Requirements: Octave or Matlab, SOFA-API

• Add the folder path/to/your/mesh2hrtf-git/mesh2hrtf/Output2HRTF/Matlab to your Matlab path
• Downlaod and add the Matlab toolbox SOFA Matlab API (or get the source code from Github to have the latest version) to your Matlab path by running SOFAstart.m
• (Note: you perhaps need a workaround to permanently add the folders to the MATLAB search path. Mine was replacing the pathdef.m file in /usr/local/MATLAB/R2020b/toolbox/local.)