Source code for acoustic_spaces.gltf

"""Scenes as glTF 2.0 binary files (``.glb``) for Blender and other 3D tools.

The file holds the room, one object per surface name with a see-through material per
scene material (its absorption and scattering per octave band as extras, which Blender
shows as custom properties), an outdoor scene's trees, hedges and belts of trees as
see-through green volumes, and the sources and listeners turned the way they face,
with an arrow along the aim. It can also hold early reflection paths as lines, one
object per order, and sound particles as an animation in slow motion: by default
100 ms of sound play over 4 s. Blender opens it with File > Import > glTF 2.0.

Scenes are Z-up and glTF is Y-up: a point (x, y, z) is written as (x, z, -y), which
the importer turns back.
"""

from __future__ import annotations

import json
import struct
from pathlib import Path
from typing import TYPE_CHECKING

import numpy as np

from acoustic_spaces._version import __version__
from acoustic_spaces.materials import OCTAVE_BANDS_HZ
from acoustic_spaces.room import UNASSIGNED, Room, _label_text
from acoustic_spaces.viz import (
    LISTENER_COLOUR,
    MATERIAL_COLOURS,
    SOURCE_COLOUR,
    VEGETATION_COLOUR,
    path_groups,
)

if TYPE_CHECKING:
    from acoustic_spaces.engine import EarlyReflections
    from acoustic_spaces.engine.particles import Particles

#: Particles the command line and the editor export: about 3 MB at 100 frames.
PARTICLE_COUNT = 1000
#: Seconds of animation per second of sound.
SLOW_MOTION = 40.0
#: Opacity of the room's surfaces.
SURFACE_ALPHA = 0.4
#: Opacity of the vegetation's volumes.
VEGETATION_ALPHA = 0.3
UNASSIGNED_GREY = "#9e9e9e"
PARTICLE_COLOUR = "#ffd166"

#: Scene to glTF coordinates: (x, y, z) -> (x, z, -y), a rotation about x.
_TO_GLTF = np.array([[1.0, 0.0, 0.0], [0.0, 0.0, 1.0], [0.0, -1.0, 0.0]])
_FLOAT, _UINT = 5126, 5125
_ARRAY_BUFFER, _ELEMENT_ARRAY_BUFFER = 34962, 34963
_LINES, _TRIANGLES = 1, 4
_JSON_CHUNK, _BIN_CHUNK = 0x4E4F534A, 0x004E4942


def _linear(colour: str, alpha: float = 1.0) -> list[float]:
    """An sRGB hex colour as the linear RGBA factors glTF materials take."""
    srgb = np.array([int(colour[k : k + 2], 16) for k in (1, 3, 5)]) / 255.0
    rgb = np.where(srgb <= 0.04045, srgb / 12.92, ((srgb + 0.055) / 1.055) ** 2.4)
    return [round(float(v), 6) for v in rgb] + [alpha]


def _point(position) -> list[float]:
    return [float(v) for v in _TO_GLTF @ np.asarray(position, dtype=float)]


def _quaternion(m: np.ndarray) -> list[float]:
    """The unit quaternion (x, y, z, w) of a rotation matrix (Shepperd's method)."""
    trace = m[0, 0] + m[1, 1] + m[2, 2]
    if trace > 0:
        s = 2.0 * np.sqrt(1.0 + trace)
        q = [(m[2, 1] - m[1, 2]) / s, (m[0, 2] - m[2, 0]) / s, (m[1, 0] - m[0, 1]) / s, s / 4]
    elif m[0, 0] > m[1, 1] and m[0, 0] > m[2, 2]:
        s = 2.0 * np.sqrt(1.0 + m[0, 0] - m[1, 1] - m[2, 2])
        q = [s / 4, (m[0, 1] + m[1, 0]) / s, (m[0, 2] + m[2, 0]) / s, (m[2, 1] - m[1, 2]) / s]
    elif m[1, 1] > m[2, 2]:
        s = 2.0 * np.sqrt(1.0 + m[1, 1] - m[0, 0] - m[2, 2])
        q = [(m[0, 1] + m[1, 0]) / s, s / 4, (m[1, 2] + m[2, 1]) / s, (m[0, 2] - m[2, 0]) / s]
    else:
        s = 2.0 * np.sqrt(1.0 + m[2, 2] - m[0, 0] - m[1, 1])
        q = [(m[0, 2] + m[2, 0]) / s, (m[1, 2] + m[2, 1]) / s, s / 4, (m[1, 0] - m[0, 1]) / s]
    q = np.array(q) / np.linalg.norm(q)
    return [float(v) for v in q]


