SOFA measurement labels are read from the database when available. Makes API more consistent.

Author: fakufaku

examples/simulate_binaural_recording.py

@@ -76,16 +76,15 @@
         fs=fs,
         interp_order=args.interp_order,
         interp_n_points=args.interp_n_points,
-        mic_labels=["left", "right"],
     )
 
     orientation = DirectionVector(
         azimuth=azimuth_deg, colatitude=colatitude_deg, degrees=True
     )
 
-    _, dir_left = hrtf.get_microphone("left", orientation=orientation)
+    dir_left = hrtf.get_mic_directivity("left", orientation=orientation)
 
-    _, dir_right = hrtf.get_microphone("right", orientation=orientation)
+    dir_right = hrtf.get_mic_directivity("right", orientation=orientation)
 
     room_dim = [6, 6, 2.4]
 
@@ -149,8 +148,8 @@
 
     room.add_source([1.5, 3.01, 1.044], signal=speech)
 
-    room.add_microphone([1.1, 3.01, 1.8], directivity=dir_left)
-    room.add_microphone([1.1, 3.01, 1.8], directivity=dir_right)
+    room.add_microphone([1.1, 3.01, 2.2], directivity=dir_left)
+    room.add_microphone([1.1, 3.01, 2.2], directivity=dir_right)
 
     room.simulate()
 

examples/simulation_with_measured_directivity.py

@@ -82,8 +82,8 @@ class DirectionVector
 
 vec_54_73 = DirectionVector(azimuth=54, colatitude=73, degrees=True)
 
