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.
This tutorial covers the scattering from a rigid sphere due to a point source that radiates sound.
Add -> Mesh -> Ico Sphere
).Subdivisions: 6
Radius: 0.1 m
Location: X 0, Y 0, Z 0
Rotation: X 0°, Y 0°, Z 0°
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
).
Location: X 0 m, Y 0.2 m, Z 0 m
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!
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.
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.
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.
>NumCalc.txt
to the command creates an additional log file.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.
python Output2HRTF.py
in a terminal. This executes output_to_hrtf from the mesh2hrtf Python package.The following files are created in YourProjectFolder/Output2HRTF:
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:
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.
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:
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!)
Apply
the visualization should look like this: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.
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:
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
Apply
the visualization should look like this:This tutorial introduces the use of materials to define admittance boundary conditions.
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
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.
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
Apply
the visualization should look like this: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.
File -> Open
or File -> Import -> ply
). For the tutorial we use this .blend file mesh.0
and Scale set to 1
.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
).
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
inspect_sofa_files
function in the Mesh2HRTF Python API to plot HRTFs for different angles.import mesh2hrtf
folder = '/path/to/your/project/folder'
mesh2hrtf.inspect_sofa_files(folder, pattern=None, atol=0.1, plot=None, savedir=None)
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.
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.
New
at the top of the text editor to open an empty text console.Edit -> Preferences -> Interface -> Display
).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.
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