Support for recorded source/mic directivities from DIRPAT database (#259

) (#302) * Support for measured source/mic directivities from DIRPAT database and other SOFA format files (#259) * This is a pretty big commit that includes loading recorded directivity files and using them in the simulation * Supports source/receiver for shoebox rooms * Interpolation in spherical harmonic domain * Adds option for using minimum phase filters See the CHANGELOG for more details. --------- Co-authored-by: prerak23 <[email protected]> * Adds download functions for the SOFA files from DIRPAT. Adds tests for the SOFA directivities. Adds samples some pre-generated samples for the tests. Removes some print statements from room.py. * open_sofa_interpolate.py: vectorizes fibonnaci computations, use spherical/cartesian conversion functions from doa sub-package. Adds a generalized pinv computation function. Adds a new plotting function. Moves doa sub-package fibonacci mapping to a dedicated function to make it available everywhere. * Adds two SOFA files for MIT Kemar HRTF. Adds an example script for binaural simulation * Modularize the RIR building routines for ISM and RT * adds soxr to requirements for doc building * Disallow directivities for 2D rooms. --------- Co-authored-by: prerak23 <[email protected]> Co-authored-by: prerak23 <[email protected]>
LCAV · Oct 29, 2024 · 38871cc · 38871cc
1 parent 890fc37
commit 38871cc
Show file tree

Hide file tree

Showing 107 changed files with 4,958 additions and 797 deletions.
diff --git a/.github/workflows/pythonpackage.yml b/.github/workflows/pythonpackage.yml
@@ -35,9 +35,17 @@ jobs:
       uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
+    - name: Upgrade pip
       run: |
         python -m pip install --upgrade pip
+    - name: Workaround for windows and python 3.8
+      if: matrix.os == 'windows-2019' && matrix.python-version == 3.8
+      run: |
+        pip install netCDF4<=1.5.8 
+        # There is no binary package of netCF4>=1.6.0 for windows and python 3.7
+        # the largest supported version is 1.5.8
+    - name: Install dependencies
+      run: |
         pip install -r requirements.txt
     - name: Build package
       run: |

diff --git a/.gitignore b/.gitignore
@@ -15,3 +15,4 @@ local_examples/
 pyroomacoustics.egg-info/
 pyroomacoustics/build_rir.c
 pyroomacoustics/**/*.so
+pyroomacoustics/directivities/tests/data/*.pdf
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -11,7 +11,55 @@ adheres to `Semantic Versioning <http://semver.org/spec/v2.0.0.html>`_.
 `Unreleased`_
 -------------
 
-Nothing yet
+This new version introduces some major changes. In particular, it introduces
+the use of measured microphone and source directivities. This new feature
+allows to simulate more accurately real recording equipments. See the
+`documentation
+<https://pyroomacoustics.readthedocs.io/en/latest/pyroomacoustics.directivities.html>`_
+for more details.
+
+Added
+~~~~~
+
+- New global parameters to control the octave bands used for simulation.
+
+  - ``octave_bands_base_freq``: the base frequency used for the octave bands (default ``125``),
+    note that together with the sampling frequency this will determine the number of sub-bands
+    used in simulation.
+  - ``octave_bands_n_fft``: lengths of the octave band filters (current is default ``512``
+    but will be changed to ``128`` in the next release)
+  - ``octave_bands_keep_dc``: extends the lowest band to include the DC offset,
+    the current default is ``False`` to match past behavior, but will be changed to
+    ``True`` in the next release because the filters have less oscillations this way.
+
+- New parameter ``min_phase`` of class ``Room``. If set to ``True``, the band-pass
+  filters are designed as minimum phase filters.
+
+- Simulation with measured directivity responses in SOFA format (limited file types) is
+  possible with the image source model.
+
+  - A flexible and extensible  SOFA file reader with optional spherical interpolation.
+  - A small database of files is bundled, including the `DIRPAT database
+    <https://aes2.org/publications/elibrary-page/?id=19538>`_, collected by
+    Manuel Brandner, Matthias Frank, and Daniel Rudrich University of Music and
+    Performing Arts Graz, Graz. The file also include two HRTF of the
+    `MIT KEMAR dummy head <https://sound.media.mit.edu/resources/KEMAR/README>`_.
+
+- Introduces a new class ``pyroomacoustics.directivities.Rotation3D`` to specify
+  the orientation of sources and receivers in 3D.
+
+- Adds `soxr <https://github.com/dofuuz/python-soxr>`_ as a dependency since resampling
+  can often be necessary when working with SOFA files.
+
+Changed
+~~~~~~~
+
+- In ray tracing, the histograms are now linearly interpolated between
+  the bins to obtain smoother RIR
+- Changed the API of ``CardioidFamily`` to take a float parameter.
+  New class wrappers for ``Cardioid``, ``Hypercardioid``, ``Supercardioid``,
+  ``Bidirectional`` and ``Omnidirectional`` are added in the ``directivity``
+  sub-module. The enum of type ``DirectivityPattern`` has been removed.
 
 `0.7.7`_ - 2024-09-09
 ---------------------

diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,5 +1,10 @@
 # Acoustic data for the simulation
 include pyroomacoustics/data/materials.json
+include pyroomacoustics/data/sofa_files.json
+include pyroomacoustics/data/sofa/AKG_c480_c414_CUBE.sofa
+include pyroomacoustics/data/sofa/EM32_Directivity.sofa
+include pyroomacoustics/data/sofa/mit_kemar_large_pinna.sofa
+include pyroomacoustics/data/sofa/mit_kemar_normal_pinna.sofa
 
 # The header files for the compiled extension
 include pyroomacoustics/libroom_src/*.h
@@ -19,9 +24,12 @@ graft pyroomacoustics/tests
 graft pyroomacoustics/adaptive/tests
 graft pyroomacoustics/bss/tests
 graft pyroomacoustics/datasets/tests
+graft pyroomacoustics/denoise/tests
+graft pyroomacoustics/directivities/tests
 graft pyroomacoustics/doa/tests
 graft pyroomacoustics/experimental/tests
 graft pyroomacoustics/libroom_src/tests
+graft pyroomacoustics/phase/tests
 graft pyroomacoustics/transform/tests
 
 global-exclude *.py[co]

diff --git a/docs/conf.py b/docs/conf.py
@@ -52,6 +52,7 @@
     "mpl_toolkits.mplot3d",
     "joblib",
     "scipy.io",
+    "soxr",
 ]
 
 try:

diff --git a/docs/index.rst b/docs/index.rst
@@ -14,6 +14,7 @@ Table of contents
   contributing
   changelog
   pyroomacoustics.room
+  pyroomacoustics.directivities
   pyroomacoustics.materials.database
   pyroomacoustics.transform
   pyroomacoustics.datasets

diff --git a/docs/modules.rst b/docs/modules.rst
diff --git a/docs/pyroomacoustics.datasets.rst b/docs/pyroomacoustics.datasets.rst
@@ -16,6 +16,7 @@ Datasets Available
 
    pyroomacoustics.datasets.cmu_arctic
    pyroomacoustics.datasets.google_speech_commands
+   pyroomacoustics.datasets.sofa
    pyroomacoustics.datasets.timit
 
 Tools and Helpers

diff --git a/docs/pyroomacoustics.datasets.sofa.rst b/docs/pyroomacoustics.datasets.sofa.rst
@@ -0,0 +1,5 @@
+SOFA Database
+=============
+
+.. automodule:: pyroomacoustics.datasets.sofa
+   :members:
diff --git a/docs/pyroomacoustics.directivities.rst b/docs/pyroomacoustics.directivities.rst
@@ -1,7 +1,75 @@
-pyroomacoustics.directivities module
-====================================
+Directional Sources and Microphones
+===================================
 
 .. automodule:: pyroomacoustics.directivities
    :members:
    :undoc-members:
    :show-inheritance:
+
+Analytic Directional Responses
+------------------------------
+
+.. automodule:: pyroomacoustics.directivities.analytic
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Measured Directivities
+----------------------
+
+.. automodule:: pyroomacoustics.directivities.measured
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Built-in SOFA Files Database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: pyroomacoustics.datasets.sofa
+   :members: SOFADatabase, get_sofa_db
+   :noindex:
+
+
+Reading Other or Custom File Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to read other file types by providing a custom reader function to
+:py:class:`~pyroomacoustics.directivities.measured.MeasuredDirectivityFile` with the
+argument ``file_reader_callback``.
+The function should have the same signature as :py:func:`~pyroomacoustics.directivities.sofa.open_sofa_file`.
+
+
+SOFA File Readers
+.................
+
+.. automodule:: pyroomacoustics.directivities.sofa
+   :members:
+   :show-inheritance:
+
+Direction of the Patterns
+-------------------------
+
+.. automodule:: pyroomacoustics.directivities.direction
+   :members:
+   :show-inheritance:
+
+
+Creating New Types of Directivities
+-----------------------------------
+
+.. automodule:: pyroomacoustics.directivities.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Spherical Interpolation
+-----------------------
+
+.. automodule:: pyroomacoustics.directivities.interp
+   :members: spherical_interpolation
+
+Numerical Spherical Integral
+----------------------------
+
+.. automodule:: pyroomacoustics.directivities.integration
+   :members: spherical_integral
diff --git a/docs/pyroomacoustics.libroom.rst b/docs/pyroomacoustics.libroom.rst
diff --git a/docs/pyroomacoustics.rst b/docs/pyroomacoustics.rst
@@ -29,6 +29,7 @@ Submodules
    pyroomacoustics.parameters
    pyroomacoustics.recognition
    pyroomacoustics.room
+   pyroomacoustics.simulation
    pyroomacoustics.soundsource
    pyroomacoustics.stft
    pyroomacoustics.sync

diff --git a/docs/pyroomacoustics.simulation.ism.rst b/docs/pyroomacoustics.simulation.ism.rst
@@ -0,0 +1,7 @@
+pyroomacoustics.simulation.ism module
+=====================================
+
+.. automodule:: pyroomacoustics.simulation.ism
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/pyroomacoustics.simulation.rst b/docs/pyroomacoustics.simulation.rst
@@ -0,0 +1,21 @@
+Simulation Routines Sub-package
+===============================
+
+This sub-package contains some internal routines to simulate room acoustics.
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pyroomacoustics.simulation.ism
+   pyroomacoustics.simulation.rt
+
+Module contents
+---------------
+
+.. automodule:: pyroomacoustics.simulation
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/pyroomacoustics.simulation.rt.rst b/docs/pyroomacoustics.simulation.rt.rst
@@ -0,0 +1,7 @@
+pyroomacoustics.simulation.rt module
+====================================
+
+.. automodule:: pyroomacoustics.simulation.rt
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/pyroomacoustics.version.rst b/docs/pyroomacoustics.version.rst
diff --git a/examples/directivities/cardioid_function.py b/examples/directivities/cardioid_function.py
@@ -15,7 +15,7 @@
 direction = spher2cart(azimuth=225, degrees=True)
 
 # compute response
-resp = cardioid_func(x=cart, direction=direction, coef=0.5, magnitude=True)
+resp = cardioid_func(x=cart, direction=direction, p=0.5, magnitude=True)
 resp_db = dB(np.array(resp))
 
 # plot
@@ -33,7 +33,7 @@
 direction = spher2cart(azimuth=0, colatitude=45, degrees=True)
 
 # compute response
-resp = cardioid_func(x=cart, direction=direction, coef=0.25, magnitude=True)
+resp = cardioid_func(x=cart, direction=direction, p=0.25, magnitude=True)
 
 # plot (surface plot)
 fig = plt.figure()

diff --git a/examples/directivities/circular_mic_array.py b/examples/directivities/circular_mic_array.py
@@ -1,11 +1,7 @@
 import matplotlib.pyplot as plt
 
 import pyroomacoustics as pra
-from pyroomacoustics.directivities import (
-    CardioidFamily,
-    DirectionVector,
-    DirectivityPattern,
-)
+from pyroomacoustics.directivities import Cardioid, DirectionVector
 
 three_dim = True  # 2D or 3D
 
@@ -28,9 +24,8 @@
 room.add_source(source_loc)
 
 # add circular microphone array
-pattern = DirectivityPattern.CARDIOID
 orientation = DirectionVector(azimuth=mic_rotation, colatitude=colatitude, degrees=True)
-directivity = CardioidFamily(orientation=orientation, pattern_enum=pattern)
+directivity = Cardioid(orientation=orientation)
 mic_array = pra.beamforming.circular_microphone_array_xyplane(
     center=center,
     M=7,

diff --git a/examples/directivities/mic_array.py b/examples/directivities/mic_array.py
@@ -2,13 +2,8 @@
 import numpy as np
 
 import pyroomacoustics as pra
-from pyroomacoustics.directivities import (
-    CardioidFamily,
-    DirectionVector,
-    DirectivityPattern,
-)
+from pyroomacoustics.directivities import DirectionVector, HyperCardioid
 
-pattern = DirectivityPattern.HYPERCARDIOID
 orientation = DirectionVector(azimuth=0, colatitude=0, degrees=True)
 
 # create room
@@ -26,7 +21,7 @@
 M = 3
 R = pra.linear_2D_array(center=[5, 5], M=M, phi=0, d=0.7)
 R = np.concatenate((R, np.ones((1, M))))
-directivity = CardioidFamily(orientation=orientation, pattern_enum=pattern)
+directivity = HyperCardioid(orientation=orientation)
 room.add_microphone_array(R, directivity=directivity)
 
 # plot room

diff --git a/examples/directivities/mic_array_diff_directivities.py b/examples/directivities/mic_array_diff_directivities.py
@@ -2,24 +2,17 @@
 import numpy as np
 
 import pyroomacoustics as pra
-from pyroomacoustics.directivities import (
-    CardioidFamily,
-    DirectionVector,
-    DirectivityPattern,
-)
+from pyroomacoustics.directivities import Cardioid, DirectionVector, HyperCardioid
 
-dir_1 = CardioidFamily(
+dir_1 = Cardioid(
     orientation=DirectionVector(azimuth=180, colatitude=30, degrees=True),
-    pattern_enum=DirectivityPattern.HYPERCARDIOID,
 )
-dir_2 = CardioidFamily(
+dir_2 = HyperCardioid(
     orientation=DirectionVector(azimuth=0, colatitude=30, degrees=True),
-    pattern_enum=DirectivityPattern.HYPERCARDIOID,
 )
 # source_dir = None
-source_dir = CardioidFamily(
+source_dir = HyperCardioid(
     orientation=DirectionVector(azimuth=45, colatitude=90, degrees=True),
-    pattern_enum=DirectivityPattern.CARDIOID,
 )
 
 # create room
-Original file line number
+Diff line change
@@ Expand Up / @@ -52,6 +52,7 @@ @@
         "mpl_toolkits.mplot3d",
         "joblib",
         "scipy.io",
+        "soxr",
     ]
     try:
@@ Expand Down @@