Menu ▾ ▴

Installation_2

Sergejs

Mesh2HRTF installation in Windows (and Linux/Mac)

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.
------------------------------------------------------------ Part of the the Complete Beginner’s tutorial ------------------------------------------------------------
Previous <<< tutorial introduction \\\ Express tutorial /// Next >>> 3D scanning

Video version of this tutorial:

Note: these instructions are primarily focused on Windows (but should work great for Linux / Mac as well). Most of the steps are equally applicable to Linux and Max as well, However, Windows is not the main Mesh2HRTF platform and gets only limited development team support.
The main instructions can be found here: [Installation] and cover the primary Linux and Mac OS platforms.

Downloads and pre-requisites

To run common Mesh2HRTF workflows (as needed for this Complete Beginner’s tutorial) you need to:

  1. Download Mesh2HRTF code from GitHub by clicking on Code ==> Download ZIP and unpacking the zip file. Alternatively (for advanced users), clone the git repository to be able to use Git for fetching future updates.

    • Mesh2HRTF software has been moved to GitHub. Previously the code was hosted on SourceForge.
    • At this moment, only the develop branch is considered to be up-to-date for Mesh2HRTF v1 (any older code is no longer supported).
    • Note - place the extracted "mesh2hrtf" folder in a good location - this folder must stay in the same location as long as you will use Mesh2HRTF.

  2. Download extra Mesh2HRTF tools from SourceForge the same way (click on Download Snapshot and unpack the zip file, or clone the repository).

    • Note - "mesh2hrtf-tools" folder can serve as the main location for your Mesh2HRTF tools simulation projects
    • "mesh2hrtf-tools" folder can always be freely moved around your computer - location does not matter.

  3. Download & Install Blender (latest version or at least v2.80)

  4. Download "3d_Model_uniform.blend" example Blender file that will be used as a template. (it contains mesh from Ziegelwanger et al (2013)).

  5. Python -See next paragraph.

Install Python for Mesh2HRTF

Python (3.9 or newer v3.x) is necessary for Mesh2HRTF workflow.
There are multiple options how to install Python (and there can be many parallel Python installations on one computer). Here are some alternatives:

  1. Direct installation - fast & very convenient approach, but comes with a limited risk of disturbing other Python tools that you previously-installed in the same Python environment (if issues ever occur, you may need to re-install affected software or the default Python environment).

  2. Anaconda/Miniconda installation - safe approach, but may be unnecessary if you do not use many different custom Python-based tools.

  3. You can create venv virtual environments from Python command line or any other advanced method.

Check that all packages are up to date! if you are using existing Python environment. You could run into unpredictable errors if for example "NumPy", "pyfar" or "sofar" is too old. Typical commands are: pip list --outdated and pip install --user --upgrade ThePackageYouNeed .

alt 1- Direct Python installation

This alternative is the fastest and will install Mesh2HRTF into your main Python 3 installation. It allows for direct access to all Mesh2HRTF tools from any command line or even directly from Windows Explorer. The downside is the possibility for package conflicts with other custom Python tools.

  1. First check if you already have some form of Python3.x available on your computer. The easiest way is to open Command Prompt (cmd.exe) and type in python.
    • A - If you had Python, you will see Python version and you can type exit() to quit. Note, in case the installed Python version is 3.6 or older, then it is best to use the Anaconda approach (upgrading to a newer Python could cause previously installed Python software to stop working).
    • B - If you did not have Python3 installed, Windows will open Store page where you can safely press “Get/Install” to install the latest Python (3.10 is tested to work well).
      • Alternatively you can search for another version of Python in the Windows Store. (for example v3.9 may be more widely compatible version for other packages).
      • Alternatively you can install the same or an older version of Python from https://www.python.org/downloads/ (just make sure you choose to add the installed Python to PATH).
      • For Linux and MacOS please check the instructions from https://www.python.org/downloads/
  2. Open a command line (cmd.exe, PowerShell, etc.) in the working directory of your main Mesh2HRTF directory (folder containing “setup.py” file).
    • The easiest way is to open the correct folder in Windows Explorer and in the address bar type in cmd and hit Enter.
  3. Continue to the mesh2hrtf Python package installation

alt 2- Anaconda Python installation

