Image-source method: Matlab code [old version!]


Summary and disclaimer

As explained in the Background section, the Matlab code provided below is a first attempt at implementing Allen & Berkley's image-source method (ISM) for small-room acoustics [1], using frequency-domain simulations (i.e., Peterson's low-pass impulse method [2]). The Matlab programs available below are still fully functional, and many researchers have been using similar implementations of the ISM technique for their acoustics and/or engineering experiments. The pieces of code on this page are thus still provided for compatibility purposes, for anyone who would like to use a direct implementation of Allen & Berkley's method.

Following our research on room acoustics modeling, however, we came up with an improved implementation of the image-source model for the simulation of room impulse responses [3]. This updated method has a few advantages, including the ability to simulate impulse responses that look more realistic, and the ability to provide a relatively good prediction of the response's energy decay over time (see [3] for details). The updated Matlab code for this improved technique can be found here, and should be used instead of the programs below due to the above mentioned advantages.

As usual, feel free to download and use the files below as you like, but remember that all material available on this page is subject to the GNU general public license and comes with NO WARRANTY whatsoever.

Please don't hesitate to contact me if you find any bug or if you have interesting suggestions to make. And of course, an acknowledgement will be deeply appreciated if you happen to publish results based on the code provided below!


Image-source code [old version!]

The following Matlab files provide an implementation of Allen & Berkley's image-source technique (see [1] for more technical information) and can be used in a straightforward manner to generate samples of audio data using the image-source simulation method. An example of how to generate the impulse responses and audio data can be found below the table, and more specific implementation and usage information can be found in the Matlab help section for each of these files. Also, some of these Matlab files might require additional general-purpose functions which can be found further below.

Download all the files below in a .zip file: IM.zip
IMSetup.m Edit this file to define the various environmental parameters of the image method simulation. These parameters include the sampling frequency, sound velocity, room dimensions, wall reflection coefficients, positions of the array microphones, and trajectory of the sound source across the environment. These parameters are used as a simulation basis in the following files.
MakeIMResp.m This function computes the transfer function between a source and a receiver in a given simulation setup, using Allen & Berkley's image source method. This implementation is carried out in the frequency domain and thus allows fractional delays for each image source. This Matlab function was specifically optimised for execution speed by only considering the image sources relevant to the final transfer function, so the computation time should be as minimal as possible. Click the figure on the right to see an example of transfer function obtained with this implementation. This example corresponds to a 3m x 4m x 2.5m room with a reverberation time of approximately 0.2 s, and was computed in about 43 s on a P4 2.4GHz computer.
IMRevTimeAnalysis.m 
This function carries out a statistical analysis of the reverberation characteristics of a simulation environment defined in a file such as IMSetup.m, see above. This analysis is done in two different ways: 1) on the basis of a sound field simulation in the considered environment, see figure on the right; 2) on the basis of a direct consideration of the computed transfer functions. Note that the results from the second method are generally considered to be more accurate (no practical simulation). The full results from this reverberation time analysis are appended to the considered setup file if desired.
MakeTrajIMTFs.m
 Computes a bank of transfer functions corresponding to a simulation setup defined in a file such as IMSetup.m (see above). One impulse response is computed for every possible combination of the sensors and source trajectory points.
MakeAuData.m
 Generates samples of audio data (one sample per sensor channel) using the bank of impulse responses pre-computed with MakeTrajIMTFs.m. This function takes the source signal as input argument, and allows to set the source direction, disable/enable file saving, and disable/enable additive noise (see help for details).

The files above make it quite easy to generate samples of audio data using the image method for any simulation setup. Start by creating/editing a setup file, e.g. myIMSetup.m, similar to IMSetup.m above. Then determine an estimate of the reverberation time for the current setup in Matlab:

>> IMRevTimeAnalysis('myIMSetup');

Once this is done, simply execute the following two commands:

>> MakeTrajIMTFs('myIMSetup','myIMSetup_TFs');
>> AuData = MakeAuData('myIMSetup_TFs','myIMSetup_audio',SourceSignalVec);

The first command saves the TF bank into the file myIMSetup_TFs.mat, and the second one writes the resulting data into myIMSetup_audio.mat. The variable AuData is the resulting matrix of audio data, each column containing the data generated for the corresponding microphone with the setup described in myIMSetup.m. This .wav sample (600kB) of audio data was generated using the above commands for a source moving from left to right in front of a 2 microphone array in a room with a reverberation time of approximately 0.4 s (stereo signal, each channel contains the signal recorded by one microphone; try listening to it with headphones...).


Miscellaneous files

The table below contains a list of various custom functions that may be required by the Matlab files described above. See the files' help section for specific usage information. Also, please let me know if a function is missing from the list below.

Download all the files below in a .zip file: misc.zip
PrintLoopPCw.m   Prints the execution percentage on screen in a FOR or WHILE loop.
iseven.m 1 if input is even, 0 otherwise.
SetUserVars.m Checks and initialises some input variables from a set of user-definable parameters. To be used for functions that accept a series of ARGNAME—ARGVAL pairs to set user-definable parameters.
reusefig.m Creates or re-uses a figure with specific tag, regardless of the currently active window. When defined in a Matlab function, this command re-uses the same figure between consecutive runs and hence avoids plotting in an unwanted window or creating a new figure every time the function is executed.


References

[1] J. Allen and D. Berkley, Image method for efficiently simulating small-room acoustics, Journal of the Acoustical Society of America, vol. 65(4), pp. 943-950, April 1979.
[2] P. Peterson, Simulating the response of multiple microphones to a single acoustic source in a reverberant room, Journal of the Acoustical Society of America, vol. 80(5), pp. 1527–1529, November 1986.
[3] E. Lehmann and A. Johansson, Prediction of energy decay in room impulse responses simulated with an image-source model, Journal of the Acoustical Society of America, vol. 124(1), pp. 269-277, July 2008.