Keep only the Rosella and .jochrtf binaural paths

The runtime renders two inputs now: the Rosella .personalized_headphone model and
an already compiled .jochrtf field. SOFA import, the full-HRIR direct renderer
and the SOFA -> .jochrtf fitting compiler leave this checkout; they continue as
an offline tool that only produces caches this repository loads.

The .jochrtf renderer goes back to the implementation that predates the direct
SOFA work: 64-QMF analysis, 77 hybrid bands, per-object hybrid path delays and
the project room (six first-order images plus the shared FDN tail) computed in
code. It is restored verbatim under the .jochrtf vocabulary
(SofaBinauralBackend -> JochrtfBackend) and gains one switch:
--jochrtf-room on|off, off by default. With the room off the renderer outputs
only the field's direct binaural sound, and in either mode it reads no audio
assets.

Because the room is computed in code again, the generated sofa-room*.npz assets
and the modules only the SOFA path used are removed (sofa_canonical, sofa_hrir,
sofa_direct_backend, sofa_room, hybrid_paths, partitioned_convolution,
point_source, compile_hrtf, generate_sofa_room). data/ keeps the decode tables
and the Rosella filterbanks.

The CLI drops --sofa-hrtf, --hrtf-radius-m, --sofa-interpolation,
--hrtf-cache-policy, --hrtf-cache-dir, --sofa-room, --sofa-room-preset and
--source-reference-distance-m. A .jochrtf is still explicit through
--compiled-hrtf-cache, and the default binaural input is the personalized model.

Rosella parsing, filterbank, room and timing are untouched and its output stays
bit-identical. The .jochrtf path reproduces the pre-SOFA renderer sample for
sample, with the room on and with it off.
This commit is contained in:
TheM14 committed 2026-11-01 19:00:40 +08:00
1 parent 3ea285e407
commit 07a26b41fe
21 files changed
+692 -2309

No files matched your search

