From c286e549db297d6abee03c4f757215ffa6bfec09 Mon Sep 17 00:00:00 2001
From: Robin Scheibler <fakufaku@gmail.com>
Date: Mon, 28 Oct 2024 23:34:41 +0900
Subject: [PATCH] CHANGELOG and some improvements to the doc of directivities.

---
 CHANGELOG.rst                              | 30 +++++++++++++++++-----
 pyroomacoustics/datasets/sofa.py           |  4 +++
 pyroomacoustics/directivities/base.py      |  9 ++++---
 pyroomacoustics/directivities/direction.py |  3 ++-
 4 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index b7f7c3e3..d33499ce 100644
--- a/CHANGELOG.rst
+++ b/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
 ---------------------
 
diff --git a/pyroomacoustics/datasets/sofa.py b/pyroomacoustics/datasets/sofa.py
index d9b38134..753b9058 100644
--- a/pyroomacoustics/datasets/sofa.py
+++ b/pyroomacoustics/datasets/sofa.py
@@ -36,10 +36,12 @@
     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.
+
   - ``LSPs_HATS_GuitarCabinets_Akustikmessplatz.sofa`` that contains 12 source
     directivities.
   - ``AKG_c480_c414_CUBE.sofa`` containing the directive responses of a
@@ -51,6 +53,8 @@
     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.
diff --git a/pyroomacoustics/directivities/base.py b/pyroomacoustics/directivities/base.py
index 15ff1040..349f25f9 100644
--- a/pyroomacoustics/directivities/base.py
+++ b/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
 
diff --git a/pyroomacoustics/directivities/direction.py b/pyroomacoustics/directivities/direction.py
index 0992612d..c0463ea1 100644
--- a/pyroomacoustics/directivities/direction.py
+++ b/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.