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

.github/workflows/pythonpackage.yml

@@ -32,14 +32,15 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -r requirements.txt
-    - name: Lint with flake8
+    - name: Workaround for windows and python 3.7
+      if: matrix.os == 'windows-latest' && matrix.python-version == 3.7
+      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 flake8
-        # stop the build if there are Python syntax errors or undefined names
-        # flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        # flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+        pip install -r requirements.txt
     - name: Build package
       run: |
         python -m pip install -e .

.gitignore

@@ -15,3 +15,4 @@ local_examples/
 pyroomacoustics.egg-info/
 pyroomacoustics/build_rir.c
 pyroomacoustics/**/*.so
+pyroomacoustics/directivities/tests/data/*.pdf

CHANGELOG.rst

@@ -8,6 +8,38 @@ The format is based on `Keep a
 Changelog <http://keepachangelog.com/en/1.0.0/>`__ and this project
 adheres to `Semantic Versioning <http://semver.org/spec/v2.0.0.html>`_.
 
+dev/dirpat
+----------
+
+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.
+
+- Simulation with measured directivity responses in SOFA format (limited file types) is
+  possible with the image source model.
+- 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.
+
 `Unreleased`_
 -------------
 

MANIFEST.in

@@ -1,5 +1,9 @@
 # Acoustic data for the simulation
 include pyroomacoustics/data/materials.json
+include pyroomacoustics/data/AKG_c480_c414_CUBE.sofa
+include pyroomacoustics/data/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

docs/conf.py

@@ -52,6 +52,7 @@
     "mpl_toolkits.mplot3d",
     "joblib",
     "scipy.io",
+    "soxr",
 ]
 
 try:

docs/index.rst

@@ -14,6 +14,7 @@ Table of contents
   contributing
   changelog
   pyroomacoustics.room
+  pyroomacoustics.directivities
   pyroomacoustics.materials.database
   pyroomacoustics.transform
   pyroomacoustics.datasets

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

docs/pyroomacoustics.datasets.sofa.rst

@@ -0,0 +1,5 @@
+SOFA Database
+=============
+
+.. automodule:: pyroomacoustics.datasets.sofa
+   :members:

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

docs/pyroomacoustics.rst

@@ -29,6 +29,7 @@ Submodules
    pyroomacoustics.parameters
    pyroomacoustics.recognition
    pyroomacoustics.room
+   pyroomacoustics.simulation
    pyroomacoustics.soundsource
    pyroomacoustics.stft
    pyroomacoustics.sync

docs/pyroomacoustics.simulation.ism.rst

@@ -0,0 +1,7 @@
+pyroomacoustics.simulation.ism module
+=====================================
+
+.. automodule:: pyroomacoustics.simulation.ism
+   :members:
+   :undoc-members:
+   :show-inheritance:

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:

docs/pyroomacoustics.simulation.rt.rst

@@ -0,0 +1,7 @@
+pyroomacoustics.simulation.rt module
+====================================
+
+.. automodule:: pyroomacoustics.simulation.rt
+   :members:
+   :undoc-members:
+   :show-inheritance:

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()

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,

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

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

examples/directivities/plot_directivity_2D.py

@@ -3,9 +3,11 @@
 
 from pyroomacoustics import dB
 from pyroomacoustics.directivities import (
-    CardioidFamily,
+    Cardioid,
     DirectionVector,
-    DirectivityPattern,
+    FigureEight,
+    HyperCardioid,
+    SubCardioid,
 )
 
 orientation = DirectionVector(azimuth=0, colatitude=90, degrees=True)
@@ -18,11 +20,11 @@
 # plot each pattern
 fig = plt.figure()
 ax = plt.subplot(111, projection="polar")
-for pattern in DirectivityPattern:
-    dir_obj = CardioidFamily(orientation=orientation, pattern_enum=pattern)
+for obj in [SubCardioid, Cardioid, HyperCardioid, FigureEight]:
+    dir_obj = obj(orientation=orientation)
     resp = dir_obj.get_response(azimuth=angles, magnitude=True, degrees=False)
     resp_db = dB(np.array(resp))
-    ax.plot(angles, resp_db, label=pattern.name)
+    ax.plot(angles, resp_db, label=dir_obj.directivity_pattern)
 
 plt.legend(bbox_to_anchor=(1, 1))
 plt.ylim([lower_gain, 0])

examples/directivities/plot_directivity_3D.py

@@ -1,17 +1,12 @@
 import matplotlib.pyplot as plt
 import numpy as np
 
-from pyroomacoustics.directivities import (
-    CardioidFamily,
-    DirectionVector,
-    DirectivityPattern,
-)
+from pyroomacoustics.directivities import DirectionVector, HyperCardioid
 
-pattern = DirectivityPattern.HYPERCARDIOID
 orientation = DirectionVector(azimuth=0, colatitude=45, degrees=True)
 
 # create cardioid object
-dir_obj = CardioidFamily(orientation=orientation, pattern_enum=pattern)
+dir_obj = HyperCardioid(orientation=orientation)
 
 # plot
 azimuth = np.linspace(start=0, stop=360, num=361, endpoint=True)