Add SphericalHarmonicsAudio classes

spharpy/classes/__init__.py

@@ -4,6 +4,8 @@
 
 from .audio import (
     SphericalHarmonicSignal,
+    SphericalHarmonicTimeData,
+    SphericalHarmonicFrequencyData
 )
 
 from .coordinates import (
@@ -13,5 +15,7 @@
 __all__ = [
     'SphericalHarmonics'
     'SphericalHarmonicSignal',
+    'SphericalHarmonicTimeData',
+    'SphericalHarmonicFrequencyData',
     'SamplingSphere',
 ]

spharpy/classes/audio.py

@@ -1,34 +1,27 @@
-from pyfar import Signal
+from pyfar import Signal, TimeData, FrequencyData
+from pyfar.classes.audio import _Audio
 from spharpy.spherical import renormalize, change_channel_convention
 import numpy as np
 
 
-class SphericalHarmonicSignal(Signal):
-    """Create audio object with spherical harmonics coefficients in time or
-    frequency domain.
+class SphericalHarmonicAudio(_Audio):
+    """Base class for spherical harmonics audio objects.
+
+    This class extends the pyfar Audio class with all methods and
+    properties required for spherical harmonics data and are common to the 
+    three sub-classes :py:func:`SphericalHarmonicsTimeData`,
+    :py:func:`SphericalHarmonicsFrequencyData`, and
+    :py:func:`SphericalHarmonicsSignal`.
 
     Objects of this class contain spherical harmonics coefficients which are
-    directly convertible between time and frequency domain (equally spaced
-    samples and frequency bins), the channel conventions ACN and FUMA, as
+    directly convertible between channel conventions ACN and FUMA, as
     well as the normalizations N3D, SN3D, or MaxN, see [#]_. The definition of
     the spherical harmonics basis functions is based on the scipy convention
     which includes the Condon-Shortley phase, [#]_, [#]_.
 
 
     Parameters
     ----------
-    data : ndarray, double
-        Raw data of the spherical harmonics signal in the time or
-        frequency domain. The data should have at least 3 dimensions,
-        according to the 'C' memory layout, e.g. data of
-        ``shape = (1, 4, 1024)`` has 1 channel with 4 spherical harmonic
-        coefficients with 1024 samples or frequency
-        bins each. Time data is converted to ``float``. Frequency is
-        converted to ``complex`` and must be provided as single
-        sided spectra, i.e., for all frequencies between 0 Hz and
-        half the sampling rate.
-    sampling_rate : double
-        Sampling rate in Hz
     basis_type : str
         Type of spherical harmonic basis, either ``'complex'`` or
         ``'real'``.
@@ -41,24 +34,10 @@ class SphericalHarmonicSignal(Signal):
     condon_shortley : bool
         Flag to indicate if the Condon-Shortley phase term is included
         (``True``) or not (``False``).
-    n_samples : int, optional
-        Number of time domain samples. Required if domain is ``'freq'``.
-        The default is ``None``, which assumes an even number of samples
-        if the data is provided in the frequency domain.
     domain : ``'time'``, ``'freq'``, optional
         Domain of data. The default is ``'time'``
-    fft_norm : str, optional
-        The normalization of the Discrete Fourier Transform (DFT). Can be
-        ``'none'``, ``'unitary'``, ``'amplitude'``, ``'rms'``, ``'power'``,
-        or ``'psd'``. See :py:func:`~pyfar.dsp.fft.normalization` and [#]_
-        for more information. The default is ``'none'``, which is typically
-        used for energy signals, such as impulse responses.
     comment : str
         A comment related to `data`. The default is ``None``.
-    is_complex : bool, optional
-        Specifies if the underlying time domain data are complex
-        or real-valued. If ``True`` and `domain` is ``'time'``, the
-        input data will be cast to complex. The default is ``False``.
 
     References
     ----------
@@ -70,32 +49,20 @@ class SphericalHarmonicSignal(Signal):
     .. [#] E.G. Williams, "Fourier Acoustics", (1999), Academic Press
 
     """
-    def __init__(
-            self,
-            data,
-            sampling_rate,
-            basis_type,
-            normalization,
-            channel_convention,
-            condon_shortley,
-            n_samples=None,
-            domain='time',
-            fft_norm='none',
-            comment="",
-            is_complex=False):
-        """
-        Create SphericalHarmonicSignal with data, and sampling rate.
-        """
+    def __init__(self, basis_type, normalization, channel_convention,
+                 condon_shortley, domain, comment=""):
+        _Audio.__init__(self, domain=domain, comment=comment)
+
         # check dimensions
-        if len(data.shape) < 3:
+        if len(self._data.shape) < 3:
             raise ValueError("Invalid number of dimensions. Data should have "
                              "at least 3 dimensions.")
 
         # set n_max
-        n_max = np.sqrt(data.shape[-2])-1
+        n_max = np.sqrt(self._data.shape[-2])-1
         if n_max - int(n_max) != 0:
             raise ValueError("Invalid number of SH channels: "
-                             f"{data.shape[-2]}. It must match (n_max + 1)^2.")
+                             f"{self._data.shape[-2]}. It must match (n_max + 1)^2.")
         self._n_max = int(n_max)
 
         # set basis_type
@@ -121,10 +88,6 @@ def __init__(
             raise ValueError("Condon_shortley has to be a bool.")
         self._condon_shortley = condon_shortley
 
-        Signal.__init__(self, data, sampling_rate=sampling_rate,
-                        n_samples=n_samples, domain=domain, fft_norm=fft_norm,
-                        comment=comment, is_complex=is_complex)
-
     @property
     def n_max(self):
         """Get the maximum spherical harmonic order."""
@@ -178,3 +141,182 @@ def channel_convention(self, value):
                                                    self.channel_convention,
                                                    value, axis=-2)
             self._channel_convention = value
+
+
+class SphericalHarmonicTimeData(SphericalHarmonicAudio, TimeData):
+    """
+    Create spherical harmonic audio object with time domain spherical
+    harmonic coefficients and times.
+
+    Objects of this class contain time data which is not directly convertible
+    to frequency domain, i.e., non-equidistant samples.
+
+    Parameters
+    ----------
+    data : array, double
+        Raw data in the time domain. The data should have at least 3
+        dimensions, according to the 'C' memory layout, e.g. data of
+        ``shape = (1, 4, 1024)`` has 1 channel with 4 spherical harmonic
+        coefficients with 1024 samples each. The data can be ``int`` or
+        ``float`` and is converted to ``float`` in any case.
+    times : array, double
+        Times in seconds at which the data is sampled. The number of times
+        must match the `size` of the last dimension of `data`.
+    basis_type : str
+        Type of spherical harmonic basis, either ``'complex'`` or
+        ``'real'``.
+    normalization : str
+        Normalization convention, either ``'n3d'``, ``'maxN'`` or
+        ``'sn3d'``. (maxN is only supported up to 3rd order)
+    channel_convention : str
+        Channel ordering convention, either ``'acn'`` or ``'fuma'``.
+        (FuMa is only supported up to 3rd order)
+    condon_shortley : bool
+        Flag to indicate if the Condon-Shortley phase term is included
+        (``True``) or not (``False``).
+    comment : str
+        A comment related to `data`. The default is ``None``.
+    is_complex : bool, optional
+        A flag which indicates if the time data are real or complex-valued.
+        The default is ``False``.
+    """
+    def __init__(self, data, times, basis_type, normalization,
+                 channel_convention, condon_shortley, comment="",
+                 is_complex=False):
+        TimeData.__init__(self, data=data, times=times, comment=comment,
+                          is_complex=is_complex)
+        SphericalHarmonicAudio.__init__(
+            self, basis_type, normalization, channel_convention,
+            condon_shortley, domain="time", comment=comment)
+
+
+class SphericalHarmonicFrequencyData(SphericalHarmonicAudio, FrequencyData):
+    """
+    Create spherical harmonic audio object with frequency domain spherical
+    harmonic coefficients and frequencies.
+
+    Objects of this class contain frequency data which is not directly
+    convertible to the time domain, i.e., non-equidistantly spaced bins or
+    incomplete spectra.
+
+    Parameters
+    ----------
+    data : array, double
+        Raw data in the frequency domain. The data should have at least
+        3 dimensions, according to the 'C' memory layout, e.g. data of
+        ``shape = (1, 4, 1024)`` has 1 channel with 4 spherical harmonic
+        coefficients with 1024 frequency bins each.. Data can be ``int``,
+        ``float`` or ``complex``. Data of type ``int`` is converted to
+        ``float``.
+    frequencies : array, double
+        Frequencies of the data in Hz. The number of frequencies must match
+        the size of the last dimension of data.
+    basis_type : str
+        Type of spherical harmonic basis, either ``'complex'`` or
+        ``'real'``.
+    normalization : str
+        Normalization convention, either ``'n3d'``, ``'maxN'`` or
+        ``'sn3d'``. (maxN is only supported up to 3rd order)
+    channel_convention : str
+        Channel ordering convention, either ``'acn'`` or ``'fuma'``.
+        (FuMa is only supported up to 3rd order)
+    condon_shortley : bool
+        Flag to indicate if the Condon-Shortley phase term is included
+        (``True``) or not (``False``).
+    comment : str
+        A comment related to `data`. The default is ``None``.
+    """
+    def __init__(self, data, frequencies, basis_type, normalization,
+                 channel_convention, condon_shortley, comment=""):
+        FrequencyData.__init__(self, data=data, frequencies=frequencies,
+                               comment=comment)
+        SphericalHarmonicAudio.__init__(
+            self, basis_type, normalization, channel_convention,
+            condon_shortley, domain="time", comment=comment)
+
+
+class SphericalHarmonicSignal(SphericalHarmonicAudio, Signal):
+    """Create audio object with spherical harmonics coefficients in time or
+    frequency domain.
+
+    Objects of this class contain spherical harmonics coefficients which are
+    directly convertible between time and frequency domain (equally spaced
+    samples and frequency bins), the channel conventions ACN and FUMA, as
+    well as the normalizations N3D, SN3D, or MaxN, see [#]_. The definition of
+    the spherical harmonics basis functions is based on the scipy convention
+    which includes the Condon-Shortley phase, [#]_, [#]_.
+
+
+    Parameters
+    ----------
+    data : ndarray, double
+        Raw data of the spherical harmonics signal in the time or
+        frequency domain. The data should have at least 3 dimensions,
+        according to the 'C' memory layout, e.g. data of
+        ``shape = (1, 4, 1024)`` has 1 channel with 4 spherical harmonic
+        coefficients with 1024 samples or frequency
+        bins each. Time data is converted to ``float``. Frequency is
+        converted to ``complex`` and must be provided as single
+        sided spectra, i.e., for all frequencies between 0 Hz and
+        half the sampling rate.
+    sampling_rate : double
+        Sampling rate in Hz
+    basis_type : str
+        Type of spherical harmonic basis, either ``'complex'`` or
+        ``'real'``.
+    normalization : str
+        Normalization convention, either ``'n3d'``, ``'maxN'`` or
+        ``'sn3d'``. (maxN is only supported up to 3rd order)
+    channel_convention : str
+        Channel ordering convention, either ``'acn'`` or ``'fuma'``.
+        (FuMa is only supported up to 3rd order)
+    condon_shortley : bool
+        Flag to indicate if the Condon-Shortley phase term is included
+        (``True``) or not (``False``).
+    n_samples : int, optional
+        Number of time domain samples. Required if domain is ``'freq'``.
+        The default is ``None``, which assumes an even number of samples
+        if the data is provided in the frequency domain.
+    domain : ``'time'``, ``'freq'``, optional
+        Domain of data. The default is ``'time'``
+    fft_norm : str, optional
+        The normalization of the Discrete Fourier Transform (DFT). Can be
+        ``'none'``, ``'unitary'``, ``'amplitude'``, ``'rms'``, ``'power'``,
+        or ``'psd'``. See :py:func:`~pyfar.dsp.fft.normalization` and [#]_
+        for more information. The default is ``'none'``, which is typically
+        used for energy signals, such as impulse responses.
+    comment : str
+        A comment related to `data`. The default is ``None``.
+    is_complex : bool, optional
+        Specifies if the underlying time domain data are complex
+        or real-valued. If ``True`` and `domain` is ``'time'``, the
+        input data will be cast to complex. The default is ``False``.
+
+    References
+    ----------
+    .. [#] F. Zotter, M. Frank, "Ambisonics A Practical 3D Audio Theory
+            for Recording, Studio Production, Sound Reinforcement, and
+            Virtual Reality", (2019), Springer-Verlag
+    .. [#] B. Rafely, "Fundamentals of Spherical Array Processing", (2015),
+            Springer-Verlag
+    .. [#] E.G. Williams, "Fourier Acoustics", (1999), Academic Press
+
+    """
+    def __init__(self,
+                 data,
+                 sampling_rate,
+                 basis_type,
+                 normalization,
+                 channel_convention,
+                 condon_shortley,
+                 n_samples=None,
+                 domain='time',
+                 fft_norm='none',
+                 comment="",
+                 is_complex=False):
+        Signal.__init__(self, data=data, sampling_rate=sampling_rate,
+                        n_samples=n_samples, domain=domain, fft_norm=fft_norm,
+                        comment=comment, is_complex=is_complex)
+        SphericalHarmonicAudio.__init__(
+            self, basis_type, normalization, channel_convention,
+            condon_shortley, domain="time", comment=comment)

tests/test_spherical_harmonics_audio.py

@@ -0,0 +1,26 @@
+from pytest import raises
+from spharpy.classes.audio import SphericalHarmonicAudio
+from spharpy.classes.audio import SphericalHarmonicTimeData
+from spharpy.classes.audio import SphericalHarmonicFrequencyData
+import numpy as np
+import re
+
+
+def test_init_sh_time_data():
+    data = np.ones((1, 4, 4))
+    times = [1, 2, 3, 4]
+    sh_time_data = SphericalHarmonicTimeData(
+        data, times,  basis_type='real', normalization='sn3d',
+        channel_convention="acn", condon_shortley=False,
+        comment="")
+    assert isinstance(sh_time_data, SphericalHarmonicTimeData)
+
+
+def test_init_sh_frequency_data():
+    data = np.ones((1, 4, 4))
+    frequencies = [1, 2, 3, 4]
+    sh_freq_data = SphericalHarmonicFrequencyData(
+        data, frequencies, basis_type='real', normalization='sn3d',
+        channel_convention="acn", condon_shortley=False,
+        comment="")
+    assert isinstance(sh_freq_data, SphericalHarmonicFrequencyData)