The following tutorials show how to use Mesh2HRTF. If you are new to Mesh2HRTF it is recommended that you go through all of the tutorials before starting your own projects.

Scattering from a rigid sphere

This tutorial covers the scattering from a rigid sphere due to a point source that radiates sound.

Pre-processing

Open Blender.
Delete the box, to have an empty space (Leave the camera and the light. They are needed for saving images of your project).
Add an ico-sphere mesh (Add -> Mesh -> Ico Sphere).
In the Add Ico Sphere window at the bottom left, adjust the mesh settings:
- Subdivisions: 6
- Radius: 0.1 m
- Location: X 0, Y 0, Z 0
- Rotation: X 0°, Y 0°, Z 0°
Rename the Icosphere object to "Reference" (case-sensitive!).
If you are working on the 'Radiation' tutorial, go back.
Add a point source (Add -> Light -> Point).
In the Add Light window at the bottom left, adjust the position:
- Location: X 0 m, Y 0.2 m, Z 0 m
Rename the Point object to "Point source" (case-sensitive!).
If you are currently doing the 'Non-rigid boundary conditions' tutorial, go back.
If you are currently doing the 'Scripting Blender with Python' tutorial, go back.

Project export

Once the Mesh2HRTF project is prepared in Blender it has to be exported for the numerical calculation as follows.
If you are currently doing the 'Scripting Blender' tutorial, go back.

Open the Mesh2HRTF Export Menu (File -> Export -> Mesh2HRTF). (If you cannot find the export option, go to the [Installation] section and just follow the 'Mesh2Input' section.)
Choose or create an export folder, e.g., /Users/JDoe/Simulations/RigidSpherePointSource.

CAUTION: Before you click on Export Mesh2HRTF you have to adjust the following settings accordingly!

The file name field at the bottom of the window must be empty, remove any default text such as "untitled".
Adjust the export settings:
- Title: Scattering from a rigid sphere by a point source
- BEM Method: ML-FMM BEM
- Source Type: Point source
- Pictures: False
- Reference: False
- Compute HRIRs: False
- Unit: m
- c: 343.18
- rho: 1.1839
- Evaluation Grids Name: PlaneHorizontal
- Materials Path(s): None
- Min. frequency: 1000
- Max. frequency: 16000
- Frequencies: Step size
- Value: 1000

Press Export Mesh2HRTF.
A detailed description of all export parameters can be found here.
A detailed description of the project folder structure that is created by the export can be found here.
If you are working on the 'Radiation' tutorial, go back.
If you are currently doing the 'Non-rigid boundary conditions' tutorial, go back.
If you are currently doing the 'HRTF' tutorial, go back.

Numerical calculation

In the folder /Users/JDoe/Simulations/RigidSpherePointSource/NumCalc/source_1 run the command NumCalc from a terminal.

Adding >NumCalc.txt to the command creates an additional log file.
Adding 2>NumCalcErr.txt to the command creates an additional error log file, i.e. NumCalc >NumCalc.txt 2>NumCalcErr.txt.

Note: There are bash scripts that can be used or modified to run multiple projects and cores with a single command. See [NumCalc] for more information

Note: NumCalc saves the HRTFs in a bunch of text files. For a detailed description of the created files, see [Mesh2HRTF Project Folder]

Post-processing

If you are doing the post-processing for first time, follow the installation steps for [Output2HRTF]
When all calculations are done, run python Output2HRTF.py in a terminal in your project folder. This executes output_to_hrtf from the mesh2hrtf Python package for your proejct.
The following files are created in YourProjectFolder/Output2HRTF:
- ObjectMesh_name.npz - mesh file for each object mesh
- HRTF_evalgrid name .sofa - pressure transfer functions and impulse responses in SOFA format for each evaluation grid
- report_source_X.csv - a log file for each source simulated inNumCalc/source_X, containing information about convergence and computation time for each frequency step
To generate VTK files for visualization in Paraview, you need to run export_to_vtk from the mesh2hrtf Python package in a next step.
The following files are created in YourProjectFolder/Output2HRTF/Reference_vtk:
- frequency_step_frequency index.vtk - SPL values on the object mesh for each frequency that was simulated in VTK format
If you are currently doing the 'Non-rigid boundary conditions' tutorial, go back.
If you are working on the 'HRTF' tutorial, go back.

