Generating a Measurement-based Transfer Function
for RASP-ZX Using HARKTOOL5

Table of Contents

1. Overview

2. Creating Microphone Array Positions XML File

3. Creating Sound Source Positions XML File

4. Generating Transfer Function

1.  Overview

This manual will focus on using the measurement-based transfer function generation.  Generating transfer functions from actual measurements using TSP (Time Stretched Pulse) can be divided to two parts: (1) playing the TSP signal and recording the TSP response, and (2) calculating the impulse responses from TSP responses. This manual will use the RASP-ZX device, which produces a synchronized recording.  This manual will assume that the TSP Responses have already been recorded using the Recording TSP response steps found in the RASP-ZX manual. After recording, the impulse response for each TSP signal can be calculated by adding each TSP and calculating the converse of the inverse TSP signal with the added TSP. This manual will detail the steps on generating a transfer function using HARKTOOL5 after recording TSP Responses.

2.  Creating Microphone Array Positions XML File

1. Run HARKTOOL5-GUI.  See https://www.hark.jp/document/2.4.0/packages/harktool5-gui-en/harktool5-gui.html#id1 on how to run the HARKTOOL5- GUI service.
   


2. Open a web browser (Google Chrome is recommended) and enter http://localhost:3001.
   HARKTOOL5-GUI will open as shown in Figure 1.
   
   Figure 1. Opened HARKTOOL5-GUI
   


3. Under the Microphone array positions panel, click the Create button as shown in Figure 2.
   
   Figure 2. Create button for microphone array positions
   


4. In the Create Microphone Array Positions page, choose the Circle template (Figure 3). Note that for the measurement-based transfer function generation, the positions of each microphone in a microphone array do not need to be correctly specified whereas the number of microphones in a microphone array needs to be correct. Please refer to the separate comprehensive manual for generating a transfer function, How to Generate a Transfer Function using HARKTOOL5 for the further information.
   
   Figure 3.  Circle template button for microphone array positions
   


5. Leave the value in Output File parameter to its default value microphones.xml (Figure 4). This parameter can be edited to use the desired output filename for the microphone array positions xml.
   
   Figure 4. Output File parameter for microphone array positions
   


6. Edit the parameter values under the Azimuth section (Figure 5) to:
   
   
   • from = 0
   • to = 359
   • interval = 45
   
   The parameter values should be adjusted to match the number of microphones of the recording device that was used.  In the Recording TSP Response using RASP-ZX manual, the RASP-ZX has 8 microphones. The parameter value above configures the template to position a microphone at every 45 degrees from 0 to 359 degrees and this results to having 8 microphones.
   
   Figure 5. Azimuth section for microphone array positions
   


7. Leave all other parameters to their default values.  Figure 6 shows the values of the parameters after setting for the steps from 5 to 7.
   
   Figure 6. Values for the Microphone Array Positions parameters
   


8. Click the Create! Button (Figure 7) near the bottom of the page.
   
   Figure 7. Create! button for microphone array positions
   


9. After a successful generation, check the 3D Visualization on the right side of the page.  Figure 8 shows the expected output for the 3D visualization using the parameters values shown in Figure 6. If the visualization shows the correct number of microphones (represented by red dots), click the link bordered in green found at the bottom part to go back to the top page.
   
   Figure 8. 3D Visualization output of the Microphone Array Positions and link to return the top page
   


10. In the top page, the filename of the successfully generated microphone array positions xml should be displayed in the File Name text box under the microphone array positions panel (Figure 9).
    
    Figure 9. Filename of successfully generated microphone array positions in the top page
    


11. The generated microphone array positions xml can be downloaded.  To do this, click on the Download button (Figure 10) in the microphone array positions panel.  The downloaded microphone array positions xml can be used to upload the same configuration instead of creating the same microphone array positions xml again.
    
    Figure 10. Download and Upload button for microphone array positions
    


12. To see the visualization or to modify the values of the generated microphone array positions xml, click the Visualize button (Figure 11).  Figure 12 shows the page that will be displayed after the Visualize button is pressed.
    
    Figure 11. Visualize button for microphone array positions
    
    
    Figure 12 Visualization page for microphone array positions
    



3. Creating Sound Source Positions XML File

1. Open the HARKTOOL5-GUI. Please refer to steps 1 and 2 of 2. Creating Microphone Array Positions XML File.
   


2. Under the sound source positions panel, click the Create button (Figure 13).
   
   Figure 13. Create button for sound source positions
   


3. Select the Circle template (Figure 14) for the sound source positions.  The template should match the layout used in the recording set-up.  In the Recording TSP Response using RASP-ZX manual, the layout is circular, so the Circle template will be used.
   
   Figure 14. Circle template button for sound source positions
   


