Source code for acoustic_spaces.spatial.microphone

"""A listener's microphone: the pattern its mono output picks up sound through.

A first-order capsule picks up ``w + d . v`` of sound arriving from the direction ``v``
(head coordinates: x forward, y left, z up, as the listener's ``orientation`` turns
them). Aimed forward that is ``a + (1 - a) cos(theta)``, with the ``a`` the pattern's
name gives in :data:`acoustic_spaces.directivity.PATTERNS`: 1 straight ahead, the same
at every frequency. A coincident pair puts two capsules in one place, their channels
left and right:

- ``xy``: two capsules of one pattern aimed ``angle_deg`` apart in the horizontal
  plane, the left one to the left of the front.
- ``blumlein``: two figure-eights aimed 45 degrees to each side.
- ``ms``: a mid capsule aimed forward and a figure-eight aimed left, decoded to
  ``M + g S`` on the left and ``M - g S`` on the right, ``g`` the side's gain.

Each early path is picked up from the direction it arrives from, and each impulse of
the late part from the direction it is drawn from (:mod:`acoustic_spaces.spatial.render`).
A pair's channels hold the same late impulses, as two capsules in one place hear the
same reverberation.

A pattern may change with frequency, as a real capsule's does (wider in the bass, say):
an ``a`` per octave band (8) or third-octave band (24), given as pattern names or
values, for a single capsule, an XY pair's capsules or an MS pair's mid one. Its ``a``
goes from band to band across the crossovers of the synthesis's band filters
(:func:`acoustic_spaces.synthesis.band_gains`): a capsule picks up
``(d . v) + a(f) (1 - d . v)``, ``d`` its aim, so the response is rendered twice, once
through the part that does not change (``d . v``) and once through the part ``a``
scales, which then goes through a filter of gain ``a`` in each band
(:meth:`Microphone.parts`). The two take the same paths and impulses, so this is
exact; a pattern that is the same in every band is rendered once, as before.
"""

from __future__ import annotations

import math
from collections.abc import Sequence
from dataclasses import dataclass, replace

import numpy as np

from acoustic_spaces import products
from acoustic_spaces.directivity import PATTERNS, FirstOrder
from acoustic_spaces.materials import OCTAVE_BANDS_HZ
from acoustic_spaces.materials.bands import resolution_of

#: The band whose pattern a microphone that changes with frequency is drawn in (its
#: balloon in the editor): 1 kHz, as a source's balloon is.
SHOWN_BAND = OCTAVE_BANDS_HZ.index(1000)
#: A direction or an axis, in head coordinates.
Vector = tuple[float, float, float]


def _vector(values) -> Vector:
    x, y, z = (float(v) for v in values)
    return (x, y, z)