This alternative will crate a separate Python installation (environment) only for Mesh2HRTF. Anaconda makes use of virtual Python environments quite easy.
The downside is that Anaconda creates a Lot of files in your C:\Users\%username% folder which can remain there even after uninstalling Anaconda.
Another reason to choose Anaconda is if you plan to use other scientific software or Matlab-like Python editor - Spyder (Conda is practically required to use Spyder with custom Python package support).

  1. Download and install either Anaconda Individual edition or the more minimalistic version called Miniconda (with Python 3.9 or the Python version you intend to use for Mesh2HRTF). Default settings should work fine.
  2. Open “Anaconda PowerShell Prompt” by using shortcut in Windows Start menu.
  3. Optional, for Miniconda only: you can install Anaconda GUI interface that gives direct overview over existing Environments and other Anaconda features by executing: conda install anaconda-navigator
  4. Create the separate Python environment for Mesh2HRTF (press “yes” to everything): conda create --name mesh2hrtf python=3.9
  5. Activate the new environment (this can also be done from Anaconda Navigator GUI): conda activate mesh2hrtf
  6. Optional: To add a Matlab-like graphical interface for running Python scrips, it is recommended to also install and use Spyder: conda install -c anaconda spyder
    • If you open Spyder using normal shortcut, then to configure Spyder to work with your mesh2hrtf environment you need to go to 'Tools > Preferences > Python Interpreter > Use the following interpreter'
    • in Windows Anaconda should also create a dedicated "Spyder (mesh2hrtf)" start-menu shortcut for opening Spyder using "mesh2hrtf" environment.
  7. Change directory to your main Mesh2HRTF directory (folder containing “setup.py” file): cd c:\your\path\to\mesh2hrtf
  8. Continue to the next paragraph...

mesh2hrtf Python package installation

This is a continuation of Python installation from either Direct or Anaconda Python installation.

  1. For a computer that will Run simulations: Type pip install psutil to install prerequisite to run "NumCalcManager.py".
    • Note that to only run simulations using "NumCalcManager.py" this is the only command you need. There is no need to install the complete "mesh2hrtf" package and no need to have main Mesh2HRTF directory on a simulation-only computer.
    • Note, this command can be executed from any current directory, as it only installs additional common software from the Internet into your Python environment.
    • Fail-safe approach, ONLY in case you get an error that “pip is not recognized as a command":
      • In the command line type python or python3 to open Python.
      • Then type import pip, followed by pip.main(['install', 'psutil']).
      • Now if you enter import psutil you should not get any errors and you are done (maybe you will need to re-start the Python to see the effect).
  2. For a computer that will post-process Mesh2HRTF projects: Type pip install -e . to Install mesh2hrtf Python package using pip (into the current Python environment). It will install all external Python dependencies and the mesh2hrtf Python package that generates final SOFA files (Output2HRTF).
    • Note that the -e option will make changes in Mesh2HRTF Python files immediately available. This is helpful if you download updates or make your own changes to the code. If you do not want this, omit this option.
    • Remember that this command must be executed in a command-line from the folder containing mesh2HRTF “setup.py” file. (Do not run this inside Python)
  3. Done.

Optional: 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 pytest numpy>=1.14.0 scipy>=1.5.0 matplotlib
Don't forget to
pip install ipykernel
in case you want to interactively debug your changes.

Configure Blender to create Mesh2HRTF projects

