Skip to main content

An image source-based method used to simulate room transfer functions for arbitrary room shapes.

Project description

Diffraction Enhanced Image Source Method - Arbitrary Room Geometry (DEISM-ARG)

The code in this folder is able to solve the following problem:

A source and a receiver transducer with arbitrary directivity are mounted on one/two speakers; The local scattering and diffraction effects around the transducers result in complex directivity patterns. The directivity patterns can be obtained by analytical expressions, numerical simulations or measurements.

In DEISM-ARG, we can model the room transfer function between transducers mounted on one/two speakers using the image source method while incorporating the local diffraction effects around the transducers. The local diffraction effects are captured using spherical-harmonic directivity coefficients obtained on a sphere around the transducers. In addition to DEISM in shoebox rooms, DEISM-ARG can model more complex room shapes. However, for version 2.0, we now only supports convex shapes. In short, DEISM-ARG has the following features:

  1. Arbitrary directivities of the source and receiver
  2. Angle-dependent reflection coefficients
  3. Convex room shapes

image-20240812131054348

Preparation and installing

Build locally

  • In you encounter errors like "unrecognized arguments: deism_envs_exact.yml", please type the following commands manuelly in the command line.
  • Clone or download the repository to your local directory
  • Use the command conda env create -f deism_env.yml to create a Conda environment for the DEISM algorithms. If this does not work, try conda env create -f deism_env_exact.yml as the file deism_envs_exact.yml records the versions of all packages.
  • Activate the created environment by "conda activate DEISM"
  • Running pip install -e . will build the deism package including the c++ extensions locally. You can also modify the sources codes and check out the effects. In case you receiver errors like "ModuleNotFoundError: No module named 'pybind11" even after activated the conda environment, you can use python -m pip install -e . to try install again.
  • Run scripts in the test folder.

Using pip to install remotely

  • Run pip install deism to install deism.

Running codes

Single set of parameters

The default parameters are defined in file configSingleParam.yml or configSingleParam_ARG.yml, depending on whether you want to run for shoebox rooms or more complicated room shapes. Take DEISM-ARG (configSingleParam_ARG.yml) as an example, there are two ways of running the codes:

  1. You can directly run deism_arg_singleparam_example.py in an IDE, which utilizes the parameters defined in configSingleParam_arg.yml.
  2. You can run deism_arg_singleparam_example.py from the command line after activating the conda environment. In addition, you can access help information quickly by python deism_arg_singleparam_example.py --help. You can then change the parameters based on the instructions from the help message, e.g., python deism_arg_singleparam_example.py -c 350 -zs 20 will change the parameter sound speed and the wall impedance. The new input value of the parameters then overrides the ones in file configSingleParam_arg.yml. After choosing the needed values, you can run the codes using, e.g., python deism_arg_singleparam_example.py -c 350 -zs 20 --run.
  3. You need to specify additionally the following parameters in the function init_parameters of deism_arg_singleparam_example.py:
    1. The vertices of the room
    2. If rotate the room w.r.t the origin. This can be useful if you want to have some comparisons with the rooms created using pyroomacoustics.
    3. The rotation angles of the room if it needs to be rotated.
  4. You can suppress all output information in the command line by adding flag "--quiet" or by setting the first parameters in the configuration.yml file SilentMode to 1.

Examples

DEISM-ARG

  • An example of running DEISM-ARG is examples/deism_arg_single_example.py
    • You can run this from IDEs or via the command line, as introduced in the previous section
  • An example of comparing different versions of DEISM-ARG is given in examples/deism_args_compare.py. The room transfer functions are compared among:
    • Original version (most computation-costly)
    • LC version (fastest)
    • Mix version (Trade-offs between Original and LC versions): Early reflections up to some changeable order (default is 2) are calculated using the original version and the higher orders are calculated using the LC version.
  • An example of comparing DEISM-ARG and pyroomacoustics is examples/deism_arg_pra_compare.py, Comparisons are done regarding if the following results are identical or mismatched only by a small deviation:
    • number of images
    • the positions of the images

DEISM for shoebox

We provide two examples for running the original DEISM for shoebox rooms

  • An example of running DEISM-shoebox is examples/deism_singleparam_example.py
    • You can either run this from IDEs or via the cmd
  • An example of comparing different DEISM versions are shown in examples/deisms_lc_mix_test.py. In this script, the following methods are compared
    • DEISM - original
    • DEISM - MIX (original + LC vectorized)
    • DEISM - LC vectorized
    • FEM as groundtruth (only for this specific parameter settings)