Alternative: MATLAB Post-processing

When all calculation processes are done, start Matlab.
If you are doing the post-processing for first time, follow the installation steps for [Output2HRTF]
Navigate to your project folder (/Users/JDoe/Simulations/RigidSpherePointSource).
Run Output2HRTF. The following files are created in YourProjectFolder/Output2HRTF:
- computationTime.mat - struct containing computation times for each ear, CPU and core
- ObjectMesh_name.mat - mesh file for each object mesh
- HRTF_evalgrid name .sofa - pressure transfer functions and impulse responses in SOFA format for each evaluation grid
The repository also contains a script Output2HRTF_RunAll.m located in mesh2hrtf-git/mesh2hrtf/Output2HRTF/Source. It allows you to run Output2HRTF in every NumCalc subfolder of your project if you ran calculations on multiple CPUs/cores. It also comes with an option of deleting the raw simulation data after processing, as it can be rather storage-intensive depending on your simulation.
If you are currently doing the 'Non-rigid boundary conditions' tutorial, go back.
If you are working on the 'HRTF' tutorial, go back.
Run Output2VTK to create VTK-files for visualization. (Make sure that you added the directory mesh2hrtf/PostProcessing/VisualizationForParaView(Matlab) in the source files to your Matlab path. Otherwise there might be an error!)
The following files are created in YourProjectFolder/Visualization/ObjectMesh:
- amp_frequency index.vtk - SPL values on the object mesh for each frequency that was simulated in VTK format

Visualization

Start Paraview.
Load the VTK-files. They are located in /Output2HRTF/Reference_vtk within your project folder.
When you click on Apply the visualization should look like this:

Radiation from an active vibrating element in a rigid sphere

This tutorial covers the usage of material definitions on a rigid sphere to define a sound source (vibrating element) its the surface and calculate the resulting sound pressure distribution on the sphere.

Pre-processing

Prepare a Blender project and add an ico-sphere mesh as in the first tutorial.
Switch Viewport Shading to Material Preview Mode.
Select the ico-sphere and go to the Materials panel.
Add three materials ("Skin", "Left ear", "Right ear" - warning: case-sensitive!). For each:
- Add a Material Slot.
- Add a new Material.
- Name it accordingly.
- Assign a Base Color in the Surface section of the Materials panel.

The complete materials list looks like this:

Switch the top panel to Edit mode (3D View: Object Mode -> Edit mode or Tab).
Define all elements as Skin and one single element as Left ear:
- Select all elements (press 'A').
- Assign the material Skin to all (should already be the case by default if you defined that material first).
- If you are currently doing the 'Non-rigid boundary conditions' tutorial, go back.
- Switch to Face Select.
- If you are currently doing the 'HRTF' tutorial, go back.
- Select a single element.
- Assign the material Left ear to this element.

Project export

Follow the steps in the first tutorial, but using the following export settings:
- Title: Radiation from an active vibrating element in a sphere
- BEM Method: ML-FMM BEM
- Source Type: Left ear
- Pictures: False
- Reference: False
- Compute HRIRs: False
- Unit: m
- c: 343.18
- rho: 1.1839
- Evaluation Grids Name: ARI
- Materials Path(s): None
- Min. frequency: 1000
- Max. frequency: 16000
- Frequencies: Step size
- Value: 1000

Numerical Calculation

Follow the steps in the first tutorial.

Post-processiung

Follow the steps in the first tutorial.

Visualization

Start Paraview.
Load the VTK-files. They are located in /Output2HRTF/Reference_vtk within your project folder.
When you click on Apply the visualization should look like this:

