Initial commit

Author: ehabets

.github/workflows/python-package.yml

@@ -0,0 +1,34 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Python package
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install --upgrade setuptools setuptools_scm
+        pip install build
+    - name: Build Package
+      run: |
+        python -m build

.github/workflows/python-publish.yml

@@ -0,0 +1,40 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install --upgrade setuptools setuptools_scm
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -0,0 +1,64 @@
+#####=== Python ===#####
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.c
+*.o
+*.so
+*.h.gch
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+rirgenerator.c

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2023 Friedrich-Alexander-Universität Erlangen-Nürnberg, Germany  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,90 @@
+# **Generating coherence-constrained multisensor signals using balanced mixing and spectrally smooth filters**
+
+Project Overview
+====================
+This project provides a Python function for generating multi-channel audio signals with predefined spatial coherence.
+
+Abstract
+====================
+
+The spatial properties of a noise field can be described by a spatial coherence function. Synthetic multichannel noise signals exhibiting a specific spatial coherence can be generated by properly mixing a set of uncorrelated, possibly nonstationary, signals. The mixing matrix can be obtained by decomposing the spatial coherence matrix. As proposed in a widely used method, the factorization can be performed using a Cholesky or an eigenvalue decomposition. The limitations of these two methods are discussed and addressed in [[1]](#1). In particular, specific properties of the mixing matrix are analyzed, namely the spectral smoothness and the mix balance. The first quantifies the mixing matrix-filters variation across frequency, and the second quantifies how much each input contributes to each output. Three methods based on the unitary Procrustes solution are proposed to enhance the spectral smoothness, the mix balance, and both properties jointly. A performance evaluation confirms the improvements of the mixing matrix in terms of objective measures. Further, the evaluation results show that the error between the target and the generated coherence is lowered by increasing the spectral smoothness of the mixing matrix.
+
+Method
+====================
+
+This method is able to generate multi-channel audio signals that exhibit a predefined spatial coherence. It also enhances specific properties of the mixing matrix obtained with the baseline approach (Cholesky or eigenvalue decompositions). These properties are:<br/> 
+
+- **Spectral Variation**: variation of the mixing matrix's filter response in the frequency domain. The mixing matrix is considered smooth if it slowly varies over frequency. For this reason, we denote a low Spectral Variation with 'Spectral Smoothness'. This variation can be quantified by the squared Frobenius norm of the difference between two frequency-bands adjacent mixing matrices. 
+- **Coherence Error**: accuracy of the generated spatial coherence at frequency bands that are not resolved by the chosen DFT length. A mixing matrix yields a low coherence error when the squared Frobenius norm of the difference between the target coherence matrix and the generated coherence matrix is low.
+- **Mix Balance**: balance of the mixing, i.e., the number of input signals that contribute to each output signal. A balanced mixing matrix contains similar contributions from each input signal to each output signal. The balance can be quantified by the l1-norm of the mixing matrix.
+
+The coherence error is inherently decreased by increasing the spectral smoothness. In addition, a smooth mixing matrix yields shorter impulse responses compared to non-smooth counterparts. The benefits of improving the smoothness and the balance are also perceptually evident. A smooth mix leads to less distortions in the output signals (especially during transients). A balanced mix is such that the input signals are filtered and summed similarly among all the channels, leading to an increased perceptual plausibility.
+
+Settings
+====================
+Different parameters can be chosen for the signal generation (e.g., sampling frequency, DFT length, spatial coherence model). The microphone positions are arranged in a matrix (`M` x 3), i.e., *number of channels* x coordinates *xyz*. The generator works for any arbitrary 3-D microphone constellation.
+
+Supported spatial coherence models:<br/> 
+1. 3-D spherically isotropic diffuse sound field: `spherical`
+2. 2-D cylindrically isotropic diffuse sound field: `cylindrical`
+3. Corcos model (turbulent aerodynamic noise, e.g., atmospheric-wind noise): `corcos`
+
+The first and second model depends solely on the microphone positions. The third model has two additional parameters: `speed` and `direction` of the turbulent airflow. When selecting this model, it is suggested to use an inter-microphone distance of less than 2 cm to appreciate differences with respect to a noise field with uncorrelated signals. 
+
+Supported factorization methods to decompose the target coherence matrix and obtain the mixing matrix:
+1. Cholesky decomposition: `chd`
+2. Eigenvalue decomposition: `evd`
+
+The `chd` yields a smooth but unbalanced mix. The `evd` yields a more balanced but non-smooth mix. 
+
+Three methods are available to enhance the properties of the mixing matrix:
+1. Enhance smoothness: `smooth`
+2. Enhance balance: `balanced`
+3. Enhance balance and smoothness: `balanced+smooth`
+4. No post-processing: `standard`
+
+The `smooth` method enhances the smoothness (i.e., decreases the spectral variation) and lowers the coherence error while leaving almost unaltered the mix balance. The `balanced` method maximizes the balance but significantly increases the spectral variation and the coherence error. The `balanced+smooth` method enhances both properties with a reasonable trade-off. The `standard` method leaves the Cholesky or the eigenvalue decomposition unaltered.
+
+Installation
+====================
+```ruby
+   pip install anf-generator
+```
+
+Example Code
+====================
+```ruby
+   import numpy as np
+   import anf_generator as anf
+
+   # Define signals
+   duration = 10  # Duration in seconds
+   num_channels = 4  # Number of microphones
+
+   # Define target spatial coherence
+   params = anf.CoherenceMatrix.Parameters(
+      mic_positions=np.array([[0.04 * i, 0, 0] for i in range(num_channels)]),
+      sc_type="spherical",
+      sample_frequency=16000,
+      nfft=1024,
+      )
+
+   # Generate "num_channels" mutually independent input signals of length "duration"
+   input_signals = np.random.randn(num_channels, duration * params.sample_frequency)
+
+   # Generate output signals with the desired spatial coherence
+   output_signals, coherence_target, mixing_matrix = anf.generate_signals(
+      input_signals, params, decomposition='evd', processing='balance+smooth')
+```
+
+Two more test scripts are provided: `tests/example.py` and `tests/example_babble.py`.
+
+Audio Examples
+====================
+Click [here](https://www.audiolabs-erlangen.de/resources/2020-JASA-CCR) to listen to examples generated using this method.
+
+References
+====================
+<a id="1">[1]</a> D. Mirabilii, S. J. Schlecht, E.A.P. Habets, *'Generating coherence-constrained multisensor signals using balanced mixing and spectrally smooth filters'*, The Journal of the Acoustical Society of America, Vol. 149, 1425, 2021.
+
+<a id="2">[2]</a> E.A.P. Habets, I. Cohen and S. Gannot, *'Generating nonstationary multisensor signals under a spatial coherence constraint,'* Journal of the Acoustical Society of America, Vol. 124, Issue 5, pp. 2911-2917, Nov. 2008. [Code](https://github.com/ehabets/ANF-Generator)

anf_generator/CoherenceMatrix.py

@@ -0,0 +1,89 @@
+import numpy as np
+from scipy.special import jv
+
+
+class Parameters:
+    def __init__(self, mic_positions, sc_type, sample_frequency, nfft=1024, c=340, speed=20, direction=60):
+        self.mic_positions = mic_positions  # Microphone positions [M x 3]
+        # Spatial coherence model: 'corcos', 'spherical', or 'cylindrical'
+        self.sc_type = sc_type.lower()
+        self.sample_frequency = sample_frequency  # Sample frequency (Hz)
+        self.nfft = nfft  # FFT length
+        self.c = c  # Sound velocity (m/s)
+        self.speed = speed  # Wind speed (m/s)
+        self.direction = direction  # Wind direction (degrees)
+
+    def copy(self):
+        return Parameters(
+            mic_positions=self.mic_positions.copy(),
+            sc_type=self.sc_type,
+            sample_frequency=self.sample_frequency,
+            nfft=self.nfft,
+            c=self.c,
+            speed=self.speed,
+            direction=self.direction
+        )
+
+
+class CoherenceMatrix:
+    def __init__(self, params: Parameters):
+        self.params = params
+        self.matrix = self.generate_target_coherence()
+
+    def generate_target_coherence(self):
+        """
+        Generate the analytical target coherence based on the model
+        (e.g., diffuse spherical/cylindrical, Corcos), the sensor positions, 
+        and the FFT length. Valid for an arbitrary 3D-array geometry.
+
+        Returns:
+            DC (np.array): Target coherence matrix [Channels x Channels x nfft/2+1]
+        """
+
+        # Angular frequency vector
+        ww = 2 * np.pi * self.params.sample_frequency * \
+            np.arange(self.params.nfft // 2 + 1) / self.params.nfft
+
+        # Matrix of position vectors
+        rr = self.params.mic_positions[:, None, :] - \
+            self.params.mic_positions[None, :, :]
+
+        # Matrix of inter-sensor distances
+        d = np.linalg.norm(rr, axis=2)
+
+        if self.params.sc_type == 'corcos':
+            # Desired wind speed and direction
+            Ud = self.params.speed / 3.6  # Wind speed [m/s]
+            theta = np.deg2rad(self.params.direction)  # Angle in radians
+
+            # Rotation matrix for wind direction
+            R = np.array([[np.cos(theta), -np.sin(theta), 0],
+                          [np.sin(theta), np.cos(theta), 0],
+                          [0, 0, 1]])
+            yy = np.array([0, 1, 0])  # y axis = true North
+            u = np.dot(yy, R)  # Wind direction unit vector
+            # Wind direction unit perpendicular vector
+            u_p = np.array([u[1], -u[0], 0])
+
+            # Coherence parameters
+            alpha1, alpha2 = -0.125, -0.7
+            alpha__ = alpha1 * np.abs(np.sum(u[None, None, :] * rr, axis=2)) \
+                + alpha2 * np.abs(np.sum(u_p[None, None, :] * rr, axis=2))
+            im__ = np.sum(u[None, None, :] * rr, axis=2)
+            U = 0.8 * Ud  # Convective turbulence speed
+            AA = np.einsum('ij,k->ijk', alpha__ - 1j * im__, ww)
+            DC = np.exp(AA / U)
+
+        elif self.params.sc_type == 'spherical':
+            DC = np.sinc(d[:, :, None] * ww[None, None, :] /
+                         (self.params.c * np.pi))
+
+        elif self.params.sc_type == 'cylindrical':
+            DC = jv(0,d[:, :, None] * ww[None, None, :] /
+                         (self.params.c))
+
+        else:
+            raise ValueError(
+                'Unknown coherence model. Please select "corcos", "spherical", or "cylindrical".')
+
+        return DC