"""Source directivity: how a source shares its sound power between directions, per
octave band (or third-octave band).
A directivity gives energy weights that average 1 over the sphere in every band, so a
source radiates its sound power (``level_db``) whatever its pattern; the pattern only
says where that power goes. Directions are in the source's own frame: x forward, y left,
z up, as :class:`acoustic_spaces.scene.Orientation` turns them; azimuth turns from the
front towards the left and elevation is positive upwards, in degrees.
- :class:`FirstOrder`: the patterns ``a + (1 - a) cos(theta)`` from omni (a = 1) to
figure-8 (a = 0), one per band, so a loudspeaker can be omni in the bass and narrow
in the treble.
- :class:`Balloon`: measured levels at any set of directions, read from a SOFA file
(AES69, the ``FreeFieldDirectivityTF`` convention) or a CSV table, interpolated over
the sphere; or the far-field pattern of a coherent array
(:func:`array_directivity`).
``load_directivity`` turns a source's ``directivity`` entry of a scene file into one::
directivity: cardioid # one pattern for every band
directivity: {pattern: [omni, omni, subcardioid, cardioid, cardioid, supercardioid,
hypercardioid, hypercardioid]}
directivity: {file: speaker.sofa} # or speaker.csv
directivity: {array: {count: 8, spacing_m: 0.15, steer_deg: -8}}
directivity: {file: line_array.yaml} # an array's fields in a YAML file
The CSV table has a header row ``azimuth, elevation`` followed by band centre
frequencies in Hz (octaves, thirds or any other layout), then one row per direction
with the level in dB in each band (any reference; only differences matter). Lines
starting with ``#`` are comments.
Measured data is averaged into octave bands. A simulation in third-octave bands takes
each octave band's directivity for its three third octaves (:meth:`Directivity.in_bands`).
"""
from __future__ import annotations
import math
import re
from dataclasses import dataclass, field
from pathlib import Path
import numpy as np
from acoustic_spaces import products
from acoustic_spaces._extras import install_hint
from acoustic_spaces.air import speed_of_sound
from acoustic_spaces.materials import OCTAVE_BANDS_HZ, THIRD_OCTAVE_BANDS_HZ
from acoustic_spaces.materials.bands import (
Resolution,
convert,
crossover_frequencies,
resolution_of,
)
#: The first-order patterns by name: the pressure is a + (1 - a) cos(theta).
PATTERNS: dict[str, float] = {
"omni": 1.0,
"subcardioid": 0.7,
"cardioid": 0.5,
"supercardioid": 0.37,
"hypercardioid": 0.25,
"figure8": 0.0,
}
#: Angular step of the grid measured data is interpolated on (degrees).
GRID_STEP_DEG = 5.0
#: Speed of sound (m/s) an array's phases take when no room gives one: air at 20 C.
SPEED_OF_SOUND = speed_of_sound(20.0)
#: Directions times pairs of elements an array's pattern is worked out for at a time.
_ARRAY_CHUNK = 1 << 18
#: Measured directions a grid point is interpolated from, but where several are equally
#: near it (``Balloon.from_measurements``).
NEIGHBOURS = 4
#: Measured directions whose unit vectors are no further apart than this are one
#: direction, and those whose distances from a grid point differ by no more are equally
#: near it (a millionth of a radian, 0.00006 degrees).
SAME_DIRECTION = 1e-6
_BANDS = len(OCTAVE_BANDS_HZ)
_BAND_COUNTS = (len(OCTAVE_BANDS_HZ), len(THIRD_OCTAVE_BANDS_HZ))
_SEPARATOR = re.compile(r"[,;\t]")
_SPACES = re.compile(r"\s+")
def _unit(directions) -> np.ndarray:
v = np.asarray(directions, dtype=float).reshape(-1, 3)
return v / np.maximum(np.linalg.norm(v, axis=1, keepdims=True), 1e-300)
def _merged(directions: np.ndarray, energy: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
"""Unit ``directions`` (n, 3) and their ``energy`` (n, bands) with the directions
that are one (within ``SAME_DIRECTION`` of another, or joined to it by others that
are) as one: the mean of them, of unit length, with the mean of their energies, in
the order of the first of each."""
from scipy.sparse import coo_matrix
from scipy.sparse.csgraph import connected_components
from scipy.spatial import cKDTree
pairs = cKDTree(directions).query_pairs(SAME_DIRECTION, output_type="ndarray")
if not len(pairs):
return directions, energy
count = len(directions)
graph = coo_matrix((np.ones(len(pairs)), (pairs[:, 0], pairs[:, 1])), shape=(count, count))
_, label = connected_components(graph, directed=False)
_, first, group = np.unique(label, return_index=True, return_inverse=True)
order = np.argsort(first)
rank = np.empty(len(order), dtype=np.int64)
rank[order] = np.arange(len(order))
group = rank[group.ravel()]
size = np.bincount(group)
summed = np.zeros((len(order), energy.shape[1]))
np.add.at(summed, group, energy)
middle = np.zeros((len(order), 3))
np.add.at(middle, group, directions)
middle = _unit(middle)
alone = size == 1
middle[alone] = directions[first[order][alone]]
return middle, summed / size[:, None]
def _from_angles(azimuth_deg, elevation_deg) -> np.ndarray:
az, el = np.broadcast_arrays(
np.radians(np.asarray(azimuth_deg, dtype=float)),
np.radians(np.asarray(elevation_deg, dtype=float)),
)
return np.stack([np.cos(el) * np.cos(az), np.cos(el) * np.sin(az), np.sin(el)], axis=-1)
def _sphere(n: int) -> np.ndarray:
"""``n`` near-uniform directions (a Fibonacci lattice)."""
i = np.arange(n, dtype=float)
z = 1.0 - (2.0 * i + 1.0) / n
r = np.sqrt(np.maximum(0.0, 1.0 - z * z))
phi = math.pi * (3.0 - math.sqrt(5.0)) * i
return np.column_stack([r * np.cos(phi), r * np.sin(phi), z])
[docs]
class Directivity:
"""Energy weights per direction and octave band; see the module docstring."""
#: Short description, for listings and reports.
name: str = ""
#: Octave bands (Hz) without data of their own, copied from the nearest band.
extrapolated: tuple[int, ...] = ()
[docs]
def energy(self, directions) -> np.ndarray:
"""Energy weights (n, bands) for unit vectors (n, 3) in the source's frame;
they average 1 over the sphere in each band."""
raise NotImplementedError
[docs]
def index(self) -> np.ndarray:
"""Directivity index per band (dB): the on-axis level above the average."""
on_axis = self.energy([[1.0, 0.0, 0.0]])[0]
with np.errstate(divide="ignore"):
return 10.0 * np.log10(on_axis)
[docs]
def native(self) -> tuple[np.ndarray, np.ndarray]:
"""What the compiled tracer takes: the first-order ``a`` per band, and a table of
weights on the interpolation grid (elevations x azimuths x bands, empty for
first-order patterns)."""
raise NotImplementedError
[docs]
def in_bands(self, bands: Resolution) -> Directivity:
"""This directivity in octave or third-octave ``bands``: an octave band's
weights for each of its three third octaves, or the mean of three third
octaves' for their octave."""
raise NotImplementedError
@property
def omni(self) -> bool:
return False
[docs]
@dataclass(frozen=True)
class FirstOrder(Directivity):
"""``a + (1 - a) cos(theta)`` patterns, one ``a`` per octave band."""
a: tuple[float, ...]
name: str = ""
extrapolated: tuple[int, ...] = ()
def __post_init__(self) -> None:
if len(self.a) not in _BAND_COUNTS or not all(0.0 <= a <= 1.0 for a in self.a):
raise ValueError(
f"expected {_BANDS} values of a between 0 and 1 (or "
f"{len(THIRD_OCTAVE_BANDS_HZ)} for third-octave bands), got {self.a}"
)
[docs]
@classmethod
def pattern(cls, name: str) -> FirstOrder:
"""The same named pattern in every band."""
return cls((PATTERNS[name],) * _BANDS, name)
[docs]
def energy(self, directions) -> np.ndarray:
a = np.asarray(self.a)
p = a + (1.0 - a) * _unit(directions)[:, :1]
return p**2 / (a**2 + (1.0 - a) ** 2 / 3.0)
[docs]
def native(self) -> tuple[np.ndarray, np.ndarray]:
return np.asarray(self.a, dtype=float), np.zeros((0, 0, len(self.a)))
[docs]
def in_bands(self, bands: Resolution) -> FirstOrder:
if resolution_of(len(self.a)) == bands:
return self
return FirstOrder(tuple(convert(self.a, bands)), self.name, self.extrapolated)
@property
def omni(self) -> bool:
return all(a == 1.0 for a in self.a)
def _cell(shape: tuple[int, ...], directions) -> tuple[np.ndarray, ...]:
"""The cell of the grid of :func:`on_grid` (``shape``: elevations, azimuths) round
each direction: its lower elevation's index, its two azimuths' indices, and how far
across the cell the direction lies in elevation and in azimuth (0 to 1)."""
v = _unit(directions)
n_el, n_az = shape[:2]
el = np.degrees(np.arcsin(np.clip(v[:, 2], -1.0, 1.0)))
az = np.degrees(np.arctan2(v[:, 1], v[:, 0])) % 360.0
fi = (el + 90.0) / (180.0 / (n_el - 1))
fj = az / (360.0 / n_az)
i0 = np.clip(np.floor(fi).astype(int), 0, n_el - 2)
j0 = np.floor(fj).astype(int) % n_az
return i0, j0, (j0 + 1) % n_az, fi - i0, fj - np.floor(fj)
[docs]
def on_grid(table: np.ndarray, directions) -> np.ndarray:
"""(n, ...) the values ``table`` (elevations, azimuths, ...) holds on a grid of
elevations from -90 to 90 degrees and azimuths from 0 up to 360, each evenly spaced,
read bilinearly at unit vectors (n, 3) in the source's frame."""
i0, j0, j1, ti, tj = _cell(table.shape[:2], directions)
shape = (-1,) + (1,) * (table.ndim - 2)
ti, tj = ti.reshape(shape), tj.reshape(shape)
t = table
return (1 - ti) * ((1 - tj) * t[i0, j0] + tj * t[i0, j1]) + ti * (
(1 - tj) * t[i0 + 1, j0] + tj * t[i0 + 1, j1]
)
[docs]
def sphere_mean(table: np.ndarray) -> np.ndarray:
"""(...) the mean over the sphere of what ``table`` holds on the grid of
:func:`on_grid`, read bilinearly as it reads them."""
return on_grid(table, _sphere(8192)).mean(axis=0)
def _grid(step: float) -> tuple[np.ndarray, np.ndarray]:
elevation = np.linspace(-90.0, 90.0, int(round(180.0 / step)) + 1)
azimuth = np.arange(0.0, 360.0, 360.0 / int(round(360.0 / step)))
return elevation, azimuth
[docs]
@dataclass(frozen=True)
class Balloon(Directivity):
"""Measured energy at some directions, interpolated over the sphere.
The measurements are first spread onto a regular grid of elevations and azimuths
(``GRID_STEP_DEG`` apart), each of its points from the measured directions nearest
to it (``from_measurements``), then read off it bilinearly, which the compiled
tracer does the same way. Each band is scaled to average 1 over the sphere.
"""
#: Interpolation grid: energy weights (elevations, azimuths, bands).
table: np.ndarray = field(repr=False)
name: str = ""
extrapolated: tuple[int, ...] = ()
#: A coherent array's elements, for its sound added up element by element near it
#: (``near_field: true``); None reads every weight off the pattern.
near: NearField | None = field(default=None, repr=False, compare=False)
[docs]
@classmethod
def from_measurements(
cls,
directions,
energy,
name: str = "",
extrapolated: tuple[int, ...] = (),
step: float = GRID_STEP_DEG,
) -> Balloon:
"""Interpolate energies (n, bands) measured in the directions of vectors (n, 3).
Directions given more than once (a table's -180 and 180 degrees of azimuth,
its rows at a pole) are one direction, the mean of them, with the mean of
their energies. Each grid point takes the ``NEIGHBOURS`` directions nearest to
it, weighted by the inverse squares of their angles from it. Where several are
as near as the last of those (within ``SAME_DIRECTION``) and not all of them
are among the ``NEIGHBOURS``, none of them is taken, only the nearer ones; or
all of them, if none is nearer. So directions equally near a point are taken
alike, whatever their order in the data and the last digits of their
distances."""
measured = np.asarray(directions, dtype=float).reshape(-1, 3)
energy = np.asarray(energy, dtype=float).reshape(len(measured), -1)
if energy.shape[1] not in _BAND_COUNTS:
raise ValueError(f"expected {_BANDS} bands, got {energy.shape[1]}")
if len(measured) == 0 or not np.all(np.isfinite(energy)) or (energy < 0).any():
raise ValueError("directivity data must be finite, non-negative energies")
# Each direction over its largest component first: its length is then between 1
# and the root of 3, whatever the size of the vector given.
largest = np.abs(measured).max(axis=1, keepdims=True)
if not (np.isfinite(largest) & (largest > 0.0)).all():
raise ValueError("directivity data must have finite directions other than (0, 0, 0)")
measured, energy = _merged(_unit(measured / largest), energy)
elevation, azimuth = _grid(step)
points = _from_angles(azimuth[None, :], elevation[:, None]).reshape(-1, 3)
# The distance between the unit vectors of each grid point and each measured
# direction, (grid, measured), from differences, squares and a root: directions
# equally near a point come out within some 1e-15 of one another, and one the
# point is on within that of 0, far inside SAME_DIRECTION.
chord = np.zeros((len(points), len(measured)))
apart = np.empty_like(chord)
for axis in range(3):
np.subtract.outer(points[:, axis], measured[:, axis], out=apart)
apart *= apart
chord += apart
np.sqrt(chord, out=chord)
k = min(NEIGHBOURS, len(measured))
apart[:] = chord
apart.partition(k - 1, axis=1)
last = apart[:, k - 1].copy()[:, None]
del apart
near = chord <= last + SAME_DIRECTION
nearer = chord < last - SAME_DIRECTION
cut = (near.sum(axis=1) > k) & nearer.any(axis=1)
near[cut] = nearer[cut]
del nearer
point, taken = np.nonzero(near)
del near
angle = 2.0 * np.arcsin(np.minimum(0.5 * chord[point, taken], 1.0))
weight = 1.0 / np.maximum(angle, 1e-9) ** 2
weight /= np.bincount(point, weights=weight, minlength=len(points))[point]
values = np.zeros((len(points), energy.shape[1]))
np.add.at(values, point, weight[:, None] * energy[taken])
table = values.reshape(len(elevation), len(azimuth), energy.shape[1])
return cls.from_table(table, name, extrapolated)
[docs]
@classmethod
def from_table(cls, table, name: str = "", extrapolated: tuple[int, ...] = ()) -> Balloon:
"""Energies on the grid of elevations (-90 to 90 degrees) and azimuths (0 up to
360) that ``table`` (elevations, azimuths, bands) spans, each band scaled to
average 1 over the sphere; silent bands become omnidirectional."""
table = np.asarray(table, dtype=float)
mean = sphere_mean(table)
silent = mean <= 0.0
table = np.where(silent, 1.0, table / np.where(silent, 1.0, mean))
centres = OCTAVE_BANDS_HZ if table.shape[-1] == _BANDS else THIRD_OCTAVE_BANDS_HZ
missing = tuple(f for f, s in zip(centres, silent, strict=True) if s)
return cls(table, name, tuple(sorted(set(extrapolated) | set(missing))))
def _interpolate(self, directions) -> np.ndarray:
return on_grid(self.table, directions)
[docs]
def energy(self, directions) -> np.ndarray:
return self._interpolate(directions)
[docs]
def near_energy(self, points) -> np.ndarray:
"""Energy weights (n, bands) at points (n, 3) in the source's frame: for an
array with ``near``, its elements added up from where each is; otherwise, and
far from the array alike, the pattern's weights towards the points."""
if self.near is None:
return self.energy(points)
weights = self.near.weights(points)
if self.table.shape[-1] == _BANDS:
weights = weights.reshape(len(weights), _BANDS, 3).mean(axis=-1)
return weights
[docs]
def native(self) -> tuple[np.ndarray, np.ndarray]:
return np.ones(self.table.shape[-1]), np.ascontiguousarray(self.table, dtype=float)
[docs]
def in_bands(self, bands: Resolution) -> Balloon:
have = resolution_of(self.table.shape[-1])
if have == bands:
return self
if bands == "third_octave":
table = np.repeat(self.table, 3, axis=-1)
else:
table = self.table.reshape(*self.table.shape[:-1], -1, 3).mean(axis=-1)
return Balloon(table, self.name, self.extrapolated, self.near)
[docs]
@dataclass(frozen=True, eq=False)
class NearField:
"""A coherent array's elements (see :func:`array_directivity`), to add up their
pressures at points near it, each from its own position with its own distance and
direction, rather than read the far-field pattern off one point."""
#: (elements, 3) positions in the source's frame (m).
positions: np.ndarray
#: (elements,) pressure gains, negative where the polarity is inverted.
gains: np.ndarray
#: (elements,) the feed's delays (s), steering included.
delays: np.ndarray
#: (elements, 3, 3) each element's forward, left and up axes as columns.
turns: np.ndarray
#: The elements' own pattern, in third-octave bands.
element: Directivity
speed_of_sound: float
#: (25,) the third-octave bands' edges (Hz).
edges: np.ndarray
#: (24,) one over the pattern's mean energy over the sphere in each third-octave
#: band, which scales it to the weights' average of 1; 0 where the band is silent.
scale: np.ndarray
[docs]
def weights(self, points) -> np.ndarray:
"""Energy weights (n, 24) at points (n, 3) in the source's frame, per
third-octave band, as the pattern's weights are: the elements' energy there,
averaged over each band (of a flat spectrum) exactly, times the squared distance
from the source's position. Far away they become the pattern's."""
points = np.asarray(points, dtype=float).reshape(-1, 3)
reach = np.linalg.norm(points, axis=1)
offsets = points[None] - self.positions[:, None] # (elements, n, 3)
spread = np.maximum(np.linalg.norm(offsets, axis=2), 1e-9)
local = np.einsum("enk,ekj->enj", offsets / spread[..., None], self.turns)
amplitude = _amplitudes(self.element, local) * (self.gains[:, None] / spread)[..., None]
arrival = spread / self.speed_of_sound + self.delays[:, None] # (elements, n)
first_of, second_of = np.triu_indices(len(self.positions))
twice = np.where(first_of == second_of, 1.0, 2.0)[:, None]
# How much sooner one element of each pair is heard than the other (s).
lag = arrival[first_of] - arrival[second_of] # (pairs, n)
still = np.abs(lag) < 1e-15
energy = np.zeros((len(points), len(self.edges) - 1))
below = np.sin(2.0 * math.pi * self.edges[0] * lag)
for b in range(len(self.edges) - 1):
above = np.sin(2.0 * math.pi * self.edges[b + 1] * lag)
span = 2.0 * math.pi * (self.edges[b + 1] - self.edges[b]) * np.where(still, 1.0, lag)
mean_cos = np.where(still, 1.0, (above - below) / span)
pair = amplitude[first_of, :, b] * amplitude[second_of, :, b]
energy[:, b] = np.sum(twice * pair * mean_cos, axis=0)
below = above
weights = energy * (reach**2)[:, None] * self.scale
return np.where(self.scale > 0.0, weights, 1.0)
# -- reading ----------------------------------------------------------------------------
def _octaves(frequencies, energy) -> tuple[np.ndarray, tuple[int, ...]]:
"""Energies (..., frequencies) averaged into octave bands (..., bands); octaves
without data copy the nearest octave that has some."""
freqs = np.asarray(frequencies, dtype=float)
energy = np.asarray(energy, dtype=float)
out = np.full((*energy.shape[:-1], _BANDS), np.nan)
have = np.zeros(_BANDS, dtype=bool)
for k, fc in enumerate(OCTAVE_BANDS_HZ):
inside = (freqs >= fc / math.sqrt(2.0)) & (freqs < fc * math.sqrt(2.0))
if inside.any():
out[..., k] = energy[..., inside].mean(axis=-1)
have[k] = True
known = np.flatnonzero(have)
if len(known) == 0:
raise ValueError("no directivity data between 44 Hz and 11 kHz")
for k in np.flatnonzero(~have):
out[..., k] = out[..., known[np.argmin(np.abs(known - k))]]
return out, tuple(OCTAVE_BANDS_HZ[k] for k in np.flatnonzero(~have))
[docs]
def read_directivity_csv(path: str | Path) -> Balloon:
"""A :class:`Balloon` from a CSV table of levels (see the module docstring)."""
path = Path(path)
header: list[str] | None = None
rows: list[list[float]] = []
with path.open(encoding="utf-8-sig") as fh:
for lineno, line in enumerate(fh, start=1):
line = line.strip()
if not line or line.startswith("#"):
continue
separator = _SEPARATOR if _SEPARATOR.search(line) else _SPACES
tokens = [t.strip() for t in separator.split(line) if t.strip()]
if header is None:
header = tokens
continue
try:
rows.append([float(t) for t in tokens])
except ValueError:
raise ValueError(f"{path}:{lineno}: expected numbers, got {line!r}") from None
if len(rows[-1]) != len(header):
count = len(rows[-1])
raise ValueError(f"{path}:{lineno}: {count} values for {len(header)} columns")
if (
header is None
or len(header) < 3
or [h.lower() for h in header[:2]]
!= [
"azimuth",
"elevation",
]
):
raise ValueError(f"{path}: the header must be azimuth, elevation, then frequencies")
try:
frequencies = [float(h.lower().removesuffix("hz").strip()) for h in header[2:]]
except ValueError:
raise ValueError(f"{path}: band columns must be frequencies in Hz") from None
if not rows:
raise ValueError(f"{path}: no directions")
data = np.asarray(rows)
directions = _from_angles(data[:, 0], data[:, 1])
energy, extrapolated = _octaves(frequencies, 10.0 ** (data[:, 2:] / 10.0))
return Balloon.from_measurements(directions, energy, f"file {path.name}", extrapolated)
[docs]
def write_directivity_csv(path: str | Path, balloon: Balloon, comment: str = "") -> Path:
"""Write ``balloon`` (in octave bands) as the CSV table :func:`read_directivity_csv`
reads back: a row for each direction of its grid with its level in each band (dB
over the sphere's mean), under ``comment``'s lines."""
path = Path(path)
table = balloon.in_bands("octave").table
elevation, azimuth = _grid(180.0 / (table.shape[0] - 1))
levels = 10.0 * np.log10(np.maximum(table, 1e-30))
lines = [f"# {line}".rstrip() for line in comment.splitlines()]
lines.append(", ".join(["azimuth", "elevation", *(f"{f:g}" for f in OCTAVE_BANDS_HZ)]))
for i, el in enumerate(elevation):
for j, az in enumerate(azimuth):
values = ", ".join(f"{v:.2f}" for v in levels[i, j])
lines.append(f"{az:g}, {el:g}, {values}")
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
return path
def _frame(view: np.ndarray, up: np.ndarray) -> np.ndarray:
"""Rotation (3, 3) whose columns are forward, left and up for a view and up vector."""
view = view / np.linalg.norm(view)
up = up - (up @ view) * view
up = up / np.linalg.norm(up)
return np.column_stack([view, np.cross(up, view), up])
def _per_measurement(f, name: str, default, count: int) -> np.ndarray:
"""A SOFA position variable as Cartesian vectors (count, 3), one per measurement."""
from acoustic_spaces.spatial.hrtf import _positions
if name not in f:
return np.broadcast_to(np.asarray(default, dtype=float), (count, 3))
values = _positions(f[name])
return np.broadcast_to(values, (count, 3)) if len(values) == 1 else values[:count]
[docs]
def read_directivity_sofa(path: str | Path, measurement: int | None = None) -> Balloon:
"""A :class:`Balloon` from a SOFA file of source directivities (the
``FreeFieldDirectivityTF`` convention, or impulse responses in ``Data.IR``).
Every receiver of every measurement gives one direction: where it sits relative to
the source, in the source's frame (``SourceView`` and ``SourceUp``). ``measurement``
picks one measurement (an instrument's notes, for example); by default their
energies are averaged. Spectra are averaged in energy over each octave band.
"""
try:
import h5py
except ImportError as exc:
raise ImportError(f"reading SOFA files needs h5py: {install_hint('sofa')}") from exc
from acoustic_spaces.spatial.hrtf import _positions, _text
path = Path(path)
with h5py.File(path, "r") as f:
if "Data.Real" in f:
spectrum = np.asarray(f["Data.Real"][()], dtype=float)
if "Data.Imag" in f:
spectrum = spectrum + 1j * np.asarray(f["Data.Imag"][()], dtype=float)
frequencies = np.asarray(f["N"][()], dtype=float).ravel()
elif "Data.IR" in f:
ir = np.asarray(f["Data.IR"][()], dtype=float)
rate = float(np.asarray(f["Data.SamplingRate"][()]).ravel()[0])
spectrum = np.fft.rfft(ir, axis=-1)
frequencies = np.fft.rfftfreq(ir.shape[-1], 1.0 / rate)
else:
raise ValueError(f"{path}: no Data.Real or Data.IR; not a SOFA directivity file")
if spectrum.ndim != 3 or spectrum.shape[-1] != len(frequencies):
raise ValueError(f"{path}: expected data (measurements, receivers, frequencies)")
m_count, r_count = spectrum.shape[:2]
if measurement is not None and not 0 <= measurement < m_count:
raise ValueError(f"{path}: measurement {measurement} of {m_count}")
receivers = np.zeros((1, r_count, 3))
if "ReceiverPosition" in f:
dataset = f["ReceiverPosition"]
raw = np.asarray(dataset[()], dtype=float)
if raw.ndim == 3: # (R, 3, M): receivers that move between measurements
per_m = [_positions_array(raw[:, :, m], dataset) for m in range(raw.shape[2])]
receivers = np.stack(per_m)
else:
receivers = _positions(dataset).reshape(1, -1, 3)
listener = _per_measurement(f, "ListenerPosition", [0.0, 0.0, 0.0], m_count)
listener_view = _per_measurement(f, "ListenerView", [1.0, 0.0, 0.0], m_count)
listener_up = _per_measurement(f, "ListenerUp", [0.0, 0.0, 1.0], m_count)
source = _per_measurement(f, "SourcePosition", [0.0, 0.0, 0.0], m_count)
source_view = _per_measurement(f, "SourceView", [1.0, 0.0, 0.0], m_count)
source_up = _per_measurement(f, "SourceUp", [0.0, 0.0, 1.0], m_count)
title = _text(f.attrs.get("Title", "")) or path.stem
chosen = range(m_count) if measurement is None else [measurement]
directions, energy = [], []
for m in chosen:
local = receivers[min(m, len(receivers) - 1)]
if len(local) != r_count:
local = np.broadcast_to(local, (r_count, 3))
world = listener[m] + local @ _frame(listener_view[m], listener_up[m]).T
directions.append((world - source[m]) @ _frame(source_view[m], source_up[m]))
energy.append(np.abs(spectrum[m]) ** 2)
directions = np.concatenate(directions)
if (np.linalg.norm(directions, axis=1) < 1e-9).any():
raise ValueError(f"{path}: a receiver sits on the source; no direction to it")
bands, extrapolated = _octaves(frequencies, np.concatenate(energy))
# The same direction in several measurements (notes): average their energies.
keys = np.round(_unit(directions), 6)
unique, inverse = np.unique(keys, axis=0, return_inverse=True)
inverse = inverse.ravel()
summed = np.zeros((len(unique), _BANDS))
np.add.at(summed, inverse, bands)
counts = np.bincount(inverse, minlength=len(unique))[:, None]
return Balloon.from_measurements(unique, summed / counts, f"SOFA {title}", extrapolated)
def _positions_array(values: np.ndarray, dataset) -> np.ndarray:
"""Like ``hrtf._positions`` for an array already read from ``dataset``."""
from acoustic_spaces.spatial.hrtf import _text
kind = _text(dataset.attrs.get("Type", "cartesian")).lower()
if kind != "spherical":
return values.reshape(-1, 3)
units = _text(dataset.attrs.get("Units", "degree")).lower()
az, el, r = values[:, 0], values[:, 1], values[:, 2]
if "degree" not in units:
az, el = np.degrees(az), np.degrees(el)
return _from_angles(az, el) * r[:, None]
[docs]
def read_directivity(
path: str | Path,
measurement: int | None = None,
speed_of_sound: float = SPEED_OF_SOUND,
near_field: bool = False,
) -> Balloon:
"""Measured directivity from a ``.sofa`` file or a CSV table, or an array's from a
YAML file (``.yaml`` or ``.yml``; see :func:`read_array`), with its elements for
``near_field``."""
path = Path(path)
if not path.exists():
raise ValueError(f"directivity file not found: {path}")
if path.suffix.lower() == ".sofa":
return read_directivity_sofa(path, measurement)
if path.suffix.lower() in (".yaml", ".yml"):
return array_directivity(read_array(path), speed_of_sound, near_field)
return read_directivity_csv(path)
[docs]
def read_array(path: str | Path):
"""A coherent array (:class:`~acoustic_spaces.scene.ArraySpec`) from a YAML file
holding its fields; files named in it are found next to it."""
import yaml
from pydantic import ValidationError
from acoustic_spaces.scene.model import ArraySpec, load_yaml
path = Path(path)
try:
data = load_yaml(path.read_text(encoding="utf-8"))
return ArraySpec.model_validate(data, context={"base_dir": path.parent})
except (yaml.YAMLError, ValidationError) as exc:
raise ValueError(f"{path.name}: not an array description: {exc}") from None
[docs]
def directivity_files(spec, _seen: frozenset[Path] = frozenset()) -> list[Path]:
"""The files a source's directivity entry uses: its own file and, for a coherent
array, its element's, whether the array is in the entry or in a YAML file (which
names its element's file relative to itself), and so on down."""
if spec is None or isinstance(spec, str):
return []
if getattr(spec, "file", None) is not None:
return [Path(spec.file), *array_files(spec.file, _seen)]
if getattr(spec, "array", None) is not None:
return directivity_files(spec.array.element, _seen)
return []
[docs]
def array_files(path: str | Path, _seen: frozenset[Path] = frozenset()) -> list[Path]:
"""The files a coherent array's YAML file names for its element, and those they name
in turn; none for other files, or a missing one."""
path = Path(path)
if path.suffix.lower() not in (".yaml", ".yml") or not path.is_file() or path in _seen:
return []
return directivity_files(read_array(path).element, _seen | {path})
def _amplitudes(element: Directivity, local: np.ndarray) -> np.ndarray:
"""Pressure amplitudes (elements, directions, bands) of an element pattern towards
directions in each element's own frame (elements, directions, 3): first-order
patterns with their sign, others by magnitude."""
if isinstance(element, FirstOrder):
a = np.asarray(element.a)
return a + (1.0 - a) * local[..., :1]
flat = element.energy(local.reshape(-1, 3))
return np.sqrt(flat).reshape(*local.shape[:2], -1)
[docs]
def array_directivity(
spec, speed_of_sound: float = SPEED_OF_SOUND, near_field: bool = False
) -> Balloon:
"""The far-field pattern of a coherent array (an
:class:`~acoustic_spaces.scene.ArraySpec`), per third-octave band; with
``near_field``, it also keeps the elements (:class:`NearField`), whose sound the
early paths add up element by element.
The elements' pressures add up with their phases: the path difference towards each
direction, the feed's delays and the steering, the gains and polarities, and each
element's own pattern along its aim (first-order patterns with their sign, measured
ones by magnitude). Energies are exact averages over each band (of a flat spectrum),
on a grid fine enough for the beam (1 to 5 degrees). The pattern holds in the far
field, beyond about the array's length squared over the wavelength.
"""
elements = spec.layout()
c = float(speed_of_sound)
positions = np.array([e.position for e in elements], dtype=float)
gains = np.array([10.0 ** (e.gain_db / 20.0) * (-1 if e.invert else 1) for e in elements])
delays = np.array([e.delay_ms * 1e-3 for e in elements])
if spec.steer_deg:
aim = _from_angles(0.0, spec.steer_deg).reshape(3)
lead = positions @ aim
delays = delays + (lead - lead.min()) / c
turns = np.array([e.orientation.rotation() for e in elements], dtype=float)
element = load_directivity(spec.element).in_bands("third_octave")
length = float(np.max(np.linalg.norm(positions[:, None] - positions[None], axis=2)))
# A grid fine enough for the beam at the top band (a quarter of its width), 1 to 5 deg.
top = THIRD_OCTAVE_BANDS_HZ[-1] * 2 ** (1 / 6)
width = math.degrees(c / top / max(length, 1e-9))
step = next((s for s in (5.0, 2.5, 2.0, 1.0) if s <= width / 4), 1.0)
elevation, azimuth = _grid(step)
directions = _from_angles(azimuth[None, :], elevation[:, None]).reshape(-1, 3)
# Band edges, as the filter banks split the spectrum.
inner = crossover_frequencies("third_octave")
edges = np.concatenate([[inner[0] / 2 ** (1 / 3)], inner, [inner[-1] * 2 ** (1 / 3)]])
first_of, second_of = np.triu_indices(len(elements))
twice = np.where(first_of == second_of, 1.0, 2.0) # each pair of elements counts twice
offsets = positions[first_of] - positions[second_of]
shifts = delays[first_of] - delays[second_of]
alike = bool(np.allclose(turns, turns[0]))
if alike:
# Elements aimed alike share a pattern: pairs the same distance and delay apart
# (a straight column's, say) add up into one term.
key = np.round(np.column_stack([offsets, shifts * c]) * 1e9)
_, first_seen, group = np.unique(key, axis=0, return_index=True, return_inverse=True)
pair_gains = np.bincount(group.ravel(), weights=gains[first_of] * gains[second_of] * twice)
offsets, shifts = offsets[first_seen], shifts[first_seen]
energy = np.zeros((len(directions), len(edges) - 1))
chunk_size = max(64, _ARRAY_CHUNK // len(offsets))
for first in range(0, len(directions), chunk_size):
chunk = directions[first : first + chunk_size]
# Each element's amplitude towards these directions, along its own aim.
amplitude = _amplitudes(
element, np.einsum("dk,nkj->ndj", chunk, turns[:1] if alike else turns)
)
# How much sooner one element of each pair is heard than the other (s).
lag = products.product(chunk, offsets.T) / c - shifts[None, :] # (directions, pairs)
still = np.abs(lag) < 1e-15
# The energy is the sum over pairs of w_i w_k cos(2 pi f lag); its mean over a
# band, exactly: (sin(2 pi f2 lag) - sin(2 pi f1 lag)) / (2 pi (f2 - f1) lag).
below = np.sin(2.0 * math.pi * edges[0] * lag)
for b in range(len(edges) - 1):
above = np.sin(2.0 * math.pi * edges[b + 1] * lag)
span = 2.0 * math.pi * (edges[b + 1] - edges[b]) * np.where(still, 1.0, lag)
mean_cos = np.where(still, 1.0, (above - below) / span)
if alike:
weights = amplitude[0, :, b, None] ** 2 * pair_gains[None, :]
else:
pair = amplitude[first_of, :, b] * amplitude[second_of, :, b]
weights = (pair * (gains[first_of] * gains[second_of] * twice)[:, None]).T
energy[first : first + len(chunk), b] = np.sum(weights * mean_cos, axis=1)
below = above
table = energy.reshape(len(elevation), len(azimuth), -1)
balloon = Balloon.from_table(table, f"array of {len(elements)} elements")
if not near_field:
return balloon
# The mean that from_table scales the pattern by.
mean = Balloon(table)._interpolate(_sphere(8192)).mean(axis=0)
scale = np.where(mean > 0.0, 1.0 / np.where(mean > 0.0, mean, 1.0), 0.0)
near = NearField(positions, gains, delays, turns, element, c, edges, scale)
return Balloon(balloon.table, balloon.name, balloon.extrapolated, near)
[docs]
def lambert() -> Balloon:
"""A vibrating surface's radiation: energy in proportion to the cosine of the angle
to the forward axis, nothing behind (Lambert's law), in every band."""
elevation, azimuth = _grid(GRID_STEP_DEG)
points = _from_angles(azimuth[None, :], elevation[:, None]).reshape(-1, 3)
energy = np.repeat(np.maximum(points[:, :1], 0.0), _BANDS, axis=1)
return Balloon.from_measurements(points, energy, "lambert")
#: The frequency (Hz) at which :func:`far_field_distance` is given in warnings.
FAR_FIELD_HZ = 1000.0
[docs]
def array_length(spec) -> float | None:
"""The largest distance between two elements (m) of the coherent array a source's
directivity entry describes, given in the scene or in a YAML file; None for other
directivities."""
if getattr(spec, "array", None) is not None:
array = spec.array
elif getattr(spec, "file", None) is not None and Path(spec.file).suffix.lower() in (
".yaml",
".yml",
):
array = read_array(spec.file)
else:
return None
positions = np.array([e.position for e in array.layout()], dtype=float)
return float(np.max(np.linalg.norm(positions[:, None] - positions[None], axis=2)))
[docs]
def far_field_distance(
length_m: float, frequency_hz: float = FAR_FIELD_HZ, speed_of_sound: float = SPEED_OF_SOUND
) -> float:
"""From how far (m) an array ``length_m`` long acts as one point with its far-field
pattern at ``frequency_hz``: its length squared over the wavelength. Nearer, its
sound spreads as a line's and its beam has not formed yet."""
return float(length_m) ** 2 * float(frequency_hz) / float(speed_of_sound)
[docs]
def load_directivity(spec, speed_of_sound: float = SPEED_OF_SOUND) -> Directivity:
"""The directivity a scene's source entry describes: a pattern name (or
``lambert``), or an object with ``pattern`` (a name or ``a`` value per band),
``file`` or ``array``; an array's phases take ``speed_of_sound`` (m/s)."""
if spec == "lambert":
return lambert()
if isinstance(spec, str):
return FirstOrder.pattern(spec)
near_field = bool(getattr(spec, "near_field", None))
if getattr(spec, "array", None) is not None:
return array_directivity(spec.array, speed_of_sound, near_field)
if getattr(spec, "file", None) is not None:
return read_directivity(spec.file, spec.measurement, speed_of_sound, near_field)
values = [PATTERNS[v] if isinstance(v, str) else float(v) for v in spec.pattern]
names = [v if isinstance(v, str) else f"a={float(v):g}" for v in spec.pattern]
return FirstOrder(tuple(values), "per band: " + ", ".join(names))
__all__ = [
"FAR_FIELD_HZ",
"GRID_STEP_DEG",
"PATTERNS",
"SPEED_OF_SOUND",
"Balloon",
"Directivity",
"FirstOrder",
"NearField",
"array_directivity",
"array_files",
"array_length",
"directivity_files",
"far_field_distance",
"lambert",
"load_directivity",
"on_grid",
"read_array",
"read_directivity",
"read_directivity_csv",
"read_directivity_sofa",
"sphere_mean",
"write_directivity_csv",
]