changes the interface for cardioid family. Removes the enum, uses sep…

…arate classes wrapper instead (Cardioid, Sub-cardioid, etc). Adds Rotation3D class to apply arbitrary rotations to measured directivities.

.gitignore

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

CHANGELOG.rst

@@ -33,6 +33,10 @@ 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.
 
 `Unreleased`_
 -------------

examples/simulate_binaural_recording.py

@@ -18,12 +18,7 @@
 from scipy.signal import fftconvolve
 
 import pyroomacoustics as pra
-from pyroomacoustics.directivities import (
-    CardioidFamily,
-    DirectionVector,
-    DirectivityPattern,
-    MeasuredDirectivityFile,
-)
+from pyroomacoustics.directivities import MeasuredDirectivityFile, Rotation3D
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(
@@ -78,12 +73,8 @@
         interp_n_points=args.interp_n_points,
     )
 
-    orientation = DirectionVector(
-        azimuth=azimuth_deg, colatitude=colatitude_deg, degrees=True
-    )
-
+    orientation = Rotation3D([colatitude_deg, azimuth_deg], "yz", degrees=True)
     dir_left = hrtf.get_mic_directivity("left", orientation=orientation)
-
     dir_right = hrtf.get_mic_directivity("right", orientation=orientation)
 
     room_dim = [6, 6, 2.4]

examples/simulation_with_measured_directivity.py

@@ -71,29 +71,28 @@ class DirectionVector
 
 import pyroomacoustics as pra
 from pyroomacoustics.directivities import (
-    CardioidFamily,
+    Cardioid,
+    FigureEight,
     DirectionVector,
-    DirectivityPattern,
     MeasuredDirectivityFile,
+    Rotation3D,
 )
 
 eigenmike = MeasuredDirectivityFile("EM32_Directivity", fs=16000)
 akg = MeasuredDirectivityFile("AKG_c480_c414_CUBE", fs=16000)
 
-vec_54_73 = DirectionVector(azimuth=54, colatitude=73, degrees=True)
+rot_54_73 = Rotation3D([73, 54], "yz", degrees=True)
 
-dir_obj_Dmic = akg.get_mic_directivity("AKG_c414K", orientation=vec_54_73)
-dir_obj_Emic = eigenmike.get_mic_directivity("EM_32_9", orientation=vec_54_73)
+dir_obj_Dmic = akg.get_mic_directivity("AKG_c414K", orientation=rot_54_73)
+dir_obj_Emic = eigenmike.get_mic_directivity("EM_32_9", orientation=rot_54_73)
 
-dir_obj_Cmic = CardioidFamily(
+dir_obj_Cmic = FigureEight(
     orientation=DirectionVector(azimuth=90, colatitude=123, degrees=True),
-    pattern_enum=DirectivityPattern.FIGURE_EIGHT,
 )
 
 
-dir_obj_Csrc = CardioidFamily(
+dir_obj_Csrc = Cardioid(
     orientation=DirectionVector(azimuth=56, colatitude=123, degrees=True),
-    pattern_enum=DirectivityPattern.CARDIOID,
 )
 
 
@@ -163,7 +162,7 @@ class DirectionVector
 
 room.add_microphone([2.31, 1.65, 1.163], directivity=dir_mic)
 
-dir_mic.set_orientation(DirectionVector(54, 73))
+dir_mic.set_orientation(Rotation3D([73, 54], rot_order="yz"))
 
 
 room.compute_rir()

pyroomacoustics/beamforming.py

@@ -30,12 +30,7 @@
 from . import transform
 from . import utilities as u
 from . import windows
-from .directivities import (
-    CardioidFamily,
-    DirectionVector,
-    Directivity,
-    DirectivityPattern,
-)
+from .directivities import Omnidirectional, DirectionVector, Directivity
 from .parameters import constants
 from .soundsource import build_rir_matrix
 
@@ -306,10 +301,7 @@ def circular_microphone_array_xyplane(
     if directivity is not None:
         assert isinstance(directivity, Directivity)
     else:
-        orientation = DirectionVector(azimuth=0, colatitude=colatitude, degrees=True)
-        directivity = CardioidFamily(
-            orientation=orientation, pattern_enum=DirectivityPattern.OMNI
-        )
+        directivity = Omnidirectional()
 
     # for plotting
     azimuth_plot = None

pyroomacoustics/directivities/__init__.py

@@ -23,16 +23,41 @@
 # You should have received a copy of the MIT License along with this program. If
 # not, see <https://opensource.org/licenses/MIT>.
 r"""
-# Directional Responses
+## Directional Responses
 
 Real-world microphones and sound sources usually exhibit directional responses.
 That is, the impulse response (or frequency response) depends on the emission
 or reception angle (for sources and microphones, respectively).
+A concrete example is the human ear attached to the head. The left ear is
+typically more sensitive to sounds coming from the left side than from the right.
 
 This sub-module provides an interface to add such directional responses to
 microphones and sources in the room impulse response simulation.
+
+.. warning::
+    The directional responses are currently only supported for the
+    image source method based simulation.
+
+The directivities are described by an object of a class derived from py:class:`pyroomacoustics.directivities.base.Directivity`.
+
+.. code-block:: python
+    from pyroomacoustics.directivities import Directivity
+
+### Analytical Directional Responses
+
+
+### Measured Directional Responses
+
 """
-from .analytic import CardioidFamily, DirectivityPattern, cardioid_func
+from .analytic import (
+    CardioidFamily,
+    Cardioid,
+    SubCardioid,
+    HyperCardioid,
+    FigureEight,
+    Omnidirectional,
+    cardioid_func,
+)
 from .base import Directivity
-from .direction import DirectionVector
+from .direction import DirectionVector, Rotation3D
 from .measured import MeasuredDirectivity, MeasuredDirectivityFile