"""Material libraries of other room acoustics programs: CATT-Acoustic and ODEON.
A scene's material can take its coefficients from an entry of such a library, with
``file`` naming the library and ``entry`` the material in it, and
``acoustic-spaces materials --file`` lists a library's entries.
CATT-Acoustic writes materials in its geometry and library files as
``ABS name = <a125 a250 a500 a1k a2k a4k> L <s125 s250 s500 s1k s2k s4k> {r g b}``:
absorption and scattering in percent from 125 Hz to 4 kHz, with values at 8 and 16 kHz
optional (after a colon, ``<a125 ... a4k : a8k a16k>``, or without one). ``ABS1`` gives
them as fractions from 0 to 1 instead. ``L <...>`` and the colour may be left out, ``;``
starts a comment, and ``ABS name = other`` gives a material the coefficients of another
in the same file. Scattering that CATT estimates itself (``L <estimate(...)>``) is not
read.
ODEON's library (``Material.Li8``) has each material on two lines: its number and
description, then eight absorption coefficients from 63 Hz to 8 kHz. ODEON's own
library writes the description as ``{Product name*=...}, {Category=...}``, and the
materials its Material calculator made carry the calculator's settings after the
description and, after the eight values, ``/Area`` and ``/A`` with the sample area and
third-octave values, which are not read: ODEON simulates with the octave values.
Libraries of six values (125 Hz to 4 kHz) are read too. ODEON gives scattering to
surfaces, not to materials, so these entries have none.
"""
from __future__ import annotations
import dataclasses
import math
import re
from dataclasses import dataclass
from pathlib import Path
#: Centre frequencies (Hz) of CATT-Acoustic's bands, 125 Hz to 16 kHz.
CATT_BANDS_HZ = (125.0, 250.0, 500.0, 1000.0, 2000.0, 4000.0, 8000.0, 16000.0)
#: ODEON's bands, 63 Hz to 8 kHz; a library of six values starts at 125 Hz.
ODEON_BANDS_HZ = (63.0, 125.0, 250.0, 500.0, 1000.0, 2000.0, 4000.0, 8000.0)
_CATT = re.compile(
r"\bABS(?P<fraction>1)?\s+(?P<name>[^\s=;]+)\s*=\s*"
r"(?:<(?P<absorption>[^>]*)>|(?P<alias>[^\s<{;]+))"
r"(?:\s*L\s*<(?P<scattering>[^>]*)>)?",
re.IGNORECASE,
)
[docs]
@dataclass(frozen=True)
class LibraryMaterial:
"""One material of a library."""
#: Its name: CATT's material name, or ODEON's description.
name: str
#: ODEON's material number; None in CATT libraries.
number: int | None
#: Centre frequencies (Hz) of the values.
frequencies: tuple[float, ...]
#: Random-incidence absorption coefficients, from 0 to 1.
absorption: tuple[float, ...]
#: Scattering coefficients at the same frequencies, or None.
scattering: tuple[float, ...] | None = None
#: ODEON's category of the material (``{Category=...}``), or None.
category: str | None = None
@property
def label(self) -> str:
"""How the material is named in messages: with its number, if it has one."""
return self.name if self.number is None else f"{self.number} {self.name}"
def _text(path: Path) -> str:
data = path.read_bytes()
try:
return data.decode("utf-8-sig")
except UnicodeDecodeError:
return data.decode("cp1252", errors="replace") # ODEON is a Windows program
def _numbers(text: str) -> list[float] | None:
"""The numbers of a line, or None when it holds anything else."""
try:
values = [float(t.replace(",", ".")) for t in text.split()]
except ValueError:
return None
return values if values and all(math.isfinite(v) for v in values) else None
[docs]
def read_library(path: str | Path) -> list[LibraryMaterial]:
"""Every material of a CATT-Acoustic or ODEON library, in file order.
The format is found from the contents: ``ABS`` definitions make a CATT file, and
numbered descriptions followed by a line of coefficients an ODEON one.
"""
path = Path(path)
text = _text(path)
without_comments = "\n".join(line.split(";", 1)[0] for line in text.splitlines())
if _CATT.search(without_comments):
return _read_catt(path, without_comments)
materials = _read_odeon(path, text)
if not materials:
raise ValueError(
f"{path}: no materials found; expected CATT-Acoustic ABS definitions or an "
"ODEON library (a material's number and description, then its coefficients)"
)
return materials
def _read_catt(path: Path, text: str) -> list[LibraryMaterial]:
found: dict[str, LibraryMaterial] = {}
aliases: list[tuple[str, str]] = []
for match in _CATT.finditer(text):
name = match["name"]
if match["alias"] is not None:
aliases.append((name, match["alias"]))
continue
# ABS gives percent, ABS1 fractions; a colon may set off the 8 and 16 kHz values.
scale, unit = (1.0, "from 0 to 1") if match["fraction"] else (100.0, "in percent")
absorption = _numbers(match["absorption"].replace(":", " "))
if absorption is None or not 6 <= len(absorption) <= len(CATT_BANDS_HZ):
raise ValueError(
f"{path}: material {name!r}: expected 6 to 8 absorption values {unit} "
f"(125 Hz to 4, 8 or 16 kHz), got <{match['absorption'].strip()}>"
)
# Scattering that CATT estimates (estimate(...)) is no list of numbers: none.
given = match["scattering"]
scattering = None if given is None else _numbers(given.replace(":", " "))
if scattering is not None and not 6 <= len(scattering) <= len(CATT_BANDS_HZ):
raise ValueError(
f"{path}: material {name!r}: expected 6 to 8 scattering values {unit}, "
f"got <{given.strip()}>"
)
found[name.lower()] = LibraryMaterial(
name=name,
number=None,
frequencies=CATT_BANDS_HZ[: len(absorption)],
absorption=tuple(v / scale for v in absorption),
scattering=None if scattering is None else _held(scattering, len(absorption), scale),
)
for name, other in aliases:
if other.lower() not in found:
raise ValueError(
f"{path}: material {name!r} is {other!r}, which the file does not define "
"(it may come from a CATT library: give that file instead)"
)
found[name.lower()] = _renamed(found[other.lower()], name)
return list(found.values())
def _held(given: list[float], count: int, scale: float) -> tuple[float, ...]:
"""Scattering in percent (``scale`` 100) or fractions (1) as shares at as many bands
as the absorption: cut, or the last value held."""
values = [v / scale for v in given]
return tuple((values + values[-1:] * count)[:count])
def _renamed(material: LibraryMaterial, name: str) -> LibraryMaterial:
return dataclasses.replace(material, name=name)
#: A field of an ODEON description, such as ``{Product name*=Carpet}``.
_ODEON_FIELD = re.compile(r"\{([^{}=]+)=([^{}]*)\}")
def _odeon_description(text: str) -> tuple[str, str | None]:
"""A material's name and category from its ODEON description: the product name and
category fields where it has them, else the whole description."""
fields = {
key.strip().rstrip("*").lower(): value.strip() for key, value in _ODEON_FIELD.findall(text)
}
if fields.get("product name"):
return fields["product name"], fields.get("category") or None
return text, None
def _read_odeon(path: Path, text: str) -> list[LibraryMaterial]:
lines = [line.strip() for line in text.splitlines()]
lines = [line for line in lines if line]
out = []
k = 0
while k < len(lines) - 1:
head = re.match(r"(-?\d+)\s+(.*\S)", lines[k])
# The Material calculator's /Area and /A (third octaves) follow the octave values.
values = _numbers(lines[k + 1].split("/", 1)[0])
if head is None or _numbers(lines[k]) is not None or values is None:
k += 1
continue
name, category = _odeon_description(head[2])
if len(values) not in (6, len(ODEON_BANDS_HZ)):
raise ValueError(
f"{path}: material {head[1]} {name!r}: expected 8 absorption values "
f"(63 Hz to 8 kHz) or 6 (125 Hz to 4 kHz), got {len(values)}"
)
bands = ODEON_BANDS_HZ if len(values) == len(ODEON_BANDS_HZ) else ODEON_BANDS_HZ[1:7]
out.append(LibraryMaterial(name, int(head[1]), bands, tuple(values), category=category))
k += 2
return out
[docs]
def find_material(path: str | Path, entry: str | int) -> LibraryMaterial:
"""The material of a library named ``entry``: a name or description (any case), or
an ODEON material's number."""
materials = read_library(path)
key = str(entry).strip()
for material in materials:
if material.name.lower() == key.lower() or str(material.number) == key:
return material
known = ", ".join(m.label for m in materials[:12])
more = f" and {len(materials) - 12} more" if len(materials) > 12 else ""
raise ValueError(f"{path}: no material {key!r}; it has {known}{more}")
__all__ = [
"CATT_BANDS_HZ",
"ODEON_BANDS_HZ",
"LibraryMaterial",
"find_material",
"read_library",
]