Skip to content

Unix_Tutorials

Jump to bottom
Fabian Brinkmann edited this page Aug 17, 2022 · 14 revisions

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. There are five basic tutorials

Scattering from a rigid sphere

Radiation from a vibrating element on a rigid sphere

Simulations with non-rigid boundary conditions

HRTF tutorial

Scripting Mesh2HRTF

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

Post-processing

  • If you are doing the post-processing for the first time, follow the installation steps for Output2HRTF
  • When all calculations are done go output2hrtf from the Mesh2HRTF API. e.g. using iPython
ipython
import mesh2hrtf as m2h
m2h.output2hrtf('path/to/YourProjectFolder')

  • The following files are created in YourProjectFolder/Output2HRTF:

    • HRTF_EvaluationGridName.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_EvaluationGridName.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_vtk from the Mesh2HRTF API in a next step.

  • The vtk-files are exported to the folder YourProjectFolder/Output2HRTF/vtk/

  • If you want to process or delete data from multiple Mesh2HRTF projects, you can use the functions process_multiple_outputs2hrtf and remove_outputs from the Mesh2HRTF API.

  • If you are currently doing the 'Non-rigid boundary conditions' tutorial, go back.

  • If you are working on the 'HRTF' tutorial, go back.

Visualization

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

Radiation from a vibrating element on 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](https://github.com/Any2HRTF/Mesh2HRTF/wiki/Unix_Tutorials#pre-processing-2).
+ Switch to *Face Select*.

+ If you are currently doing the 'HRTF' tutorial, [go back](https://github.com/Any2HRTF/Mesh2HRTF/wiki/Unix_Tutorials#pre-processing-3).
+  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

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!)
    • except the Light has the following coordinates:Location: X 0 m, Y 0.5 m, Z 0 m

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 Mesh2HRTF 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

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

  • 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 API (only available in Python)](Mesh2HRTF 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.
  • Now you can use the SOFA Matlab API to plot the HRTF using these instructions:
your_variable = SOFAload('HRTF_ARI.sofa');
SOFAplotHRTF(your_variable, 'mode');

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 (as above). We recommend to use the Compute HRIRs option during the project export in Blender and directly pass 'HRIR_ARI.sofa' to these functions.

Clone this wiki locally