Simulations with non-rigid boundary conditions

This tutorial introduces the use of materials to define admittance boundary conditions.

Pre-processing

Follow the steps in the first tutorial to create an Icosphere and a Light Point source in Blender (remember to name them correctly!)
Similar to the Material definition of the second tutorial
- Add a material named "ExampleAdmittance" (case-sensitive!).
- Assign it to the entire Ico Sphere.

Project export

Follow the steps in the first tutorial, but using the following export settings:
- Title: Non-rigid boundary conditions
- BEM Method: ML-FMM BEM
- Source Type: Point source
- Pictures: False
- Reference: False
- Compute HRIRs: False
- Unit: m
- c: 343.18
- rho: 1.1839
- Evaluation Grids Name: PlaneHorizontal
- Materials Path(s): None
- Min. frequency: 2000
- Max. frequency: 2001
- Frequencies: Step size
- Value: 1

Numerical calculation

Follow the steps in the first tutorial.

Post-processing

Follow the steps in the first tutorial.

Visualization

Start Paraview.
Load the VTK-files. They are located in /Output2HRTF/Reference_vtk within your project folder.
When you click on Apply the visualization should look like this:

[TBD: re-do with Left ear] HRTF tutorial

This tutorial covers the calculation of a head-related transfer function based on a head-shaped mesh and a point source placed directly next to one of the ears.

Pre-processing

Open Blender.
Either open the .blend file or import the .stl, .obj, or .ply files (File -> Open or File -> Import -> ply). For the tutorial we use this .blend file mesh (sourceforge.net) from Ziegelwanger et al (2015). Cite this paper when using this mesh.
Check if Rotation and Location are all set to 0 and Scale set to 1.
Check whether the ear canal is placed on the y-axis (or Frankfurt Plane).
Rename the object to "Reference".
Add three materials, switch to Edit mode, assign the Skin material to all elements and switch to Face Select as in the second tutorial.

Assign the materials Left ear and Right ear to elements within the ear canal. These will represent the microphones.
Switch back to Object Mode (3D View: Edit mode -> Object Mode or Tab).
Add a point source (Add -> Light -> Point).
Rename the Light object to 'Point source' (case-sensitive!)
Switch back to Edit mode and switch to Vertex Select.
Select a vertex within the left ear canal, close to the Y-axis.
Copy the coordinates in the Transform window and paste them one by one into the Transform window of the point source object Point.
[TBD: which is the correct translatio?n(+screenshots)] Translate the point source outward by 0.5 on the Y-Axis.
Now you have placed the point source directly in front of the left ear canal.

Project export

Follow the steps in the first tutorial, but using the following export settings:
- Title: Uniform HRTF Calculation
- BEM Method: ML-FMM BEM
- Source Type: Point Source
- Pictures: False
- Reference: True
- Compute HRIRs: True
- c: 343.18
- rho: 1.1839
- Unit: mm
- Evaluation Grids: ARI
- Materials Path(s): None
- Min. frequency: 100
- Max. frequency: 16000
- Frequencies: Step size
- Value: 100

Numerical Calculation

Follow the steps in the first tutorial.

[TBD: replace with Python plots] Post-processing

Follow the steps in the first tutorial.
You can now use the inspect_sofa_files function in the mesh2hrtf package to plot HRTFs for different angles
[TBD:] Reference to Python doc string
An example script to run would be:

import mesh2hrtf

folder = '/path/to/your/project/folder'

mesh2hrtf.inspect_sofa_files(folder, pattern=None, atol=0.1, plot=None, savedir=None)

this generates the following .pdf plot in the /Output2HRTF subfolder of your project:

Alternative: Post-processing in MATLAB

Navigate to the /Output2HRTF folder in your project folder in Matlab.
Now you can use the SOFA Matlab API toolbox ( '[Output2HRTF]') to plot your HRTF using these instructions:

[TBD] Please try if your_variable = SOFAload('HRIR_ARI.sofa'); works as well. Using the HRTFs results in time reversed HRIRs.

