Skip to content

Installation_2

Jump to bottom
Sergejs edited this page Apr 29, 2023 · 6 revisions

Mesh2HRTF installation in Windows (and Linux/Mac)

------------------------------------------------------------ Part of the the Complete Beginner’s tutorial ------------------------------------------------------------
Previous <<< tutorial introduction last updated in 2023-04-29 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 the latest release of Mesh2HRTF "Source code (zip)" from GitHub and extract it to "mesh2hrtf" folder.

    • since the video tutorials Mesh2HRTF is now fully released. Note that any release contains the same files as the master Code repository - cloning git repository is still a valid installation approach.
    • Place the extracted "mesh2hrtf" folder in a good location - this folder must stay in the same location as long as you will use Mesh2HRTF.
    • Note - Mesh2HRTF project has been moved to GitHub since June 2022. Previously the code was hosted on SourceForge.
    • Note - for the absolute latest code, you can try using code from the Develop branch 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.

  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. 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)
    • note: this Python installation is necessary for any computers that will Run simulations using the recommended "manage_numcalc_script.py" or be used for Python Post-processing of Mesh2HRTF projects.

  2. Done.

  3. manual installation of "pip install psutil" is no longer need.

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

The special mesh2input Add-in is used to generate input data for Mesh2HRTF simulation projects from Blender.

"exportMesh2HRTF.py" was renamed to "mesh2input.py" in the release version (still the same thing).

  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 mesh2input.py file which is located in for example: path/to/your/mesh2hrtf-git/mesh2hrtf/Mesh2Input/mesh2input.py

  4. press Install Install Add-on to install it.

  5. 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)

  6. 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 needed for most users.

Main Mesh2HRTF simulation program

The main simulation solver of the Mesh2HRTF is called "NumCalc" - it is the executable that will run for hours and requires many GigaBytes of memory to find the HRTF solutions. In addition, there is a "manage_numcalc_script.py" manager that is usually used to run the simulation.

Install NumCalc manager script

Since 2022-08 "NumCalcManager" functionality is included in the main Mesh2HRTF project but it is necessary to manually locate the correct script:

  1. Find manage_numcalc_script.py in the extracted Mesh2HRTF folder structure: path/to/your/mesh2hrtf-git/mesh2hrtf/NumCalc/

  2. Copy manage_numcalc_script.py into the folder where you will run Mesh2HRTF simulations: folder where you extracted Mesh2HRTF tools is recommended, but not required.

    • on Windows, "NumCalc_WindowsExe" folder (included in Mesh2HRTF tools) must always be located next to the "manage_numcalc_script.py".

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/src run the command make (in the command line, type "make" and hit Enter)
  2. Change to the directory path/to/your/mesh2hrtf-git/mesh2hrtf/NumCalc/bin
  3. "Install" (copy) NumCalc to a folder in your program path: in the same directory run sudo cp NumCalc /usr/local/bin/
  4. 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 manage_numcalc_script.py is provided as a 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 open MSYS2 MSYS.exe and update everything 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/src

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

      • make

    3. You should now have “NumCalc.exe” ready in the "bin" folder (path/to/your/mesh2hrtf-git/mesh2hrtf/NumCalc/bin), 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 may not be fully equivalent to the Python alternative - recommended for advanced users only.

  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\')

Next tutorial step >>> 3D scanning

Clone this wiki locally