Source code for acoustic_spaces.materials.libraries

"""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", ]