4. Set Position type to tsp (Figure 15).  The appropriate type for the wav file used should be selected.  In the Recording TSP Response using RASP-ZX manual, the TSP signal was used, so the tsp setting is chosen.
   
   Figure 15. Position Type parameter
   


5. Edit the Wav File Path parameter to point to the correct location of the wav files and the expected filename of the wav files.  It is expected that there will be multiple wav files so the Wav File Path parameter can use a special pattern of {tag:format} in the filename parameter to automatically change the filename for each wav file based on the corresponding position. Table 1 shows a list of the tags and its respective units of measurement.
   
   Table 1. Name Templates and Units

   Tag	Unit
   RADIUS	m
   ELEVATION	deg
   AZIMUTH	deg
   X_AXIS	mm
   Y_AXIS	mm
   Z_AXIS	mm
   HEIGHT	mm

   
   The format after the tag follows the printf format for Decimal floating point, lowercase (%f).  See http://www.cplusplus.com/reference/cstdio/printf/ for more information on the printf format for Decimal floating point, lowercase (%f). In the Recording TSP Response using RASP-ZX manual, the recording layout is circular with a radius of 1 meter, the azimuth interval is for every 30 degrees from 0 - 330 degrees, and the speaker and microphone are on the same elevation. The files are named based on their Azimuth angle as shown in Table 2.
   
   Table 2. Azimuth Filename Examples

   Location of the speaker where TSP was played	Example Filename
   0°	sep_000.wav
   30°	sep_030.wav
   60°	sep_060.wav
   ...	...
   330°	sep_330.wav

   
   Assuming the files are in the /home/user/raspzx_rec,
     the Wav File Path will be: /home/user/raspzx_rec/sep_{AZIMUTH:%03.0f}.wav (Figure 16)
   
   
   Figure 16. Wav File Path parameter
   


6. Leave the value in Output File parameter to its default value source.xml (Figure 17).  The parameter value can be edited to use the desired output filename for the sound source positions xml.
   
   Figure 17. Output File parameter for sound source positions
   


7. Edit the values of the parameters in the Radius, Azimuth and Elevation sections to:
   
   
   • Radius Section: from = 1, to = 1 and Interval = 0
   • Azimuth Section: from = 0, to = 359 and Interval = 30
   • Elevation Section: value = 0
   
   The position parameters should match the layout of the sound source location done for the TSP recording.  The values above match the set-up in the separate manual, Recording TSP Response using RASP-ZX manual: the recording layout is circular with a radius of 1 meter, the azimuth interval is for every 30 degrees from 0 - 330 degrees, and the speaker and microphone are on the same elevation.
   
   Figure 18 shows the values for the parameters in the Radius, Azimuth and Elevation sections.
   
   Figure 18. Values for the parameters in the Radius, Azimuth and Elevation sections
   


8. Click the Create! Button (Figure 19) at the bottom of the sound source positions page.
   
   Figure 19. Create! button for sound source positions
   


9. After a successful generation, check the 3D Visualization on the right side of the page. Figure 20 shows the expected output for the 3D visualization using the parameters values set in steps 3 - 7. If the visualization shows the correct positions and number of sound sources (represented by red dots), click the link bordered in green found near the bottom part of the page to go back to the top page.
   
   
   Figure 20. 3D Visualization output of the sound source positions and link to return the top page
   


10. In the top page, the filename of the successfully generated sound source positions xml should be displayed in the File Name text box under the sound source positions panel (Figure 21).
    
    Figure 21. Filename of successfully generated sound source positions xml in the top page
    


11. Under the sound source positions panel, click the Visualize button (Figure 22).
    
    Figure 22. Visualize button for sound source positions
    


12. In the new page, check the positions and Wav File Path if everything is as expected. One common cause for error during transfer function generation is that the file paths are not correct. Figure 23 highlights where the file paths can be checked and edited. The visualization in the right part of Figure 24 can also be used to check the positions.
    
    Figure 23. Wav File Path values and 3D Visualization in sound source positions visualize page
    


13. Edit the values as needed. If the values are edited, click the Create! button to apply the changes made.
    


14. If the positions and filenames are not correct, go back to the top page.
    


15. The generated sound source positions xml can be downloaded. To do this, click the Download button (Figure 24) in the sound source positions panel. The downloaded sound source positions xml can be used to upload the same configuration instead of creating the same sound source positions xml again.
    
    Figure 24. Download and Upload button for sound source positions
    



4. Generating Transfer Function

1. Open the HARKTOOL5-GUI. Please refer to steps 1 and 2 of 2. Creating Microphone Array Positions XML File.