Tips

The example code only provides essential functionalities based on DEISM. For more complex scenarios, please contact the authors (zeyu.xu@audiolabs-erlangen.de) for support. In the following, a few important tips might be helpful for you:

  • If you want to simulate the scenario where both the source and receiver are positioned on the same speaker, you need to run DEISM for all reflection path except for the direct path.
  • It is recommended to set the distance at least 1m between the transducers and the walls.

Directivities

Modeling the directivities of the source and receiver in the room acoustics simulation is receiving increasing attention. The directivities of the source or receiver can include both the transducer directional properties and the local diffraction and scatterring effects caused by the enclosure where the transducers are mounted. Modern smart speakers are typical embodiments of such scenarios. Human heads are also a very common case.

Simple directivities

  • Monopole

Arbitrary directivities

Some key information should be provided if you want to include your own directivity data:

  1. Frequencies at which the directivities are simulated or measured. A 1D array.
  2. The spherical sampling directions around the transducer: azimuth from $0$ ( $+x$ direction) to $2 \pi$, inclination angle from $0$ ($+z$ direction) to $\pi$. A 2D array with size (number of directions, 2).
  3. The sampled pressure field at the specified directions and frequencies. A 2D array with size (number of frequencies, number of directions).
  4. The radius of the sampling sphere. A 1D array or float number.

For more information about directivity definition used in DEISM and DEISM-ARG, please refer to the following publication:

Zeyu Xu, Adrian Herzog, Alexander Lodermeyer, Emanuël A. P. Habets, Albert G. Prinn; Acoustic reciprocity in the spherical harmonic domain: A formulation for directional sources and receivers. JASA Express Lett. 1 December 2022; 2 (12): 124801. https://doi.org/10.1121/10.0016542

Contributors

  • M. Sc. Zeyu Xu
  • Songjiang Tan
  • M. Sc. Hasan Nazım Biçer
  • Dr. Albert Prinn
  • Prof. Dr. ir. Emanuël Habets

Academic publications

If you use this package in your research, please cite our paper:

Zeyu Xu, Adrian Herzog, Alexander Lodermeyer, Emanuël A. P. Habets, Albert G. Prinn; Simulating room transfer functions between transducers mounted on audio devices using a modified image source method. J. Acoust. Soc. Am. 1 January 2024; 155 (1): 343–357. https://doi.org/10.1121/10.0023935

Z. Xu, E.A.P. Habets and A.G. Prinn; Simulating sound fields in rooms with arbitrary geometries using the diffraction-enhanced image source method, Proc. of International Workshop on Acoustic Signal Enhancement (IWAENC), 2024.

Description of the codes and functions

configSingleParam_ARG.yml

In this file you define the default parameters for DEISM-ARG to run. Note that this file is different from the configSingleParam.yml on these parameters:

  • The dimensions are defined separately in the example script.
  • You also need to specify if you want to rotate the room, and the rotation angles as well.

configSingleParam.yml

In this file you define the default parameters for DEISM-shoebox to run.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

deism-2.0.1.tar.gz (2.4 MB view details)

Uploaded Source

Built Distributions

deism-2.0.1-cp311-cp311-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.11 Windows x86-64

deism-2.0.1-cp311-cp311-macosx_11_0_universal2.whl (3.6 MB view details)

Uploaded CPython 3.11 macOS 11.0+ universal2 (ARM64, x86-64)

deism-2.0.1-cp311-cp311-macosx_10_9_universal2.whl (4.0 MB view details)

Uploaded CPython 3.11 macOS 10.9+ universal2 (ARM64, x86-64)

deism-2.0.1-cp310-cp310-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.10 Windows x86-64

deism-2.0.1-cp310-cp310-macosx_12_0_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.10 macOS 12.0+ x86-64

deism-2.0.1-cp310-cp310-macosx_11_0_universal2.whl (3.6 MB view details)

Uploaded CPython 3.10 macOS 11.0+ universal2 (ARM64, x86-64)

deism-2.0.1-cp39-cp39-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.9 Windows x86-64

deism-2.0.1-cp39-cp39-macosx_12_0_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.9 macOS 12.0+ x86-64

File details

Details for the file deism-2.0.1.tar.gz.

File metadata

  • Download URL: deism-2.0.1.tar.gz
  • Upload date:
  • Size: 2.4 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for deism-2.0.1.tar.gz