def _lathe(profile: list[tuple[float, float]], segments: int) -> tuple[np.ndarray, np.ndarray]:
    """A closed surface of revolution about the x axis, facing outwards.

    ``profile`` lists (x, radius) from one end on the axis to the other, x increasing
    along the sides. Returns the vertices and the triangles.
    """
    angles = 2.0 * np.pi * np.arange(segments) / segments
    vertices, triangles = [], []
    count, previous, was_ring = 0, None, False
    for x, r in profile:
        n = segments if r > 0 else 1
        cos, sin = np.cos(angles[:n]), np.sin(angles[:n])
        vertices.append(np.column_stack([np.full(n, x), r * cos, r * sin]))
        ring = count + np.arange(segments) % n  # a point on the axis repeats its index
        if was_ring:
            triangles.append(np.column_stack([previous, np.roll(previous, -1), np.roll(ring, -1)]))
        if previous is not None and n > 1:
            triangles.append(np.column_stack([previous, np.roll(ring, -1), ring]))
        previous, was_ring = ring, n > 1
        count += n
    return np.vstack(vertices), np.vstack(triangles)


def _sphere(radius: float, segments: int, rings: int) -> tuple[np.ndarray, np.ndarray]:
    """A sphere around the origin with its poles on the x axis."""
    theta = np.pi * np.arange(rings + 1) / rings
    profile = list(zip(-radius * np.cos(theta), radius * np.sin(theta), strict=True))
    profile[0], profile[-1] = (-radius, 0.0), (radius, 0.0)
    return _lathe(profile, segments)


def _arrow(length: float) -> tuple[np.ndarray, np.ndarray]:
    """An arrow along +x from the origin, shaped as the 3D view draws them."""
    shaft, tip, head = 0.05 * length, 0.1 * length, 0.75 * length
    return _lathe([(0.0, 0.0), (0.0, shaft), (head, shaft), (head, tip), (length, 0.0)], 16)


def _marker_radius(room: Room) -> float:
    """Radius of the source and listener spheres: 1.2 % of the model's size, the least
    the editor's 3D view gives them where they do not crowd."""
    lo, hi = np.array(room.report.bounds_min), np.array(room.report.bounds_max)
    size = float(np.linalg.norm(hi - lo)) or 1.0
    return max(0.012 * size, 0.05)