+8 -60
View File
@@ -1,4 +1,4 @@
"""JOC frame adapter for independent SOFA and compact HRTF rendering."""
"""JOC frame adapter for the compiled .jochrtf renderer."""
from __future__ import annotations
import math
@@ -8,11 +8,6 @@ import numpy as np
from binaural_metadata import OamdPositionTimeline
from public_filterbank import ANALYSIS_SYNTHESIS_LATENCY_SAMPLES
from sofa_hrtf_field import (
DEFAULT_HRTF_CACHE_DIR,
DEFAULT_PROJECTION_RIDGE,
DEFAULT_SH_RIDGE,
)
SAMPLE_RATE = 48000
@@ -24,7 +19,6 @@ SOURCE_CHANNELS = 16
OUTPUT_CHANNELS = 2
PROJECT_DIR = Path(__file__).resolve().parent.parent
DEFAULT_HRTF_DIR = PROJECT_DIR / "HRTF"
DEFAULT_SOFA_HRTF = DEFAULT_HRTF_DIR / "binaural.sofa"
def _resolve_hrtf_file(path: str | Path, suffix: str, label: str) -> Path:
@@ -36,17 +30,12 @@ def _resolve_hrtf_file(path: str | Path, suffix: str, label: str) -> Path:
return target
def resolve_sofa_hrtf(path: str | Path) -> Path:
"""Resolve an explicitly selected public SOFA source."""
return _resolve_hrtf_file(path, ".sofa", "SOFA HRTF")
def resolve_compiled_hrtf_cache(path: str | Path) -> Path:
"""Resolve an explicitly selected JOC compiled HRTF cache."""
return _resolve_hrtf_file(path, ".jochrtf", "compiled HRTF cache")
class SofaBinauralRenderer:
class JochrtfBinauralRenderer:
"""Render interleaved LFE plus fifteen JOC objects to stereo.
The adapter owns frame buffering and sample-timed OAMD updates; the
@@ -103,46 +92,6 @@ class SofaBinauralRenderer:
self.finished = False
self.metadata_block_updates = 0
@classmethod
def from_sofa(
cls, sofa: str | Path, *,
mode: str | None = None,
cache_policy: str | None = None,
cache_dir: str | Path | None = None,
shell_radius_m: float | None = None,
projection_ridge: float = DEFAULT_PROJECTION_RIDGE,
sh_ridge: float = DEFAULT_SH_RIDGE,
object_delay_samples: int = 1473,
tail_seconds: float = 5.0,
output_gain: float = 1.0,
chunk_frames: int = 64,
bed_channels=None,
interpolation: str = "lf_logmag_phase",
reference_distance_m: float | None = None,
sofa_room: bool = False,
room_preset: str | None = None) -> "SofaBinauralRenderer":
from sofa_direct_backend import DirectSofaBackend
if cache_policy not in (None, "none", "memory") or cache_dir is not None:
raise ValueError("SOFA renders full HRIRs; use compile_hrtf.py to export a .jochrtf")
if projection_ridge != DEFAULT_PROJECTION_RIDGE or sh_ridge != DEFAULT_SH_RIDGE:
raise ValueError("full HRIR rendering does not use projection/SH ridge parameters")
source = resolve_sofa_hrtf(sofa)
backend = DirectSofaBackend(
source,
source_count=SOURCE_CHANNELS,
output_gain=output_gain,
mode=mode,
shell_radius_m=shell_radius_m,
method=interpolation,
reference_distance_m=reference_distance_m, sofa_room=sofa_room, room_preset=room_preset)
return cls(
backend,
mode=mode,
object_delay_samples=object_delay_samples,
tail_seconds=tail_seconds,
chunk_frames=chunk_frames,
bed_channels=bed_channels)
@classmethod
def from_compiled_cache(
cls, cache: str | Path, *,
@@ -152,16 +101,15 @@ class SofaBinauralRenderer:
output_gain: float = 1.0,
chunk_frames: int = 64,
bed_channels=None,
reference_distance_m: float | None = None,
sofa_room: bool = False,
room_preset: str | None = None) -> "SofaBinauralRenderer":
from sofa_direct_backend import DirectSofaBackend
room: bool = False) -> "JochrtfBinauralRenderer":
from jochrtf_backend import JochrtfBackend
source = resolve_compiled_hrtf_cache(cache)
backend = DirectSofaBackend(
backend = JochrtfBackend.from_compiled_cache(
source,
source_count=SOURCE_CHANNELS,
compiled=True, output_gain=output_gain, mode=mode,
reference_distance_m=reference_distance_m, sofa_room=sofa_room, room_preset=room_preset)
default_profile=mode or "mid",
output_gain=output_gain,
room=room)
return cls(
backend,
mode=mode,
-26
View File
@@ -1,26 +0,0 @@
"""Explicit offline export of a SOFA source to the compact cache format."""
import argparse
from pathlib import Path
from sofa_canonical import load_simple_free_field_hrir
from sofa_hrtf_field import compile_sofa_hrtf
def main(argv=None):
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("sofa", type=Path)
parser.add_argument("output", type=Path)
parser.add_argument("--radius-m", type=float)
args = parser.parse_args(argv)
if args.output.suffix.lower() != ".jochrtf":
parser.error("output must use .jochrtf")
canonical = load_simple_free_field_hrir(args.sofa, target_sample_rate_hz=48000)
if args.radius_m is None and len(canonical.shells_m) != 1:
parser.error("multi-radius input requires --radius-m")
radius = float(canonical.shells_m[0]) if args.radius_m is None else args.radius_m
field = compile_sofa_hrtf(canonical, shell_radius_m=radius, cache_policy="none")
field.save(args.output)
print(args.output.resolve())
if __name__ == "__main__":
main()
-89
View File
@@ -1,89 +0,0 @@
"""Generate a float64 FIR realization of the existing project room FDN."""
from __future__ import annotations
import argparse
from dataclasses import asdict, replace
import hashlib
import json
from pathlib import Path
import time
import numpy as np
from public_room import LateFdnConfig, SharedUnitaryFdn, ShoeboxRoomConfig
SCHEMA = "sofa-project-room-v1"
DEFAULT_PATH = Path(__file__).resolve().parents[1] / "data" / "sofa-room.npz"
ROOM_PATHS = {"legacy": DEFAULT_PATH, "compact": DEFAULT_PATH.with_name("sofa-room-compact.npz")}
def preset_config(preset):
early, late = ShoeboxRoomConfig(), LateFdnConfig()
provenance = {"preset": preset, "size_time_scale": 1.}
if preset == "compact":
dimensions = np.array([8.5, 11.3, 5.2])
original = np.array(early.dimensions_m)
def volume_over_area(d):
return float(np.prod(d) / (2 * (d[0] * d[1] + d[0] * d[2] + d[1] * d[2])))
scale = volume_over_area(dimensions) / volume_over_area(original)
early = replace(early, dimensions_m=tuple(dimensions), listener_position_m=tuple(dimensions / 2))
late = replace(late, rt60_seconds=late.rt60_seconds * scale,
delay_seconds=tuple(v * scale for v in late.delay_seconds),
allpass_seconds=tuple(v * scale for v in late.allpass_seconds))
provenance.update(size_time_scale=scale,
geometry_reference="Zahorik 2009, Table 1 model 9, L=11.3 W=8.5 H=5.2 m",
geometry_reference_url="https://pmc.ncbi.nlm.nih.gov/articles/PMC2730711/",
scaling="V/S ratio; same effective average wall absorption; original FDN algorithm",
reproduction_scope="geometry only; not a reproduction of the paper's BRIR model")
elif preset != "legacy":
raise ValueError("room preset must be compact or legacy")
return early, late, provenance
def generate(path=None, *, preset="legacy"):
started = time.perf_counter()
early, config, provenance = preset_config(preset)
fdn = SharedUnitaryFdn(config)
length = int(np.ceil(2 * config.rt60_seconds * config.sample_rate_hz))
probe_length = int(np.ceil(config.rt60_seconds * config.sample_rate_hz))
impulse = np.zeros(length + probe_length)
impulse[0] = 1.
response = fdn.process(impulse)
kernel = np.ascontiguousarray(response[:length].T, dtype="<f8")
discarded = float(np.sum(response[length:] ** 2) / np.sum(kernel ** 2))
if discarded > 1e-12:
raise ValueError(f"FDN FIR tail exceeds the -120 dB energy budget: {discarded}")
metadata = dict(schema=SCHEMA, sample_rate_hz=config.sample_rate_hz,
fdn_config=asdict(config), early_config=asdict(early), **provenance,
algorithm=fdn.info(), impulse_samples=length,
discarded_probe_samples=probe_length, discarded_energy_ratio=discarded,
kernel_sha256=hashlib.sha256(kernel.tobytes()).hexdigest(),
source_algorithm_sha256=hashlib.sha256(
Path(__file__).with_name("public_room.py").read_bytes()).hexdigest(),
generation_seconds=time.perf_counter() - started)
path = Path(ROOM_PATHS[preset] if path is None else path).expanduser().resolve()
path.parent.mkdir(parents=True, exist_ok=True)
np.savez_compressed(path, schema=np.array(SCHEMA), sample_rate_hz=np.int64(48000),
late_fir=kernel, metadata_json=np.array(json.dumps(metadata, sort_keys=True)))
print(json.dumps(dict(path=str(path), taps=length, bytes=path.stat().st_size,
preset=preset, dimensions_m=early.dimensions_m, rt60_parameter_s=config.rt60_seconds,
discarded_energy_ratio=discarded,
generation_seconds=metadata["generation_seconds"]), indent=2))
return metadata
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("output", nargs="?", type=Path)
parser.add_argument("--preset", choices=("all", "legacy", "compact"), default="all")
args = parser.parse_args()
if args.preset == "all":
if args.output is not None:
parser.error("a custom output requires --preset legacy or compact")
for name in ROOM_PATHS:
generate(preset=name)
else:
generate(args.output, preset=args.preset)
-121
View File
@@ -1,121 +0,0 @@
"""Stateful direct and reflected paths for compact HRTF fields."""
from __future__ import annotations
from dataclasses import dataclass
import numpy as np
from public_filterbank import HYBRID_BANDS
@dataclass(frozen=True)
class HybridPath:
label: str
delay_slots: np.ndarray # whole-QMF delay per ear, [2]
transfer: np.ndarray # [ear,77], includes gain and residual delay
def __post_init__(self):
slots = np.asarray(self.delay_slots)
if slots.shape == ():
slots = np.repeat(slots, 2)
if slots.shape != (2,) or slots.dtype.kind not in "iu":
raise ValueError("hybrid path delay_slots must contain two integers")
slots = np.asarray(slots, dtype=np.int64)
transfer = np.asarray(self.transfer, dtype=np.complex128)
if transfer.shape != (2, HYBRID_BANDS) or not np.isfinite(transfer).all():
raise ValueError("hybrid path transfer must have finite shape [2,77]")
if np.any(slots < 0):
raise ValueError("hybrid path delay_slots must be non-negative")
slots.setflags(write=False)
transfer.setflags(write=False)
object.__setattr__(self, "delay_slots", slots)
object.__setattr__(self, "transfer", transfer)
class HybridObjectPathRenderer:
"""Per-object hybrid histories and path transitions."""
def __init__(self, source_count: int, *, history_slots: int = 256,
transition_slots: int = 8):
self.source_count = int(source_count)
self.history_slots = int(history_slots)
self.transition_slots = int(transition_slots)
if min(self.source_count, self.history_slots) <= 0 or self.transition_slots < 0:
raise ValueError("invalid hybrid path renderer dimensions")
self.history = np.zeros(
(self.source_count, self.history_slots, HYBRID_BANDS), dtype=np.complex128)
self.position = 0
self.current: list[tuple[HybridPath, ...]] = [tuple() for _ in range(self.source_count)]
self.target: list[tuple[HybridPath, ...] | None] = [None] * self.source_count
self.fade_position = np.zeros(self.source_count, dtype=np.int32)
self.fade_total = np.zeros(self.source_count, dtype=np.int32)
self.processed_slots = 0
def reset(self) -> None:
self.history.fill(0.0)
self.position = 0
self.target = [None] * self.source_count
self.fade_position.fill(0)
self.fade_total.fill(0)
self.processed_slots = 0
def set_paths(self, source: int, paths, *, fade_slots: int | None = None) -> None:
source = int(source)
if not 0 <= source < self.source_count:
raise IndexError(source)
values = tuple(paths)
for path in values:
if np.any(path.delay_slots >= self.history_slots):
raise ValueError(
f"path {path.label!r} needs {path.delay_slots.tolist()} slots, "
f"history capacity is {self.history_slots}")
fade = self.transition_slots if fade_slots is None else int(fade_slots)
if fade < 0:
raise ValueError("path fade must be non-negative")
if self.target[source] is not None:
self.current[source] = self.target[source]
self.target[source] = None
if not self.processed_slots or fade == 0:
self.current[source] = values
self.target[source] = None
self.fade_position[source] = 0
self.fade_total[source] = 0
else:
self.target[source] = values
self.fade_position[source] = 0
self.fade_total[source] = fade
def _render_paths(self, source: int, paths: tuple[HybridPath, ...]) -> np.ndarray:
result = np.zeros((2, HYBRID_BANDS), dtype=np.complex128)
for path in paths:
indices = (self.position - path.delay_slots) % self.history_slots
delayed = self.history[source, indices, :]
result += delayed * path.transfer
return result
def process(self, hybrid) -> np.ndarray:
values = np.asarray(hybrid, dtype=np.complex128)
if values.ndim != 3 or values.shape[1:] != (self.source_count, HYBRID_BANDS):
raise ValueError(
f"hybrid input must have shape [slots,{self.source_count},77]")
if not np.isfinite(values).all():
raise ValueError("hybrid input contains non-finite values")
output = np.zeros((len(values), 2, HYBRID_BANDS), dtype=np.complex128)
for slot in range(len(values)):
self.history[:, self.position, :] = values[slot]
for source in range(self.source_count - 1, -1, -1):
current = self._render_paths(source, self.current[source])
target_paths = self.target[source]
if target_paths is None:
output[slot] += current
continue
target = self._render_paths(source, target_paths)
self.fade_position[source] += 1
amount = min(
1.0, self.fade_position[source] / float(self.fade_total[source]))
output[slot] += current * (1.0 - amount) + target * amount
if self.fade_position[source] >= self.fade_total[source]:
self.current[source] = target_paths
self.target[source] = None
self.fade_position[source] = 0
self.fade_total[source] = 0
self.position = (self.position + 1) % self.history_slots
self.processed_slots += 1
return output
+515
View File
@@ -0,0 +1,515 @@
"""Stateful .jochrtf binaural renderer.
The runtime topology mirrors the existing multi-object binaural path:
64-QMF -> 77 hybrid -> per-object directional transfer -> stereo synthesis.
The HRTF parameter source is a SOFA-derived fifth-order field. Early
reflections and the late room use project-owned behavior.
"""
from __future__ import annotations
from dataclasses import dataclass
import math
from pathlib import Path
import numpy as np
from public_filterbank import (
ANALYSIS_SYNTHESIS_LATENCY_SAMPLES,
HYBRID_BANDS,
QMF_HOP,
PublicAnalysis77,
PublicSynthesis77,
table_info as filterbank_table_info,
)
from public_room import (
LateFdnConfig,
SharedUnitaryFdn,
ShoeboxRoomConfig,
first_order_image_sources,
)
from reference_distance import DistanceState, ReferenceDistanceProfileV1
from sofa_hrtf_field import SofaHrtfField
@dataclass(frozen=True)
class HybridPath:
label: str
delay_slots: np.ndarray # whole-QMF delay per ear, [2]
transfer: np.ndarray # [ear,77], includes residual delay and HRTF delay
def __post_init__(self):
slots = np.asarray(self.delay_slots)
if slots.shape == ():
slots = np.repeat(slots, 2)
if slots.shape != (2,) or slots.dtype.kind not in "iu":
raise ValueError("hybrid path delay_slots must contain two integers")
slots = np.asarray(slots, dtype=np.int64)
transfer = np.asarray(self.transfer, dtype=np.complex128)
if transfer.shape != (2, HYBRID_BANDS) or not np.isfinite(transfer).all():
raise ValueError("hybrid path transfer must have finite shape [2,77]")
if np.any(slots < 0):
raise ValueError("hybrid path delay_slots must be non-negative")
slots.setflags(write=False)
transfer.setflags(write=False)
object.__setattr__(self, "delay_slots", slots)
object.__setattr__(self, "transfer", transfer)
class HybridObjectPathRenderer:
"""Per-object hybrid histories for direct and image-source paths."""
def __init__(self, source_count: int, *, history_slots: int = 256,
transition_slots: int = 8):
self.source_count = int(source_count)
self.history_slots = int(history_slots)
self.transition_slots = int(transition_slots)
if min(self.source_count, self.history_slots) <= 0 or self.transition_slots < 0:
raise ValueError("invalid hybrid path renderer dimensions")
self.history = np.zeros(
(self.source_count, self.history_slots, HYBRID_BANDS), dtype=np.complex128)
self.position = 0
self.current: list[tuple[HybridPath, ...]] = [tuple() for _ in range(self.source_count)]
self.target: list[tuple[HybridPath, ...] | None] = [None] * self.source_count
self.fade_position = np.zeros(self.source_count, dtype=np.int32)
self.fade_total = np.zeros(self.source_count, dtype=np.int32)
self.processed_slots = 0
def reset(self) -> None:
self.history.fill(0.0)
self.position = 0
self.target = [None] * self.source_count
self.fade_position.fill(0)
self.fade_total.fill(0)
self.processed_slots = 0
def set_paths(self, source: int, paths, *, fade_slots: int | None = None) -> None:
source = int(source)
if not 0 <= source < self.source_count:
raise IndexError(source)
values = tuple(paths)
for path in values:
if np.any(path.delay_slots >= self.history_slots):
raise ValueError(
f"path {path.label!r} needs {path.delay_slots.tolist()} slots, "
f"history capacity is {self.history_slots}")
fade = self.transition_slots if fade_slots is None else int(fade_slots)
if fade < 0:
raise ValueError("path fade must be non-negative")
if self.target[source] is not None:
# Normal 512-sample updates complete an 8-slot transition exactly.
# If a caller updates faster, use the previous target as the new
# stable side rather than resetting signal history.
self.current[source] = self.target[source]
self.target[source] = None
if not self.processed_slots or fade == 0:
self.current[source] = values
self.target[source] = None
self.fade_position[source] = 0
self.fade_total[source] = 0
else:
self.target[source] = values
self.fade_position[source] = 0
self.fade_total[source] = fade
def _render_paths(self, source: int, paths: tuple[HybridPath, ...]) -> np.ndarray:
result = np.zeros((2, HYBRID_BANDS), dtype=np.complex128)
for path in paths:
indices = (self.position - path.delay_slots) % self.history_slots
delayed = self.history[source, indices, :]
result += delayed * path.transfer
return result
def process(self, hybrid) -> np.ndarray:
values = np.asarray(hybrid, dtype=np.complex128)
if values.ndim != 3 or values.shape[1:] != (self.source_count, HYBRID_BANDS):
raise ValueError(
f"hybrid input must have shape [slots,{self.source_count},77]")
if not np.isfinite(values).all():
raise ValueError("hybrid input contains non-finite values")
output = np.zeros((len(values), 2, HYBRID_BANDS), dtype=np.complex128)
for slot in range(len(values)):
self.history[:, self.position, :] = values[slot]
for source in range(self.source_count - 1, -1, -1):
current = self._render_paths(source, self.current[source])
target_paths = self.target[source]
if target_paths is None:
output[slot] += current
continue
target = self._render_paths(source, target_paths)
self.fade_position[source] += 1
amount = min(
1.0, self.fade_position[source] / float(self.fade_total[source]))
output[slot] += current * (1.0 - amount) + target * amount
if self.fade_position[source] >= self.fade_total[source]:
self.current[source] = target_paths
self.target[source] = None
self.fade_position[source] = 0
self.fade_total[source] = 0
self.position = (self.position + 1) % self.history_slots
self.processed_slots += 1
return output
class _StereoDelay:
def __init__(self, delay_samples: int):
self.delay_samples = int(delay_samples)
if self.delay_samples < 0:
raise ValueError("delay must be non-negative")
self.state = np.zeros((self.delay_samples, 2), dtype=np.float64)
def reset(self) -> None:
self.state.fill(0.0)
def process(self, values) -> np.ndarray:
source = np.asarray(values, dtype=np.float64)
if source.ndim != 2 or source.shape[1] != 2:
raise ValueError("stereo delay input must have shape [samples,2]")
if self.delay_samples == 0:
return source.copy()
joined = np.concatenate((self.state, source), axis=0)
output = joined[:len(source)].copy()
self.state = joined[len(source):len(source) + self.delay_samples].copy()
return output
class JochrtfBackend:
"""77-band/SH renderer for a compiled .jochrtf field, with the project room."""
def __init__(
self,
field: SofaHrtfField,
*,
source_count: int = 16,
sample_rate_hz: float = 48000.0,
default_profile: str = "mid",
room: bool = True,
room_config: ShoeboxRoomConfig = ShoeboxRoomConfig(),
fdn_config: LateFdnConfig | None = None,
transition_slots: int = 8,
history_slots: int = 256,
output_gain: float = 1.0):
self.source_count = int(source_count)
self.sample_rate_hz = float(sample_rate_hz)
self.default_profile = ReferenceDistanceProfileV1.validate_profile(default_profile)
self.room_enabled = bool(room)
self.enable_early_reflections = self.room_enabled
self.enable_late_room = self.room_enabled
self.room_config = room_config
self.room_config.validate()
self.output_gain = float(output_gain)
if (self.source_count <= 0 or not math.isfinite(self.sample_rate_hz)
or self.sample_rate_hz <= 0.0):
raise ValueError("source_count and sample rate must be positive")
if not math.isfinite(self.output_gain):
raise ValueError("output gain must be finite")
if abs(self.sample_rate_hz - 48000.0) > 1.0e-9:
raise ValueError("the public binaural runtime requires 48 kHz")
if not isinstance(field, SofaHrtfField):
raise TypeError(
"field must be SofaHrtfField; use from_compiled_cache() for a file")
self.field = field
self.hrtf_input_kind = "field"
self.hrtf_input_path: str | None = None
self.cache_policy: str | None = None
if abs(self.field.sample_rate_hz - self.sample_rate_hz) > 1.0e-9:
raise ValueError("HRTF field sample rate does not match the renderer")
self.early_history_slots = int(history_slots)
if self.early_history_slots <= 0:
raise ValueError("history_slots must be positive")
maximum_hrtf_delay = float(np.max(self.field.delay_bounds[:, 1], initial=0.0))
self.maximum_hrtf_delay_samples = maximum_hrtf_delay
self.hrtf_history_slots = int(math.ceil(maximum_hrtf_delay / QMF_HOP))
self.analysis = PublicAnalysis77(self.source_count)
self.paths = HybridObjectPathRenderer(
self.source_count,
history_slots=self.early_history_slots + self.hrtf_history_slots,
transition_slots=transition_slots)
self.synthesis = PublicSynthesis77(2)
actual_fdn_config = fdn_config or LateFdnConfig(sample_rate_hz=self.sample_rate_hz)
if abs(actual_fdn_config.sample_rate_hz - self.sample_rate_hz) > 1.0e-9:
raise ValueError("FDN sample rate does not match the renderer")
self.fdn = SharedUnitaryFdn(actual_fdn_config)
self.late_delay = _StereoDelay(ANALYSIS_SYNTHESIS_LATENCY_SAMPLES)
self.positions = np.zeros((self.source_count, 3), dtype=np.float64)
self.positions[:, 1] = 1.0
self.profiles = [self.default_profile] * self.source_count
self.user_gain = np.ones(self.source_count, dtype=np.float64)
self.special_lfe = np.zeros(self.source_count, dtype=bool)
self.distance_state: list[DistanceState | None] = [None] * self.source_count
self.late_current = np.zeros(self.source_count, dtype=np.float64)
self.late_start = np.zeros(self.source_count, dtype=np.float64)
self.late_target = np.zeros(self.source_count, dtype=np.float64)
self.late_fade_position = np.zeros(self.source_count, dtype=np.int64)
self.late_fade_total = np.zeros(self.source_count, dtype=np.int64)
self.maximum_early_delay_samples = 0.0
self.latency_to_discard = ANALYSIS_SYNTHESIS_LATENCY_SAMPLES
self.processed_input_samples = 0
self.output_samples = 0
self.parameter_updates = 0
self.finished = False
for source in range(self.source_count):
self.set_source(
source, self.positions[source], profile=self.default_profile,
fade=False)
@classmethod
def from_compiled_cache(
cls, cache: str | Path, **renderer_options
) -> "JochrtfBackend":
"""Load an explicitly selected validated JOC compiled HRTF cache."""
path = Path(cache).expanduser().resolve()
field = SofaHrtfField.load(path)
result = cls(field, **renderer_options)
result.hrtf_input_kind = "compiled_cache"
result.hrtf_input_path = str(path)
result.cache_policy = None
return result
def _make_path(self, label: str, direction_adm, path_distance_m: float,
extra_delay_samples: float, amplitude: float) -> HybridPath:
del path_distance_m
evaluation = self.field.evaluate_adm(direction_adm)
extra_delay = float(extra_delay_samples)
if not math.isfinite(extra_delay) or extra_delay < 0.0:
raise ValueError("path delay must be finite and non-negative")
early_delay_slots = int(math.floor(extra_delay / QMF_HOP))
if early_delay_slots >= self.early_history_slots:
raise ValueError(
f"path {label!r} needs {early_delay_slots} early-delay slots, "
f"early history capacity is {self.early_history_slots}")
total_delay = np.asarray(evaluation.delay_samples, dtype=np.float64) + extra_delay
delay_slots = np.floor(total_delay / QMF_HOP).astype(np.int64)
residual = total_delay - delay_slots * QMF_HOP
propagation_phase = np.exp(
-2j * np.pi * self.field.band_center_frequencies_hz[None, :]
* residual[:, None]
/ self.sample_rate_hz)
transfer = np.asarray(
evaluation.aligned_gains * propagation_phase * float(amplitude),
dtype=np.complex128)
return HybridPath(label, delay_slots, transfer)
def _ordinary_paths(self, state: DistanceState, gain: float) -> tuple[HybridPath, ...]:
# Object PCM is programme-normalized. Physical distance controls room
# geometry, while the project profile supplies the direct presentation
# coefficient instead of applying a second free-field 1/r attenuation.
direct_amplitude = gain * ReferenceDistanceProfileV1.direct_level_gain(state)
room_gain = ReferenceDistanceProfileV1.room_calibration_gain(state)
paths = [self._make_path(
"direct", state.direction_adm, state.physical_distance_m, 0.0,
direct_amplitude)]
if self.enable_early_reflections:
reflections = first_order_image_sources(
state.direction_adm, state.physical_distance_m,
self.sample_rate_hz, self.room_config)
for reflection in reflections:
amplitude = (
gain * room_gain * reflection.reflection_gain
* ReferenceDistanceProfileV1.inverse_distance_gain(
self.field.measurement_radius_m,
reflection.path_distance_m))
paths.append(self._make_path(
f"early:{reflection.wall}", reflection.direction_adm,
reflection.path_distance_m, reflection.extra_delay_samples,
amplitude))
self.maximum_early_delay_samples = max(
self.maximum_early_delay_samples,
reflection.extra_delay_samples)
return tuple(paths)
def _lfe_paths(self, gain: float) -> tuple[HybridPath, ...]:
frequency = self.field.band_center_frequencies_hz
lowpass = np.ones(HYBRID_BANDS, dtype=np.float64)
lowpass[frequency >= 180.0] = 0.0
transition = (frequency > 120.0) & (frequency < 180.0)
amount = (frequency[transition] - 120.0) / 60.0
lowpass[transition] = np.cos(0.5 * np.pi * amount) ** 2
transfer = np.repeat(
(gain * lowpass / math.sqrt(2.0))[None, :], 2, axis=0
).astype(np.complex128)
return (HybridPath(
"public_lfe_lowpass", np.zeros(2, dtype=np.int64), transfer),)
def _set_late_target(self, source: int, value: float, fade: bool) -> None:
value = float(value)
fade_samples = (self.paths.transition_slots * QMF_HOP
if fade and self.processed_input_samples else 0)
if fade_samples == 0:
self.late_current[source] = value
self.late_start[source] = value
self.late_target[source] = value
self.late_fade_position[source] = 0
self.late_fade_total[source] = 0
else:
self.late_start[source] = self.late_current[source]
self.late_target[source] = value
self.late_fade_position[source] = 0
self.late_fade_total[source] = fade_samples
def set_source(self, source: int, position_adm, *, profile: str | None = None,
gain: float = 1.0, enabled: bool = True,
special_lfe: bool = False, fade: bool = True) -> None:
if self.finished:
raise RuntimeError("SOFA renderer is finished")
source = int(source)
if not 0 <= source < self.source_count:
raise IndexError(source)
gain = float(gain)
if not math.isfinite(gain):
raise ValueError("source gain must be finite")
effective_gain = gain if enabled else 0.0
name = self.default_profile if profile is None else profile
state = ReferenceDistanceProfileV1.map_adm_position(position_adm, name)
path_set = (self._lfe_paths(effective_gain) if special_lfe
else self._ordinary_paths(state, effective_gain))
self.paths.set_paths(
source, path_set,
fade_slots=(self.paths.transition_slots if fade else 0))
late_send = (0.0 if special_lfe or not self.enable_late_room or not enabled
else effective_gain
* ReferenceDistanceProfileV1.room_calibration_gain(state)
* ReferenceDistanceProfileV1.late_send(state))
self._set_late_target(source, late_send, fade)
self.positions[source] = np.asarray(position_adm, dtype=np.float64)
self.profiles[source] = state.profile
self.user_gain[source] = gain
self.special_lfe[source] = bool(special_lfe)
self.distance_state[source] = state
self.parameter_updates += 1
def _late_send_envelope(self, sample_count: int) -> np.ndarray:
envelope = np.empty((sample_count, self.source_count), dtype=np.float64)
for source in range(self.source_count):
total = int(self.late_fade_total[source])
if total == 0:
envelope[:, source] = self.late_current[source]
continue
start_position = int(self.late_fade_position[source])
position = start_position + np.arange(1, sample_count + 1)
amount = np.clip(position / float(total), 0.0, 1.0)
envelope[:, source] = (
self.late_start[source] * (1.0 - amount)
+ self.late_target[source] * amount)
new_position = start_position + sample_count
if new_position >= total:
self.late_current[source] = self.late_target[source]
self.late_start[source] = self.late_target[source]
self.late_fade_position[source] = 0
self.late_fade_total[source] = 0
else:
self.late_current[source] = float(envelope[-1, source])
self.late_fade_position[source] = new_position
return envelope
def _process(self, sources) -> np.ndarray:
values = np.asarray(sources, dtype=np.float64)
if values.ndim != 2 or values.shape[1] != self.source_count:
raise ValueError(f"sources must have shape [samples,{self.source_count}]")
if len(values) % QMF_HOP:
raise ValueError("SOFA backend input must be divisible by 64 samples")
if not np.isfinite(values).all():
raise ValueError("SOFA backend input contains non-finite values")
hybrid = self.analysis.process(values)
direct_and_early = self.paths.process(hybrid)
direct_pcm = self.synthesis.process(direct_and_early)
if self.enable_late_room:
sends = self._late_send_envelope(len(values))
mono = np.sum(values * sends, axis=1, dtype=np.float64)
late_pcm = self.late_delay.process(self.fdn.process(mono))
else:
# Still advance any pending send fade deterministically.
self._late_send_envelope(len(values))
late_pcm = np.zeros_like(direct_pcm)
mixed = np.asarray((direct_pcm + late_pcm) * self.output_gain, dtype=np.float64)
skip = min(self.latency_to_discard, len(mixed))
self.latency_to_discard -= skip
self.processed_input_samples += len(values)
output = mixed[skip:]
self.output_samples += len(output)
return output
def process(self, sources) -> np.ndarray:
if self.finished:
raise RuntimeError("SOFA renderer is finished")
return self._process(sources)
def finish(self, *, tail_seconds: float | None = None) -> np.ndarray:
if self.finished:
return np.zeros((0, 2), dtype=np.float64)
if tail_seconds is not None and (
not math.isfinite(float(tail_seconds)) or float(tail_seconds) < 0.0):
raise ValueError("tail_seconds must be finite and non-negative")
requested = (self.fdn.tail_samples if tail_seconds is None
else int(math.ceil(float(tail_seconds) * self.sample_rate_hz)))
drain = max(
requested if self.enable_late_room else 0,
int(math.ceil(
self.maximum_hrtf_delay_samples
+ self.maximum_early_delay_samples)) + 2048,
) + ANALYSIS_SYNTHESIS_LATENCY_SAMPLES
drain = int(math.ceil(drain / QMF_HOP) * QMF_HOP)
output = self._process(np.zeros((drain, self.source_count), dtype=np.float64))
self.finished = True
return output
def finish_output_capacity(self, tail_seconds: float | None = None) -> int:
"""Return a conservative bound for one future :meth:`finish` output."""
if tail_seconds is not None and (
not math.isfinite(float(tail_seconds)) or float(tail_seconds) < 0.0):
raise ValueError("tail_seconds must be finite and non-negative")
requested = (self.fdn.tail_samples if tail_seconds is None
else int(math.ceil(float(tail_seconds) * self.sample_rate_hz)))
hrtf_bound = self.hrtf_history_slots * QMF_HOP
early_bound = hrtf_bound + 2048
if self.enable_early_reflections:
early_bound += self.early_history_slots * QMF_HOP
drain = max(requested if self.enable_late_room else 0, early_bound)
drain += ANALYSIS_SYNTHESIS_LATENCY_SAMPLES
return int(math.ceil(drain / QMF_HOP) * QMF_HOP)
def reset(self) -> None:
self.analysis.reset()
self.paths.reset()
self.synthesis.reset()
self.fdn.reset()
self.late_delay.reset()
self.latency_to_discard = ANALYSIS_SYNTHESIS_LATENCY_SAMPLES
self.processed_input_samples = 0
self.output_samples = 0
self.finished = False
for source in range(self.source_count):
self.set_source(
source, self.positions[source], profile=self.profiles[source],
gain=float(self.user_gain[source]),
special_lfe=bool(self.special_lfe[source]), fade=False)
def info(self) -> dict:
return {
"name": "SofaBinauralBackend",
"source_count": self.source_count,
"sample_rate_hz": self.sample_rate_hz,
"precision": "float64/complex128",
"signal_path": (
"public 64-QMF -> public 77-hybrid -> SOFA order-5 real-SH "
"direct/early -> public synthesis + shared unitary FDN"),
"hrtf_input_kind": self.hrtf_input_kind,
"hrtf_input_path": self.hrtf_input_path,
"cache_policy": self.cache_policy,
"latency_compensated_samples": ANALYSIS_SYNTHESIS_LATENCY_SAMPLES,
"enable_early_reflections": self.enable_early_reflections,
"enable_late_room": self.enable_late_room,
"early_history_slots": self.early_history_slots,
"hrtf_history_slots": self.hrtf_history_slots,
"maximum_hrtf_delay_samples": self.maximum_hrtf_delay_samples,
"maximum_early_delay_samples": self.maximum_early_delay_samples,
"parameter_updates": self.parameter_updates,
"processed_input_samples_including_flush": self.processed_input_samples,
"output_samples_before_trim": self.output_samples,
"distance": ReferenceDistanceProfileV1.info(),
"filterbank": filterbank_table_info(),
"field": self.field.info(),
"late_room": self.fdn.info(),
}
-217
View File
@@ -1,217 +0,0 @@
"""Uniform partitioned convolution with float64/complex128 state."""
from __future__ import annotations
import math
import numpy as np
class UniformPartitionedConvolver:
"""Overlap-add FIR convolution with shared input history.
Filter updates crossfade outputs with independent old/new overlap tails.
"""
def __init__(self, filters, *, block_size: int = 128,
max_filter_taps: int | None = None):
values = np.asarray(filters, dtype=np.float64)
if values.ndim == 1:
values = values[None, :]
if values.ndim != 2 or values.shape[0] <= 0 or values.shape[1] <= 0:
raise ValueError("filters must have shape [outputs,taps]")
if not np.isfinite(values).all():
raise ValueError("filters must be finite")
self.block_size = int(block_size)
if self.block_size <= 0:
raise ValueError("block_size must be positive")
self.fft_size = 2 * self.block_size
self.frequency_bins = self.block_size + 1
self.outputs = int(values.shape[0])
self.max_filter_taps = int(max_filter_taps or values.shape[1])
if self.max_filter_taps < values.shape[1]:
raise ValueError("max_filter_taps is shorter than the initial filter")
self.partition_count = int(math.ceil(self.max_filter_taps / self.block_size))
self.input_history = np.zeros(
(self.partition_count, self.frequency_bins), dtype=np.complex128)
self.write_index = -1
self.processed_blocks = 0
self.current_spectra = self._partition(values)
self.current_overlap = np.zeros(
(self.outputs, self.block_size), dtype=np.float64)
self.target_spectra: np.ndarray | None = None
self.target_overlap: np.ndarray | None = None
self.fade_samples = 0
self.fade_position = 0
@property
def transition_active(self) -> bool:
return self.target_spectra is not None
def _partition(self, filters) -> np.ndarray:
values = np.asarray(filters, dtype=np.float64)
if values.ndim == 1:
values = values[None, :]
if values.shape[0] != self.outputs or values.shape[1] > self.max_filter_taps:
raise ValueError(
f"filter update must have shape [{self.outputs}, <= {self.max_filter_taps}]")
if not np.isfinite(values).all():
raise ValueError("filter update contains non-finite values")
padded = np.zeros(
(self.outputs, self.partition_count, self.fft_size), dtype=np.float64)
for partition in range(self.partition_count):
start = partition * self.block_size
stop = min(start + self.block_size, values.shape[1])
if stop > start:
padded[:, partition, :stop - start] = values[:, start:stop]
return np.asarray(np.fft.rfft(padded, axis=-1), dtype=np.complex128)
def _ordered_input_history(self) -> np.ndarray:
if self.write_index < 0:
return np.zeros_like(self.input_history)
indices = (self.write_index - np.arange(self.partition_count)) % self.partition_count
return self.input_history[indices]
def _convolution_block(self, spectra: np.ndarray,
overlap: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
ordered = self._ordered_input_history()
frequency = np.einsum(
"pf,opf->of", ordered, spectra, dtype=np.complex128, optimize=False)
time = np.asarray(np.fft.irfft(frequency, self.fft_size, axis=-1),
dtype=np.float64)
output = time[:, :self.block_size] + overlap
return output, time[:, self.block_size:].copy()
def _overlap_for_previous_block(self, spectra: np.ndarray) -> np.ndarray:
if self.processed_blocks == 0:
return np.zeros((self.outputs, self.block_size), dtype=np.float64)
ordered = self._ordered_input_history()
frequency = np.einsum(
"pf,opf->of", ordered, spectra, dtype=np.complex128, optimize=False)
time = np.asarray(np.fft.irfft(frequency, self.fft_size, axis=-1),
dtype=np.float64)
return time[:, self.block_size:].copy()
def set_filter(self, filters, *, fade_blocks: int = 0) -> None:
if self.transition_active:
raise RuntimeError("finish the current filter crossfade before another update")
target = self._partition(filters)
fade_blocks = int(fade_blocks)
if fade_blocks < 0:
raise ValueError("fade_blocks must be non-negative")
if fade_blocks == 0:
self.current_spectra = target
self.current_overlap = self._overlap_for_previous_block(target)
return
self.target_spectra = target
self.target_overlap = self._overlap_for_previous_block(target)
self.fade_samples = fade_blocks * self.block_size
self.fade_position = 0
def process_block(self, samples) -> np.ndarray:
values = np.asarray(samples, dtype=np.float64)
if values.shape != (self.block_size,) or not np.isfinite(values).all():
raise ValueError(f"samples must have finite shape ({self.block_size},)")
padded = np.zeros(self.fft_size, dtype=np.float64)
padded[:self.block_size] = values
spectrum = np.asarray(np.fft.rfft(padded), dtype=np.complex128)
self.write_index = (self.write_index + 1) % self.partition_count
self.input_history[self.write_index] = spectrum
current, next_current_overlap = self._convolution_block(
self.current_spectra, self.current_overlap)
if not self.transition_active:
self.current_overlap = next_current_overlap
self.processed_blocks += 1
return current.T.copy()
target, next_target_overlap = self._convolution_block(
self.target_spectra, self.target_overlap)
sample_indices = self.fade_position + np.arange(
1, self.block_size + 1, dtype=np.float64)
amount = np.clip(sample_indices / float(self.fade_samples), 0.0, 1.0)
output = current * (1.0 - amount[None, :]) + target * amount[None, :]
self.fade_position += self.block_size
self.current_overlap = next_current_overlap
self.target_overlap = next_target_overlap
if self.fade_position >= self.fade_samples:
self.current_spectra = self.target_spectra
self.current_overlap = self.target_overlap
self.target_spectra = None
self.target_overlap = None
self.fade_samples = 0
self.fade_position = 0
self.processed_blocks += 1
return output.T.copy()
def reset(self) -> None:
self.input_history.fill(0.0)
self.current_overlap.fill(0.0)
if self.target_overlap is not None:
self.target_overlap.fill(0.0)
self.write_index = -1
self.processed_blocks = 0
self.target_spectra = None
self.target_overlap = None
self.fade_samples = 0
self.fade_position = 0
class MultiSourcePartitionedConvolver:
"""Sum independent per-source convolution outputs."""
def __init__(self, source_count: int, *, block_size: int,
max_filter_taps: int, output_channels: int = 2):
self.source_count = int(source_count)
self.block_size = int(block_size)
self.output_channels = int(output_channels)
if min(self.source_count, self.block_size, self.output_channels,
int(max_filter_taps)) <= 0:
raise ValueError("source_count, block_size, outputs and taps must be positive")
zero = np.zeros((self.output_channels, int(max_filter_taps)), dtype=np.float64)
self.convolvers = [
UniformPartitionedConvolver(
zero, block_size=self.block_size, max_filter_taps=max_filter_taps)
for _ in range(self.source_count)
]
def set_filter(self, source: int, filters, *, fade_blocks: int = 0) -> None:
source = int(source)
if not 0 <= source < self.source_count:
raise IndexError(source)
self.convolvers[source].set_filter(filters, fade_blocks=fade_blocks)
def process_block(self, sources) -> np.ndarray:
values = np.asarray(sources, dtype=np.float64)
if values.shape != (self.block_size, self.source_count):
raise ValueError(
f"sources must have shape ({self.block_size},{self.source_count})")
if not np.isfinite(values).all():
raise ValueError("sources contain non-finite values")
output = np.zeros((self.block_size, self.output_channels), dtype=np.float64)
for source in range(self.source_count):
output += self.convolvers[source].process_block(values[:, source])
return output
def process(self, sources) -> np.ndarray:
values = np.asarray(sources, dtype=np.float64)
if values.ndim != 2 or values.shape[1] != self.source_count:
raise ValueError(f"sources must have shape [samples,{self.source_count}]")
if len(values) % self.block_size:
raise ValueError("partitioned input length must be divisible by block_size")
blocks = [
self.process_block(values[start:start + self.block_size])
for start in range(0, len(values), self.block_size)
]
return (np.concatenate(blocks, axis=0) if blocks
else np.zeros((0, self.output_channels), dtype=np.float64))
def flush(self, blocks: int | None = None) -> np.ndarray:
count = (max(conv.partition_count for conv in self.convolvers) + 2
if blocks is None else int(blocks))
if count < 0:
raise ValueError("flush block count must be non-negative")
zero = np.zeros((self.block_size, self.source_count), dtype=np.float64)
return self.process(np.tile(zero, (count, 1)))
def reset(self) -> None:
for convolver in self.convolvers:
convolver.reset()
-49
View File
@@ -1,49 +0,0 @@
"""Listener-centred point-source coordinates for direct HRTF rendering."""
from __future__ import annotations
from dataclasses import dataclass
import math
import numpy as np
from reference_distance import ReferenceDistanceProfileV1
@dataclass(frozen=True)
class PointSourcePosition:
direction: np.ndarray
distance_m: float
normalized_radius: float
class PointSourceReference:
def __init__(self, reference_distance_m=None, *, mode=None):
self.mode = ReferenceDistanceProfileV1.validate_profile("mid" if mode is None else mode)
self.reference_distance_m = float(ReferenceDistanceProfileV1.DISTANCE_M[self.mode]
if reference_distance_m is None else reference_distance_m)
if not math.isfinite(self.reference_distance_m) or self.reference_distance_m <= 0:
raise ValueError("source reference distance must be finite and positive")
def map_position(self, position, *, previous_direction=None):
values = np.asarray(position, dtype=np.float64)
if values.shape != (3,) or not np.isfinite(values).all():
raise ValueError("source position must contain three finite values")
if np.max(np.abs(values)) > 50.1 + 1e-8:
raise ValueError("source position exceeds the finite metadata domain")
radius = float(np.linalg.norm(values))
direction = values[[1, 0, 2]] * [1., -1., 1.]
if radius > 1e-12:
direction /= radius
elif previous_direction is None:
direction = np.array([1., 0., 0.])
else:
direction = np.asarray(previous_direction, dtype=np.float64).copy()
return PointSourcePosition(direction, radius * self.reference_distance_m, radius)
def info(self):
return dict(reference_variant="direct-point-source-v1",
reference_distance_m=self.reference_distance_m,
mode=self.mode, profile_distances_m=dict(ReferenceDistanceProfileV1.DISTANCE_M),
distance_semantics="nominal-object-coordinate-scale",
distance_attenuation="none; preserve authored programme gain",
radial_adaptation="none; retain selected SOFA measurement shell",
coincident_source_direction="previous direction, otherwise front",
additional_absolute_propagation_delay=False)
-637
View File
@@ -1,637 +0,0 @@
"""Strict SimpleFreeFieldHRIR to canonical HRTF import.
The canonical representation keeps ``Data.IR`` and ``Data.Delay`` separate.
No importer operation silently bakes the SOFA delay into the stored FIRs. A
caller must explicitly request :meth:`CanonicalHrtf.materialized_measurement`
when a time-domain FIR with ``Data.Delay`` applied exactly once is required.
"""
from __future__ import annotations
from contextlib import contextmanager
from dataclasses import dataclass, replace
from fractions import Fraction
import hashlib
import math
from pathlib import Path
from typing import Any
import h5py
import numpy as np
from scipy import signal
from scipy.fft import next_fast_len
_SUPPORTED_VERSIONS = {"0.4", "1.0", "1.1"}
_FREE_FIELD_ROOM_TYPES = {"free field", "free-field", "anechoic", "hemi-anechoic"}
_LENGTH_UNITS = {
"m": 1.0,
"metre": 1.0,
"metres": 1.0,
"meter": 1.0,
"meters": 1.0,
"cm": 1.0e-2,
"centimetre": 1.0e-2,
"centimetres": 1.0e-2,
"centimeter": 1.0e-2,
"centimeters": 1.0e-2,
"mm": 1.0e-3,
"millimetre": 1.0e-3,
"millimetres": 1.0e-3,
"millimeter": 1.0e-3,
"millimeters": 1.0e-3,
}
_ANGLE_UNITS = {
"degree": np.deg2rad,
"degrees": np.deg2rad,
"radian": lambda value: np.asarray(value, dtype=np.float64),
"radians": lambda value: np.asarray(value, dtype=np.float64),
}
class SofaImportError(ValueError):
"""The file is outside the deliberately narrow public SOFA contract."""
def _text(value: Any) -> str:
if isinstance(value, np.ndarray) and value.shape == ():
value = value.item()
if isinstance(value, (bytes, np.bytes_)):
return value.decode("utf-8", "strict")
return str(value)
def _sha256_stream(stream) -> str:
digest = hashlib.sha256()
stream.seek(0)
for block in iter(lambda: stream.read(4 << 20), b""):
digest.update(block)
stream.seek(0)
return digest.hexdigest().upper()
@contextmanager
def _stable_hdf5_source(path: Path):
"""Read arrays and content identity from one stable open-file snapshot."""
with path.open("rb") as stream:
before = _sha256_stream(stream)
with h5py.File(stream, "r") as file:
yield file, before
after = _sha256_stream(stream)
if after != before:
raise SofaImportError("SOFA file changed while it was being imported")
def _tokens(units: str) -> list[str]:
return [token.strip().lower() for token in units.split(",") if token.strip()]
def _coordinate_attributes(dataset: h5py.Dataset, *, inherit=None) -> tuple[str, str]:
source = dataset.attrs
if "Type" not in source or "Units" not in source:
if inherit is None or "Type" not in inherit.attrs or "Units" not in inherit.attrs:
raise SofaImportError(f"{dataset.name} must declare Type and Units")
source = inherit.attrs
return _text(source["Type"]).strip().lower(), _text(source["Units"]).strip()
def coordinates_to_cartesian_m(values, coordinate_type: str, units: str,
*, variable: str) -> np.ndarray:
"""Convert a SOFA coordinate array to Cartesian metres without reshaping it."""
data = np.asarray(values, dtype=np.float64)
if data.shape[-1] != 3 or not np.isfinite(data).all():
raise SofaImportError(f"{variable} must contain finite C=3 coordinates")
kind = coordinate_type.strip().lower()
unit_tokens = _tokens(units)
if kind == "cartesian":
if len(unit_tokens) == 1:
factors = [_LENGTH_UNITS.get(unit_tokens[0])] * 3
elif len(unit_tokens) == 3:
factors = [_LENGTH_UNITS.get(token) for token in unit_tokens]
else:
factors = []
if len(factors) != 3 or any(value is None for value in factors):
raise SofaImportError(f"unsupported Cartesian units for {variable}: {units!r}")
return data * np.asarray(factors, dtype=np.float64)
if kind != "spherical" or len(unit_tokens) != 3:
raise SofaImportError(
f"unsupported coordinates for {variable}: Type={coordinate_type!r}, Units={units!r}")
if unit_tokens[0] not in _ANGLE_UNITS or unit_tokens[1] not in _ANGLE_UNITS:
raise SofaImportError(f"unsupported spherical angle units for {variable}: {units!r}")
radius_factor = _LENGTH_UNITS.get(unit_tokens[2])
if radius_factor is None:
raise SofaImportError(f"unsupported spherical radius unit for {variable}: {units!r}")
azimuth = _ANGLE_UNITS[unit_tokens[0]](data[..., 0])
elevation = _ANGLE_UNITS[unit_tokens[1]](data[..., 1])
radius = data[..., 2] * radius_factor
if np.any(radius < 0.0):
raise SofaImportError(f"{variable} contains a negative spherical radius")
horizontal = np.cos(elevation)
return np.stack(
(radius * horizontal * np.cos(azimuth),
radius * horizontal * np.sin(azimuth),
radius * np.sin(elevation)),
axis=-1,
).astype(np.float64, copy=False)
def _rows(file: h5py.File, name: str, measurements: int, *, inherit=None) -> np.ndarray:
if name not in file:
raise SofaImportError(f"missing required SOFA variable {name}")
dataset = file[name]
kind, units = _coordinate_attributes(dataset, inherit=inherit)
result = coordinates_to_cartesian_m(dataset[...], kind, units, variable=name)
if result.shape not in ((1, 3), (measurements, 3)):
raise SofaImportError(
f"{name} must have shape [I,C] or [M,C], got {result.shape}")
return np.broadcast_to(result, (measurements, 3)).astype(np.float64, copy=True)
def _receiver_rows(file: h5py.File, measurements: int) -> np.ndarray:
if "ReceiverPosition" not in file:
raise SofaImportError("missing required SOFA variable ReceiverPosition")
dataset = file["ReceiverPosition"]
raw = np.asarray(dataset[...], dtype=np.float64)
if raw.shape not in ((2, 3, 1), (2, 3, measurements)):
raise SofaImportError(
"ReceiverPosition must have shape [R=2,C=3,I=1 or M]")
values = np.moveaxis(raw, 1, -1) # [R,I/M,C]
kind, units = _coordinate_attributes(dataset)
cartesian = coordinates_to_cartesian_m(
values, kind, units, variable="ReceiverPosition")
cartesian = np.moveaxis(cartesian, 0, 1) # [I/M,R,C]
return np.broadcast_to(cartesian, (measurements, 2, 3)).astype(
np.float64, copy=True)
def _emitter_is_origin(file: h5py.File, measurements: int) -> None:
if "EmitterPosition" not in file:
raise SofaImportError("missing required SOFA variable EmitterPosition")
dataset = file["EmitterPosition"]
raw = np.asarray(dataset[...], dtype=np.float64)
if raw.shape not in ((1, 3, 1), (1, 3, measurements)):
raise SofaImportError("SimpleFreeFieldHRIR v1 requires E=1 EmitterPosition[E,C,I/M]")
values = np.moveaxis(raw, 1, -1)
kind, units = _coordinate_attributes(dataset)
cartesian = coordinates_to_cartesian_m(
values, kind, units, variable="EmitterPosition")
if np.max(np.abs(cartesian), initial=0.0) > 1.0e-9:
raise SofaImportError("non-zero EmitterPosition needs a separate source-pose adapter")
def _sampling_rate(file: h5py.File) -> float:
if "Data.SamplingRate" not in file:
raise SofaImportError("missing Data.SamplingRate")
dataset = file["Data.SamplingRate"]
values = np.asarray(dataset[...], dtype=np.float64).reshape(-1)
if values.size != 1 or not math.isfinite(float(values[0])) or values[0] <= 0.0:
raise SofaImportError("Data.SamplingRate must contain one positive finite value")
units = _text(dataset.attrs.get("Units", "")).strip().lower()
if units not in {"hertz", "hz"}:
raise SofaImportError(f"Data.SamplingRate Units must be hertz, got {units!r}")
return float(values[0])
def _processing_label(file: h5py.File) -> str:
parts = []
for key in ("DatabaseName", "Title", "ListenerShortName", "Comment"):
value = _text(file.attrs.get(key, "")).strip()
if value and value not in parts:
parts.append(value)
return " | ".join(parts)
def _read_delay(file: h5py.File, measurements: int) -> np.ndarray:
if "Data.Delay" not in file:
raise SofaImportError("missing Data.Delay")
delay = np.asarray(file["Data.Delay"][...], dtype=np.float64)
if delay.shape not in ((1, 2), (measurements, 2)) or not np.isfinite(delay).all():
raise SofaImportError("Data.Delay must have finite shape [I=1,R=2] or [M,R=2]")
delay = np.broadcast_to(delay, (measurements, 2)).astype(np.float64, copy=True)
if np.min(delay, initial=0.0) < -1.0e-9:
raise SofaImportError("negative Data.Delay is outside the supported causal contract")
delay[delay < 0.0] = 0.0
return delay
def _readonly(array, dtype) -> np.ndarray:
result = np.asarray(array, dtype=dtype)
result.setflags(write=False)
return result
@dataclass(frozen=True)
class CanonicalHrtf:
source_path: str
source_sha256: str
convention: str
convention_version: str
sofa_version: str
source_sample_rate_hz: float
sample_rate_hz: float
source_position_cartesian_m: np.ndarray # listener-local [M,3]
listener_view: np.ndarray # world, normalized [M,3]
listener_up: np.ndarray # world, orthonormal [M,3]
receiver_position_cartesian_m: np.ndarray # listener-local, L/R [M,2,3]
left_receiver_index: int
right_receiver_index: int
hrir: np.ndarray # canonical L/R [M,2,N]
delay_samples: np.ndarray # canonical L/R [M,2], not applied
measurement_radius_m: np.ndarray # [M]
processing_label: str
resampling_label: str = "none"
def __post_init__(self):
object.__setattr__(self, "source_position_cartesian_m", _readonly(
self.source_position_cartesian_m, np.float64))
object.__setattr__(self, "listener_view", _readonly(self.listener_view, np.float64))
object.__setattr__(self, "listener_up", _readonly(self.listener_up, np.float64))
object.__setattr__(self, "receiver_position_cartesian_m", _readonly(
self.receiver_position_cartesian_m, np.float64))
object.__setattr__(self, "hrir", _readonly(self.hrir, np.float64))
object.__setattr__(self, "delay_samples", _readonly(self.delay_samples, np.float64))
object.__setattr__(self, "measurement_radius_m", _readonly(
self.measurement_radius_m, np.float64))
@property
def measurements(self) -> int:
return int(self.hrir.shape[0])
@property
def taps(self) -> int:
return int(self.hrir.shape[2])
@property
def unit_directions(self) -> np.ndarray:
return self.source_position_cartesian_m / self.measurement_radius_m[:, None]
@property
def shells_m(self) -> np.ndarray:
return np.unique(np.round(self.measurement_radius_m, 9))
def shell_indices(self, radius_m: float) -> np.ndarray:
shell = float(self.shells_m[np.argmin(np.abs(self.shells_m - float(radius_m)))])
return np.flatnonzero(np.isclose(
self.measurement_radius_m, shell, atol=5.0e-7, rtol=0.0))
def nearest_index(self, direction_sofa, radius_m: float = 1.0) -> tuple[int, float]:
direction = np.asarray(direction_sofa, dtype=np.float64)
if direction.shape != (3,) or not np.isfinite(direction).all():
raise ValueError("direction must contain three finite SOFA Cartesian values")
norm = float(np.linalg.norm(direction))
if norm <= 1.0e-15:
raise ValueError("direction must be non-zero")
direction = direction / norm
indices = self.shell_indices(radius_m)
dots = self.unit_directions[indices] @ direction
local = int(np.argmax(dots))
error = math.degrees(math.acos(float(np.clip(dots[local], -1.0, 1.0))))
return int(indices[local]), float(error)
def resampled(self, target_sample_rate_hz: float) -> "CanonicalHrtf":
target = float(target_sample_rate_hz)
if not math.isfinite(target) or target <= 0.0:
raise ValueError("target sample rate must be positive and finite")
if abs(target - self.sample_rate_hz) <= 1.0e-9:
return self
ratio = target / self.sample_rate_hz
fraction = Fraction(ratio).limit_denominator(100000)
if abs(float(fraction) - ratio) > 1.0e-10:
raise ValueError("sample-rate ratio cannot be represented safely")
converted = signal.resample_poly(
np.asarray(self.hrir, dtype=np.float64), fraction.numerator,
fraction.denominator, axis=-1, window=("kaiser", 8.6), padtype="constant")
converted = np.asarray(converted, dtype=np.float64)
return replace(
self,
sample_rate_hz=target,
hrir=converted,
delay_samples=np.asarray(self.delay_samples * ratio, dtype=np.float64),
resampling_label=(
f"scipy.signal.resample_poly {self.sample_rate_hz:g}->{target:g} Hz "
f"({fraction.numerator}/{fraction.denominator}, Kaiser beta=8.6)"),
)
def materialized_measurement(self, index: int, *, fractional_half_length: int = 48
) -> np.ndarray:
"""Return [L/R,taps] with SOFA Data.Delay applied exactly once."""
index = int(index)
if not 0 <= index < self.measurements:
raise IndexError(index)
ears = []
for ear in range(2):
ears.append(apply_fractional_delay(
self.hrir[index, ear], float(self.delay_samples[index, ear]),
half_length=fractional_half_length))
length = max(map(len, ears))
result = np.zeros((2, length), dtype=np.float64)
for ear, value in enumerate(ears):
result[ear, :len(value)] = value
return result
def info(self) -> dict:
return {
"source_path": self.source_path,
"source_sha256": self.source_sha256,
"convention": self.convention,
"convention_version": self.convention_version,
"sofa_version": self.sofa_version,
"source_sample_rate_hz": self.source_sample_rate_hz,
"sample_rate_hz": self.sample_rate_hz,
"measurements": self.measurements,
"taps": self.taps,
"shells_m": [float(value) for value in self.shells_m],
"source_receiver_order": [self.left_receiver_index, self.right_receiver_index],
"canonical_ear_order": ["left", "right"],
"data_delay_samples_min": float(np.min(self.delay_samples)),
"data_delay_samples_max": float(np.max(self.delay_samples)),
"data_delay_applied": False,
"processing_label": self.processing_label,
"resampling": self.resampling_label,
"precision": "float64",
}
def load_simple_free_field_hrir(path, *, target_sample_rate_hz: float | None = None
) -> CanonicalHrtf:
"""Strictly import the supported SimpleFreeFieldHRIR subset."""
source = Path(path).expanduser().resolve()
if not source.is_file():
raise FileNotFoundError(source)
with _stable_hdf5_source(source) as (file, source_sha256):
if _text(file.attrs.get("Conventions", "")) != "SOFA":
raise SofaImportError("Conventions must be SOFA")
convention = _text(file.attrs.get("SOFAConventions", ""))
if convention != "SimpleFreeFieldHRIR":
raise SofaImportError(
f"unsupported SOFAConventions={convention!r}; convert explicitly first")
convention_version = _text(file.attrs.get("SOFAConventionsVersion", ""))
if convention_version not in _SUPPORTED_VERSIONS:
raise SofaImportError(
f"unsupported SimpleFreeFieldHRIR version {convention_version!r}; "
f"supported={sorted(_SUPPORTED_VERSIONS)}")
if _text(file.attrs.get("DataType", "")) != "FIR":
raise SofaImportError("DataType must be FIR")
room_type = _text(file.attrs.get("RoomType", "")).strip().lower()
if room_type not in _FREE_FIELD_ROOM_TYPES:
raise SofaImportError(f"RoomType must explicitly be free-field, got {room_type!r}")
if "Data.IR" not in file:
raise SofaImportError("missing Data.IR")
hrir_source = np.asarray(file["Data.IR"][...], dtype=np.float64)
if hrir_source.ndim != 3 or hrir_source.shape[1] != 2 or min(hrir_source.shape) <= 0:
raise SofaImportError("Data.IR must have shape [M,R=2,N]")
if not np.isfinite(hrir_source).all():
raise SofaImportError("Data.IR contains non-finite values")
measurements = int(hrir_source.shape[0])
sample_rate = _sampling_rate(file)
delay_source = _read_delay(file, measurements)
_emitter_is_origin(file, measurements)
listener_position = _rows(file, "ListenerPosition", measurements)
listener_view = _rows(file, "ListenerView", measurements)
listener_up_raw = _rows(
file, "ListenerUp", measurements,
inherit=file["ListenerView"] if "ListenerView" in file else None)
forward_norm = np.linalg.norm(listener_view, axis=1)
if np.any(forward_norm <= 1.0e-12):
raise SofaImportError("ListenerView must be non-zero")
forward = listener_view / forward_norm[:, None]
left = np.cross(listener_up_raw, forward)
left_norm = np.linalg.norm(left, axis=1)
if np.any(left_norm <= 1.0e-12):
raise SofaImportError("ListenerUp must not be parallel to ListenerView")
left /= left_norm[:, None]
up = np.cross(forward, left)
if "SourcePosition" not in file:
raise SofaImportError("missing required SOFA variable SourcePosition")
source_dataset = file["SourcePosition"]
source_type, source_units = _coordinate_attributes(source_dataset)
source_world = coordinates_to_cartesian_m(
source_dataset[...], source_type, source_units, variable="SourcePosition")
if source_world.shape != (measurements, 3):
raise SofaImportError("SourcePosition must have shape [M,C=3]")
relative = source_world - listener_position
source_local = np.stack(
(np.sum(relative * forward, axis=1),
np.sum(relative * left, axis=1),
np.sum(relative * up, axis=1)), axis=1)
radii = np.linalg.norm(source_local, axis=1)
if np.any(radii <= 1.0e-8) or not np.isfinite(radii).all():
raise SofaImportError("every source measurement must have a positive radius")
receiver = _receiver_rows(file, measurements)
lateral_difference = receiver[:, 0, 1] - receiver[:, 1, 1]
if np.all(lateral_difference > 1.0e-5):
left_index, right_index = 0, 1
elif np.all(lateral_difference < -1.0e-5):
left_index, right_index = 1, 0
else:
raise SofaImportError(
"ReceiverPosition does not identify one consistently-left and one "
"consistently-right receiver")
ear_order = [left_index, right_index]
hrir = hrir_source[:, ear_order, :]
delay = delay_source[:, ear_order]
receiver = receiver[:, ear_order, :]
processing_label = _processing_label(file)
sofa_version = _text(file.attrs.get("Version", ""))
canonical = CanonicalHrtf(
source_path=str(source),
source_sha256=source_sha256,
convention=convention,
convention_version=convention_version,
sofa_version=sofa_version,
source_sample_rate_hz=sample_rate,
sample_rate_hz=sample_rate,
source_position_cartesian_m=source_local,
listener_view=forward,
listener_up=up,
receiver_position_cartesian_m=receiver,
left_receiver_index=left_index,
right_receiver_index=right_index,
hrir=hrir,
delay_samples=delay,
measurement_radius_m=radii,
processing_label=processing_label,
)
return (canonical if target_sample_rate_hz is None
else canonical.resampled(target_sample_rate_hz))
def apply_fractional_delay(values, delay_samples: float, *, half_length: int = 48
) -> np.ndarray:
"""Apply one causal non-negative delay to a real FIR using windowed sinc."""
source = np.asarray(values, dtype=np.float64)
delay = float(delay_samples)
if source.ndim != 1 or not np.isfinite(source).all():
raise ValueError("fractional delay input must be a finite real vector")
if not math.isfinite(delay) or delay < -1.0e-12:
raise ValueError("fractional delay must be finite and non-negative")
if delay < 1.0e-12:
return source.copy()
integer = int(math.floor(delay))
fraction = delay - integer
if fraction < 1.0e-12:
return np.pad(source, (integer, 0)).astype(np.float64, copy=False)
half = int(half_length)
if half < 8:
raise ValueError("fractional delay half_length must be at least 8")
index = np.arange(-half, half + 1, dtype=np.float64)
kernel = np.sinc(index - fraction) * np.kaiser(2 * half + 1, 8.6)
kernel /= np.sum(kernel, dtype=np.float64)
full = signal.fftconvolve(source, kernel, mode="full")
causal = np.asarray(full[half:], dtype=np.float64)
return np.pad(causal, (integer, 0)).astype(np.float64, copy=False)
def shift_signal_fft(values, shift_samples: float) -> np.ndarray:
"""Band-limited linear shift; positive is delay and negative is advance."""
source = np.asarray(values, dtype=np.float64)
shift = float(shift_samples)
if source.ndim != 1 or not np.isfinite(source).all() or not math.isfinite(shift):
raise ValueError("shift input and amount must be finite")
if abs(shift) < 1.0e-12:
return source.copy()
guard = max(128, int(math.ceil(abs(shift))) + 64)
needed = len(source) + 2 * guard
fft_size = next_fast_len(needed)
padded = np.zeros(fft_size, dtype=np.float64)
padded[guard:guard + len(source)] = source
bins = np.arange(fft_size // 2 + 1, dtype=np.float64)
spectrum = np.fft.rfft(padded)
spectrum *= np.exp(-2j * np.pi * bins * shift / fft_size)
shifted = np.fft.irfft(spectrum, fft_size)
return np.asarray(shifted[guard:guard + len(source)], dtype=np.float64)
def estimate_interaural_delay_samples(left, right, sample_rate_hz: float,
*, low_hz: float = 200.0,
high_hz: float = 1500.0) -> float:
"""Estimate L-minus-R delay by low-frequency circular phase coherence.
A coarse-to-fine delay search avoids the phase-unwrapping branch failures
that ordinary straight-line regression can exhibit for strongly filtered
Far responses.
"""
left = np.asarray(left, dtype=np.float64)
right = np.asarray(right, dtype=np.float64)
if left.shape != right.shape or left.ndim != 1:
raise ValueError("ITD inputs must be equal-length vectors")
fft_size = next_fast_len(max(4096, 4 * len(left)))
left_spectrum = np.fft.rfft(left, fft_size)
right_spectrum = np.fft.rfft(right, fft_size)
frequency = np.fft.rfftfreq(fft_size, 1.0 / float(sample_rate_hz))
selected = (frequency >= low_hz) & (frequency <= high_hz)
if np.count_nonzero(selected) < 8:
return 0.0
cross = left_spectrum[selected] * np.conj(right_spectrum[selected])
magnitude = np.abs(cross)
maximum = float(np.max(magnitude, initial=0.0))
if maximum <= 1.0e-20:
return 0.0
weighted_unit = cross / np.maximum(magnitude, 1.0e-30)
weight = np.sqrt(magnitude / maximum)
weighted_unit *= weight
omega = 2.0 * np.pi * frequency[selected] / float(sample_rate_hz)
limit = 0.0012 * float(sample_rate_hz)
def best(candidates: np.ndarray) -> float:
steering = np.exp(1j * omega[:, None] * candidates[None, :])
score = np.abs(weighted_unit @ steering)
return float(candidates[int(np.argmax(score))])
coarse = np.arange(-limit, limit + 0.25, 0.5, dtype=np.float64)
estimate = best(coarse)
fine = np.arange(estimate - 0.6, estimate + 0.6001, 0.02, dtype=np.float64)
return float(np.clip(best(fine), -limit, limit))
def _subsample_peak(values: np.ndarray) -> float:
magnitude = np.abs(np.asarray(values, dtype=np.float64))
index = int(np.argmax(magnitude))
if index == 0 or index + 1 >= len(magnitude):
return float(index)
y0, y1, y2 = (float(magnitude[index - 1]), float(magnitude[index]),
float(magnitude[index + 1]))
denominator = y0 - 2.0 * y1 + y2
correction = 0.0 if abs(denominator) < 1.0e-30 else 0.5 * (y0 - y2) / denominator
return float(index + np.clip(correction, -0.5, 0.5))
@dataclass(frozen=True)
class TimeAlignedHrtf:
canonical: CanonicalHrtf
aligned_hrir: np.ndarray
runtime_delay_samples: np.ndarray
embedded_delay_removed_samples: np.ndarray
delay_source: str
def __post_init__(self):
object.__setattr__(self, "aligned_hrir", _readonly(self.aligned_hrir, np.float64))
object.__setattr__(self, "runtime_delay_samples", _readonly(
self.runtime_delay_samples, np.float64))
object.__setattr__(self, "embedded_delay_removed_samples", _readonly(
self.embedded_delay_removed_samples, np.float64))
def time_align_hrtf(canonical: CanonicalHrtf) -> TimeAlignedHrtf:
"""Separate one delay representation before directional interpolation.
Trusted non-zero ``Data.Delay`` is external to ``Data.IR`` and is therefore
retained without de-rotating the FIR. When ``Data.Delay`` is identically
zero, ordinary measured HRIRs with a positive onset use their per-ear main
peaks. A zero-origin effective FIR is already expressed at one common
time origin; its interaural phase is therefore retained in ``Data.IR``.
These representations are mutually exclusive. Runtime rendering must
restore exactly the delay separated here and must not add any second ear
delay or phase-group delay.
"""
hrir = np.asarray(canonical.hrir, dtype=np.float64)
if np.max(np.abs(canonical.delay_samples), initial=0.0) > 1.0e-12:
return TimeAlignedHrtf(
canonical=canonical,
aligned_hrir=hrir.copy(),
runtime_delay_samples=np.asarray(canonical.delay_samples, dtype=np.float64),
embedded_delay_removed_samples=np.zeros_like(canonical.delay_samples),
delay_source="Data.Delay (external; applied once at render time)",
)
measurements = canonical.measurements
runtime = np.zeros((measurements, 2), dtype=np.float64)
removed = np.zeros_like(runtime)
used_peak = 0
retained_embedded_phase = 0
for measurement in range(measurements):
peaks = np.asarray([
_subsample_peak(hrir[measurement, 0]),
_subsample_peak(hrir[measurement, 1]),
], dtype=np.float64)
if float(np.max(peaks)) > 2.0:
delays = peaks
used_peak += 1
else:
# An effective response can have both ear FIRs beginning at sample
# zero while still carrying the correct ITD in complex phase. Do
# not invent an external delay which SOFA did not author.
delays = np.zeros(2, dtype=np.float64)
retained_embedded_phase += 1
runtime[measurement] = delays
removed[measurement] = delays
aligned = np.empty_like(hrir)
for measurement in range(measurements):
for ear in range(2):
aligned[measurement, ear] = shift_signal_fft(
hrir[measurement, ear], -float(removed[measurement, ear]))
source = (
f"embedded Data.IR arrival separation: peak={used_peak}, "
f"zero-origin embedded phase retained={retained_embedded_phase}; "
"positive onset restored once at render time")
return TimeAlignedHrtf(
canonical=canonical,
aligned_hrir=aligned,
runtime_delay_samples=runtime,
embedded_delay_removed_samples=removed,
delay_source=source,
)
-254
View File
@@ -1,254 +0,0 @@
"""Direct rendering of full SOFA HRIRs and explicitly selected compact fields."""
from __future__ import annotations
from collections import deque
import math
from pathlib import Path
import warnings
import numpy as np
from scipy import signal
from partitioned_convolution import MultiSourcePartitionedConvolver
from point_source import PointSourceReference
from sofa_hrir import FullHrirField
class _CompiledField:
def __init__(self, path):
from sofa_hrtf_field import SofaHrtfField
self.field = SofaHrtfField.load(path)
self.fft_size = 2048
self.measurement_radius_m = self.field.measurement_radius_m
i = np.arange(128)
z = 1 - 2 * (i + .5) / 128
phi = i * np.pi * (3 - math.sqrt(5))
directions = np.column_stack((np.sqrt(1 - z * z) * np.cos(phi),
np.sqrt(1 - z * z) * np.sin(phi), z))
self.recording_origin_samples = int(round(float(np.median([
self.field.evaluate_sofa(q).delay_samples.mean() for q in directions]))))
def info(self):
return dict(source_sha256=self.field.source_sha256, method="compiled-band-field",
measurement_radius_m=self.measurement_radius_m,
cache_key=self.field.cache_key, format_version=self.field.format_version,
recording_origin_samples=self.recording_origin_samples,
radial_adaptation="none")
class DirectSofaBackend:
fixed_reference = True
default_profile = "mid"
dsp_backend = "python-full-hrir"
block_samples = 128
def __init__(self, source, *, compiled=False, source_count=16, output_gain=1.,
method="lf_logmag_phase", shell_radius_m=None, mode=None,
reference_distance_m=None, sofa_room=False, room_preset=None):
if source_count <= 0 or not math.isfinite(output_gain):
raise ValueError("invalid source count or output gain")
self.source_count, self.output_gain = int(source_count), float(output_gain)
self.reference = PointSourceReference(reference_distance_m, mode=mode)
self.default_profile = self.reference.mode
self.compiled = bool(compiled)
self.field = (_CompiledField(source) if compiled else
FullHrirField(source, method=method, shell_radius_m=shell_radius_m))
self.hrtf_input_kind = "compiled_cache" if compiled else "sofa"
self.response_kind = "hrir" if compiled else getattr(self.field, "response_kind", "hrir")
if self.response_kind == "brir":
message = "输入为包含房间响应的BRIR,将直接渲染文件响应。"
if sofa_room:
message += "已忽略--sofa-room。"
warnings.warn(message, UserWarning)
sofa_room = False
self.hrtf_input_path = str(Path(source).expanduser().resolve())
self._last = [None] * self.source_count
self.distance_states = [None] * self.source_count
self.processed_input_samples = self.output_samples = self.parameter_updates = 0
self.finished = False
self._filter_updates = deque()
self.origin = self.field.recording_origin_samples
if compiled:
from hybrid_paths import HybridObjectPathRenderer
from rosella_bank import RosellaBank
self.dsp_backend = "python-compiled-hrtf"
self.bank = RosellaBank(1, source_channels=self.source_count, output_channels=2)
maximum = int(math.ceil(float(np.max(self.field.field.delay_bounds)) / 64))
self.paths = HybridObjectPathRenderer(self.source_count, history_slots=maximum + 8,
transition_slots=2)
self.latency_samples = self.bank.latency_samples
from rosella_direct import special_lfe_direct
self.lfe_transfer = special_lfe_direct().gains
else:
self.latency_samples = self.field.common_latency_samples
self.convolver = MultiSourcePartitionedConvolver(
self.source_count, block_size=128, max_filter_taps=self.field.fft_size)
self.lfe_filter = np.zeros((2, self.field.fft_size), dtype=np.float64)
start = self.latency_samples + max(self.origin, 0) - 64
if start < 0 or start + 129 > self.field.fft_size:
raise ValueError("LFE latency exceeds filter budget")
self.lfe_filter[:, start:start + 129] = signal.firwin(129, 150., fs=48000) / math.sqrt(2)
self._latency_remaining = self.latency_samples
self.room = None
self.filter_taps = self.field.fft_size
if sofa_room:
from sofa_room import SofaRoom
self.room = SofaRoom(self.source_count, self.reference,
implementation_latency=self.latency_samples, recording_origin=self.origin,
preset=room_preset)
if self.compiled:
maximum += int(math.ceil(self.room.early_delay_bound_samples / 64))
self.paths = HybridObjectPathRenderer(self.source_count, history_slots=maximum + 8,
transition_slots=2)
else:
self.filter_taps = self.room.filter_budget(self.field)
self.convolver = MultiSourcePartitionedConvolver(
self.source_count, block_size=128, max_filter_taps=self.filter_taps)
def set_source(self, source, position_adm, *, profile=None, gain=1., enabled=True,
special_lfe=False, fade=True):
if self.finished:
raise RuntimeError("renderer is finished")
source = int(source)
if not 0 <= source < self.source_count or not math.isfinite(gain):
raise ValueError("invalid source or gain")
if profile not in (None, self.default_profile):
raise ValueError("source profile must match the selected reference mode")
position = np.asarray(position_adm, dtype=np.float64)
if position.shape != (3,) or not np.isfinite(position).all():
raise ValueError("source position must be finite")
gain = float(gain) if enabled else 0.
key = (tuple(position), gain, bool(special_lfe))
if key == self._last[source]:
return
first = self.processed_input_samples == 0
if special_lfe:
if self.room is not None:
self.room.set_source(source, None, gain, first=first, special_lfe=True)
if self.compiled:
from hybrid_paths import HybridPath
f = self.field.field.band_center_frequencies_hz
transfer = self.lfe_transfer * gain * np.exp(-2j * np.pi * (self.origin % 64) * f / 48000)
path = HybridPath("lfe", np.full(2, self.origin // 64, dtype=np.int64), transfer)
self.paths.set_paths(source, (path,), fade_slots=0 if first else 2)
else:
self._set_filter(source, self.lfe_filter * gain, first=first, fade=fade)
else:
previous = self.distance_states[source]
state = self.reference.map_position(
position, previous_direction=None if previous is None else previous.direction)
if self.compiled:
from hybrid_paths import HybridPath
evaluation = self.field.field.evaluate_sofa(state.direction)
slots = np.floor(evaluation.delay_samples / 64).astype(np.int64)
residual = evaluation.delay_samples - slots * 64
f = self.field.field.band_center_frequencies_hz
transfer = evaluation.aligned_gains * np.exp(-2j * np.pi * residual[:, None] * f / 48000)
direct_gain = 1. if self.room is None else self.room.direct_gain(state)
paths = [HybridPath("direct", slots, transfer * gain * direct_gain)]
if self.room is not None:
for reflection in self.room.paths(state):
q = reflection.direction_adm[[1, 0, 2]] * [1, -1, 1]
e = self.field.field.evaluate_sofa(q)
total = e.delay_samples + reflection.extra_delay_samples
early_slots = np.floor(total / 64).astype(np.int64)
residual = total - early_slots * 64
h = e.aligned_gains * np.exp(-2j * np.pi * residual[:, None] * f / 48000)
h *= gain * self.room.early_gain(reflection, self.field.measurement_radius_m)
paths.append(HybridPath("early:" + reflection.wall, early_slots, h))
self.paths.set_paths(source, paths, fade_slots=0 if first or not fade else 2)
else:
if self.room is None:
spectrum = self.field.spectrum(state.direction)
hrir = np.roll(np.fft.irfft(spectrum, self.field.fft_size),
self.field.common_latency_samples, axis=-1)
else:
hrir = self.room.full_hrir(self.field, state)
self._set_filter(source, hrir * gain, first=first, fade=fade)
self.distance_states[source] = state
if self.room is not None:
self.room.set_source(source, state, gain, first=first)
self._last[source] = key
self.parameter_updates += 1
def _set_filter(self, source, hrir, *, first, fade):
if first:
self.convolver.set_filter(source, hrir, fade_blocks=0)
else:
# Keep parameter changes on the source timeline after removing the common FIR shift.
due = self.processed_input_samples + self.field.common_latency_samples
update = (due, source, hrir, int(bool(fade)))
for index in range(len(self._filter_updates) - 1, -1, -1):
item = self._filter_updates[index]
if item[0] != due:
break
if item[1] == source:
self._filter_updates[index] = update
return
self._filter_updates.append(update)
def process(self, source):
if self.finished:
raise RuntimeError("renderer is finished")
values = np.asarray(source, dtype=np.float64)
if (values.ndim != 2 or values.shape[1] != self.source_count or len(values) % 128
or not np.isfinite(values).all()):
raise ValueError("input must contain finite complete 128-sample source blocks")
outputs = []
for start in range(0, len(values), 128):
block = values[start:start + 128]
if self.compiled:
hops = block.reshape(2, 64, self.source_count).transpose(0, 2, 1)
hybrid = self.bank.hybrid_analysis.process_chunk(self.bank.qmf_analysis.process_chunk(hops))
direct = self.paths.process(hybrid)
time = self.bank.qmf_synthesis.process_chunk(self.bank.hybrid_synthesis.process_chunk(direct))
output = time.transpose(0, 2, 1).reshape(-1, 2)
else:
while self._filter_updates and self._filter_updates[0][0] <= self.processed_input_samples:
_, source, hrir, fade_blocks = self._filter_updates.popleft()
self.convolver.set_filter(source, hrir, fade_blocks=fade_blocks)
output = self.convolver.process(block)
self.processed_input_samples += 128
if self.room is not None:
output = self.room.process(block, output)
if len(output) == 0:
continue
skip = min(len(output), self._latency_remaining)
self._latency_remaining -= skip
outputs.append(output[skip:] * self.output_gain)
result = np.concatenate(outputs) if outputs else np.empty((0, 2))
self.output_samples += len(result)
return result
def finish_output_capacity(self, tail_seconds):
tail = float(tail_seconds)
if not math.isfinite(tail) or tail < 0:
raise ValueError("tail must be finite and nonnegative")
return int(math.ceil((tail * 48000 + self.latency_samples + self.filter_taps) / 128) * 128)
def finish(self, *, tail_seconds=5.):
if self.finished:
return np.empty((0, 2))
count = self.finish_output_capacity(tail_seconds)
expected = max(0, self.processed_input_samples + count - self.latency_samples - self.output_samples)
if self.room is not None:
pending = len(self.room.pending_direct) * 128
count = int(math.ceil((count + pending) / self.room.batch_samples) * self.room.batch_samples) - pending
output = self.process(np.zeros((count, self.source_count)))
self.output_samples -= max(0, len(output) - expected)
self.finished = True
return output[:expected]
def info(self):
return dict(hrtf_input_kind=self.hrtf_input_kind, hrtf_input_path=self.hrtf_input_path,
cache_policy=None, field=self.field.info(), reference=self.reference.info(),
level_calibration=1., latency_compensated_samples=self.latency_samples,
processing_batch_samples=128 if self.room is None else self.room.batch_samples,
recording_origin_compensated_samples=0,
recording_origin_preserved_samples=self.origin,
parameter_alignment_delay_samples=0 if self.compiled else self.field.common_latency_samples,
current_reference_distances_m=[s.distance_m for s in self.distance_states if s is not None],
parameter_updates=self.parameter_updates,
direct_representation="77-band" if self.compiled else "full-HRIR",
radial_model="none", room_processing=self.room is not None,
room={"enabled": False} if self.room is None else self.room.info(),
response_kind=self.response_kind, precision="float64/complex128")
-161
View File
@@ -1,161 +0,0 @@
"""Local spherical interpolation of full complex HRIR spectra."""
from __future__ import annotations
from collections import OrderedDict
import math
import numpy as np
from scipy.interpolate import PchipInterpolator
from scipy.spatial import ConvexHull, cKDTree
from sofa_canonical import CanonicalHrtf, load_simple_free_field_hrir
class FullHrirField:
response_kind = "hrir"
def __init__(self, source, *, method="lf_logmag_phase", shell_radius_m=None,
fft_size=None):
if method not in ("lf_logmag_phase", "lf_mca_zero"):
raise ValueError("unsupported full HRIR interpolation method")
self.canonical = (source if isinstance(source, CanonicalHrtf) else
load_simple_free_field_hrir(source, target_sample_rate_hz=48000))
c = self.canonical
if c.sample_rate_hz != 48000:
raise ValueError("full HRIR renderer requires 48000 Hz")
shells = c.shells_m
if shell_radius_m is not None and (not math.isfinite(shell_radius_m) or shell_radius_m <= 0):
raise ValueError("shell radius must be finite and positive")
if shell_radius_m is None and len(shells) != 1:
raise ValueError("multi-radius SOFA requires an explicit --hrtf-radius-m")
selected = c.shell_indices(shells[0] if shell_radius_m is None else shell_radius_m)
if np.any(np.sum(c.hrir[selected]**2, axis=-1) <= 0):
raise ValueError("each selected HRIR ear must contain signal energy")
self.measurement_radius_m = float(np.median(c.measurement_radius_m[selected]))
support = c.taps + int(math.ceil(float(np.max(c.delay_samples[selected])))) + 1
if fft_size is None:
fft_size = max(2048, 1 << (2*support-1).bit_length())
if fft_size > 16384:
raise ValueError("HRIR and Data.Delay exceed the automatic FFT budget")
self.method, self.fft_size = method, int(fft_size)
if self.fft_size < 64 or self.fft_size % 2 or c.taps + np.max(c.delay_samples[selected]) >= self.fft_size//2:
raise ValueError("HRIR and Data.Delay exceed the selected FFT time budget")
receiver = c.receiver_position_cartesian_m[selected]
if not np.allclose(receiver, receiver[0], atol=1e-9, rtol=0):
raise ValueError("moving receiver geometry is unsupported")
self.receivers = receiver[0].copy()
unit = c.unit_directions[selected]
_, first, inverse = np.unique(np.round(unit, 10), axis=0, return_index=True, return_inverse=True)
for group in np.flatnonzero(np.bincount(inverse) > 1):
members = selected[inverse == group]
if not (np.allclose(c.hrir[members], c.hrir[members[0]], atol=1e-10, rtol=1e-8)
and np.allclose(c.delay_samples[members], c.delay_samples[members[0]], atol=1e-10, rtol=0)):
raise ValueError("coincident SOFA measurements disagree")
selected = selected[np.sort(first)]
self.directions = c.unit_directions[selected].copy()
self.tree = cKDTree(self.directions)
hull = ConvexHull(self.directions)
if np.any(hull.equations[:, 3] >= -1e-9):
raise ValueError("SOFA must enclose the listener; extrapolation is unsupported")
self.faces = hull.simplices
vertices = self.directions[self.faces]
dots = np.einsum("fij,fkj->fik", vertices, vertices)
self.max_triangle_edge_degrees = math.degrees(math.acos(float(np.clip(dots.min(), -1, 1))))
matrix = self.directions[self.faces].transpose(0, 2, 1)
if np.max(np.linalg.cond(matrix)) > 1e8:
raise ValueError("ill-conditioned spherical interpolation mesh")
self.inverse = np.linalg.inv(matrix)
self.frequencies = np.fft.rfftfreq(self.fft_size, 1/c.sample_rate_hz)
self.omega = 2*np.pi*self.frequencies/c.sample_rate_hz
raw = np.fft.rfft(c.hrir[selected], self.fft_size)
fit = (self.frequencies >= 200) & (self.frequencies <= 1500)
x = self.omega[fit]-self.omega[fit].mean()
phase = np.unwrap(np.angle(raw), axis=-1)[..., fit]
self.delays = -np.sum(x*phase, axis=-1)/np.sum(x*x) + c.delay_samples[selected]
residual_phase = phase+(self.delays-c.delay_samples[selected])[..., None]*self.omega[fit]
residual_phase -= residual_phase.mean(axis=-1, keepdims=True)
self.phase_fit_rms_rad = np.sqrt(np.mean(residual_phase**2, axis=-1))
self.recording_origin_samples = int(round(float(np.median(self.delays.mean(axis=1)))))
self.common_latency_samples = self.fft_size//2
physical = raw*np.exp(-1j*self.omega*c.delay_samples[selected, :, None])
self.floor = max(float(np.max(np.abs(physical)))*1e-6, 1e-15)
self.aligned = physical*np.exp(1j*self.omega*self.delays[..., None])
self.log_magnitude = None
self.auditory = None
if method == "lf_logmag_phase":
self.log_magnitude = np.log(np.maximum(np.abs(physical), self.floor))
else:
erb = lambda f: 21.4*np.log10(1+.00437*f)
self.centres = (10**(np.linspace(erb(50), erb(20000), 41)/21.4)-1)/.00437
bw = 1.019*24.7*(1+.00437*self.centres)
self.bank = (1+((self.frequencies[None, :]-self.centres[:, None])/bw[:, None])**2)**-4
self.bank[:, 1:-1] *= 2
self.bank /= self.bank.sum(axis=1, keepdims=True)
self.auditory = self._auditory_db(physical)
self._cache = OrderedDict()
def _auditory_db(self, spectrum):
return 10*np.log10(np.maximum(np.abs(spectrum)**2 @ self.bank.T, 1e-24))
def weights(self, direction):
q = np.asarray(direction, dtype=np.float64)
if q.shape != (3,) or not np.isfinite(q).all() or np.linalg.norm(q) <= 1e-12:
raise ValueError("query direction must be a finite nonzero vector")
q = q/np.linalg.norm(q)
distance, nearest = self.tree.query(q)
if distance < 1e-10:
return np.array([nearest]), np.array([1.]), 0.
g = self.inverse @ q
valid = np.flatnonzero(np.min(g, axis=1) >= -1e-10)
if not len(valid):
raise ValueError("no containing spherical triangle")
face = int(valid[0])
weights = np.maximum(g[face], 0)
weights /= weights.sum()
ids = self.faces[face]
vertices = self.directions[ids]
edge = math.degrees(math.acos(float(np.clip(np.min(vertices @ vertices.T), -1, 1))))
return ids, weights, edge
def spectrum(self, direction):
q = np.asarray(direction, dtype=np.float64)
if q.shape != (3,) or not np.isfinite(q).all() or np.linalg.norm(q) <= 1e-12:
raise ValueError("query direction must be a finite nonzero vector")
q = q/np.linalg.norm(q)
key = tuple(q)
if key in self._cache:
self._cache.move_to_end(key)
return self._cache[key].copy()
ids, weights, _ = self.weights(q)
delay = weights @ self.delays[ids]
spectrum = np.einsum("i,ief->ef", weights, self.aligned[ids])
spectrum *= np.exp(-1j*self.omega*delay[:, None])
if len(ids) > 1:
if self.method == "lf_logmag_phase":
magnitude = np.exp(np.einsum("i,ief->ef", weights, self.log_magnitude[ids]))
spectrum = magnitude*spectrum/np.maximum(np.abs(spectrum), self.floor)
else:
target = np.einsum("i,ieb->eb", weights, self.auditory[ids])
difference = target-self._auditory_db(spectrum)
correction = PchipInterpolator(self.centres, difference, axis=-1)(
np.clip(self.frequencies, self.centres[0], self.centres[-1]))
spectrum *= 10**(np.clip(correction, -12, 12)/20)
self._cache[key] = spectrum.copy()
if len(self._cache) > 128:
self._cache.popitem(last=False)
return spectrum
def info(self):
arrays = [self.aligned, self.log_magnitude, self.auditory, self.delays,
self.inverse, self.directions, self.faces]
return dict(source_sha256=self.canonical.source_sha256,
sample_rate_hz=self.canonical.sample_rate_hz,
convention=self.canonical.convention,
measurement_radius_m=self.measurement_radius_m,
method=self.method, fft_size=self.fft_size,
retained_filter_taps=self.fft_size,
recording_origin_samples=self.recording_origin_samples,
interpolation_storage_bytes=sum(x.nbytes for x in arrays if x is not None),
max_triangle_edge_degrees=self.max_triangle_edge_degrees,
phase_fit_rms_rad_p95=float(np.percentile(self.phase_fit_rms_rad, 95)),
ear_model="measured-SOFA-receivers",
receiver_positions_m=self.receivers.tolist())
-214
View File
@@ -29,11 +29,6 @@ from public_filterbank import (
hybrid_band_center_frequencies_hz,
project_hrir_to_hybrid_gains,
)
from sofa_canonical import (
CanonicalHrtf,
load_simple_free_field_hrir,
time_align_hrtf,
)
from spherical_harmonics import (
evaluate_real_spherical_harmonics,
fit_real_spherical_harmonics,
@@ -118,22 +113,6 @@ def sofa_to_adm_direction(position) -> np.ndarray:
return result / length
def _group_coincident(directions, gains, delays):
unit = np.asarray(directions, dtype=np.float64)
keys = np.round(unit, 10)
_, first, inverse = np.unique(keys, axis=0, return_index=True, return_inverse=True)
grouped_directions = unit[first]
grouped_gains = np.zeros((len(first),) + gains.shape[1:], dtype=np.complex128)
grouped_delays = np.zeros((len(first), 2), dtype=np.float64)
counts = np.bincount(inverse).astype(np.float64)
for measurement, group in enumerate(inverse):
grouped_gains[group] += gains[measurement]
grouped_delays[group] += delays[measurement]
grouped_gains /= counts[:, None, None]
grouped_delays /= counts[:, None]
return grouped_directions, grouped_gains, grouped_delays
def _cache_key_payload(*, source_sha256: str, sample_rate_hz: float,
shell_radius_m: float, order: int,
projection_ridge: float, sh_ridge: float) -> dict:
@@ -556,109 +535,6 @@ class SofaHrtfField:
object.__setattr__(self, "fit_report", json.loads(
_json_bytes(dict(self.fit_report)).decode("utf-8")))
@classmethod
def fit(cls, canonical: CanonicalHrtf, *, shell_radius_m: float | None = None,
order: int = DEFAULT_ORDER, ridge: float = DEFAULT_SH_RIDGE,
projection_ridge: float = DEFAULT_PROJECTION_RIDGE) -> "SofaHrtfField":
order = _strict_integer(order, "field order")
if order != DEFAULT_ORDER:
raise ValueError("the runtime HRTF field is fixed at fifth order")
if abs(float(canonical.sample_rate_hz) - TARGET_SAMPLE_RATE_HZ) > 1.0e-9:
raise ValueError("SOFA HRTF fields must be compiled at 48 kHz")
aligned = time_align_hrtf(canonical)
shell_target = 1.0 if shell_radius_m is None else float(shell_radius_m)
if not math.isfinite(shell_target) or shell_target <= 0.0:
raise ValueError("shell_radius_m must be positive and finite")
indices = canonical.shell_indices(shell_target)
if len(indices) < (order + 1) ** 2:
raise ValueError(
f"fifth-order SH needs at least 36 measurements on one shell, got {len(indices)}")
shell_radius = float(np.mean(canonical.measurement_radius_m[indices]))
directions = canonical.unit_directions[indices]
runtime_delay = np.asarray(aligned.runtime_delay_samples[indices], dtype=np.float64)
centers = hybrid_band_center_frequencies_hz(canonical.sample_rate_hz)
gains, projection_report = project_hrir_to_hybrid_gains(
np.asarray(canonical.hrir[indices], dtype=np.float64),
embedded_delay_samples=np.asarray(
aligned.embedded_delay_removed_samples[indices], dtype=np.float64),
sample_rate_hz=canonical.sample_rate_hz,
ridge=projection_ridge)
directions, gains, runtime_delay = _group_coincident(
directions, gains, runtime_delay)
if len(directions) < (order + 1) ** 2:
raise ValueError("coincident-direction merging left fewer than 36 directions")
weights = spherical_voronoi_weights(directions)
coefficients = fit_real_spherical_harmonics(
directions, gains, order=order, ridge=ridge, weights=weights)
delay_coefficients = fit_real_spherical_harmonics(
directions, runtime_delay, order=order, ridge=ridge, weights=weights)
reconstructed_aligned = evaluate_real_spherical_harmonics(
coefficients, directions, order=order)
delay_reconstructed = evaluate_real_spherical_harmonics(
delay_coefficients, directions, order=order)
reference_phase = np.exp(
-2j * np.pi * runtime_delay[..., None]
* centers[None, None, :] / canonical.sample_rate_hz)
reconstructed_phase = np.exp(
-2j * np.pi * delay_reconstructed[..., None]
* centers[None, None, :] / canonical.sample_rate_hz)
reference_transfer = np.asarray(gains * reference_phase, dtype=np.complex128)
reconstructed_transfer = np.asarray(
reconstructed_aligned * reconstructed_phase, dtype=np.complex128)
magnitude_reference = np.maximum(np.abs(reference_transfer), 1.0e-12)
relative = np.abs(reconstructed_transfer - reference_transfer) / magnitude_reference
magnitude_db_error = np.abs(
20.0 * np.log10(np.maximum(np.abs(reconstructed_transfer), 1.0e-12))
- 20.0 * np.log10(magnitude_reference))
delay_error = delay_reconstructed - runtime_delay
report = {
"format": "SOFA FIR -> public 64-QMF/77-hybrid -> ACN/N3D real SH",
"order": order,
"terms": (order + 1) ** 2,
"input_measurements": int(len(indices)),
"unique_directions": int(len(directions)),
"shell_radius_m": shell_radius,
"spherical_harmonic_ridge": float(ridge),
"projection": projection_report,
"phase_policy_version": PHASE_POLICY_VERSION,
"complex_relative_error_median": float(np.median(relative)),
"complex_relative_error_p95": float(np.percentile(relative, 95.0)),
"magnitude_error_db_median": float(np.median(magnitude_db_error)),
"magnitude_error_db_p95": float(np.percentile(magnitude_db_error, 95.0)),
"delay_error_samples_rms": float(np.sqrt(np.mean(delay_error * delay_error))),
"delay_error_samples_max": float(np.max(np.abs(delay_error))),
"delay_source": aligned.delay_source,
"precision": "float64/complex128",
}
delay_bounds = np.stack(
(np.min(runtime_delay, axis=0), np.max(runtime_delay, axis=0)), axis=1)
cache_key = compiled_hrtf_cache_key(
source_sha256=canonical.source_sha256,
sample_rate_hz=canonical.sample_rate_hz,
shell_radius_m=shell_radius,
order=order,
projection_ridge=float(projection_ridge),
sh_ridge=float(ridge),
)
display_name = Path(canonical.source_path).name if canonical.source_path else None
return cls(
source_sha256=canonical.source_sha256,
source_display_name=display_name,
sample_rate_hz=canonical.sample_rate_hz,
measurement_radius_m=shell_radius,
order=order,
projection_ridge=float(projection_ridge),
spherical_harmonic_ridge=float(ridge),
band_center_frequencies_hz=centers,
coefficients=coefficients,
delay_coefficients=delay_coefficients,
delay_bounds=delay_bounds,
delay_source=aligned.delay_source,
fit_report=report,
cache_key=cache_key,
)
def evaluate_sofa(self, direction_sofa) -> FieldEvaluation:
direction = np.asarray(direction_sofa, dtype=np.float64)
if direction.shape != (3,) or not np.isfinite(direction).all():
@@ -928,93 +804,3 @@ class SofaHrtfField:
"fit_report": self.fit_report,
"precision": "float64/complex128",
}
def _cache_file_name(display_name: str | None, cache_key: str) -> str:
stem = Path(display_name).stem if display_name else "hrtf"
safe = re.sub(r"[^A-Za-z0-9._-]+", "_", stem).strip("._") or "hrtf"
return f"{safe}.{cache_key[:20]}.jochrtf"
def compile_sofa_hrtf(
sofa: str | Path | CanonicalHrtf, *,
target_sample_rate_hz: float = TARGET_SAMPLE_RATE_HZ,
shell_radius_m: float = 1.0,
order: int = DEFAULT_ORDER,
projection_ridge: float = DEFAULT_PROJECTION_RIDGE,
sh_ridge: float = DEFAULT_SH_RIDGE,
cache_policy: str = "memory",
cache_dir: str | Path | None = None) -> SofaHrtfField:
"""Compile SOFA in memory, optionally using a validated disposable cache."""
policy = str(cache_policy).strip().lower()
if policy not in {"none", "memory", "disk"}:
raise ValueError("cache_policy must be none, memory, or disk")
target_rate = float(target_sample_rate_hz)
if (not math.isfinite(target_rate)
or abs(target_rate - TARGET_SAMPLE_RATE_HZ) > 1.0e-9):
raise ValueError("the public binaural runtime currently requires 48 kHz")
radius = float(shell_radius_m)
projection_ridge = float(projection_ridge)
sh_ridge = float(sh_ridge)
if not math.isfinite(radius) or radius <= 0.0:
raise ValueError("shell_radius_m must be positive and finite")
if (not math.isfinite(projection_ridge) or projection_ridge < 0.0
or not math.isfinite(sh_ridge) or sh_ridge < 0.0):
raise ValueError("compiler ridge values must be finite and non-negative")
order = _strict_integer(order, "compiler order")
if order != DEFAULT_ORDER:
raise ValueError("the runtime HRTF field is fixed at fifth order")
if isinstance(sofa, CanonicalHrtf):
canonical = (sofa if abs(sofa.sample_rate_hz - target_rate) <= 1.0e-9
else sofa.resampled(target_rate))
else:
canonical = load_simple_free_field_hrir(
sofa, target_sample_rate_hz=target_rate)
selected = canonical.shell_indices(radius)
actual_radius = float(np.mean(canonical.measurement_radius_m[selected]))
key = compiled_hrtf_cache_key(
source_sha256=canonical.source_sha256,
sample_rate_hz=target_rate,
shell_radius_m=actual_radius,
order=order,
projection_ridge=projection_ridge,
sh_ridge=sh_ridge,
)
cached = None
if policy in {"memory", "disk"}:
cached = _memory_cache_get(key)
if policy == "memory" and cached is not None:
return cached
target: Path | None = None
if policy == "disk":
directory = (DEFAULT_HRTF_CACHE_DIR if cache_dir is None
else Path(cache_dir).expanduser().resolve())
directory.mkdir(parents=True, exist_ok=True)
display_name = Path(canonical.source_path).name if canonical.source_path else None
target = directory / _cache_file_name(display_name, key)
if target.is_file():
try:
field = SofaHrtfField.load(
target,
expected_source_sha256=canonical.source_sha256,
expected_cache_key=key)
_memory_cache_put(key, field)
return field
except (HrtfCacheError, OSError):
pass
if cached is not None:
cached.save(target)
return cached
field = SofaHrtfField.fit(
canonical,
shell_radius_m=actual_radius,
order=order,
ridge=sh_ridge,
projection_ridge=projection_ridge)
if field.cache_key != key:
raise RuntimeError("internal compiled HRTF cache-key mismatch")
if target is not None:
field.save(target)
if policy in {"memory", "disk"}:
_memory_cache_put(key, field)
return field
-123
View File
@@ -1,123 +0,0 @@
"""Full-resolution coupling to the existing project-owned early/late room."""
from __future__ import annotations
from dataclasses import asdict
import hashlib
import json
import math
from pathlib import Path
import numpy as np
from scipy import fft
from generate_sofa_room import SCHEMA, ROOM_PATHS
from partitioned_convolution import UniformPartitionedConvolver
from public_room import ShoeboxRoomConfig, first_order_image_sources
from reference_distance import DistanceState, ReferenceDistanceProfileV1
class SofaRoom:
batch_samples = 1536
def __init__(self, source_count, reference, *, implementation_latency, recording_origin,
path=None, preset=None):
self.reference = reference
self.preset = ("legacy" if reference.mode == "far" else "compact") if preset is None else str(preset)
if self.preset not in ROOM_PATHS:
raise ValueError("room preset must be compact or legacy")
self.path = Path(ROOM_PATHS[self.preset] if path is None else path)
with np.load(self.path, allow_pickle=False) as data:
if str(data["schema"]) != SCHEMA or int(data["sample_rate_hz"]) != 48000:
raise ValueError("unsupported SOFA room asset schema or sample rate")
kernel = np.asarray(data["late_fir"], dtype="<f8")
self.metadata = json.loads(str(data["metadata_json"]))
if (kernel.ndim != 2 or kernel.shape[0] != 2 or kernel.shape[1] < 1
or not np.isfinite(kernel).all()
or hashlib.sha256(kernel.tobytes()).hexdigest() != self.metadata["kernel_sha256"]):
raise ValueError("invalid SOFA room FIR or checksum")
self.config = ShoeboxRoomConfig(**self.metadata["early_config"])
self.config.validate()
self.alignment_samples = int(implementation_latency) + max(0, int(recording_origin))
kernel = np.pad(kernel, ((0, 0), (self.alignment_samples, 0)))
self.convolver = UniformPartitionedConvolver(kernel, block_size=self.batch_samples)
self.current = np.zeros(int(source_count))
self.target = self.current.copy()
self.pending_mono, self.pending_direct = [], []
self.maximum_early_delay_samples = 0.
def distance_state(self, state):
return DistanceState(
self.reference.mode, state.normalized_radius, self.reference.reference_distance_m,
max(ReferenceDistanceProfileV1.MINIMUM_DISTANCE_M, state.distance_m),
state.direction[[1, 0, 2]] * [-1, 1, 1])
def paths(self, state):
distance = self.distance_state(state)
try:
paths = first_order_image_sources(distance.direction_adm, distance.physical_distance_m,
48000, self.config)
except ValueError as error:
raise ValueError("--sofa-room预设房间无法表示当前声源位置;关闭该开关可保留直接声") from error
self.maximum_early_delay_samples = max(
self.maximum_early_delay_samples, max(p.extra_delay_samples for p in paths))
return paths
def direct_gain(self, state):
return ReferenceDistanceProfileV1.direct_level_gain(self.distance_state(state))
def early_gain(self, path, measurement_radius_m):
return (ReferenceDistanceProfileV1.PUBLIC_ROOM_CALIBRATION_GAIN * path.reflection_gain
* measurement_radius_m / path.path_distance_m)
def set_source(self, source, state, gain, *, first=False, special_lfe=False):
value = 0. if special_lfe else (float(gain) * ReferenceDistanceProfileV1.PUBLIC_ROOM_CALIBRATION_GAIN
* ReferenceDistanceProfileV1.late_send(self.distance_state(state)))
self.target[source] = value
if first:
self.current[source] = value
def filter_budget(self, field):
needed = field.fft_size + int(math.ceil(self.early_delay_bound_samples)) + 64
return 1 << (needed - 1).bit_length()
@property
def early_delay_bound_samples(self):
dimensions = np.asarray(self.config.dimensions_m)
listener = np.asarray(self.config.listener_position_m)
return 2 * float(np.max(np.maximum(listener, dimensions - listener))) * 48000 / self.config.speed_of_sound_m_s
def full_hrir(self, field, state):
length = self.filter_budget(field)
omega = 2 * math.pi * fft.rfftfreq(length)
direct = np.roll(np.fft.irfft(field.spectrum(state.direction), field.fft_size),
field.common_latency_samples, axis=-1)
spectrum = fft.rfft(direct, length) * self.direct_gain(state)
for path in self.paths(state):
q = path.direction_adm[[1, 0, 2]] * [1, -1, 1]
hrir = np.roll(np.fft.irfft(field.spectrum(q), field.fft_size),
field.common_latency_samples, axis=-1)
spectrum += (fft.rfft(hrir, length) * np.exp(-1j * omega * path.extra_delay_samples)
* self.early_gain(path, field.measurement_radius_m))
return fft.irfft(spectrum, length, axis=-1)
def process(self, source_block, direct_block):
amount = np.arange(1, 129, dtype=np.float64)[:, None] / 128
sends = self.current + (self.target - self.current) * amount
self.pending_mono.append(np.einsum("ts,ts->t", source_block, sends))
self.pending_direct.append(direct_block)
self.current[:] = self.target
if len(self.pending_mono) * 128 < self.batch_samples:
return np.empty((0, 2))
result = np.concatenate(self.pending_direct) + self.convolver.process_block(np.concatenate(self.pending_mono))
self.pending_mono.clear()
self.pending_direct.clear()
return result
def info(self):
return dict(enabled=True, schema=SCHEMA, preset=self.preset, asset=str(self.path.resolve()),
late_fir=self.metadata, early_config=asdict(self.config),
maximum_early_delay_samples=self.maximum_early_delay_samples,
late_alignment_samples=self.alignment_samples,
distance_coupling=ReferenceDistanceProfileV1.info(),
high_precision_adaptation="full-HRIR early paths with fractional delay; PCM float64 late FIR",
normalization="original project room coupling; not a measured BRIR")