a) your_variable = SOFAload('HRTF_ARI.sofa');
b) SOFAplotHRTF(your_variable, 'mode');
'mode' being chosen from the following to display the HRTF:

    - 'EtcHorizontal'  energy-time curve in the horizontal plane (+/- 5 deg)
    - 'EtcMedian'      energy-time curve in the median plane (+/- 2 deg)
    - 'MagHorizontal'  magnitude spectra in the horizontal plane (+/- 5 deg)
    - 'MagMedian'      magnitude spectra in the median plane (+/- 2 deg)
    - 'magspectrum'    single magnitude spectrum for direction DIR in COLOR

The following image shows the energy time curve in the horzontal pane (mode = EtcHorizontal):

WARNING: Using 'HRTF_ARI.sofa' with SOFAplotHRTF and SOFAconvertConventions results in time reversed HRIRs. We recommend to use the Compute HRIRs option during the project export in Blender and directly pass 'HRIR_ARI.sofa' to these functions.

Scriptability of Blender and Export

Additionally to the GUI-based use of Blender for preparing the Mesh2HRTF simulations, there is the option of scripting both the export and the generation of the geometries with Blender's built-in Python IDE.

Set-up

Open Blender. (Using the first tutorial as an example project here.)
Open a new text editor window:
- Move the cursor to the bottom right corner of the main 3D Viewport window.
- It becomes a Plus shape.
- Click and pull to the left, opening a second 3D Viewport window.
- In the settings at the top, change this to Text Editor.
Now your screen should look something like this:
Press New at the top of the text editor to open an empty text console.
Optionally, enable Python Tooltips (Edit -> Preferences -> Interface -> Display).
This way a Python command will be displayed for each scriptable element when hovering the cursor over it. For example like this:

Export

As an example, do the first tutorial up to project export.
Now, instead of using the export window, you can copy and adjust the following script into the text editor.

import bpy

# save Mesh2HRTF project ----------------------------------
bpy.ops.export_mesh2hrtf.inp(
    filepath="/path/to/project_folder",  # change this path to your export folder
    programPath="/path/to/mesh2hrtf-git/mesh2hrtf",  # change this to the location of Mesh2HRTF
    materialSearchPaths='None',
    title="Scattering from a rigid sphere by a point source",
    method="ML-FMM BEM",
    sourceType = "Point source",
    pictures=False,
    reference=False,
    computeHRIRs=False,
    unit="m",
    speedOfSound="343.18",
    densityOfMedium="1.1839",
    evaluationGrids="PlaneHorizontal",
    minFrequency=1000,
    maxFrequency=16000,
    frequencyVectorType="Step size",
    frequencyVectorValue=1000)

Press the "Play" button at the top of the text editor to execute the script. This alternative method triggers the exact same export routine described in the first tutorial .

Please note! The variables speedOfSound and densityOfMedium are string representations of the numbers. This was done in order to avoid rounding errors due to limited precision in Blender. The strings are written into the NC.inp text file where they are then correctly used for the numerical calculation.

Other

Apart from the Export Mesh2HRTF routine, you can script almost any other operation in Blender and in this way hard code your pre-processing steps. For instance you could loop over several iterations with small changes in your setup or export parameters easily. For more information on scripting Blender, refer to the Blender documentation.

Mesh2HRTF Wiki

Tutorials

Tutorials

Scattering from a rigid sphere

Pre-processing

Project export

Numerical calculation

Post-processing

Visualization

Radiation from an active vibrating element in a rigid sphere

Pre-processing

Project export

Numerical Calculation

Post-processiung

Visualization

Simulations with non-rigid boundary conditions

Pre-processing

Project export

Numerical calculation

Post-processing

Visualization

[TBD: re-do with Left ear] HRTF tutorial

Pre-processing

Project export

Numerical Calculation

[TBD: replace with Python plots] Post-processing

Scriptability of Blender and Export

Set-up

Export

Other