class _Document:
    """A glTF document and its binary chunk, built up piece by piece."""

    def __init__(self, name: str) -> None:
        self.json: dict = {
            "asset": {"version": "2.0", "generator": f"acoustic_spaces {__version__}"},
            "scene": 0,
            "scenes": [{"name": name, "nodes": []}],
        }
        self.binary = bytearray()

    def add(self, kind: str, item: dict) -> int:
        """Append ``item`` to the top-level array ``kind`` and return its index."""
        items = self.json.setdefault(kind, [])
        items.append(item)
        return len(items) - 1

    def accessors(
        self, data: np.ndarray, target: int | None = None, bounds: bool = False
    ) -> list[int]:
        """One accessor per entry of ``data`` (n, count) or (n, count, 3), all in one
        buffer view, as 32-bit floats or unsigned integers; returns their indices."""
        integer = np.issubdtype(data.dtype, np.integer)
        data = np.ascontiguousarray(data, dtype=np.uint32 if integer else np.float32)
        self.binary.extend(bytes(-len(self.binary) % 4))
        view = {"buffer": 0, "byteOffset": len(self.binary), "byteLength": data.nbytes}
        if target is not None:
            view["target"] = target
        self.binary.extend(data.tobytes())
        view_index = self.add("bufferViews", view)
        out = []
        for n, block in enumerate(data):
            accessor = {
                "bufferView": view_index,
                "componentType": _UINT if integer else _FLOAT,
                "count": len(block),
                "type": "SCALAR" if block.ndim == 1 else "VEC3",
            }
            if n:
                accessor["byteOffset"] = n * block.nbytes
            if bounds:
                accessor["min"] = np.atleast_1d(block.min(axis=0)).tolist()
                accessor["max"] = np.atleast_1d(block.max(axis=0)).tolist()
            out.append(self.add("accessors", accessor))
        return out

    def accessor(self, data: np.ndarray, target: int | None = None, bounds: bool = False) -> int:
        return self.accessors(data[None], target, bounds)[0]

    def material(
        self, name: str, colour: str, alpha: float = 1.0, glow: bool = False, extras=None
    ) -> int:
        material = {
            "name": name,
            "pbrMetallicRoughness": {
                "baseColorFactor": _linear(colour, alpha),
                "metallicFactor": 0.0,
                "roughnessFactor": 0.8,
            },
            "doubleSided": True,
        }
        if alpha < 1.0:
            material["alphaMode"] = "BLEND"
        if glow:
            material["emissiveFactor"] = _linear(colour)[:3]
        if extras:
            material["extras"] = extras
        return self.add("materials", material)

    def mesh(
        self,
        name: str,
        vertices: np.ndarray,
        indices: np.ndarray,
        material: int,
        mode: int = _TRIANGLES,
        normals: np.ndarray | None = None,
    ) -> int:
        """A mesh of one primitive; ``vertices`` and ``normals`` in scene coordinates."""
        position = self.accessor(vertices @ _TO_GLTF.T, _ARRAY_BUFFER, bounds=True)
        attributes = {"POSITION": position}
        if normals is not None:
            attributes["NORMAL"] = self.accessor(normals @ _TO_GLTF.T, _ARRAY_BUFFER)
        primitive = {
            "attributes": attributes,
            "indices": self.accessor(indices.ravel(), _ELEMENT_ARRAY_BUFFER),
            "material": material,
            "mode": mode,
        }
        return self.add("meshes", {"name": name, "primitives": [primitive]})

    def node(self, name: str, parent: int | None = None, **fields) -> int:
        """A node under ``parent``, or at the root of the scene."""
        index = self.add("nodes", {"name": name, **fields})
        if parent is None:
            self.json["scenes"][0]["nodes"].append(index)
        else:
            self.json["nodes"][parent].setdefault("children", []).append(index)
        return index

    def write(self, path: str | Path) -> None:
        self.binary.extend(bytes(-len(self.binary) % 4))
        self.json["buffers"] = [{"byteLength": len(self.binary)}]
        text = json.dumps(self.json, ensure_ascii=False, separators=(",", ":")).encode()
        text += b" " * (-len(text) % 4)
        chunks = (
            struct.pack("<II", len(text), _JSON_CHUNK)
            + text
            + struct.pack("<II", len(self.binary), _BIN_CHUNK)
            + self.binary
        )
        Path(path).write_bytes(struct.pack("<4sII", b"glTF", 2, 12 + len(chunks)) + chunks)


def _room_material(doc: _Document, room: Room, k: int) -> int:
    """Material ``k`` of the room (or grey for none), with its coefficients as extras."""
    if k == UNASSIGNED:
        return doc.material("no material", UNASSIGNED_GREY, SURFACE_ALPHA)
    name = room.material_names[k]
    material = room.scene.materials[name]
    absorption, scattering = material.coefficients("octave")
    extras = {"absorption": absorption, "scattering": scattering, "bands_hz": list(OCTAVE_BANDS_HZ)}
    if material.source:
        extras["source"] = material.source
    colour = MATERIAL_COLOURS[k % len(MATERIAL_COLOURS)]
    return doc.material(name, colour, SURFACE_ALPHA, extras=extras)


def _add_room(doc: _Document, room: Room) -> None:
    """One node per surface name under a ``room`` node; materials as they are used."""
    mesh = room.mesh
    areas = mesh.face_areas()
    materials: dict[int, int] = {}
    group = doc.node("room")
    shown = room.shown_faces()  # outdoors, not the open sky
    for label in np.unique(mesh.face_labels[shown]):
        faces = np.flatnonzero(mesh.face_labels == label)
        k = int(room.face_materials[faces[0]])
        if k not in materials:
            materials[k] = _room_material(doc, room, k)
        extras = {"area_m2": round(float(areas[faces].sum()), 3)}
        if k != UNASSIGNED:
            extras["material"] = room.material_names[k]
        used, local = np.unique(mesh.faces[faces], return_inverse=True)
        name = _label_text(mesh.labels[label])
        index = doc.mesh(name, mesh.vertices[used], local.reshape(-1, 3), materials[k])
        doc.node(name, group, mesh=index, extras=extras)


