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 to make sure the edge lengths are sufficiently small:
- 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 light that will give the position of the point source used in the numerical calculations (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.
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 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.
More information on how to inspect and generate Evaluation grids can be found here.
For errors connected to the Object mesh created in the Blender scene, check Preparing the mesh.
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. This will calculate the sound field for all frequencies using a single thread and might take a while.

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: NumCalc can be parallelized to speed up the calculations and there scripts for automatically running one or multiple Mesh2HRTF projects. See NumCalc for more information

Note: NumCalc saves the raw data in text files. For a detailed description of the created files, see Mesh2HRTF Project Folder

Note: For easier automated handling of the NumCalc routine (also for multiple projects at a time), copy the Python script NumCalcManager.py located in the repository next to or into your project folder and execute it there. For further detaisl on how to use the script, refer to this tutorial.

Post-processing

If you are doing the post-processing for the first time, follow the installation steps for Output2HRTF here.
When all calculations are done go to your Mesh2HRTF project folder and run python Output2HRTF.py in a terminal. This executes output_to_hrtf from the mesh2hrtf Python package.
The following files are created in YourProjectFolder/Output2HRTF:
- HRTF_evalgrid name .sofa - the sound pressure at the evaluation grid nodes in the SOFA file format. For example use sofar to read data inside SOFA files and see sofaconventions for more information on the SOFA file format.
- HRIR_evalgrid name .sofa - the impulse responses in at the evaluation grid nodes in the SOFA file format
- ObjectMesh_Reference.npz - the pressure on the 3D mesh as numpy arrays.
- 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. If known issues occurred, there will be a file report_issues.txt .
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 want to process or delete data from multiple Mesh2HRTF projects, you can use the functions outputs_to_hrtfs and remove_outputs from the Python API.
If you are currently doing the 'Non-rigid boundary conditions' tutorial, go back.
If you are working on the 'HRTF' tutorial, go back.

Alternative: Octave/Matlab Post-processing
- When all calculation processes are done, start Octave or Matlab.
- If you are doing the post-processing for first time, follow the installation steps for Output2HRTF here.
- 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 volume velocity sound source (think of it as an vibrating element in the mesh) 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: Default
- Materials Path(s): None
- Min. frequency: 1000
- Max. frequency: 16000
- Frequencies: Step size
- Value: 1000

Numerical Calculation and Post-Processing

Follow the steps in the first tutorial and 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.

This workflow can be used to assign arbitrary materials to a mesh and material data can be written with the function write_boundary_condition from the Python API.

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 and Post-Processing

Follow the steps in the first tutorial and 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:

HRTF tutorial

This tutorial covers the calculation of a head-related transfer function based on a head-shaped mesh and a volume velocity sources at the blocked ear channel entrances.

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

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: Both ears
- Pictures: False
- Reference: True
- Compute HRIRs: True
- c: 343.18
- rho: 1.1839
- Unit: mm
- Evaluation Grids: Default
- Materials Path(s): None
- Min. frequency: 100
- Max. frequency: 16000
- Frequencies: Step size
- Value: 100

Numerical Calculation and Post-Processing

Follow the steps in the first tutorial and the first tutorial.
You can now use the inspect_sofa_files function in the Mesh2HRTF Python API to plot HRTFs for different angles.
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.
- Run the Output2HRTF.m script. It calls these functions.
- Now you can use the SOFA Matlab API toolbox to plot your HRTF using these instructions:

a) `your_variable = SOFAload('HRTF_Default.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_Default.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

Now, instead of using the export window, you can copy and adjust the following script into the text editor.

import bpy  # this imports the Blender Python API that is available from within Blender

# save Mesh2HRTF project ----------------------------------
bpy.ops.export_mesh2hrtf.inp(
    title="Scattering from a rigid sphere by a point source",
    method="ML-FMM BEM",
    sourceType = "Point source",
    filepath="/path/to/project_folder",              # this is the folder where the Mesh2HRTF project is saved
    programPath="/path/to/mesh2hrtf-git/mesh2hrtf",  # change this to the location of Mesh2HRTF
    pictures=False,
    reference=False,
    computeHRIRs=False,
    unit="m",
    speedOfSound="343.18",                           # this is passed as a string
    densityOfMedium="1.1839",                        # this is passed as a string
    evaluationGrids="Default",
    materialSearchPaths='None',
    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.

Wiki: Basic_HRTF_NumCalc_Simulation
Wiki: Basic_HRTF_tutorial
Wiki: Evaluation grids
Wiki: Installation
Wiki: Mesh2HRTF Export Parameters
Wiki: Mesh2HRTF Project Folder
Wiki: NumCalc
Wiki: Preparing the mesh
Wiki: Tutorials

Mesh2HRTF Wiki

Unix 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 and Post-Processing

Visualization

Simulations with non-rigid boundary conditions

Pre-processing

Project export

Numerical Calculation and Post-Processing

Visualization

HRTF tutorial

Pre-processing

Project export

Numerical Calculation and Post-Processing

Scriptability of Blender and Export

Set-up

Export

Other

Related