-_, dir_obj_Dmic = akg.get_microphone("AKG_c414K", orientation=vec_54_73)
-_, dir_obj_Emic = eigenmike.get_microphone("EM_32_9", orientation=vec_54_73)
+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_Cmic = CardioidFamily(
     orientation=DirectionVector(azimuth=90, colatitude=123, degrees=True),

pyroomacoustics/data/sofa_files.json

@@ -100,7 +100,7 @@
     "type": "microphones",
     "url": "http://sofacoustics.org/data/database/mit/mit_kemar_large_pinna.sofa",
     "homepage": "https://sound.media.mit.edu/resources/KEMAR/",
-    "license": "custom-attribution",
+    "license": "This data is Copyright 1994 by the MIT Media Laboratory. It is provided free with no restrictions on use, provided the authors are cited when the data is used in any research or commercial application.",
     "contains": [
       "left",
       "right"
@@ -111,7 +111,7 @@
     "type": "microphones",
     "url": "http://sofacoustics.org/data/database/mit/mit_kemar_normal_pinna.sofa",
     "homepage": "https://sound.media.mit.edu/resources/KEMAR/",
-    "license": "custom-attribution",
+    "license": "This data is Copyright 1994 by the MIT Media Laboratory. It is provided free with no restrictions on use, provided the authors are cited when the data is used in any research or commercial application.",
     "contains": [
       "left",
       "right"

pyroomacoustics/datasets/sofa.py

@@ -1,4 +1,6 @@
 import json
+import typing as tp
+from dataclasses import dataclass
 from pathlib import Path
 
 from .utils import AttrDict, download_multiple
@@ -7,6 +9,42 @@
 DEFAULT_SOFA_PATH = _pra_data_folder / "sofa"
 SOFA_INFO = _pra_data_folder / "sofa_files.json"
 
+_DIRPAT_FILES = [
+    "Soundfield_ST450_CUBE",
+    "AKG_c480_c414_CUBE",
+    "Oktava_MK4012_CUBE",
+    "LSPs_HATS_GuitarCabinets_Akustikmessplatz",
+]
+
+
+def is_dirpat(name):
+    if isinstance(name, Path):
+        name = name.stem
+    return name in _DIRPAT_FILES
+
+
+def get_sofa_db():
+    # we want to avoid loading the database multiple times
+    global sofa_db
+    try:
+        return sofa_db
+    except NameError:
+        sofa_db = SOFADatabase()
+        return sofa_db
+
+
+def resolve_sofa_path(path):
+    path = Path(path)
+
+    if path.exists():
+        return path
+
+    sofa_db = get_sofa_db()
+    if path.stem in sofa_db:
+        return Path(sofa_db[path.stem].path)
+
+    raise ValueError(f"SOFA file {path} could not be found")
+
 
 def get_sofa_db_info():
     with open(SOFA_INFO, "r") as f:
@@ -51,7 +89,66 @@ def download_sofa_files(path=None, overwrite=False, verbose=False, no_fail=False
     return list(files.keys())
 
 
+@dataclass
+class SOFAFileInfo:
+    """
+    A class to store information about a SOFA file
+
+    Parameters
+    ----------
+    path: Path
+        The path to the SOFA file
+    supported: bool
+        Whether the SOFA file is supported by Pyroom Acoustics
+    type: str
+        The type of device (e.g., 'sources' or 'microphones')
+    url: str
+        The URL where the SOFA file can be downloaded
+    homepage: str
+        The URL of the SOFA file homepage
+    license: str
+        The license of the SOFA file
+    contains: List[str]
+        The labels of the sources/microphones contained in the SOFA file,
+        or``None`` if the information is not available
+    """
+
+    path: Path
+    supported: bool = True
+    type: str = "unknown"
+    url: str = "unknown"
+    homepage: str = "unknown"
+    license: str = "unknown"
+    contains: tp.List[str] = None
+
+
 class SOFADatabase(dict):
+    """
+    A small database of SOFA files containing source/microphone directional
+    impulse responses
+
+    The database object is a dictionary-like object where the keys are the
+    names of the SOFA files and the values are objects with the following
+    attributes:
+
+    .. code-block:: python
+
+        db = SOFADatabase()
+
+        # type of device: 'sources' or 'microphones'
+        db["Soundfield_ST450_CUBE"].type
+
+        # list of the labels of the sources/microphones
+        db["Soundfield_ST450_CUBE"].contains
+
+
+    Parameters
+    ----------
+    download: bool, optional
+        If set to `True`, the SOFA files are downloaded if they are not already
+        present in the default folder
+    """
+
     def __init__(self, download=True):
         super().__init__()
 
@@ -63,29 +160,22 @@ def __init__(self, download=True):
         for name, info in get_sofa_db_info().items():
             path = self.root / f"{name}.sofa"
             if path.exists():
-                dict.__setitem__(self, name, AttrDict(info))
-                self[name]["path"] = path
+                dict.__setitem__(self, name, SOFAFileInfo(path=path, **info))
 
         for path in DEFAULT_SOFA_PATH.glob("*.sofa"):
             name = path.stem
             if name not in self:
                 dict.__setitem__(
                     self,
                     name,
-                    AttrDict(
-                        {
-                            "path": path,
-                            "supported": "???",
-                            "type": "unknown",
-                            "url": "???",
-                            "homepage": "???",
-                            "license": "???",
-                            "contains": None,
-                        }
-                    ),
+                    SOFAFileInfo(path=path),
                 )
 
     def list(self):
+        """
+        Print a list of the available SOFA files and the labels of the
+        different devices they contain
+        """
         for name, info in self.items():
             print(f"- {name} ({info.type})")
             if info.contains is not None:
@@ -94,10 +184,12 @@ def list(self):
 
     @property
     def root(self):
+        """The path to the folder containing the SOFA files"""
         return DEFAULT_SOFA_PATH
 
     @property
     def db_info_path(self):
+        """The path to the JSON file containing the SOFA files information"""
         return SOFA_INFO
 
     def __setitem__(self, key, val):

pyroomacoustics/directivities/measured.py

@@ -20,7 +20,7 @@
 from ..doa import Grid, GridSphere, cart2spher, fibonacci_spherical_sampling, spher2cart
 from ..utilities import requires_matplotlib, resample
 from .interp import spherical_interpolation
-from .sofa import get_sofa_db, open_sofa_file
+from .sofa import open_sofa_file
 
 
 class MeasuredDirectivity(Directivity):
@@ -205,23 +205,44 @@ def __init__(
         source_labels=None,
     ):
         self.path = Path(path)
-        self.mic_labels, self.source_labels = self._set_labels(
-            self.path, mic_labels, source_labels
-        )
 
         if file_reader_callback is None:
+            # default reader is for SOFA files
             file_reader_callback = open_sofa_file
 
         (
             self.impulse_responses,  # (n_sources, n_mics, taps)
-            self.sources_loc,  # (3, n_sources), spherical coordinates
-            self.mics_loc,  # (3, n_mics), cartesian coordinates
             self.fs,
+            self.source_locs,  # (3, n_sources), spherical coordinates
+            self.mic_locs,  # (3, n_mics), cartesian coordinates
+            src_labels_file,
+            mic_labels_file,
         ) = file_reader_callback(
             path=self.path,
             fs=fs,
         )
 
+        if mic_labels is None:
+            self.mic_labels = mic_labels_file
+        else:
+            if len(mic_labels) != self.mic_locs.shape[1]:
+                breakpoint()
+                raise ValueError(
+                    f"Number of labels provided ({len(mic_labels)}) does not match the "
+                    f"number of microphones ({self.mic_locs.shape[1]})"
+                )
+            self.mic_labels = mic_labels
+
+        if source_labels is None:
+            self.source_labels = src_labels_file
+        else:
+            if len(source_labels) != self.source_locs.shape[1]:
+                raise ValueError(
+                    f"Number of labels provided ({len(source_labels)}) does not match "
+                    f"the number of sources ({self.source_locs.shape[1]})"
+                )
+            self.source_labels = source_labels
+
         self.interp_order = interp_order
         self.interp_n_points = interp_n_points
 
@@ -233,16 +254,6 @@ def __init__(
         else:
             self.interp_grid = None
 
-    def _set_labels(self, path, mic_labels, src_labels):
-        sofa_db = get_sofa_db()
-        if path.stem in sofa_db:
-            info = sofa_db[path.stem]
-            if info.type == "microphones" and mic_labels is None:
-                mic_labels = info.contains
-            elif info.type == "sources" and src_labels is None:
-                src_labels = info.contains
-        return mic_labels, src_labels
-
     def _interpolate(self, type, mid, grid, impulse_responses):
         if self.interp_order is None:
             return grid, impulse_responses
@@ -272,40 +283,57 @@ def _get_measurement_index(self, meas_id, labels):
 
         raise ValueError(f"Measurement id {meas_id} not found")
 
-    def get_microphone(self, measurement_id, orientation, offset=None):
+    def get_mic_position(self, measurement_id):
+        mid = self._get_measurement_index(measurement_id, self.mic_labels)
+
+        if not (0 <= mid < self.mic_locs.shape[1]):
+            raise ValueError(f"Microphone id {mid} not found")
+
+        return self.mic_locs[:, mid]
+
+    def get_source_position(self, measurement_id):
+        mid = self._get_measurement_index(measurement_id, self.source_labels)
+
+        if not (0 <= mid < self.source_locs.shape[1]):
+            raise ValueError(f"Source id {mid} not found")
+
+        # convert to cartesian since the sources are stored by
+        # default in spherical coordinates
+        pos = spher2cart(*self.source_locs[:, mid])
+
+        return pos
+
+    def get_mic_directivity(self, measurement_id, orientation):
         mid = self._get_measurement_index(measurement_id, self.mic_labels)
 
+        if not (0 <= mid < self.mic_locs.shape[1]):
+            raise ValueError(f"Microphone id {mid} not found")
+
         # select the measurements corresponding to the mic id
         ir = self.impulse_responses[:, mid, :]
-        src_grid = GridSphere(spherical_points=self.sources_loc[:2])
-
-        mic_loc = self.mics_loc[:, mid]
-        if offset is not None:
-            mic_loc += offset
+        src_grid = GridSphere(spherical_points=self.source_locs[:2])
 
         # interpolate the IR
         grid, ir = self._interpolate("mic", mid, src_grid, ir)
 
         dir_obj = MeasuredDirectivity(orientation, grid, ir, self.fs)
-        return mic_loc, dir_obj
+        return dir_obj
 
-    def get_source(self, measurement_id, orientation, offset=None):
+    def get_source_directivity(self, measurement_id, orientation):
         mid = self._get_measurement_index(measurement_id, self.source_labels)
 
+        if not (0 <= mid < self.source_locs.shape[1]):
+            raise ValueError(f"Source id {mid} not found")
+
         # select the measurements corresponding to the mic id
         ir = self.impulse_responses[mid, :, :]
 
         # here we need to swap the coordinate types
-        mic_pos = np.array(cart2spher(self.mics_loc))
+        mic_pos = np.array(cart2spher(self.mic_locs))
         mic_grid = GridSphere(spherical_points=mic_pos[:2])
 
-        # source location
-        src_loc = spher2cart(*self.sources_loc[:, mid])
-        if offset is not None:
-            src_loc += offset
-
         # interpolate the IR
         grid, ir = self._interpolate("source", mid, mic_grid, ir)
 
         dir_obj = MeasuredDirectivity(orientation, grid, ir, self.fs)
-        return src_loc, dir_obj
+        return dir_obj