def _add_vegetation(doc: _Document, room: Room) -> None:
    """Outdoors, one node per tree, hedge or belt of trees under a ``vegetation`` node."""
    from acoustic_spaces.geometry.builders import extruded_mesh

    shapes = room.outdoor.vegetation if room.outdoor is not None else ()
    if not shapes:
        return
    material = doc.material("vegetation", VEGETATION_COLOUR, VEGETATION_ALPHA)
    group = doc.node("vegetation")
    for shape in shapes:
        if shape.outline is None:
            vertices, triangles = _sphere(1.0, 24, 12)
            axes = np.array([shape.radius, shape.radius, shape.half_height])
            vertices = vertices * axes + shape.centre
        else:
            prism = extruded_mesh(shape.outline, shape.high - shape.low)
            vertices, triangles = prism.vertices + [0.0, 0.0, shape.low], prism.faces
        index = doc.mesh(shape.name, vertices, triangles, material)
        doc.node(shape.name, group, mesh=index, extras={"kind": shape.kind})


def _add_points(doc: _Document, room: Room, radius: float) -> None:
    """Sources and listeners as spheres turned the way they face, with an arrow along
    the aim (for listeners, and for sources that are not omnidirectional)."""
    sphere, triangles = _sphere(radius, 24, 16)
    arrow = _arrow(6.0 * radius)
    scene = room.scene
    for kind, items, colour in (
        ("source", scene.sources, SOURCE_COLOUR),
        ("listener", scene.listeners, LISTENER_COLOUR),
    ):
        material = doc.material(kind, colour)
        marker = doc.mesh(kind, sphere, triangles, material, normals=sphere / radius)
        aim = None
        for k, item in enumerate(items):
            extras = {"kind": kind}
            directional = kind == "listener"
            if kind == "source":
                directivity = room.directivities[k]
                directional = not directivity.omni
                extras.update(
                    directivity=directivity.name or "omni",
                    directivity_index_db=[
                        round(float(v), 2) if np.isfinite(v) else None
                        for v in directivity.in_bands("octave").index()
                    ],
                    level_db=item.level_db,
                )
                if item.line_m is not None:
                    extras["line_m"] = item.line_m
                if item.surface_m is not None:
                    extras["surface_m"] = list(item.surface_m)
            rotation = _TO_GLTF @ np.array(item.orientation.rotation()) @ _TO_GLTF.T
            node = doc.node(
                item.name,
                translation=_point(item.position),
                rotation=_quaternion(rotation),
                mesh=marker,
                extras=extras,
            )
            if directional:
                if aim is None:
                    aim = doc.mesh(f"{kind} aim", *arrow, material)
                doc.node(f"{item.name} aim", node, mesh=aim)
            if kind == "source" and item.extended:
                doc.node(f"{item.name} extent", node, mesh=_extent(doc, item, material))


def _extent(doc: _Document, source, material: int) -> int:
    """A line source as a line along its left axis, a surface source as its rectangle
    across the left and up axes, in the source's own axes."""
    if source.line_m is not None:
        half = 0.5 * source.line_m
        ends = np.array([[0.0, -half, 0.0], [0.0, half, 0.0]])
        return doc.mesh(f"{source.name} line", ends, np.array([[0, 1]]), material, mode=_LINES)
    w, h = 0.5 * source.surface_m[0], 0.5 * source.surface_m[1]
    corners = np.array([[0.0, -w, -h], [0.0, w, -h], [0.0, w, h], [0.0, -w, h]])
    triangles = np.array([[0, 1, 2], [0, 2, 3]])
    return doc.mesh(f"{source.name} surface", corners, triangles, material)


