Doc

Author: fakufaku

docs/pyroomacoustics.directivities.rst

@@ -1,5 +1,5 @@
-Directional Source and Microphone Responses
-===========================================
+Directional Sources and Microphones
+===================================
 
 .. automodule:: pyroomacoustics.directivities
    :members:
@@ -26,8 +26,7 @@ Built-in SOFA Files Database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: pyroomacoustics.datasets.sofa
-   :members:
-   :show-inheritance:
+   :members: SOFADatabase, get_sofa_db
    :noindex:
 
 

pyroomacoustics/datasets/sofa.py

@@ -62,6 +62,9 @@ def is_dirpat(name):
 
 
 def get_sofa_db():
+    """
+    A helper function to quickly load the SOFA database
+    """
     # we want to avoid loading the database multiple times
     global sofa_db
     try:

pyroomacoustics/directivities/analytic.py

@@ -383,7 +383,7 @@ def __init__(self, gain=1.0):
         self._pattern_name = "omni"
 
 
-def cardioid_func(x, direction, coef, gain=1.0, normalize=True, magnitude=False):
+def cardioid_func(x, direction, p, gain=1.0, normalize=True, magnitude=False):
     """
     One-shot function for computing cardioid response.
 
@@ -392,36 +392,54 @@ def cardioid_func(x, direction, coef, gain=1.0, normalize=True, magnitude=False)
     x: array_like, shape (n_dim, ...)
          Cartesian coordinates
     direction: array_like, shape (n_dim)
-         Direction vector, should be normalized.
-    coef: float
-         Parameter for the cardioid function.
+         Direction vector, should be normalized
+    p: float
+         Parameter for the cardioid function (between 0 and 1)
     gain: float
-         The gain.
+         The gain
     normalize : bool
-        Whether to normalize coordinates and direction vector.
+        Whether to normalize coordinates and direction vector
     magnitude : bool
-        Whether to return magnitude, default is False.
+        Whether to return magnitude, default is False
 
     Returns
     -------
     resp : :py:class:`~numpy.ndarray`
         Response at provided angles for the speficied cardioid function.
     """
-    assert coef >= 0.0
-    assert coef <= 1.0
+    if not 0.0 <= p <= 1.0:
+        raise ValueError("The parameter p must be between 0 and 1.")
 
     # normalize positions
     if normalize:
         x /= np.linalg.norm(x, axis=0)
         direction /= np.linalg.norm(direction)
 
     # compute response
-    resp = gain * (coef + (1 - coef) * np.matmul(direction, x))
+    resp = gain * (p + (1 - p) * np.matmul(direction, x))
     if magnitude:
         return np.abs(resp)
     else:
         return resp
 
 
-def cardioid_energy(coef, gain=1.0):
-    return gain**2 * (4.0 * np.pi / 3.0) * (4 * coef**2 - 2 * coef + 1)
+def cardioid_energy(p, gain=1.0):
+    r"""
+    This function gives the exact value of the surface integral of the cardioid
+    (family) function on the unit sphere
+
+    .. math::
+
+        E(p, G) = \iint_{\mathbb{S}^2} G^2 \left( p + (1 - p) \boldsymbol{d}^\top \boldsymbol{r} \right)^2 d\boldsymbol{r}
+        = \frac{4 \pi}{3} G^2 \left( 4 p^2 - 2 p + 1 \right).
+
+    This can be used to normalize the energy sent/received.
+
+    Parameters
+    ---------
+    p: float
+        The parameter of the cardioid function (between 0 and 1)
+    gain: float
+        The gain of the cardioid function
+    """
+    return gain**2 * (4.0 * np.pi / 3.0) * (4 * p**2 - 2 * p + 1)

pyroomacoustics/directivities/measured.py

@@ -174,6 +174,29 @@ def get_response(
 
     @requires_matplotlib
     def plot(self, freq_bin=0, n_grid=100, ax=None, depth=False, offset=None):
+        """
+        Plot the directivity pattern at a given frequency.
+
+        Parameters
+        ----------
+        freq_bin: int
+            The frequency bin to plot
+        n_grid: int
+            The number of points to use for the interpolation grid
+        ax: matplotlib.axes.Axes, optional
+            The axes to plot on. If not provided, a new figure is created
+        depth: bool
+            If ``True``, directive response is both depicted by color and depth
+            of the surface. If ``False``, then only the color map denotes the
+            intensity. (default ``False``)
+        offset: float
+            An offset to apply to the directivity pattern
+
+        Returns
+        -------
+        ax: matplotlib.axes.Axes
+            The axes on which the directivity is plotted
+        """
         import matplotlib.pyplot as plt
         from matplotlib import cm
 
@@ -225,7 +248,7 @@ def plot(self, freq_bin=0, n_grid=100, ax=None, depth=False, offset=None):
 class MeasuredDirectivityFile:
     """
     This class reads measured directivities from a
-    `SOFA <https://www.sofaconventions.org>`_ format file.
+    `SOFA`_ format file.
     Optionally, it can perform interpolation of the impulse responses onto a finer grid.
     The interpolation is done in the spherical harmonics domain.
 

pyroomacoustics/directivities/sofa.py

@@ -22,7 +22,7 @@
 # You should have received a copy of the MIT License along with this program. If
 # not, see <https://opensource.org/licenses/MIT>.
 r"""
-`SOFA <https://www.sofaconventions.org/>` is a very flexible file format for storing
+`SOFA <https://www.sofaconventions.org/>`_ is a very flexible file format for storing
 direction impulse responses. This module provides a function to read SOFA files and
 extract the impulse responses in a format that can be used for simulation.
 """

pyroomacoustics/utilities.py

@@ -24,6 +24,7 @@
 from __future__ import division
 
 import itertools
+import functools
 
 import numpy as np
 import soxr
@@ -36,6 +37,7 @@
 
 
 def requires_matplotlib(func):
+    @functools.wraps(func)  # preserves name, docstrings, and signature of function
     def function_wrapper(*args, **kwargs):
         try:
             import matplotlib.pyplot as plt