Edits CHANGELOG. Adds more details about the SOFA files included incl…

…uding origin and license in the documentation.

CHANGELOG.rst

@@ -8,8 +8,15 @@ 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
-----------
+`Unreleased`_
+-------------
+
+This new version introduces some major changes. In particular, it introduces
+the use of measured microphone and source directivities. This new feature
+allows to simulate more accurately real recording equipments. See the
+`documentation
+<https://pyroomacoustics.readthedocs.io/en/latest/pyroomacoustics.directivities.html>`_
+for more details.
 
 Added
 ~~~~~
@@ -25,8 +32,22 @@ Added
     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.
 
+- New parameter ``min_phase`` of class ``Room``. If set to ``True``, the band-pass
+  filters are designed as minimum phase filters.
+
 - Simulation with measured directivity responses in SOFA format (limited file types) is
   possible with the image source model.
+
+  - A flexible and extensible  SOFA file reader with optional spherical interpolation.
+  - A small database of files is bundled, including the `DIRPAT database
+    <https://aes2.org/publications/elibrary-page/?id=19538>`_, collected by
+    Manuel Brandner, Matthias Frank, and Daniel Rudrich University of Music and
+    Performing Arts Graz, Graz. The file also include two HRTF of the
+    `MIT KEMAR dummy head <https://sound.media.mit.edu/resources/KEMAR/README>`_.
+
+- Introduces a new class ``pyroomacoustics.directivities.Rotation3D`` to specify
+  the orientation of sources and receivers in 3D.
+
 - Adds `soxr <https://github.com/dofuuz/python-soxr>`_ as a dependency since resampling
   can often be necessary when working with SOFA files.
 
@@ -40,11 +61,6 @@ Changed
   ``Bidirectional`` and ``Omnidirectional`` are added in the ``directivity``
   sub-module. The enum of type ``DirectivityPattern`` has been removed.
 
-`Unreleased`_
--------------
-
-Nothing yet
-
 `0.7.7`_ - 2024-09-09
 ---------------------
 

MANIFEST.in

@@ -1,7 +1,8 @@
 # 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_files.json
+include pyroomacoustics/data/sofa/AKG_c480_c414_CUBE.sofa
+include pyroomacoustics/data/sofa/EM32_Directivity.sofa
 include pyroomacoustics/data/sofa/mit_kemar_large_pinna.sofa
 include pyroomacoustics/data/sofa/mit_kemar_normal_pinna.sofa
 
@@ -23,9 +24,12 @@ graft pyroomacoustics/tests
 graft pyroomacoustics/adaptive/tests
 graft pyroomacoustics/bss/tests
 graft pyroomacoustics/datasets/tests
+graft pyroomacoustics/denoise/tests
+graft pyroomacoustics/directivities/tests
 graft pyroomacoustics/doa/tests
 graft pyroomacoustics/experimental/tests
 graft pyroomacoustics/libroom_src/tests
+graft pyroomacoustics/phase/tests
 graft pyroomacoustics/transform/tests
 
 global-exclude *.py[co]

pyroomacoustics/datasets/sofa.py

@@ -24,7 +24,8 @@
 r"""
 Pyroomacoustics contains a small database of SOFA files that have been tested
 and can be used for simultions.
-The database can be loaded using the function :py:class:`~pyroomacoustics.datasets.sofa.SOFADatabase`.
+The database can be loaded using the function
+:py:class:`~pyroomacoustics.datasets.sofa.SOFADatabase`.
 
 .. code-block:: python
 
@@ -33,6 +34,39 @@
 
     db = SOFADatabase()
     db.list()
+
+The database contains the following files.
+
+- Three files from the `DIRPAT database
+  <https://phaidra.kug.ac.at/detail/o:68229#?page=1&pagesize=10&collection=o:67857>`_
+  collected by Manuel Brandner, Matthias Frank, and Daniel Rudrich University
+  of Music and Performing Arts, Graz.
+
+  - ``AKG_c480_c414_CUBE.sofa`` containing the directive responses of a
+    microphone with 4 different patterns.
+  - ``EM32_Directivity.sofa`` that contains the directional response of the
+    `Eigenmike em32 <https://eigenmike.com/eigenmike-em32>`_ microphone array.
+  - ``LSPs_HATS_GuitarCabinets_Akustikmessplatz.sofa`` that contains 12 source
+    directivities. This file is dynamically downloaded upon its first use.
+  - The files are public domain
+    (`CC0 <https://creativecommons.org/public-domain/cc0/>`_),
+    but if you use them in your research, please cite the following
+    `paper <https://aes2.org/publications/elibrary-page/?id=19538>`_.
+
+    ::
+
+        M. Brandner, M. Frank, and D. Rudrich, "DirPat—Database and
+        Viewer of 2D/3D Directivity Patterns of Sound Sources and Receivers,"
+        in Audio Engineering Society Convention 144, Paper 425, 2018.
+
+- Two head-related transfer functions of the MIT KEMAR dummy head
+  with normal and large pinna. The data was collected by Bill Gardner
+  and Keith Martin from MIT and is free to use provided the authors are
+  cited. See the
+  `full license <https://sound.media.mit.edu/resources/KEMAR/README>`_
+  for more details.
+
+
 """
 
 

pyroomacoustics/directivities/base.py

@@ -28,9 +28,12 @@
 directivity patterns.
 
 The class should implement the following methods:
-- `get_response` to get the response for a given angle and frequency
-- `is_impulse_response` to indicate whether the directivity is an impulse response or just band coefficients
-- `filter_len_ir` to return the length of the impulse response. This should return 1 if the directivity is not an impulse response.
+
+- ``get_response`` to get the response for a given angle and frequency
+- ``is_impulse_response`` to indicate whether the directivity is an impulse response or
+  just band coefficients
+- ``filter_len_ir`` to return the length of the impulse response. This should return 1
+  if the directivity is not an impulse response.
 """
 import abc
 

pyroomacoustics/directivities/direction.py

@@ -129,7 +129,8 @@ def _make_rot_matrix(a, axis):
 
 class Rotation3D:
     """
-    An object representing 3D rotations by their [Euler angles](https://en.wikipedia.org/wiki/Euler_angles).
+    An object representing 3D rotations by their
+    `Euler angles <https://en.wikipedia.org/wiki/Euler_angles>`_.
 
     A rotation in 3D space can be fully described by 3 angles (i.e., the Euler angles). Each rotation is applied
     around one of the three axes and there are 12 possible ways of pickinig the order or the rotations.