2. Prepare the microphone array positions xml file and the sound source positions xml file. If the two files are ready for transfer function generation, the panels for microphone array positions and sound source positions should show a check mark as shown in Figure 25. If the files are not ready, use the steps in 2. Creating Microphone Array Positions XML File or 3. Creating Sound Source Positions XML File to prepare the files. The files can also be uploaded if the files were previously downloaded as shown in Figure 11 and Figure 25.
   
   Figure 25. Microphone array positions xml file and sound source positions xml file ready for transfer function generation, as indicated by the check marks
   


3. With the microphone array positions xml file and the sound source positions xml file ready, click the Create button (Figure 26) under the transfer function panel.
   
   Figure 26. Create button for transfer function
   


4. Leave the values for the Config (General Parameters) to their default values. The default values are shown in Figure 27. A short description of each parameter is available in https://www.hark.jp/document/2.4.0/packages/harktool5-gui-en/harktool5-gui.html#create-tf-label>.
   
   Figure 27. Default values for Config (General Parameters)
   


5. Leave the value for the Output File Name (zip) parameter to the default value tf.zip (Figure 28). The parameter value can be edited to use the desired output filename for the transfer function zip file.
   
   Figure 28. Output File Name (zip) parameter
   


6. Select the Use TSP Record Files for the TF Calculation Type (Figure 29). The value for TF Calculation Type will depend on the algorithm and wav files to be used. For measurement-based transfer functions, it will be either Use TSP Record Files for synchronized recording or Use Mouth TSP Record Files for unsynchronized recording. The TSP Responses have been recorded using the steps in the Recording TSP Response using RASP-ZX manual, which produces a synchronized recording, so Use TSP Record Files is chosen. A short description of each option is available in https://www.hark.jp/document/2.4.0/packages/harktool5-gui-en/harktool5-gui.html#create-tf-label.
   
   Figure 29. Use TSP Record Files selected in TF Calculation Type
   


7. Leave the other values for the parameters in the Transfer Function Parameters section to their default values. The default values of the other parameters are shown in Figure 30.
   
   Figure 30. Default value for the other Transfer Function Parameters
   


8. Click the Create! Button (Figure 31) found near the bottom left part of the page.
   
   Figure 31. Create! Button for transfer function
   


9. The status of the transfer function generation will be displayed in the bottom left part of the page. Figure 32 shows how a successful status for the transfer function generation will look like. Figure 34 shows how an error status caused by setting an incorrect Wav File Path in step 5 of 3. Creating Sound Source Positions XML File will look like in the transfer function generation.
   
   Figure 32. Successful status in transfer function generation
   
   
   Figure 33. Error status for incorrect TSP path in transfer function generation
   


10. Once successful with the creation, the Localization and Separation transfer function will be generated and packaged in a zip file. Click the link bordered in green (Figure 34) found near the bottom part of the page to go back to the top page.
    
    Figure 34. Link to return the top page for transfer function
    


11. In the top page, the successfully generated localization and separation transfer functions zip file should be displayed in the File Name text box under the Transfer Function panel (Figure 35).
    
    Figure 35. Filename of successfully generated transfer function zip file in the top page
    


12. The created transfer function file can be confirmed in 3D graph by clicking the Visualize button (Figure 36) under the transfer function panel.
    
    Figure 36. Visualize button for transfer function
    


13. The TF visualize feature can graph either the Localization transfer function or Separation transfer function. To confirm the Localization transfer function, set TF Type to Localization set Domain to Time domain and set Z Axis to Amplitude as shown in Figure 37.
    
    Figure 37. Parameter values for TF Type, Domain and Z Axis to confirm the Localization transfer function
    


14. Click the Graph Plot button (Figure 39). For the TSP responses recorded using the steps in the Recording TSP Response using RASP-ZX manual, the Time domain graph of the Localization transfer function with Amplitude as the Z-axis should look something like the graph in Figure 38.
    
    Figure 38. Graph Plot button and time domain graph for the generated localization transfer function with amplitude as the z-axis
    


15. To confirm the Separation transfer function, set TF type to Separation set Domain to Time domain and set Z Axis to Amplitude as shown in Figure 39.
    
    Figure 39. Parameter values for TF type, Domain and Z Axis to confirm the Separation transfer function
    


16. Click the Graph Plot button (Figure 40). For the TSP responses recorded using the steps in the Recording TSP Response using RASP-ZX manual, the Time domain graph of the Separation transfer function with Amplitude as the Z-axis should look something like the graph in Figure 40.
    
    Figure 40. Graph Plot button and time domain graph for the generated separation transfer function with amplitude as the z-axis
    


17. To download the generated transfer function, click Download on the transfer function panel shown in Figure 41. The downloaded transfer function can be used in HARK Designer for sound source localization or sound source separation.
    
    Figure 41. Download button for transfer function
    






---- End-----