Source code for acoustic_spaces.spatial.ambisonics
"""Ambisonics in the AmbiX convention: ACN channel order, SN3D normalisation.
Channel ``n * n + n + m`` carries the real spherical harmonic of order n and degree m,
without the Condon-Shortley phase and normalised so every order peaks at 1. First order
is then W = 1, Y = y, Z = z, X = x for a plane wave from the unit vector (x, y, z).
"""
from __future__ import annotations
import math
from dataclasses import dataclass
import numpy as np
#: Highest order the encoder accepts.
MAX_ORDER = 7
[docs]
def real_spherical_harmonics(order: int, directions: np.ndarray) -> np.ndarray:
"""ACN / SN3D spherical harmonics (dirs, (order + 1) ** 2) of unit vectors (dirs, 3)."""
if not 0 <= order <= MAX_ORDER:
raise ValueError(f"Ambisonics order must be 0 to {MAX_ORDER}, got {order}")
v = np.atleast_2d(np.asarray(directions, dtype=float))
length = np.linalg.norm(v, axis=1, keepdims=True)
if not np.all(length > 0):
raise ValueError("every direction needs a length above zero (and no NaN)")
v = v / length
sin_el = np.clip(v[:, 2], -1.0, 1.0)
cos_el = np.sqrt(np.maximum(0.0, 1.0 - sin_el**2))
azimuth = np.arctan2(v[:, 1], v[:, 0])
out = np.empty((len(v), (order + 1) ** 2))
for m in range(order + 1):
# Associated Legendre functions P_l^m(sin el) for l = m .. order, by recurrence.
p_mm = math.prod(range(1, 2 * m, 2)) * cos_el**m # (2m - 1)!! cos^m
legendre = {m: p_mm}
if m < order:
legendre[m + 1] = sin_el * (2 * m + 1) * p_mm
for n in range(m + 2, order + 1):
legendre[n] = (
(2 * n - 1) * sin_el * legendre[n - 1] - (n + m - 1) * legendre[n - 2]
) / (n - m)
for n in range(m, order + 1):
norm = math.sqrt(
(1.0 if m == 0 else 2.0) * math.factorial(n - m) / math.factorial(n + m)
)
out[:, n * n + n + m] = norm * legendre[n] * np.cos(m * azimuth)
if m > 0:
out[:, n * n + n - m] = norm * legendre[n] * np.sin(m * azimuth)
return out
_FIRST_ORDER = ("W", "Y", "Z", "X")
[docs]
@dataclass(frozen=True)
class Ambisonics:
"""AmbiX (ACN / SN3D) encoding of the given order: (order + 1) ** 2 channels."""
order: int = 1
def __post_init__(self) -> None:
if not 0 <= self.order <= MAX_ORDER:
raise ValueError(f"Ambisonics order must be 0 to {MAX_ORDER}, got {self.order}")
@property
def channels(self) -> int:
return (self.order + 1) ** 2
@property
def label(self) -> str:
return f"ambix{self.order}"
[docs]
def pressure_gains(self) -> np.ndarray:
"""(channels,) what each channel picks up of a sound pressure that is the same
all over the room (all of it in W, none in the other channels)."""
out = np.zeros(self.channels)
out[0] = 1.0
return out
@property
def channel_names(self) -> list[str]:
if self.order <= 1:
return list(_FIRST_ORDER[: self.channels])
return [f"ACN{k}" for k in range(self.channels)]
[docs]
def gains(self, directions: np.ndarray) -> np.ndarray:
"""Encoding gains (dirs, channels) of plane waves from head directions (dirs, 3)."""
return real_spherical_harmonics(self.order, directions)
__all__ = ["MAX_ORDER", "Ambisonics", "real_spherical_harmonics"]