Algorithm Hash digest
SHA256 65597c158bf76e1579bce650aef354cce0a2e99586ddcd46cafc55ae01a97171
MD5 1a961192a966cdeab42242dd5e0a9a49
BLAKE2b-256 0615584c96183c7a3c5889f0f9ee4b313a1ccb2993c142603d58e9c681e249c9

See more details on using hashes here.

Provenance

The following attestation bundles were made for deism-2.0.1.tar.gz:

Publisher: python-publish.yml on audiolabs/DEISM

Attestations:

File details

Details for the file deism-2.0.1-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: deism-2.0.1-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 3.5 MB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.11.9

File hashes

Hashes for deism-2.0.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 30aff41f0ce961bae9aa1a547148620442200911da823eb5d723deed751c2395
MD5 a04e8bc53cdcc1e32446a74639a67420
BLAKE2b-256 1a302f5f47a9deee6081d1f10c33a7ca34841228214a183e7cf5f928701b2cf7

See more details on using hashes here.

File details

Details for the file deism-2.0.1-cp311-cp311-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for deism-2.0.1-cp311-cp311-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 b2a0a45b19231e8dec4698471eb66822b15c6db828e548e69689515498501554
MD5 6d31a4487618912f4963fac9e39ec1ec
BLAKE2b-256 1b34ed9284ccbf0d0c33e0ed81e68d8f6260f1ae997307a70a088889207f26de

See more details on using hashes here.

File details

Details for the file deism-2.0.1-cp311-cp311-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for deism-2.0.1-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 ea9b78132540a0212ebb815d9abd7fde8daf5ea91537a113c4727f2a4beadc83
MD5 0e5b862c5f9bc67098913c285a2607bf
BLAKE2b-256 c221858f164b0f52add337a211fed60ed7f3bdc8afc582ff8b03ad66a2383b8c

See more details on using hashes here.

File details

Details for the file deism-2.0.1-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: deism-2.0.1-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 3.5 MB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.10.11

File hashes

Hashes for deism-2.0.1-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 0f25c78475d3eab19367a4772dc61100ad31e793a263452c1fa311e7af4ce176
MD5 a387c1f619cfe0c3ec61ef0b8cde10cd
BLAKE2b-256 8b4b2fa3f432385b8f2b41ec277cb0d74922879baa32536fb5b6aad142d9da81

See more details on using hashes here.

File details

Details for the file deism-2.0.1-cp310-cp310-macosx_12_0_x86_64.whl.

File metadata

File hashes

Hashes for deism-2.0.1-cp310-cp310-macosx_12_0_x86_64.whl
Algorithm Hash digest
SHA256 3c7504c19328a5d2b337c7972513d908d8b890cf004a06b4c70f1248390b9bd3
MD5 b55acd04b9a8f3b67e6707b0b6f79968
BLAKE2b-256 8c0755c91de318ef86b1f16d5774cdcccb35996f8892e2664df05f50abd5206d

See more details on using hashes here.

File details

Details for the file deism-2.0.1-cp310-cp310-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for deism-2.0.1-cp310-cp310-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 c5bc68d2367d8aca6024c7161d7d510adabf87c75ecc5f57963392d33bcf9510
MD5 6a1e986cbf16e898f6d3837a9000ea55
BLAKE2b-256 e09bbc8a8b06f5a5b7663f035d1e13c53d02a07115955b62b5332c584568385d

See more details on using hashes here.

File details

Details for the file deism-2.0.1-cp39-cp39-win_amd64.whl.

File metadata

  • Download URL: deism-2.0.1-cp39-cp39-win_amd64.whl
  • Upload date:
  • Size: 3.5 MB
  • Tags: CPython 3.9, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.13

File hashes

Hashes for deism-2.0.1-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 e9558b649b48fdfab3d5228c0b8b25c8745b66ea2cd012430effa5e1787ec98e
MD5 2327770998885fd59b5b136fa6898256
BLAKE2b-256 8128f664a1a3fe6d79f61deba7342bd38e640f078de283f69615d6192df28baf

See more details on using hashes here.

File details

Details for the file deism-2.0.1-cp39-cp39-macosx_12_0_x86_64.whl.

File metadata

File hashes

Hashes for deism-2.0.1-cp39-cp39-macosx_12_0_x86_64.whl
Algorithm Hash digest
SHA256 f4e2d3b61486f395a86c8cba42db69e94e8208979ae84c2d6308ceed5fcf7a1d
MD5 d18fd64abb78d20e8987ef370434342b
BLAKE2b-256 3e98e3075452913b1aa1877097456d201959acbe0a80a836567e2d9e442ed9a0

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page