def _add_paths(doc: _Document, paths: EarlyReflections) -> None:
    """Early reflection paths as lines under ``reflection paths``: one node per order of
    specular paths, and one for the paths diffracted at an edge."""
    group = doc.node("reflection paths")
    for kind in path_groups(paths):
        chosen = [p for p, keep in zip(paths.points, kind.mask, strict=True) if keep]
        points = np.vstack(chosen)
        starts = np.cumsum([len(p) for p in chosen])  # where the next path begins
        first = np.arange(len(points) - 1)
        first = first[~np.isin(first + 1, starts)]
        if kind.order is None:
            name, extras = "paths diffracted", {"diffracted": True, "paths": len(chosen)}
        else:
            name, extras = f"paths order {kind.order}", {"order": kind.order, "paths": len(chosen)}
        material = doc.material(name, kind.colour, glow=True)
        lines = np.column_stack([first, first + 1])
        mesh = doc.mesh(name, points, lines, material, mode=_LINES)
        doc.node(name, group, mesh=mesh, extras=extras)


def _add_particles(
    doc: _Document, particles: Particles, radius: float, slow_motion: float, db_range: float
) -> None:
    """A node per particle under one group node, and one animation moving and scaling them."""
    times = np.asarray(particles.times * slow_motion, dtype=np.float32)
    if np.any(np.diff(times) <= 0):
        raise ValueError("particle frames must follow each other in time")
    with np.errstate(divide="ignore"):
        level = 10.0 * np.log10(particles.energy)
    scale = np.clip(1.0 + level / db_range, 0.0, 1.0)  # (frames, particles)
    positions = particles.positions @ _TO_GLTF.T

    name = f"particles from {particles.source}" if particles.source else "particles"
    material = doc.material("particle", PARTICLE_COLOUR, glow=True)
    sphere, triangles = _sphere(radius, 8, 6)
    mesh = doc.mesh("particle", sphere, triangles, material, normals=sphere / radius)
    group = doc.node(
        name,
        extras={
            "band_hz": particles.band_hz,
            "duration_ms": float(1e3 * particles.times[-1]),
            "slow_motion": slow_motion,
            "db_range": db_range,
        },
    )
    nodes = [
        doc.node(
            f"particle {k}",
            group,
            mesh=mesh,
            translation=positions[0, k].tolist(),
            scale=[float(scale[0, k])] * 3,
        )
        for k in range(positions.shape[1])
    ]
    time = doc.accessor(times, bounds=True)
    moves = doc.accessors(positions.transpose(1, 0, 2))
    sizes = doc.accessors(np.repeat(scale.T[:, :, None], 3, axis=2))
    samplers, channels = [], []
    for node, move, size in zip(nodes, moves, sizes, strict=True):
        for output, path in ((move, "translation"), (size, "scale")):
            channels.append({"sampler": len(samplers), "target": {"node": node, "path": path}})
            samplers.append({"input": time, "output": output, "interpolation": "LINEAR"})
    doc.add("animations", {"name": name, "samplers": samplers, "channels": channels})


[docs] def export_gltf( room: Room, path: str | Path, *, paths: EarlyReflections | None = None, particles: Particles | None = None, slow_motion: float = SLOW_MOTION, db_range: float = 60.0, ) -> None: """Write ``room`` with its sources and listeners to ``path`` as glTF 2.0 (``.glb``). ``paths`` (from :func:`acoustic_spaces.engine.early_paths` or a response's ``early``) adds the early reflection paths, coloured by order as in the 3D view. ``particles`` (from :func:`acoustic_spaces.engine.trace_particles`) adds an animation with a small sphere per particle that moves with it and shrinks with its level: full size at its share of the emitted energy, gone ``db_range`` dB below. The animation runs ``slow_motion`` times slower than the sound, with a keyframe at each of the particles' frames. """ if slow_motion <= 0 or db_range <= 0: raise ValueError("slow_motion and db_range must be positive") doc = _Document(room.scene.name) radius = _marker_radius(room) _add_room(doc, room) _add_vegetation(doc, room) _add_points(doc, room, radius) if paths is not None and len(paths): _add_paths(doc, paths) if particles is not None: _add_particles(doc, particles, 0.4 * radius, slow_motion, db_range) doc.write(path)
__all__ = ["PARTICLE_COUNT", "SLOW_MOTION", "export_gltf"]