[docs] @dataclass(frozen=True) class Microphone: """Capsules in one place: channel ``k`` picks up ``weights[k] + axes[k] . v`` of sound arriving from ``v`` in head coordinates.""" label: str names: tuple[str, ...] weights: tuple[float, ...] axes: tuple[Vector, ...] #: For a pattern that changes with frequency, the ``a`` of its capsules in each band #: (8 or 24; the channels share it), each channel's capsule aim (a unit vector) and #: what it picks up besides that capsule (an MS pair's figure-eight); ``weights`` #: and ``axes`` then hold the pattern at 1 kHz (:data:`SHOWN_BAND`). None for one #: pattern at every frequency. a: tuple[float, ...] | None = None aims: tuple[Vector, ...] = () sides: tuple[Vector, ...] = () @property def channels(self) -> int: return len(self.names)
[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: the capsules' omnidirectional part (in the lowest band, for a pattern that changes with frequency), none of their gradient part.""" if self.a is None: return np.asarray(self.weights, dtype=float) steady, scaled = self.parts() low = float(self.a_in(8)[0]) return np.asarray(steady.weights, dtype=float) + low * np.asarray(scaled.weights)
@property def channel_names(self) -> list[str]: return list(self.names)
[docs] def gains(self, directions: np.ndarray) -> np.ndarray: """What each channel picks up (n, channels) of sound arriving from ``directions`` (n, 3), unit vectors in head coordinates.""" if self.a is not None: raise ValueError( f"the {self.label} microphone picks up differently in each band: " "render it through its parts()" ) v = np.atleast_2d(np.asarray(directions, dtype=float)) return np.asarray(self.weights) + products.product(v, np.asarray(self.axes).T)
[docs] def parts(self) -> tuple[Microphone, Microphone]: """A microphone whose pattern changes with frequency as two that do not: what each channel picks up whatever ``a`` (``d . v`` and its side's) and what ``a`` scales (``1 - d . v``), ``d`` its capsule's aim. It picks up the first plus the second through a filter of gain ``a`` in each band (:meth:`a_in`).""" if self.a is None: raise ValueError(f"the {self.label} microphone is the same in every band") steady = tuple( _vector(np.add(aim, side)) for aim, side in zip(self.aims, self.sides, strict=True) ) scaled = tuple(_vector(np.negative(aim)) for aim in self.aims) zeros, ones = (0.0,) * self.channels, (1.0,) * self.channels return ( Microphone(self.label, self.names, zeros, steady), Microphone(self.label, self.names, ones, scaled), )
[docs] def a_in(self, bands: int) -> np.ndarray: """``a`` in ``bands`` bands (8 octaves or 24 third octaves), as a source's pattern goes from one to the other.""" if self.a is None: raise ValueError(f"the {self.label} microphone is the same in every band") return np.asarray(FirstOrder(self.a).in_bands(resolution_of(bands)).a, dtype=float)
[docs] def band_gains(self, directions: np.ndarray, bands: int) -> np.ndarray: """What each channel picks up (n, channels, bands) in each of ``bands`` bands (8 octaves or 24 third octaves) of sound arriving from ``directions`` (n, 3).""" if self.a is None: return np.repeat(self.gains(directions)[:, :, None], bands, axis=2) steady, scaled = self.parts() a = self.a_in(bands) return steady.gains(directions)[:, :, None] + scaled.gains(directions)[:, :, None] * a
[docs] def spectral_gains(self, directions: np.ndarray, shapes: np.ndarray) -> np.ndarray: """What each channel picks up (n, channels, bins) of sound arriving from ``directions`` (n, 3) at the frequencies of the synthesis's band filters ``shapes`` (bands, bins) (:func:`acoustic_spaces.synthesis.band_gains`), which sum to one: each band's gain across its share of the frequencies.""" if self.a is None: return self.gains(directions)[:, :, None] return products.product(self.band_gains(directions, len(shapes)), np.asarray(shapes))
[docs] def capsules(self) -> list[tuple[FirstOrder, np.ndarray]]: """Each channel as a first-order pattern and the rotation that aims it: columns forward, left and up in head coordinates (an MS pair's left channel is a first-order pattern aimed between the front and the left).""" out = [] for w, axis in zip(self.weights, self.axes, strict=True): d = np.asarray(axis, dtype=float) length = float(np.linalg.norm(d)) forward = d / length if length > 0 else np.array([1.0, 0.0, 0.0]) side = np.cross([0.0, 0.0, 1.0], forward) if np.linalg.norm(side) < 1e-9: # aimed straight up or down side = np.array([0.0, 1.0, 0.0]) side /= np.linalg.norm(side) turn = np.column_stack([forward, side, np.cross(forward, side)]) a = w / (w + length) if w + length > 0 else 1.0 out.append((FirstOrder((a,) * len(OCTAVE_BANDS_HZ)), turn)) return out
Pattern = str | float | Sequence[str | float] def pattern_a(pattern: Pattern) -> float | tuple[float, ...]: """The ``a`` of a pattern: a name of ``PATTERNS`` or a value, or one of them per band, which gives one ``a`` when the bands agree.""" if isinstance(pattern, str | int | float): return PATTERNS[pattern] if isinstance(pattern, str) else float(pattern) values = tuple(PATTERNS[v] if isinstance(v, str) else float(v) for v in pattern) FirstOrder(values) # 8 or 24 of them, each from 0 to 1 return values[0] if len(set(values)) == 1 else values def pattern_label(pattern: Pattern) -> str: """How a pattern is named: its name, or its value or name in each band.""" if isinstance(pattern, str | int | float): return str(pattern) if len({str(v) for v in pattern}) == 1: return str(pattern[0]) return "per band: " + ", ".join(str(v) for v in pattern) def _capsules( label: str, names: tuple[str, ...], a: float | tuple[float, ...], aims: list[Vector], sides: list[Vector], ) -> Microphone: """Capsules of one pattern (``a``, or one per band) aimed along ``aims``, each channel also picking up its row of ``sides``.""" def axes(value: float) -> tuple[Vector, ...]: return tuple( _vector((1.0 - value) * np.asarray(aim) + np.asarray(side)) for aim, side in zip(aims, sides, strict=True) ) if not isinstance(a, tuple): return Microphone(label, names, (a,) * len(names), axes(a)) shown = FirstOrder(a).in_bands("octave").a[SHOWN_BAND] return Microphone( label, names, (shown,) * len(names), axes(shown), a=a, aims=tuple(_vector(aim) for aim in aims), sides=tuple(_vector(side) for side in sides), ) def first_order(pattern: Pattern) -> Microphone: """One capsule of a first-order ``pattern`` (a name of ``PATTERNS`` or a value of ``a``, or one per band) aimed forward.""" return _capsules( pattern_label(pattern), ("M",), pattern_a(pattern), [(1.0, 0.0, 0.0)], [(0.0, 0.0, 0.0)] ) def xy(angle_deg: float = 90.0, capsule: Pattern = "cardioid") -> Microphone: """Two ``capsule`` patterns aimed ``angle_deg`` apart in the horizontal plane.""" half = math.radians(angle_deg) / 2.0 c, s = math.cos(half), math.sin(half) zero = (0.0, 0.0, 0.0) return _capsules( "xy", ("L", "R"), pattern_a(capsule), [(c, s, 0.0), (c, -s, 0.0)], [zero, zero] ) def blumlein() -> Microphone: """Two figure-eights at 90 degrees, aimed 45 degrees to each side.""" return replace(xy(90.0, "figure8"), label="blumlein") def ms(mid: Pattern = "cardioid", side_db: float = 0.0) -> Microphone: """A ``mid`` capsule aimed forward and a figure-eight aimed left ``side_db`` above it, decoded to left and right.""" g = 10.0 ** (side_db / 20.0) forward = (1.0, 0.0, 0.0) return _capsules( "ms", ("L", "R"), pattern_a(mid), [forward, forward], [(0.0, g, 0.0), (0.0, -g, 0.0)] ) def of_listener(listener) -> Microphone | None: """The microphone a listener's ``pattern`` describes (``scene.Listener``); None when it has none or it is omni.""" pattern = getattr(listener, "pattern", None) if pattern is None or pattern == "omni": return None if isinstance(pattern, str | list | tuple): return None if pattern_a(pattern) == 1.0 else first_order(pattern) if pattern.pair == "xy": return xy(pattern.angle_deg, pattern.capsule) if pattern.pair == "blumlein": return blumlein() return ms(pattern.mid, pattern.side_db)
[docs] def for_listener(fmt, listener): """The format ``listener``'s output in ``fmt`` is rendered in: its microphone when ``fmt`` is mono and it has a pattern, else ``fmt``.""" from acoustic_spaces.spatial.render import Mono if isinstance(fmt, Mono): microphone = of_listener(listener) if microphone is not None: return microphone return fmt
__all__ = [ "SHOWN_BAND", "Microphone", "blumlein", "first_order", "for_listener", "ms", "of_listener", "pattern_a", "pattern_label", "xy", ]