Mesh2Input module is used to export Mesh2HRTF projects from Blender.

  1. Start Blender

    • (Note: If you are running Linux, you can run Blender without installing, just by extracting the archive and running the command ./blender inside the directory.)

  2. Go to Edit -> Preferences -> Add-ons -> Install...

  3. Select the exportMesh2HRTF.py file which is located in for example: path/to/your/mesh2hrtf-git/mesh2hrtf/Mesh2Input/exportMesh2HRTF.py
  4. press Install Install Add-on to install it.
  5. Now find the addon in the list by typing for example mesh2 in the search field
  6. Make sure you Tick the checkbox to enable the add-on "Import-Export Mesh2HRTF"
    • Note: if you expand the information, you can see the complete path where the script is now located. (Blender will always use this copy of the script. If you need to update or modify "exportMesh2HRTF.py" script, you can either replace the Blender's copy by a new version manually or install the Add-on again)
  7. Done. (If you go to File -> Export you should now see an option Mesh2HRTF)

Advanced Blender setup: Instructions how to modify default settings of the export script - it is possible to customize the default Blender export settings so, but it is not necessary for most users.

Main Mesh2HRTF simulation program

The main simulation solver of the Mesh2HRTF is called "NumCalc" and is the executable that will run for hours and requires many GigaBytes of memory to find the HRTF solutions.

Install NumCalc on Windows

On Windows, if you have already extracted Mesh2HRTF tools then you are already Done.

  • Note, this is valid ONLY if the NumCalc.exe was compiled AFTER the latest changes to the NumCalc source files (see commit dates here). If the NumCalc.exe is obsolete, then you may need to re-compile it.

Compiling NumCalc on Linux/Mac

In Linux/Mac, you do need to compile NumCalc from source, but it is extremely easy:
1. Compile it: in the directory path/to/your/mesh2hrtf-git/mesh2hrtf/NumCalc/Source run the command make (in the command line, type "make" and hit Enter)
2. "Install" (copy) NumCalc to a folder in your program path: in the same directory run sudo cp NumCalc /usr/local/bin/
3. Done.

Note: NumCalc is only a single-threaded solver code that could be given a whole project to execute sequentially, but in practice that would be extremely slow, inefficient and risky (if NumCalc is launched without extra parameters, it deletes all previously existing output data and starts-over simulation from the 1st step).
Therefore it is highly recommended to also use NumCalcManager.py from Mesh2HRTF tools or some other scheduler that can efficiently monitor resource usage and correctly launch multiple NumCalc instances in parallel.

Compiling NumCalc on Windows using MSYS2

If you need to re-compile NumCalc.exe (compiled binaries are obsolete), then it can be compiled by any MinGW 64bit compiler. This method uses MSYS2 version of MinGW64 compiler, but there are also other valid approaches to use MinGW compiler variants on Windows.
Sidenote MSYS2 is also used to compile hrtf_mesh_grading.exe for Mesh2HRTF.

  1. Go to https://www.msys2.org and get the MSYS2 by following the excellent Installation instructions on the front-page.

    1. First run the Windows Installer using simple GUI.
    2. Then Update everything using pacman within “MSYS2 MSYS.exe” by pasting-in the following commands (answer “Y” or just hit Enter key on all prompts). Tip: re-run all update commands more than once until it says that there is nothing more to update.:
      • pacman -Syu (Update the package database and base packages.)
      • pacman -Su (Update the rest of the base packages)
    3. Install the MinGW with GCC needed for NumCalc compiling:
      • pacman -S --needed base-devel mingw-w64-x86_64-toolchain
    4. Close “MSYS2 MSYS.exe”

  2. Open “MSYS2 MinGW 64-bit.exe” that you just installed and proceed to compile NumCalc.exe:

    1. Use the following commands to change to the “Source” folder from which the compilation needs to be started. (To be on the safe side, do not use paths with spaces and non-standard characters):

      • cd C:
      • cd path/to/your/mesh2hrtf-git/mesh2hrtf/NumCalc/Source

    2. Compile (using the normal Linux make command):

      • make
    3. You should now have “NumCalc.exe” ready in the source folder, but there are a few steps left before running the simulation. Close “MSYS MinGW 64-bit.exe”

  3. Fixing the DLLs to make your NumCalc.exe work. (Note, it is somehow possible to include all the necessary DLLs into .exe file during compilation, but this method works too):

    1. Copy your “NumCalc.exe” out to another folder before running it (recommended).
    2. Try running “NumCalc.exe”. Most likely you will get “___.dll not found” error which means that it needs some .dll files in the same folder as NumCalc.exe to run.
      • You can find all the missing .dll files in the C:\msys64\mingw64\bin folder. Just copy the files with the right name next to the “NumCalc.exe”. Most likely the needed DLLs are: “libgcc_s_seh-1.dll”, “libstdc++-6.dll”, “libwinpthread-1.dll”.
    3. If you run “NumCalc.exe” and right after opening it closes without errors and you see 2 new folders and a new “NC.out” file then it means it is working and ready to be used.

Fully compiled and ready to run NumCalc instance for running on Windows includes see example here:

  • "NumCalc.exe"

  • (most likely) 3 different necessary .dll files

  • Optional, just for testing - "- run_NumCalc_instance.bat"

Optional and alternative packages

The following modules should be installed only if Necessary.
Most users will not use the following modules.

Alternative Matlab Post-Processing

There is an alternative code for Matlab to generate SOFA files.
Warning Matlab Output2HRTF code currently is not equivalent to the Python alternative and may be missing some features (for example SOFA compatibility fixes and ability to merge left and right side SOFA simulations).

  1. Get Matlab (very-expensive, commercial software) or Open-source alternative Octave. (Note, instead of using Octave, where compatibility is not being always tested, it is more reliable to just use Python post-processing).
  2. Download & extract the open-source Matlab/Octave toolbox SOFA Matlab API (preferably get the latest source code from Github.
  3. See usage instructions how to addpath() and initialize the SOFA API (SOFAstart) to use Matlab Mesh2HRTF scripts.
    • You will need to use addpath('path/to/your/mesh2hrtf-git/mesh2hrtf/Output2HRTF')
    • and addpath('path/to/your/SOFA API for Matlab and Octave\API_MO\')

EvalTools

These steps are required to visualize the sound pressure on the Mesh, e.g., a 3D head model.

Requirements: Matlab, Paraview

  • Add the folder path/to/your/mesh2hrtf-git/mesh2hrtf/PostProcessing to your Matlab path (with subfolders)

Useful 3rd party software

This software is not required and not related to Mesh2HRTF, but can be useful for Mesh2HRTF users:

Next tutorial step >>> 3D scanning

Related

Wiki: Basic_HRTF_NumCalc_Simulation
Wiki: Basic_HRTF_tutorial
Wiki: Basic_tutorial_3d_scanning
Wiki: Change_Blender_export_defaults
Wiki: Express_Basic_HRTF_tutorial
Wiki: Installation
Wiki: NumCalc

Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.