Source code for acoustic_spaces.viz

"""Pictures of rooms and responses.

- 3D view (PyVista): surfaces coloured by material, sources with their directivity
  balloons, listeners, and early reflection paths coloured by order (paths diffracted
  at an edge in a colour of their own); outdoors the vegetation, and the wind: arrows
  over the ground, the weather zones, and masts with the wind's profile up them.
- Leaks (PyVista): the open edges of a model that is not closed, and the rays of the
  leak finder that escape through its gaps.
- Animation (PyVista): sound particles spreading from a source and reflecting around
  the room, in a window with a time slider or saved as a GIF or MP4 video; a walker
  going along its walk, as a video to go with its sound.
- Response plots (matplotlib): echogram with the early paths, decay curves per band, and
  arrival directions as the listener faces; the decays of a simulated and a measured
  response band by band; polar patterns of a source directivity; the wind, temperature
  and speed of sound over the ground outdoors.
- Coverage maps: a parameter over the audience area, from above (matplotlib) or as
  coloured tiles in the 3D view.

Needs the viz extra (``pip install "acoustic-spaces[viz]"``, or ``uv sync --extra viz``
in a source checkout). The 3D view works in a desktop window, in
Jupyter, and off screen for screenshots.
"""

from __future__ import annotations

import dataclasses
import math
from pathlib import Path
from typing import TYPE_CHECKING, NamedTuple

import numpy as np

from acoustic_spaces._extras import install_hint
from acoustic_spaces.geometry import UNIT_SCALE, plan_problem
from acoustic_spaces.geometry.outdoor import _inner_point, clip_polygon, in_polygon
from acoustic_spaces.i18n import N_, _
from acoustic_spaces.room import UNASSIGNED, Room

if TYPE_CHECKING:
    import pyvista

    from acoustic_spaces.directivity import Directivity
    from acoustic_spaces.engine import CoverageMap, EarlyReflections, Response
    from acoustic_spaces.engine.leaks import Leaks
    from acoustic_spaces.engine.particles import Particles
    from acoustic_spaces.parameters import BandDecay
    from acoustic_spaces.scene.model import Atmosphere
    from acoustic_spaces.walkthrough import Movement, WalkResponses

#: ColorBrewer Set3: light colours, so the saturated source and listener markers stand out.
MATERIAL_COLOURS = (
    "#8dd3c7",
    "#ffffb3",
    "#bebada",
    "#fb8072",
    "#80b1d3",
    "#fdb462",
    "#b3de69",
    "#fccde5",
    "#d9d9d9",
    "#bc80bd",
    "#ccebc5",
    "#ffed6f",
)
UNASSIGNED_COLOUR = "#ff00ff"
SOURCE_COLOUR = "#ff5a5f"
LISTENER_COLOUR = "#4da3ff"
FACING_COLOUR = "#ffd23f"
BACKGROUND = ("#16171d", "#3a3d4a")  # bottom, top
PANEL = "#26272f"
EDGE_COLOUR = "#d0d0d0"
#: Reflection paths by order, direct sound first; orders past the end reuse the last.
ORDER_COLOURS = ("#ffffff", "#ffd166", "#f78c6b", "#ef476f", "#b5179e", "#7209b7", "#4361ee")
#: Paths that bend over an edge.
DIFFRACTED_COLOUR = "#06d6a0"
#: Octave band colours for decay curves, low to high.
BAND_COLOURS = (
    "#5e4fa2",
    "#3288bd",
    "#66c2a5",
    "#abdda4",
    "#e6f598",
    "#fdae61",
    "#f46d43",
    "#d53e4f",
)
#: Open edges and the rays that escape through them.
LEAK_COLOUR = "#ff4d4d"
ESCAPE_COLOUR = "#ffd166"
#: Escaping rays drawn at most, so a big hole does not hide the room.
MAX_ESCAPES_DRAWN = 400
#: A simulated and a measured response drawn together.
COMPARISON_COLOURS = ("#4da3ff", "#ffd166")
#: Trees, hedges and belts of trees outdoors.
VEGETATION_COLOUR = "#5cb85c"
#: The wind and the weather zones outdoors.
WIND_COLOUR = "#4cc9f0"
#: Arrows of the wind over the ground in the 3D view, about this many.
WIND_ARROWS = 40
#: The longest arrow of the wind, the strongest's, as a share of the space between them.
WIND_REACH = 0.8
#: Arrows up each mast of the wind's profile.
PROFILE_ARROWS = 5
# Translators: the wind over an outdoor scene, as the 3D view's legend shows it.
WIND_KEY = N_("wind {speed:.1f} m/s at {height:g} m")
# Translators: a weather zone's name and its wind's speed, drawn on it.
ZONE_WIND = N_("{name}: {speed:.1f} m/s")
# Translators: a weather zone's name, its wind's speed and its ground temperature.
ZONE_WIND_TEMPERATURE = N_("{name}: {speed:.1f} m/s, {temperature:.1f} °C")
# Translators: a weather zone's name and its ground temperature, in still air.
ZONE_TEMPERATURE = N_("{name}: {temperature:.1f} °C")
# Translators: the wind's speed at a height, beside an arrow up the wind's profile and
# beside the wind and each weather zone in the scene tree.
PROFILE_SPEED = N_("{speed:.1f} m/s at {height:g} m")


def _outline(part: pyvista.PolyData) -> pyvista.PolyData:
    """Edges of a surface patch without the triangulation's internal diagonals."""
    return part.extract_feature_edges(
        feature_angle=20.0,
        boundary_edges=True,
        feature_edges=True,
        manifold_edges=False,
        non_manifold_edges=True,
    )


def _pyvista():
    try:
        import pyvista
    except ImportError as exc:  # pragma: no cover - exercised without the extra
        raise ImportError(f"the 3D view needs PyVista: {install_hint('viz')}") from exc
    return pyvista


[docs] def room_polydata(room: Room, faces: np.ndarray | None = None) -> pyvista.PolyData: """Room surfaces (all, or the given face indices) as PyVista PolyData. The ``material`` cell array holds the index into ``room.material_names``. """ pv = _pyvista() mesh = room.mesh faces = np.arange(len(mesh.faces)) if faces is None else np.asarray(faces) cells = np.column_stack([np.full(len(faces), 3), mesh.faces[faces]]).ravel() poly = pv.PolyData(mesh.vertices, cells) poly.cell_data["material"] = room.face_materials[faces] return poly
#: A reflection order's name by the suffix English gives its number. _ORDER_NAMES = { # Translators: reflection orders: 1st order, 2nd order... {order} is the number. "st": N_("{order}st order"), "nd": N_("{order}nd order"), "rd": N_("{order}rd order"), "th": N_("{order}th order"), } def _order_name(order: int) -> str: if order == 0: # Translators: the direct sound's paths, in a plot's legend. return _("direct") suffix = {1: "st", 2: "nd", 3: "rd"}.get(order if order < 20 else order % 10, "th") return _(_ORDER_NAMES[suffix]).format(order=order)
[docs] def paths_polydata( paths: EarlyReflections, order: int | None = None, *, mask: np.ndarray | None = None ) -> pyvista.PolyData: """The specular paths of one reflection order, or the paths ``mask`` picks, as polylines.""" pv = _pyvista() if mask is None: mask = (paths.order == order) & ~paths.diffracted chosen = [p for p, keep in zip(paths.points, mask, strict=True) if keep] points = np.vstack(chosen) if chosen else np.zeros((0, 3)) lines, start = [], 0 for p in chosen: lines.extend([len(p), *range(start, start + len(p))]) start += len(p) return pv.PolyData(points, lines=np.array(lines, dtype=np.int64))
[docs] class PathGroup(NamedTuple): """Paths drawn together: specular paths of one ``order``, or (order None) those diffracted at an edge.""" label: str colour: str mask: np.ndarray order: int | None
[docs] def path_groups(paths: EarlyReflections, max_order: int | None = None) -> list[PathGroup]: """The specular paths by order, then those diffracted at an edge (with up to ``max_order`` reflections).""" groups = [] specular = ~paths.diffracted top = int(paths.order.max()) if len(paths) else -1 if max_order is not None: top = min(top, max_order) for order in range(top + 1): mask = specular & (paths.order == order) if mask.any(): colour = ORDER_COLOURS[min(order, len(ORDER_COLOURS) - 1)] groups.append(PathGroup(_order_name(order), colour, mask, order)) mask = paths.diffracted & (paths.order <= top) if mask.any(): groups.append(PathGroup(_("diffracted"), DIFFRACTED_COLOUR, mask, None)) return groups
[docs] def plot_paths( paths: EarlyReflections, plotter: pyvista.Plotter, *, max_order: int | None = None, line_width: float = 2.0, ) -> list[list[str]]: """Draw specular paths coloured by order and diffracted paths in their own colour; returns their legend entries.""" legend = [] for group in path_groups(paths, max_order): plotter.add_mesh( paths_polydata(paths, mask=group.mask), color=group.colour, line_width=line_width * 1.5 if group.order == 0 else line_width, opacity=0.8 if (group.order or 0) >= 2 else 1.0, ) legend.append([f"{group.label} ({int(group.mask.sum())})", group.colour]) return legend
[docs] def plot_leaks( leaks: Leaks, room: Room, plotter: pyvista.Plotter, *, render: bool = True ) -> list[list[str]]: """Draw the open edges of ``room``, the rays of ``leaks`` (from :func:`acoustic_spaces.engine.leaks.find_leaks`) that escape, from their last reflection to a little past where they leave, and a numbered marker on each gap; returns their legend entries.""" from acoustic_spaces.engine.leaks import open_edges pv = _pyvista() legend = [] corners, _faces = open_edges(room) if len(corners): lines = np.column_stack([np.full(len(corners), 2), corners]).reshape(-1) edges = pv.PolyData(room.mesh.vertices, lines=lines) plotter.add_mesh(edges, color=LEAK_COLOUR, line_width=5.0, render=False) legend.append([_("open edges ({count})").format(count=len(corners)), LEAK_COLOUR]) if leaks.escaped: lo, hi = np.array(room.report.bounds_min), np.array(room.report.bounds_max) size = float(np.linalg.norm(hi - lo)) or 1.0 step = max(1, -(-leaks.escaped // MAX_ESCAPES_DRAWN)) start = leaks.starts[::step] end = leaks.points[::step] + 0.1 * size * leaks.directions[::step] points = np.stack([start, end], axis=1).reshape(-1, 3) lines = np.column_stack([np.full(len(start), 2), np.arange(2 * len(start)).reshape(-1, 2)]) rays = pv.PolyData(points, lines=lines.reshape(-1)) plotter.add_mesh(rays, color=ESCAPE_COLOUR, line_width=1.5, opacity=0.6, render=False) legend.append([_("escaping rays ({count})").format(count=leaks.escaped), ESCAPE_COLOUR]) radius = max(0.012 * size, 0.05) centres = np.array([gap.centre for gap in leaks.gaps]) for centre in centres: plotter.add_mesh( pv.Sphere(radius=radius, center=centre), color=LEAK_COLOUR, render=False ) plotter.add_point_labels( centres + [0.0, 0.0, 1.5 * radius], [ _("gap {number}: {share:.1f} %").format( number=k, share=100.0 * gap.rays / leaks.rays ) for k, gap in enumerate(leaks.gaps, 1) ], font_size=12, text_color="white", shape_color=PANEL, shape_opacity=0.8, show_points=False, always_visible=True, render=False, ) if render: plotter.render() return legend
[docs] def balloon_polydata( directivity: Directivity, center, rotation=None, *, band: int = 4, size: float = 1.0, db_range: float = 30.0, ) -> pyvista.PolyData: """A directivity balloon around ``center`` in one octave band (``band`` indexes ``OCTAVE_BANDS_HZ``; 4 is 1 kHz): its radius grows from 0 at ``db_range`` dB below the loudest direction to ``size`` there. ``rotation`` has the source's forward, left and up axes as columns (``Orientation.rotation()``). The point data ``level`` holds the level in dB re the loudest direction. """ pv = _pyvista() sphere = pv.Sphere(radius=1.0, theta_resolution=72, phi_resolution=36) local = np.asarray(sphere.points, dtype=float) local /= np.linalg.norm(local, axis=1, keepdims=True) with np.errstate(divide="ignore"): energy = directivity.in_bands("octave").energy(local) # arrays: third octaves level = 10.0 * np.log10(np.maximum(energy[:, band], 1e-30)) level -= level.max() radius = size * np.clip(1.0 + level / db_range, 0.0, 1.0) turn = np.eye(3) if rotation is None else np.asarray(rotation, dtype=float) sphere.points = np.asarray(center, dtype=float) + (local * radius[:, None]) @ turn.T sphere.point_data["level"] = level return sphere
[docs] def extent_polydata(source, radius: float) -> pyvista.PolyData | None: """A line source as a tube of ``radius`` (m), a surface source as its rectangle, or None for a point source.""" if not source.extended: return None pv = _pyvista() corners = source.outline() if len(corners) == 2: return pv.Line(corners[0], corners[1]).tube(radius=radius) return pv.PolyData(corners, faces=[4, 0, 1, 2, 3])
[docs] def nearest_spacing(points) -> np.ndarray: """The distance from each of ``points`` (rows of coordinates) to the nearest other one: infinite for a point alone.""" points = np.asarray(points, dtype=float) nearest = np.full(len(points), np.inf) if len(points) < 2: return nearest for start in range(0, len(points), 256): # a block of rows at a time part = np.linalg.norm(points[start : start + 256, None] - points[None], axis=-1) part[np.arange(len(part)), np.arange(start, start + len(part))] = np.inf nearest[start : start + len(part)] = part.min(axis=1) return nearest
[docs] def clear_lengths(points, directions, radius, length) -> np.ndarray: """The length of the arrow from each of ``points`` along its unit row of ``directions`` (zeros for none): ``length``, cut short where the arrow would run into the marker (of ``radius``) of another point ahead of it, but no shorter than twice its own marker's radius.""" points = np.asarray(points, dtype=float) directions = np.asarray(directions, dtype=float) radius = np.broadcast_to(np.asarray(radius, dtype=float), len(points)) length = np.broadcast_to(np.asarray(length, dtype=float), len(points)).copy() for start in range(0, len(points), 256): # a block of arrows at a time rows = slice(start, start + 256) ahead = points[None] - points[rows, None] # from each arrow's start to every point along = np.einsum("bnd,bd->bn", ahead, directions[rows]) aside = np.linalg.norm(ahead - along[..., None] * directions[rows, None], axis=-1) reach = length[rows, None] # The tip is a tenth of the arrow's length in radius. hit = (along > 0) & (aside < radius + 0.1 * reach) & (along - radius < reach) stop = np.where(hit, along - radius, np.inf).min(axis=1) length[rows] = np.minimum(length[rows], np.maximum(0.9 * stop, 2 * radius[rows])) return length
[docs] def marker_radius(positions, size: float) -> float: """The radius of the markers of sources and listeners at ``positions`` where they do not crowd, in a model ``size`` metres across: a fifth of their usual spacing (the median distance to the nearest one), from 1.2 % to 2.5 % of the model's size.""" nearest = nearest_spacing(np.asarray(positions, dtype=float).reshape(-1, 3)) apart = nearest[np.isfinite(nearest)] usual = float(np.median(apart)) if len(apart) else np.inf return max(float(np.clip(0.2 * usual, 0.012 * size, 0.025 * size)), 0.05)
[docs] def common_radius(nearest, full: float, lowest: float = 0.2) -> float: """One radius for every marker, so that markers of one kind look alike: ``full`` where no two of them would touch, else as small as the closest two need (0.45 of their distance, ``nearest`` holding each one's distance to its nearest), down to ``lowest`` times ``full`` to stay clearly visible.""" nearest = np.asarray(nearest, dtype=float) closest = float(nearest.min()) if nearest.size else np.inf return float(np.clip(0.45 * closest, lowest * full, full))
[docs] def marker_sizes( positions, size: float, directions=None, *, apart=None ) -> tuple[np.ndarray, np.ndarray]: """The radius of the marker of each source or listener at ``positions`` and the length of its arrow along its unit row of ``directions``, in a model ``size`` metres across, from how far apart the points are: a fifth of their usual spacing (the median distance to the nearest one), from 1.2 % to 2.5 % of the model's size, and an arrow six times that. Where points crowd, every marker shrinks alike so that the closest two do not overlap (:func:`common_radius`), down to a fifth, and an arrow stops short of a marker ahead of it. ``apart`` (a boolean per point, default all) picks the points that are not to overlap: those in use, say, where the others are drawn faded.""" points = np.asarray(positions, dtype=float).reshape(-1, 3) keep = np.ones(len(points), bool) if apart is None else np.asarray(apart, bool) full = marker_radius(points[keep], size) radius = np.full(len(points), common_radius(nearest_spacing(points[keep]), full)) if directions is None: return radius, 6 * radius return radius, clear_lengths(points, np.reshape(directions, (-1, 3)), radius, 6 * radius)
[docs] def vegetation_polydata(shape) -> pyvista.PolyData: """The volume of a tree, a hedge or a belt of trees (:class:`~acoustic_spaces.geometry.outdoor.PlantShape`) as a closed surface: a lone tree's crown, or an outline raised from its bottom to its top.""" pv = _pyvista() if shape.outline is None: crown = pv.Sphere(radius=1.0, theta_resolution=24, phi_resolution=16) axes = np.array([shape.radius, shape.radius, shape.half_height]) crown.points = np.asarray(crown.points) * axes + shape.centre return crown n = len(shape.outline) bottom = np.column_stack([shape.outline, np.full(n, shape.low)]) plan = pv.PolyData(bottom, faces=[n, *range(n)]) return plan.extrude((0.0, 0.0, shape.high - shape.low), capping=True).triangulate()
[docs] def plot_vegetation(room: Room, plotter: pyvista.Plotter, *, render: bool = True) -> list: """Add an outdoor ``room``'s trees, hedges and belts of trees to ``plotter``, as see-through green volumes; returns their legend entries.""" shapes = room.outdoor.vegetation if room.outdoor is not None else () for shape in shapes: part = vegetation_polydata(shape) plotter.add_mesh(part, color=VEGETATION_COLOUR, opacity=0.3, pickable=False, render=render) edges = _outline(part) if edges.n_points: # a lone tree's round crown has none plotter.add_mesh( edges, color=VEGETATION_COLOUR, line_width=1.0, pickable=False, render=render ) return [[_("vegetation"), VEGETATION_COLOUR]] if shapes else []
[docs] class WindMap: """The weather over an outdoor room's ground as the views draw it: the scene's own (index 0) and each weather zone's (1 on), where each holds, and each one's wind at one ``height`` above the ground, the height the scene gives its wind's speed at, so that the zones' winds compare with the scene's. Zones are polygons in metres, cut to the ground; one that cannot be (its sides cross) or that lies off the ground is None and holds nowhere.""" def __init__(self, room: Room) -> None: from acoustic_spaces.scene.model import Wind scene = room.scene atmosphere = scene.atmosphere self.layout = room.outdoor self.weathers = atmosphere.weathers() self.names = [scene.name, *atmosphere.zone_names()] self.zones = [None, *(atmosphere.zones or [])] self.height = float((atmosphere.wind or Wind()).height_m) self.speeds = np.array([float(w.wind_speed(self.height)) for w in self.weathers]) self.directions = np.array([[*w.to_wind(), 0.0] for w in self.weathers]) scale = UNIT_SCALE[scene.geometry.units or "m"] self.polygons: list[np.ndarray | None] = [None] for zone in atmosphere.zones or []: polygon = scale * np.asarray(zone.polygon, dtype=float) simple = len(polygon) >= 3 and plan_problem(polygon) is None self.polygons.append(clip_polygon(polygon, self.layout.extent) if simple else None)
[docs] @classmethod def of(cls, room: Room) -> WindMap | None: """The map of ``room``, or None indoors and outdoors without an atmosphere.""" if room.outdoor is None or room.scene.atmosphere is None: return None return cls(room)
@property def windy(self) -> bool: """Whether the wind blows anywhere at the map's height.""" return bool(np.any(self.speeds > 0.0))
[docs] def weather_at(self, points) -> np.ndarray: """(n,) which weather holds at each point (n, 2 or 3): 0 for the scene's own, k for its zone k (the first where zones overlap).""" points = np.atleast_2d(np.asarray(points, dtype=float))[:, :2] out = np.zeros(len(points), dtype=np.int64) for k, polygon in enumerate(self.polygons): if polygon is not None: out[(out == 0) & in_polygon(points, polygon)] = k return out
[docs] def centre(self, k: int) -> np.ndarray | None: """(2,) a point inside weather zone ``k``: its centroid, or another inside if the centroid is not (an L-shaped zone); None for a zone that holds nowhere.""" polygon = self.polygons[k] if polygon is None: return None a, b = polygon, np.roll(polygon, -1, axis=0) cross = a[:, 0] * b[:, 1] - b[:, 0] * a[:, 1] centroid = ((a + b) * cross[:, None]).sum(axis=0) / (3.0 * cross.sum()) if in_polygon(centroid[None], polygon)[0]: return centroid return _inner_point(polygon)[0]
[docs] def label(self, k: int) -> str: """What weather zone ``k`` holds, in words: its name, its wind's speed (if the wind blows anywhere) and its ground temperature (if it has one of its own).""" name, zone = self.names[k], self.zones[k] temperature = None if zone is None else zone.temperature_c if not self.windy: if temperature is None: return name return _(ZONE_TEMPERATURE).format(name=name, temperature=temperature) if temperature is None: return _(ZONE_WIND).format(name=name, speed=self.speeds[k]) return _(ZONE_WIND_TEMPERATURE).format( name=name, speed=self.speeds[k], temperature=temperature )
[docs] def arrows(self, spacing: float | None = None, clear=None, within=None) -> WindArrows: """The arrows of the wind over the ground, one in the middle of each cell of a grid no more than ``spacing`` metres apart (by default about :data:`WIND_ARROWS` cells), each the wind of the weather there: the strongest :data:`WIND_REACH` of a cell long, the others in proportion, none where the air is still. Arrows that would pass near one of ``clear`` (m, 2), where sources and listeners stand, are left out, and a weather zone the grid misses gets one inside it. ``within`` (x_min, y_min, x_max, y_max) keeps only the cells it overlaps.""" x0, y0, x1, y1 = self.layout.extent width, depth = x1 - x0, y1 - y0 if spacing is None: spacing = math.sqrt(width * depth / WIND_ARROWS) # Two rows at least where there is room: sources and listeners often stand in a # line down the middle. nx, ny = ( max(1 if side < 0.5 * spacing else 2, math.ceil(side / spacing)) for side in (width, depth) ) columns, rows = np.arange(nx), np.arange(ny) if within is not None: u0, v0, u1, v1 = within columns = columns[ (x0 + (columns + 1) * width / nx > u0) & (x0 + columns * width / nx < u1) ] rows = rows[(y0 + (rows + 1) * depth / ny > v0) & (y0 + rows * depth / ny < v1)] xs = x0 + (columns + 0.5) * width / nx ys = y0 + (rows + 0.5) * depth / ny points = np.stack(np.meshgrid(xs, ys), axis=-1).reshape(-1, 2) cell = min(width / nx, depth / ny) reach = WIND_REACH * cell / float(self.speeds.max()) if self.windy else 0.0 weather = self.weather_at(points) keep = self.speeds[weather] > 0.0 clear = np.asarray(clear if clear is not None else [], dtype=float).reshape(-1, 2) if len(clear): half = 0.5 * reach * (self.speeds[weather] * self.directions[weather][:, :2].T).T start, along = points - half, 2.0 * half ahead = clear[None] - start[:, None] # (n, m) t = ( np.einsum("nmd,nd->nm", ahead, along) / np.maximum(np.einsum("nd,nd->n", along, along), 1e-300)[:, None] ) nearest = start[:, None] + np.clip(t, 0.0, 1.0)[..., None] * along[:, None] gap = np.linalg.norm(nearest - clear[None], axis=-1).min(axis=1) keep &= gap >= 0.3 * cell points, weather = points[keep], weather[keep] held = set(weather.tolist()) for k in range(1, len(self.polygons)): centre = self.centre(k) if k not in held and centre is not None and self.speeds[k] > 0.0: points, weather = np.vstack([points, centre]), np.append(weather, k) vectors = reach * (self.speeds[weather] * self.directions[weather].T).T return WindArrows(points.reshape(-1, 2), vectors.reshape(-1, 3), weather, reach, cell)
[docs] class WindArrows(NamedTuple): """The arrows of the wind over the ground (see :meth:`WindMap.arrows`).""" #: (n, 2) the middle of each arrow (m). middles: np.ndarray #: (n, 3) each arrow, horizontal, from its tail to its tip (m). vectors: np.ndarray #: (n,) the weather each arrow shows: 0 the scene's own, k its zone k. weather: np.ndarray #: How long an arrow is per m/s of wind (m). reach: float #: The size of the grid's cells (m). cell: float
def _arrows(starts, vectors, radius: float) -> pyvista.PolyData: """Arrows from each of ``starts`` (n, 3) along and as long as its row of ``vectors``, as one surface, all as thick: tips ``radius`` metres in radius (less on an arrow too short for them).""" pv = _pyvista() starts, vectors = np.asarray(starts, dtype=float), np.asarray(vectors, dtype=float) parts = [] for start, vector in zip(starts, vectors, strict=True): length = float(np.linalg.norm(vector)) if length <= 0.0: continue tip = min(radius, 0.2 * length) parts.append( pv.Arrow( start=start, direction=vector, tip_length=min(0.35, 2.5 * tip / length), tip_radius=tip / length, shaft_radius=0.4 * tip / length, scale=length, ) ) return pv.merge(parts) if parts else pv.PolyData() def _profile_points(wind: WindMap, arrows: WindArrows, clear) -> dict[int, np.ndarray]: """Where each windy weather's mast stands, in the middle of one of its ``arrows``: the one nearest the middle of the ground (of a zone, for a zone's) among those three cells or more from the sources and listeners (``clear``, (m, 2)), or failing that the one farthest from them.""" x0, y0, x1, y1 = wind.layout.extent out = {} for k in np.flatnonzero(wind.speeds > 0.0): mine = arrows.middles[arrows.weather == k] if len(mine) == 0: continue middle = np.array([(x0 + x1) / 2, (y0 + y1) / 2]) if k == 0 else wind.centre(int(k)) apart = np.full(len(mine), 3.0 * arrows.cell) if len(clear): nearest = np.linalg.norm(mine[:, None] - clear[None], axis=-1).min(axis=1) apart = np.minimum(apart, nearest) # Clear first, then nearest the middle. best = np.lexsort((np.linalg.norm(mine - middle, axis=1), -apart))[0] out[int(k)] = mine[best] return out def _plan_points(room: Room) -> np.ndarray: """(n, 2) what the sources and listeners take up seen from above, for the wind's arrows to keep clear of: where they stand, and points along the arrows the 3D view draws from them the way they face.""" items = [*room.scene.sources, *room.scene.listeners] if not items: return np.zeros((0, 2)) lo, hi = np.array(room.report.bounds_min), np.array(room.report.bounds_max) forward = np.array([item.orientation.forward() for item in items], dtype=float) positions = np.array([item.position for item in items], dtype=float) _radii, arrows = marker_sizes(positions, float(np.linalg.norm(hi - lo)) or 1.0, forward) drawn = [d is None or not d.omni for d in room.directivities] drawn += [True] * len(room.scene.listeners) along = np.linspace(0.0, 1.0, 9) points = [positions[:, :2]] for position, way, length, shown in zip(positions, forward, arrows, drawn, strict=True): if shown: points.append(position[:2] + np.outer(along * length, way[:2])) return np.vstack(points)
[docs] def plot_wind( room: Room, plotter: pyvista.Plotter, *, field: bool = True, profile: bool = False, render: bool = True, ) -> list: """Add the wind over an outdoor ``room``'s ground to ``plotter``. ``field``: sky blue arrows the way it blows, as long as it is strong, at the height the scene gives the wind's speed at above the ground, and each weather zone as see-through walls up to that height with its name and wind. ``profile``: a mast in each weather where the wind blows, with arrows at heights up it and a curve through the wind at every height, how the wind grows with height over the ground. Nothing indoors or in still air. Returns the legend entry of the wind.""" wind = WindMap.of(room) if wind is None: return [] pv = _pyvista() layout = wind.layout zones, labels = [], [] for k in range(1, len(wind.polygons)): polygon = wind.polygons[k] if polygon is None or not field: continue floor = layout.ground_at(polygon) # Under the sky, a little, where the sky is lower than the wind's height. top = floor + np.minimum(wind.height, 0.95 * (layout.sky - floor)) n = len(polygon) rings = np.vstack([np.column_stack([polygon, floor]), np.column_stack([polygon, top])]) walls = [[4, j, (j + 1) % n, n + (j + 1) % n, n + j] for j in range(n)] zones.append(pv.PolyData(rings, faces=np.ravel(walls))) edges = [[n + 1, *range(n), 0], [n + 1, *range(n, 2 * n), n]] zones.append(pv.PolyData(rings, lines=np.ravel(edges))) centre = wind.centre(k) high = float(layout.ground_at(centre[None])[0]) + 1.15 * float(np.max(top - floor)) labels.append(([*centre, high], wind.label(k))) for part in zones: line = part.n_lines > 0 plotter.add_mesh( part, color=WIND_COLOUR, opacity=0.7 if line else 0.12, line_width=1.5, pickable=False, render=False, ) legend = [] if wind.windy: clear = _plan_points(room) arrows = wind.arrows(clear=clear) middles, vectors = arrows.middles, arrows.vectors ground = layout.ground_at(middles) lift = np.minimum(wind.height, 0.95 * (layout.sky - ground)) # As thick as the markers of the sources and listeners make readable. lo, hi = np.array(room.report.bounds_min), np.array(room.report.bounds_max) everything = [item.position for item in (*room.scene.sources, *room.scene.listeners)] radius = min( 0.3 * marker_radius(everything, float(np.linalg.norm(hi - lo)) or 1.0), 0.15 * WIND_REACH * arrows.cell, ) masts = _profile_points(wind, arrows, clear) if profile else {} # Buildings taller than the arrows hide them: none inside one. roofs = np.full(len(middles), -np.inf) for _name, footprint, roof in layout.buildings: inside = in_polygon(middles, footprint) roofs[inside] = np.maximum(roofs[inside], roof) keep = np.full(len(middles), field) & (roofs < ground + lift) for at in masts.values(): keep &= np.linalg.norm(middles - at, axis=1) > 1e-9 # the mast's top arrow if keep.any(): centres = np.column_stack([middles, ground + lift]) plotter.add_mesh( _arrows(centres[keep] - 0.5 * vectors[keep], vectors[keep], radius), color=WIND_COLOUR, opacity=0.85, pickable=False, render=False, ) for k, at in masts.items(): labels.extend(_plot_mast(wind, k, at, arrows.reach, radius, plotter)) legend.append([_(WIND_KEY).format(speed=wind.speeds[0], height=wind.height), WIND_COLOUR]) if labels: plotter.add_point_labels( np.array([at for at, _text in labels], dtype=float), [text for _at, text in labels], font_size=11, text_color=WIND_COLOUR, shape_color=PANEL, shape_opacity=0.8, show_points=False, always_visible=True, render=False, ) if render: plotter.render() return legend
def _plot_mast(wind: WindMap, k: int, at, reach: float, radius: float, plotter) -> list: """Add weather ``k``'s mast at ``at`` (2,): a pole from the ground up to the map's height, arrows from it at heights evenly up it, ``reach`` metres long per m/s and as thick as the wind's (``radius``) or less to keep apart, and a curve through the wind at every height between; returns the label of its lowest arrow (the highest's wind is the one the arrows over the ground show).""" pv = _pyvista() weather, direction = wind.weathers[k], wind.directions[k] floor = float(wind.layout.ground_at(at[None])[0]) top = min(wind.height, 0.95 * (wind.layout.sky - floor)) base = np.array([at[0], at[1], floor]) heights = np.linspace(0.0, top, 49) curve = ( base + np.outer(heights, [0, 0, 1]) + np.outer(reach * weather.wind_speed(heights), direction) ) plotter.add_mesh( pv.Line(base, base + [0.0, 0.0, top]), color="white", line_width=2.0, pickable=False, render=False, ) plotter.add_mesh( pv.lines_from_points(curve), color=WIND_COLOUR, line_width=2.0, pickable=False, render=False ) levels = top * np.arange(1, PROFILE_ARROWS + 1) / PROFILE_ARROWS starts = base + np.outer(levels, [0, 0, 1]) vectors = np.outer(reach * weather.wind_speed(levels), direction) arrows = _arrows(starts, vectors, min(radius, 0.25 * top / PROFILE_ARROWS)) plotter.add_mesh(arrows, color=WIND_COLOUR, pickable=False, render=False) text = _(PROFILE_SPEED).format(speed=float(weather.wind_speed(levels[0])), height=levels[0]) return [(starts[0] + vectors[0], text)]
[docs] def plot_room( room: Room, plotter: pyvista.Plotter | None = None, *, opacity: float = 0.45, show_labels: bool = True, paths: EarlyReflections | None = None, max_order: int | None = None, coverage: CoverageMap | None = None, parameter: str = "g", band: int = 4, part: str = "value", leaks: Leaks | None = None, wind: bool = True, ) -> pyvista.Plotter: """Add the room to ``plotter`` (a new one if None) and return it. ``paths`` adds early reflection paths (from :func:`acoustic_spaces.engine.early_paths` or a response's ``early``), coloured by order up to ``max_order``. ``coverage`` adds a coverage map of one ``parameter`` and ``band``, or of a ``part`` of its spread (see :func:`plot_coverage`). ``leaks`` adds the open edges and the rays that escape through them (see :func:`plot_leaks`). Outdoors, ``wind`` adds the wind and the weather zones (see :func:`plot_wind`). """ pv = _pyvista() if plotter is None: plotter = pv.Plotter() legend = [] # Outdoors, the open sky would hide the rest: only its edges, where the ground ends. shown = room.shown_faces() if not shown.all(): plotter.add_mesh( _outline(room_polydata(room, np.flatnonzero(~shown))), color=EDGE_COLOUR, line_width=1.0 ) for k, name in enumerate(room.material_names): faces = np.flatnonzero((room.face_materials == k) & shown) if len(faces) == 0: continue mesh = room_polydata(room, faces) colour = MATERIAL_COLOURS[k % len(MATERIAL_COLOURS)] plotter.add_mesh(mesh, color=colour, opacity=opacity) plotter.add_mesh(_outline(mesh), color=EDGE_COLOUR, line_width=1.5) legend.append([name, colour]) missing = np.flatnonzero((room.face_materials == UNASSIGNED) & shown) if len(missing): mesh = room_polydata(room, missing) plotter.add_mesh(mesh, color=UNASSIGNED_COLOUR, opacity=max(opacity, 0.8)) plotter.add_mesh(_outline(mesh), color=EDGE_COLOUR, line_width=1.5) legend.append([_("no material"), UNASSIGNED_COLOUR]) legend.extend(plot_vegetation(room, plotter)) if wind: legend.extend(plot_wind(room, plotter, render=False)) lo, hi = np.array(room.report.bounds_min), np.array(room.report.bounds_max) size = float(np.linalg.norm(hi - lo)) or 1.0 sources, listeners = room.scene.sources, room.scene.listeners everything = [*sources, *listeners] radii, arrows = marker_sizes( [item.position for item in everything], size, [item.orientation.forward() for item in everything], apart=[item.in_use for item in everything], # those left out are drawn faded ) points, names = [], [] for k, (source, directivity) in enumerate(zip(sources, room.directivities, strict=True)): radius, arrow = radii[k], arrows[k] opacity = 1.0 if source.in_use else 0.3 # left out of simulations: faded sphere = pv.Sphere(radius=radius, center=source.position) plotter.add_mesh(sphere, color=SOURCE_COLOUR, opacity=opacity) extent = extent_polydata(source, radius) if extent is not None: plotter.add_mesh(extent, color=SOURCE_COLOUR, opacity=0.6 * opacity) if not directivity.omni: direction = source.orientation.forward() shape = pv.Arrow(start=source.position, direction=direction, scale=arrow) plotter.add_mesh(shape, color=SOURCE_COLOUR, opacity=opacity) balloon = balloon_polydata( directivity, source.position, source.orientation.rotation(), size=arrow ) plotter.add_mesh( balloon, scalars="level", cmap="magma", clim=(-30, 0), opacity=0.55 * opacity, show_scalar_bar=False, ) points.append(np.add(source.position, [0.0, 0.0, 1.5 * radius])) names.append(source.name) for k, listener in enumerate(listeners, len(sources)): radius, arrow = radii[k], arrows[k] opacity = 1.0 if listener.in_use else 0.3 sphere = pv.Sphere(radius=radius, center=listener.position) plotter.add_mesh(sphere, color=LISTENER_COLOUR, opacity=opacity) direction = listener.orientation.forward() shape = pv.Arrow(start=listener.position, direction=direction, scale=arrow) plotter.add_mesh(shape, color=LISTENER_COLOUR, opacity=opacity) points.append(np.add(listener.position, [0.0, 0.0, 1.5 * radius])) names.append(listener.name) legend.append(["source", SOURCE_COLOUR]) legend.append(["listener", LISTENER_COLOUR]) if paths is not None: legend.extend(plot_paths(paths, plotter, max_order=max_order)) if coverage is not None: plot_coverage(coverage, plotter, parameter=parameter, band=band, part=part) if leaks is not None: legend.extend(plot_leaks(leaks, room, plotter, render=False)) if show_labels and points: plotter.add_point_labels( np.asarray(points, dtype=float), names, font_size=14, text_color="white", shape_color=PANEL, shape_opacity=0.8, show_points=False, always_visible=True, ) plotter.set_background(BACKGROUND[0], top=BACKGROUND[1]) # Small and in a corner, where it hides little of the room and no colour bar. plotter.add_legend( legend, bcolor=PANEL, face="rectangle", loc="upper right", size=(0.15, 0.026 * len(legend)), ) plotter.add_text(room.scene.name, font_size=11, color="white") plotter.add_axes() plotter.view_isometric() return plotter
[docs] def show_room( room: Room, screenshot: str | Path | None = None, window_size: tuple[int, int] = (1280, 800), **kwargs, ) -> None: """Open the room in a window, or save a PNG to ``screenshot`` without one. Keyword arguments go to :func:`plot_room` (for example ``paths``). """ pv = _pyvista() plotter = pv.Plotter(off_screen=screenshot is not None, window_size=list(window_size)) plot_room(room, plotter, **kwargs) if screenshot is not None: plotter.screenshot(str(screenshot)) plotter.close() else: plotter.show()
def _particle_scalars(particles: Particles, frame: int, color: str, db_range: float): if color == "order": return particles.order[frame].astype(float) level = 10.0 * np.log10(np.maximum(particles.energy[frame], 1e-30)) return np.maximum(level, -db_range)
[docs] def animate_particles( room: Room, particles: Particles, path: str | Path | None = None, *, fps: int = 25, color: str = "energy", db_range: float = 40.0, window_size: tuple[int, int] = (1024, 640), ) -> None: """Show sound particles (from :func:`acoustic_spaces.engine.trace_particles`) moving through the room: in a window with a time slider, or saved to ``path`` as an animated GIF or an MP4 video. ``color`` is ``"energy"`` (level in dB relative to a particle's share at emission, down to ``-db_range``) or ``"order"`` (reflections so far). """ if color not in ("energy", "order"): raise ValueError("color must be 'energy' or 'order'") suffix = None if path is None else Path(path).suffix.lower() if suffix not in (None, ".gif", ".mp4"): raise ValueError("animations are saved as .gif or .mp4") pv = _pyvista() plotter = pv.Plotter(off_screen=path is not None, window_size=list(window_size)) plot_room(room, plotter, opacity=0.12) cloud = pv.PolyData(particles.positions[0].copy()) cloud["value"] = _particle_scalars(particles, 0, color, db_range) if color == "order": top = max(int(particles.order.max()), 1) title, clim, cmap = _("reflections"), [0, top], "turbo" else: title = _("level at {band} Hz (dB)").format(band=particles.band_hz) clim, cmap = [-db_range, 0.0], "inferno" plotter.add_mesh( cloud, scalars="value", clim=clim, cmap=cmap, render_points_as_spheres=True, point_size=max(3.0, window_size[0] / 200.0), scalar_bar_args={"title": title, "color": "white", "fmt": "%.0f"}, ) clock = plotter.add_text("t = 0.0 ms", position="lower_left", font_size=12, color="white") def show(frame: int) -> None: cloud.points = particles.positions[frame] cloud["value"] = _particle_scalars(particles, frame, color, db_range) clock.SetText(0, f"t = {1e3 * particles.times[frame]:.1f} ms") if path is None: last = len(particles.times) - 1 def on_slider(value: float) -> None: show(int(round(value / (1e3 * particles.times[-1] or 1.0) * last))) plotter.add_slider_widget( on_slider, [0.0, 1e3 * float(particles.times[-1])], value=0.0, title=_("time (ms)"), color="white", pointa=(0.35, 0.92), pointb=(0.95, 0.92), ) plotter.show() return _record(plotter, path, fps, len(particles.times), show)
# The viz extra installs both; named here for an install from before it did. _MP4_NEEDS = ( 'MP4 videos need imageio and imageio-ffmpeg: pip install "imageio>=2.31" ' '"imageio-ffmpeg>=0.5", or uv sync --extra viz in a source checkout' ) def _record(plotter, path: str | Path, fps: int, frames: int, show, sound=None) -> None: """Save ``frames`` frames of ``plotter``, each set up by ``show(frame)``, to ``path``: an animated GIF or an MP4 video, with the WAV file ``sound`` as an MP4's sound track. Closes the plotter.""" mp4 = Path(path).suffix.lower() == ".mp4" if mp4: audio = {} if sound is None else {"audio_path": str(sound), "audio_codec": "aac"} try: plotter.open_movie(str(path), framerate=fps, **audio) except ImportError as exc: plotter.close() raise ImportError(_MP4_NEEDS) from exc images = [] for frame in range(frames): show(frame) if mp4: plotter.write_frame() else: plotter.render() images.append(plotter.screenshot(return_img=True)) plotter.close() if not mp4: from PIL import Image # One palette for every frame, so colours that stay put do not flicker. sample = np.concatenate([images[0], images[len(images) // 2], images[-1]]) palette = Image.fromarray(sample).quantize(colors=255) frames = [Image.fromarray(image).quantize(palette=palette, dither=0) for image in images] frames[0].save( str(path), save_all=True, append_images=frames[1:], duration=1000 / fps, loop=0 )
[docs] def check_video(path: str | Path) -> None: """Raise what saving an animation to ``path`` would, before the work of making it: ValueError unless it is a .gif or .mp4, ImportError without PyVista or, for an MP4, without imageio and imageio-ffmpeg.""" suffix = Path(path).suffix.lower() if suffix not in (".gif", ".mp4"): raise ValueError("animations are saved as .gif or .mp4") _pyvista() if suffix == ".mp4": import importlib.util if not all(importlib.util.find_spec(name) for name in ("imageio", "imageio_ffmpeg")): raise ImportError(_MP4_NEEDS)
[docs] def animate_walk( room: Room, walk: WalkResponses, path: str | Path, *, fps: int = 25, window_size: tuple[int, int] = (1024, 640), sound: str | Path | None = None, ) -> None: """Save a walk (from :func:`acoustic_spaces.walkthrough.simulate_walk`) as an animated GIF or an MP4 video: the room, the path and the walker going along it, in time with the sound of :func:`~acoustic_spaces.walkthrough.render_walk`. ``room`` is the scene's room. ``sound``, a WAV file of that sound in one or two channels, becomes an MP4's sound track, and the video then lasts as long as the sound (a GIF has none).""" check_video(path) duration = walk.duration_s mp4 = Path(path).suffix.lower() == ".mp4" if sound is not None and mp4: from acoustic_spaces.audio import read_wav data, rate = read_wav(sound) if data.shape[1] > 2: raise ValueError(f"a video's sound has one or two channels, not {data.shape[1]}") duration = max(duration, len(data) / rate) pv = _pyvista() plotter = pv.Plotter(off_screen=True, window_size=list(window_size)) plot_room(room, plotter, opacity=0.12) points = walk.points plotter.add_mesh(pv.lines_from_points(points.positions), color="white", line_width=3) size = max(0.2, 0.02 * float(np.ptp(room.mesh.vertices, axis=0).max())) marker = pv.Sphere(radius=size, center=(0.0, 0.0, 0.0)) shape = marker.points.copy() marker.points = shape + points.positions[0] colour = SOURCE_COLOUR if walk.kind == "sources" else LISTENER_COLOUR plotter.add_mesh(marker, color=colour) yaws = points.yaws if yaws is None and walk.result is not None: # It keeps the orientation it has in the scene. scene = walk.result.room.scene walkers = scene.listeners if walk.kind == "listeners" else scene.sources first = next(w for w in walkers if w.name == walk.names[0]) yaws = np.full(len(points.times), first.orientation.yaw) arrow = None if yaws is not None: # An arrow the way the walker faces, just above it so that the path does not # hide it, and its yaw in the text. arrow = pv.Arrow( start=(0.0, 0.0, 0.0), direction=(1.0, 0.0, 0.0), tip_length=0.3, tip_radius=0.1, shaft_radius=0.04, scale=8.0 * size, ) arrow.points += (0.0, 0.0, 1.5 * size) arrow_shape = arrow.points.copy() yaws = np.unwrap(np.radians(yaws)) plotter.add_mesh(arrow, color=FACING_COLOUR, lighting=False) clock = plotter.add_text("", position="lower_left", font_size=12, color="white") plotter.view_isometric() frames = int(math.floor(duration * fps)) + 1 def show(frame: int) -> None: t = frame / fps where = [np.interp(t, points.times, points.positions[:, k]) for k in range(3)] marker.points = shape + where text = f"{walk.name}: {t:.1f} s" if arrow is not None: yaw = float(np.interp(t, points.times, yaws)) c, s = math.cos(yaw), math.sin(yaw) turn = np.array([[c, -s, 0.0], [s, c, 0.0], [0.0, 0.0, 1.0]]) arrow.points = arrow_shape @ turn.T + where # Translators: added to the name and time shown on a walkthrough video. text += _(", facing yaw {yaw:.0f}°").format( yaw=180.0 - (180.0 - math.degrees(yaw)) % 360.0 ) clock.SetText(0, text) _record(plotter, path, fps, frames, show, sound if mp4 else None)
[docs] def animate_movement( room: Room, movement: Movement, path: str | Path, *, fps: int = 25, window_size: tuple[int, int] = (1024, 640), sound: str | Path | None = None, ) -> None: """Save a movement (from :func:`acoustic_spaces.walkthrough.simulate_movement`) as an animated GIF or an MP4 video: the room, every mover's path and the movers going along them on one clock, each with an arrow the way it faces, the still sources and listeners where they stand. ``sound``, a WAV file of one listener's sound in one or two channels, becomes an MP4's sound track, and the video then lasts as long as the sound (a GIF has none).""" from acoustic_spaces.spatial.rotation import angles_matrix from acoustic_spaces.walkthrough import knots, movers check_video(path) duration = movement.duration_s mp4 = Path(path).suffix.lower() == ".mp4" if sound is not None and mp4: from acoustic_spaces.audio import read_wav data, rate = read_wav(sound) if data.shape[1] > 2: raise ValueError(f"a video's sound has one or two channels, not {data.shape[1]}") duration = max(duration, len(data) / rate) pv = _pyvista() plotter = pv.Plotter(off_screen=True, window_size=list(window_size)) moving = movers(room.scene) names = {item.name for _, item in moving} # The room with the still sources and listeners only: the movers are drawn going. still = { kind: [item for item in getattr(room.scene, kind) if item.name not in names] for kind in ("sources", "listeners") } background = dataclasses.replace(room, scene=room.scene.model_copy(update=still)) plot_room(background, plotter, opacity=0.12) size = max(0.2, 0.02 * float(np.ptp(room.mesh.vertices, axis=0).max())) markers = [] for kind, item in moving: path_of = knots(item) line = path_of.at(np.linspace(0.0, path_of.duration_s, 10 * len(path_of.times)))[0] plotter.add_mesh(pv.lines_from_points(line), color="white", line_width=3) marker = pv.Sphere(radius=size, center=(0.0, 0.0, 0.0)) colour = SOURCE_COLOUR if kind == "sources" else LISTENER_COLOUR plotter.add_mesh(marker, color=colour) # An arrow the way it faces, just above it so that the path does not hide it. arrow = pv.Arrow( start=(0.0, 0.0, 0.0), direction=(1.0, 0.0, 0.0), tip_length=0.3, tip_radius=0.1, shaft_radius=0.04, scale=8.0 * size, ) arrow.points += (0.0, 0.0, 1.5 * size) plotter.add_mesh(arrow, color=FACING_COLOUR, lighting=False) markers.append( (item.name, path_of, marker, marker.points.copy(), arrow, arrow.points.copy()) ) labels = pv.PolyData(np.array([item.position for _, item in moving], dtype=float)) plotter.add_point_labels( labels, [item.name for _, item in moving], show_points=False, always_visible=True, font_size=14, text_color="white", shape_color=PANEL, ) clock = plotter.add_text("", position="lower_left", font_size=12, color="white") plotter.view_isometric() frames = int(math.floor(duration * fps)) + 1 def show(frame: int) -> None: t = frame / fps places = [] for _name, path_of, marker, shape, arrow, arrow_shape in markers: where, angles = path_of.at(t) marker.points = shape + where arrow.points = arrow_shape @ angles_matrix(*angles).T + where places.append(where + (0.0, 0.0, 3.0 * size)) labels.points = np.array(places) clock.SetText(0, f"{t:.1f} s") _record(plotter, path, fps, frames, show, sound if mp4 else None)
# -- response plots ---------------------------------------------------------------- def _figure(**kwargs): """A matplotlib figure that needs no display or pyplot backend.""" try: from matplotlib.figure import Figure except ImportError as exc: # pragma: no cover - exercised without the extra raise ImportError(f"response plots need matplotlib: {install_hint('viz')}") from exc return Figure(**kwargs) def _dark(ax, grid: bool = True) -> None: ax.set_facecolor(PANEL) ax.tick_params(colors="white") for spine in ax.spines.values(): spine.set_color("#6b6e7a") if grid: ax.grid(True, color="#3a3d4a", linewidth=0.6) ax.xaxis.label.set_color("white") ax.yaxis.label.set_color("white") ax.title.set_color("white") def _two_panels(): """A dark figure with two stacked panels.""" fig = _figure(figsize=(10, 7), layout="constrained") axes = fig.subplots(2, 1) fig.patch.set_facecolor(BACKGROUND[0]) for ax in axes: _dark(ax) return fig, axes def _legend(ax, **kwargs) -> None: legend = ax.legend(facecolor=PANEL, edgecolor="#6b6e7a", fontsize=8, **kwargs) for text in legend.get_texts(): text.set_color("white")
[docs] def plot_response(response: Response, path: str | Path | None = None, *, band: int = 4): """Echogram and decay curves of one response; saved to ``path`` if given. The echogram shows the energy per millisecond in one octave band (``band`` indexes ``OCTAVE_BANDS_HZ``; 4 is 1 kHz) with the early specular paths as stems coloured by order. The decay panel shows the backward-integrated curve of every band. A response in third-octave bands shows them averaged into octave bands. Returns the matplotlib figure. """ from acoustic_spaces.materials.bands import OCTAVE_BANDS_HZ, to_octaves from acoustic_spaces.parameters import decay_curve energy = response.octave_energy() t_ms = np.arange(energy.shape[1]) * response.time_step * 1e3 reference = 1.0 / (4.0 * np.pi * 100.0) # free field at 10 m, as for G fig, (ax_e, ax_d) = _two_panels() with np.errstate(divide="ignore"): late = to_octaves(response.late)[band] early = to_octaves(response.early.energy, axis=1)[:, band] late_db = 10.0 * np.log10(np.maximum(late, 1e-30) / reference) early_db = 10.0 * np.log10(np.maximum(early, 1e-30) / reference) late_t = np.arange(len(late_db)) * response.time_step * 1e3 ax_e.fill_between(late_t, late_db, -100, step="post", color="#4da3ff", alpha=0.35, lw=0) ax_e.step(late_t, late_db, where="post", color="#4da3ff", lw=0.8, label=_("late (per ms)")) floor = float(np.max(early_db, initial=np.max(late_db, initial=0.0))) - 70.0 for group in path_groups(response.early): delays = response.early.delay_s[group.mask] * 1e3 ax_e.vlines(delays, floor, early_db[group.mask], color=group.colour, lw=1.2) ax_e.plot([], [], color=group.colour, label=group.label) ax_e.set_ylim(floor, floor + 80.0) ax_e.set_xlim(0, t_ms[-1] if len(t_ms) else 1) ax_e.set_xlabel(_("time (ms)")) ax_e.set_ylabel(_("level re 10 m free field (dB)")) ax_e.set_title( _("{source} to {listener}: echogram, {band} Hz band").format( source=response.source, listener=response.listener, band=OCTAVE_BANDS_HZ[band] ) ) _legend(ax_e, loc="upper right") start = int(response.direct_delay_s / response.time_step) for b, f in enumerate(OCTAVE_BANDS_HZ): decay = decay_curve(energy[b, start:], response.time_step) if not np.isfinite(decay[0]): continue ax_d.plot( t_ms[start:] - t_ms[start], decay, color=BAND_COLOURS[b], lw=1.2, label=_band_name(f) ) ax_d.set_ylim(-70, 2) ax_d.set_xlim(0, t_ms[-1] if len(t_ms) else 1) ax_d.set_xlabel(_("time after the direct sound (ms)")) ax_d.set_ylabel(_("decay (dB)")) ax_d.set_title(_("backward-integrated decay per octave band")) _legend(ax_d, ncol=4) if path is not None: fig.savefig(str(path), dpi=120, facecolor=fig.get_facecolor()) return fig
def _direction_axes(ax, title: str) -> None: ax.set_xlim(180, -180) # left of the listener on the left ax.set_ylim(-90, 90) ax.set_xticks([180, 135, 90, 45, 0, -45, -90, -135, -180]) back, left, front, right = _("back"), _("left"), _("front"), _("right") ax.set_xticklabels([back, "135", left, "45", front, "-45", right, "-135", back]) ax.set_yticks([-90, -45, 0, 45, 90]) ax.set_xlabel(_("azimuth (degrees)")) ax.set_ylabel(_("elevation (degrees)")) ax.set_title(title)
[docs] def plot_directions(response: Response, path: str | Path | None = None, *, band: int = 4): """Where the sound comes from, as the listener faces: early reflections (dots sized by level and coloured by delay) and the late energy per arrival direction, in one octave band (``band`` indexes ``OCTAVE_BANDS_HZ``; 4 is 1 kHz). Azimuth runs from the left to the right of the listener. A response in third-octave bands shows them averaged into octave bands. Returns the matplotlib figure. """ from acoustic_spaces.materials.bands import OCTAVE_BANDS_HZ, to_octaves from acoustic_spaces.spatial.directions import from_angles, to_angles, to_head fig, (ax_e, ax_l) = _two_panels() reference = 1.0 / (4.0 * np.pi * 100.0) early = response.early if len(early): az, el = to_angles(to_head(early.direction, response.orientation)) with np.errstate(divide="ignore"): in_band = to_octaves(early.energy, axis=1)[:, band] level = 10.0 * np.log10(np.maximum(in_band, 1e-30) / reference) floor = level.max() - 40.0 keep = level > floor delay_ms = (early.delay_s - response.direct_delay_s) * 1e3 order = np.argsort(-delay_ms[keep]) # earliest on top dots = ax_e.scatter( az[keep][order], el[keep][order], s=4 + 200 * ((level[keep][order] - floor) / 40.0) ** 2, c=delay_ms[keep][order], cmap="plasma", edgecolors="white", linewidths=0.4, ) bar = fig.colorbar(dots, ax=ax_e, pad=0.01) bar.set_label(_("delay after the direct sound (ms)"), color="white") bar.ax.tick_params(colors="white") _direction_axes( ax_e, _( "{source} to {listener}: early reflections, {band} Hz band (dot size: level, top 40 dB)" ).format(source=response.source, listener=response.listener, band=OCTAVE_BANDS_HZ[band]), ) if len(response.late_directions) and response.late_directional.size: energy = to_octaves(response.late_directional, axis=1)[:, band].sum(axis=1) heads = to_head(response.late_directions, response.orientation) grid_az, grid_el = np.meshgrid(np.arange(179, -180, -2.0), np.arange(-89, 90, 2.0)) cells = from_angles(grid_az, grid_el) nearest = np.argmax(cells.reshape(-1, 3) @ heads.T, axis=1).reshape(grid_az.shape) # Energy per steradian: each direction stands for an equal share of the sphere. with np.errstate(divide="ignore"): level = 10.0 * np.log10(np.maximum(energy / energy.max(), 1e-6)) image = ax_l.imshow( level[nearest], extent=(180, -180, -90, 90), origin="lower", cmap="magma", vmin=-20, vmax=0, aspect="auto", interpolation="nearest", ) bar = fig.colorbar(image, ax=ax_l, pad=0.01) bar.set_label(_("level re loudest direction (dB)"), color="white") bar.ax.tick_params(colors="white") title = _("late energy by arrival direction, {band} Hz band").format( band=OCTAVE_BANDS_HZ[band] ) else: ax_l.text( 0, 0, _("late energy arrives evenly from all directions"), color="white", ha="center", va="center", ) title = _("late energy by arrival direction") _direction_axes(ax_l, title) if path is not None: fig.savefig(str(path), dpi=120, facecolor=fig.get_facecolor()) return fig
def _polar_panels(): """A dark figure with two polar panels side by side.""" fig = _figure(figsize=(11, 5.6), layout="constrained") axes = fig.subplots(1, 2, subplot_kw={"projection": "polar"}) fig.patch.set_facecolor(BACKGROUND[0]) for ax in axes: ax.set_facecolor(PANEL) ax.tick_params(colors="white") ax.spines["polar"].set_color("#6b6e7a") ax.grid(True, color="#4a4d5a", linewidth=0.6) ax.title.set_color("white") return fig, axes
[docs] def plot_directivity( directivity: Directivity, path: str | Path | None = None, *, db_range: float = 30.0 ): """Polar patterns of a source directivity in every octave band, in dB re the loudest direction of each band: the horizontal plane (seen from above, front at the top and the source's left on the left) and the vertical plane through the front (seen from the side, front on the right and up at the top). Returns the matplotlib figure. """ from acoustic_spaces.materials.bands import OCTAVE_BANDS_HZ directivity = directivity.in_bands("octave") # an array's is in third octaves angle = np.radians(np.arange(0.0, 360.5, 1.0)) planes = { "horizontal": np.column_stack([np.cos(angle), np.sin(angle), np.zeros_like(angle)]), "vertical": np.column_stack([np.cos(angle), np.zeros_like(angle), np.sin(angle)]), } loudest = directivity.energy(planes["horizontal"]).max(axis=0) loudest = np.maximum(loudest, directivity.energy(planes["vertical"]).max(axis=0)) fig, axes = _polar_panels() for ax, (plane, directions), title, zero in zip( axes, planes.items(), (_("horizontal plane (from above)"), _("vertical plane (from the side)")), ("N", "E"), strict=True, ): ax.set_theta_zero_location(zero) with np.errstate(divide="ignore", invalid="ignore"): level = 10.0 * np.log10(directivity.energy(directions) / loudest) same = np.allclose(level, level[:, :1], atol=0.01, equal_nan=True) for b, f in enumerate(OCTAVE_BANDS_HZ): if same and b != 4: continue # the same pattern in every band: one line label = _("every band") if same else _band_name(f) ax.plot( angle, np.clip(level[:, b], -db_range, 0.0), color=BAND_COLOURS[b], lw=1.3, label=label, ) ax.set_rlim(-db_range, 0.0) ticks = np.arange(-db_range, 0.1, 10.0) ax.set_rticks(ticks, [f"{t:.0f} dB" for t in ticks]) ax.set_rlabel_position(200 if plane == "horizontal" else 290) if plane == "horizontal": ax.set_xticks( np.radians([0, 90, 180, 270]), [_("front"), _("left"), _("back"), _("right")] ) else: ax.set_xticks( np.radians([0, 90, 180, 270]), [_("front"), _("up"), _("back"), _("down")] ) ax.set_title(title, pad=14) _legend(axes[1], loc="upper left", bbox_to_anchor=(1.02, 1.0)) index = directivity.index()[4] name = directivity.name or _("directivity") fig.suptitle( # The name on a line of its own: a per-band one is long. _("{name}\ndB re the loudest direction; directivity index {index:.1f} dB at 1 kHz").format( name=name, index=index ), color="white", ) if path is not None: fig.savefig(str(path), dpi=120, facecolor=fig.get_facecolor()) return fig
[docs] def plot_atmosphere( atmosphere: Atmosphere, ground_c: float, path: str | Path | None = None, *, top: float = 100.0, ): """An outdoor atmosphere from the ground to ``top`` metres up: the temperature and the wind's speed (left), and the speed of sound (right) in still air and, with a wind, as sound going with it and against it, the speed that bends sound: towards where it is lower. ``ground_c`` is the temperature at the ground (the scene's air temperature). Returns the matplotlib figure.""" z = np.concatenate([[0.0], np.geomspace(min(0.01, top / 100.0), top, 400)]) fig = _figure(figsize=(10, 5), layout="constrained") fig.patch.set_facecolor(BACKGROUND[0]) left, right = fig.subplots(1, 2, sharey=True) for ax in (left, right): _dark(ax) left.plot(atmosphere.temperature(z, ground_c), z, color="#fdae61", lw=1.5) left.set_xlabel(_("temperature (°C)"), color="#fdae61") left.set_ylabel(_("height above the ground (m)")) wind = atmosphere.wind_speed(z) if np.any(wind > 0.0): speed = left.twiny() speed.plot(wind, z, color="#80b1d3", lw=1.5) speed.set_xlabel(_("wind speed (m/s)"), color="#80b1d3") speed.tick_params(colors="white") speed.set_xlim(left=0.0) right.plot( atmosphere.sound_speed(z, ground_c), z, color="#d9d9d9", lw=1.2, ls="--", label=_("across the wind"), ) along = atmosphere.to_wind() for sign, colour, label in ( (1.0, "#80b1d3", _("downwind")), (-1.0, "#fb8072", _("upwind")), ): right.plot( atmosphere.sound_speed(z, ground_c, sign * along), z, color=colour, lw=1.5, label=label, ) _legend(right, loc="best") else: right.plot(atmosphere.sound_speed(z, ground_c), z, color="#d9d9d9", lw=1.5) right.set_xlabel(_("speed of sound (m/s)")) left.set_ylim(0.0, top) if atmosphere.still: title = _("Still air: sound goes in straight lines") else: title = _("Sound bends towards where the speed of sound is lower") fig.suptitle(title, color="white") if path is not None: fig.savefig(str(path), dpi=120, facecolor=fig.get_facecolor()) return fig
def _decay_curves(decay: BandDecay) -> list[tuple[np.ndarray, np.ndarray] | None]: """Each band's backward-integrated decay (dB) over 1 ms slots from the direct sound on, up to where it sinks into the noise, with the noise taken off and the missing tail added, as the parameters are computed: (times in ms, levels) per band, or None for a band with too little to draw.""" from acoustic_spaces.parameters import decay_curve window = max(1, int(round(1e-3 * decay.sample_rate))) curves = [] for b in range(decay.energy.shape[0]): e = decay.cleaned(b) slots = len(e) // window curve = None if slots >= 2: per_ms = e[: slots * window].reshape(slots, window).sum(axis=1) level = decay_curve(per_ms, 1e-3) if np.isfinite(level[0]): curve = (np.arange(slots) * 1.0, level) curves.append(curve) return curves
[docs] def plot_impulse_response( ir: np.ndarray, sample_rate: float, path: str | Path | None = None, *, title: str | None = None, filters: str = "iec", noise: bool = True, ): """Level and decay curves of a measured (or any) impulse response. The top panel shows the squared response in dB over 1 ms windows and, per octave band with ``noise``, the background noise level found for it. The bottom panel shows each band's backward-integrated decay up to where it sinks into the noise, with the noise taken off and the missing tail added, as the parameters are computed. Returns the matplotlib figure; it is saved to ``path`` if given. """ from acoustic_spaces.materials.bands import OCTAVE_BANDS_HZ from acoustic_spaces.parameters import band_decay ir = np.asarray(ir, dtype=float) decay = band_decay(ir, sample_rate, filters=filters, noise=noise) window = max(1, int(round(1e-3 * sample_rate))) blocks = len(ir) // window power = (ir[: blocks * window] ** 2).reshape(blocks, window).mean(axis=1) peak = float(power.max(initial=0.0)) or 1.0 t_ms = (np.arange(blocks) + 0.5) * window / sample_rate * 1e3 fig, (ax_e, ax_d) = _two_panels() level = 10.0 * np.log10(np.maximum(power / peak, 1e-30)) ax_e.plot(t_ms, level, color="#4da3ff", lw=0.8, label=_("broadband, 1 ms windows")) onset_ms = decay.onset_s * 1e3 for b in range(len(OCTAVE_BANDS_HZ)): if decay.noise[b] > 0: noise_db = 10.0 * np.log10(decay.noise[b] / peak) end_ms = onset_ms + decay.crosspoint[b] / sample_rate * 1e3 ax_e.hlines(noise_db, end_ms, t_ms[-1], color=BAND_COLOURS[b], lw=1.0) ax_e.plot([end_ms], [noise_db], "o", color=BAND_COLOURS[b], ms=3) if np.any(decay.noise > 0): ax_e.plot([], [], "o-", color="#d0d0d0", ms=3, label=_("band noise from its crosspoint")) ax_e.set_ylim(max(float(level.min()), -120.0) - 5.0, 5.0) ax_e.set_xlim(0, t_ms[-1] if len(t_ms) else 1) ax_e.set_xlabel(_("time (ms)")) ax_e.set_ylabel(_("level re peak (dB)")) ax_e.set_title(_("{title}: level").format(title=title) if title else _("level")) _legend(ax_e, loc="upper right") for b, (f, curve) in enumerate(zip(OCTAVE_BANDS_HZ, _decay_curves(decay), strict=True)): if curve is not None: ax_d.plot(*curve, color=BAND_COLOURS[b], lw=1.2, label=_band_name(f)) ax_d.set_ylim(-70, 2) ax_d.set_xlim(0, max(t_ms[-1] - onset_ms, 1.0) if len(t_ms) else 1) ax_d.set_xlabel(_("time after the direct sound (ms)")) ax_d.set_ylabel(_("decay (dB)")) ax_d.set_title(_("backward-integrated decay per octave band, noise removed")) _legend(ax_d, ncol=4) if path is not None: fig.savefig(str(path), dpi=120, facecolor=fig.get_facecolor()) return fig
[docs] def plot_comparison( simulated: np.ndarray, simulated_rate: float, measured: np.ndarray, measured_rate: float, path: str | Path | None = None, *, title: str | None = None, labels: tuple[str, str] = ("simulated", "measured"), filters: str = "iec", noise: bool = True, ): """Decay curves of a simulated and a measured impulse response, one panel per octave band. Each panel overlays the backward-integrated (Schroeder) decays of the two, each from its own direct sound on, as :func:`plot_impulse_response` draws them: up to where the band sinks into its noise, with the noise taken off and the missing tail added. ``labels`` name the two responses in the legend. Returns the matplotlib figure; it is saved to ``path`` if given. """ from acoustic_spaces.materials.bands import OCTAVE_BANDS_HZ from acoustic_spaces.parameters import band_decay fig = _figure(figsize=(12, 6.5), layout="constrained") fig.patch.set_facecolor(BACKGROUND[0]) axes = fig.subplots(2, 4, sharex=True, sharey=True).ravel() for ax, f in zip(axes, OCTAVE_BANDS_HZ, strict=True): _dark(ax) ax.set_title(_band_name(f)) floor_db, end_ms = -70.0, 1.0 for ir, rate, label, colour in zip( (simulated, measured), (simulated_rate, measured_rate), labels, COMPARISON_COLOURS, strict=True, ): decay = band_decay(np.asarray(ir, dtype=float), rate, filters=filters, noise=noise) for ax, curve in zip(axes, _decay_curves(decay), strict=True): if curve is not None: ax.plot(*curve, color=colour, lw=1.2) # Time runs to where the slowest decay leaves the panel at the bottom. below = np.flatnonzero(curve[1] < floor_db) end_ms = max(end_ms, float(curve[0][below[0] if len(below) else -1])) # The legend's entry, drawn empty: a band may have no curve to label. axes[0].plot([], [], color=colour, lw=1.2, label=label) axes[0].set_xlim(0, end_ms) axes[0].set_ylim(floor_db, 2) for ax in axes[4:]: ax.set_xlabel(_("time after the direct sound (ms)")) for ax in axes[::4]: ax.set_ylabel(_("decay (dB)")) _legend(axes[0], loc="upper right") fig.suptitle( title or _("backward-integrated decay per octave band, noise removed"), color="white" ) if path is not None: fig.savefig(str(path), dpi=120, facecolor=fig.get_facecolor()) return fig
# -- coverage maps ----------------------------------------------------------------- #: Colour map of coverage maps. MAP_COLOURS = "turbo" #: Opacity of a coverage map in 3D: see-through, so the sources and listeners at #: listening height, half under its tiles, stay in sight. MAP_OPACITY = 0.7 def _band_name(f: int) -> str: return f"{f} Hz" if f < 1000 else f"{f // 1000} kHz" #: What a map shows of a parameter: its value, or a part of its spread #: (:meth:`~acoustic_spaces.engine.coverage.CoverageMap.spread_of`), each with the name #: it has in a title. MAP_PARTS = { "value": N_("value"), "standard": N_("standard uncertainty"), "low": N_("lower end of the interval"), "high": N_("upper end of the interval"), "at_least": N_("at least"), "at_most": N_("at most"), }
[docs] def map_values(coverage: CoverageMap, parameter: str = "g", band: int = 4, part: str = "value"): """The values a map shows of ``parameter`` (in ``band`` when it has bands, as an index into ``OCTAVE_BANDS_HZ``), in the units of its label, and its title. ``part`` (a key of :data:`MAP_PARTS`) takes, in place of the value, a part of its spread on a map run with one: its standard uncertainty, an end of its interval, or the value it is at least or at most, the last four with their probability in the title.""" from acoustic_spaces.engine.coverage import MAP_PARAMETERS from acoustic_spaces.materials.bands import OCTAVE_BANDS_HZ if parameter not in MAP_PARAMETERS: raise ValueError(f"unknown parameter {parameter!r}; use one of {', '.join(MAP_PARAMETERS)}") if part not in MAP_PARTS: raise ValueError(f"unknown part {part!r}; use one of {', '.join(MAP_PARTS)}") info = MAP_PARAMETERS[parameter] own = band if info.per_band else None label = _(info.label) title = f"{label}, {_band_name(OCTAVE_BANDS_HZ[band])}" if info.per_band else label if part == "value": return coverage.value(parameter, own) * info.scale, title values = coverage.spread_of(parameter, part, own) * info.scale what = _(MAP_PARTS[part]) if part != "standard": spread = coverage.spread probability = spread.coverage if part in ("low", "high") else spread.one_sided what = f"{what} ({100 * probability:g} %)" return values, f"{title}: {what}"
def _map_text(info, value: float, part: str) -> str: """A map value as its cell shows it: in the parameter's format, a standard uncertainty to two significant digits.""" from acoustic_spaces.engine.coverage import uncertainty_text if not np.isfinite(value): return "–" return uncertainty_text(float(value)) if part == "standard" else info.format.format(value)
[docs] def map_polydata( coverage: CoverageMap, parameter: str = "g", band: int = 4, part: str = "value" ) -> pyvista.PolyData: """The map's columns as tiles at listening height, over the audience surfaces (:meth:`~acoustic_spaces.engine.coverage.MapGrid.tiles`); the cell data ``value`` holds the parameter as :func:`map_values` gives it (NaN where undefined) and ``point`` the map point of each tile.""" pv = _pyvista() corners, owner = coverage.grid.tiles() n = len(corners) cells = np.column_stack([np.full(n, 4), np.arange(4 * n).reshape(n, 4)]).ravel() poly = pv.PolyData(corners.reshape(-1, 3), cells) poly.cell_data["value"] = map_values(coverage, parameter, band, part)[0][owner] poly.cell_data["point"] = owner return poly
def _limits(values: np.ndarray) -> tuple[float, float]: finite = values[np.isfinite(values)] if len(finite) == 0: return 0.0, 1.0 lo, hi = float(finite.min()), float(finite.max()) if hi - lo < 1e-9: lo, hi = lo - 0.5, hi + 0.5 return lo, hi
[docs] def plot_coverage( coverage: CoverageMap, plotter: pyvista.Plotter, *, parameter: str = "g", band: int = 4, render: bool = True, part: str = "value", ): """Add a coverage map to a 3D view: coloured tiles at listening height over the audience area, with a colour bar (``parameter``, ``band`` and ``part`` as :func:`map_values` takes them). Returns the actor of the tiles.""" pv = _pyvista() poly = map_polydata(coverage, parameter, band, part) _values, title = map_values(coverage, parameter, band, part) actor = plotter.add_mesh( poly, scalars="value", cmap=MAP_COLOURS, clim=_limits(poly.cell_data["value"]), nan_color="#6b6e7a", opacity=MAP_OPACITY, pickable=False, render=render, scalar_bar_args={ "title": f"{coverage.source}: {title}", "color": "white", "vertical": True, "position_x": 0.86, "position_y": 0.08, "width": 0.06, "height": 0.55, "fmt": "%.3g", "title_font_size": 14, "label_font_size": 13, }, ) # Lines between whole columns; cut columns at the edges get none. grid = coverage.grid whole = grid.squares()[grid.cover.all(axis=1)] + [0.0, 0.0, 0.01] # over the tiles if len(whole): n = len(whole) lines = np.column_stack([np.full(n, 5), np.arange(4 * n).reshape(n, 4), 4 * np.arange(n)]) outline = pv.PolyData(whole.reshape(-1, 3), lines=lines.ravel()) plotter.add_mesh( outline, color=BACKGROUND[0], line_width=0.6, opacity=MAP_OPACITY, pickable=False, render=render, ) return actor
def _floor_plan(ax, room: Room) -> None: """The walls seen from above, as thin lines, and any vegetation's outlines.""" from matplotlib.collections import LineCollection _vegetation_plan(ax, room) mesh = room.mesh walls = np.abs(mesh.face_normals()[:, 2]) < 0.25 tri = mesh.triangles[walls][:, :, :2] if len(tri) == 0: return # Each wall seen from above is a line: the two corners farthest apart. pairs = np.array([[0, 1], [1, 2], [0, 2]]) length = np.linalg.norm(tri[:, pairs[:, 0]] - tri[:, pairs[:, 1]], axis=2) best = pairs[np.argmax(length, axis=1)] rows = np.arange(len(tri)) segments = np.stack([tri[rows, best[:, 0]], tri[rows, best[:, 1]]], axis=1) ax.add_collection(LineCollection(segments, colors=EDGE_COLOUR, linewidths=0.8, alpha=0.6)) def _vegetation_plan(ax, room: Room) -> None: """The outlines of an outdoor room's trees, hedges and belts of trees, seen from above, as dashed green lines.""" from matplotlib.patches import Ellipse, Polygon for shape in room.outdoor.vegetation if room.outdoor is not None else (): style = dict(fill=False, edgecolor=VEGETATION_COLOUR, linestyle="--", linewidth=1.0) if shape.outline is None: size = 2.0 * shape.radius ax.add_patch(Ellipse(shape.centre[:2], size, size, **style)) else: ax.add_patch(Polygon(shape.outline, closed=True, **style)) def _level_image(grid, values: np.ndarray, on: np.ndarray) -> np.ndarray: """The ``values`` of the map points ``on`` (one level) as an image over the grid's columns, rows along y. Where a wall between rooms splits a column, or a point in a model of several rooms covers only part of its column (the rest may be in the next room, with too little of it there for a point of its own), the image has a pixel for each of the column's sub-squares (:attr:`~acoustic_spaces.engine.coverage.MapGrid.cover`), each with the value of the point over it, and none where no point is.""" ny, nx = grid.index.shape[:2] ix, iy = grid.columns[on, 0], grid.columns[on, 1] shown = np.full((ny, nx), np.nan) shown[iy, ix] = values[on] count = np.bincount(iy * nx + ix, minlength=nx * ny) part = (grid.room[on] >= 0) & ~grid.cover[on].all(axis=1) split = on[(count[iy * nx + ix] > 1) | part] if len(split) == 0: return shown side = math.isqrt(grid.cover.shape[1]) fine = np.repeat(np.repeat(shown, side, axis=0), side, axis=1) for k in split: x, y = grid.columns[k] * side fine[y : y + side, x : x + side] = np.nan for k in split: sub = np.flatnonzero(grid.cover[k]) x, y = grid.columns[k] * side fine[y + sub % side, x + sub // side] = values[k] return fine
[docs] def plot_map( coverage: CoverageMap, path: str | Path | None = None, *, parameter: str = "g", band: int = 4, room: Room | None = None, part: str = "value", ): """A coverage map seen from above: one panel per level (stalls, balcony, ...), columns coloured by ``parameter`` in ``band`` (an index into ``OCTAVE_BANDS_HZ``; 4 is 1 kHz) and labelled with their values when there is room; with ``part``, by that part of its spread (:func:`map_values`). With ``room`` the walls and sources are drawn too. Returns the matplotlib figure; it is saved to ``path`` if given.""" from acoustic_spaces.engine.coverage import MAP_PARAMETERS grid = coverage.grid values, title = map_values(coverage, parameter, band, part) ny, nx = grid.index.shape[:2] levels = int(grid.level.max()) + 1 lo, hi = _limits(values) x0, y0 = grid.origin extent = (x0, x0 + nx * grid.cell, y0, y0 + ny * grid.cell) # Each panel shows the map, and with a room all of its walls and sources. xs, ys = [extent[0], extent[1]], [extent[2], extent[3]] if room is not None: lo_b, hi_b = room.report.bounds_min, room.report.bounds_max xs += [lo_b[0], hi_b[0]] ys += [lo_b[1], hi_b[1]] width, depth = max(xs) - min(xs), max(ys) - min(ys) margin = 0.03 * max(width, depth) fig_width = min(16.0, 2.0 + 7.0 * levels) panel = (fig_width - 2.0) / levels fig_height = min(10.0, max(3.5, panel * depth / max(width, 1e-9) + 1.4)) fig = _figure(figsize=(fig_width, fig_height), layout="constrained") fig.patch.set_facecolor(BACKGROUND[0]) axes = fig.subplots(1, levels, squeeze=False)[0] from matplotlib.patches import PathPatch from matplotlib.path import Path as Outline # All triangles counter-clockwise, so the nonzero rule fills their union. tri = grid.footprint.copy() a, b = tri[:, 1] - tri[:, 0], tri[:, 2] - tri[:, 0] turn = a[:, 0] * b[:, 1] - a[:, 1] * b[:, 0] < 0 tri[turn] = tri[turn][:, ::-1] codes = np.tile([Outline.MOVETO, Outline.LINETO, Outline.LINETO, Outline.CLOSEPOLY], len(tri)) corners = np.concatenate([tri, tri[:, :1]], axis=1).reshape(-1, 2) outline = Outline(corners, codes) info = MAP_PARAMETERS[parameter] label_cells = nx * ny <= 400 image = None for level, ax in enumerate(axes): _dark(ax, grid=False) on = np.flatnonzero(grid.level == level) image = ax.imshow( np.ma.masked_invalid(_level_image(grid, values, on)), origin="lower", extent=extent, cmap=MAP_COLOURS, vmin=lo, vmax=hi, interpolation="nearest", ) # Columns at the edge of the surfaces show only the part over them. image.set_clip_path(PathPatch(outline, transform=ax.transData)) if label_cells: size = max(5.0, min(9.0, 60.0 / max(nx, ny))) for k in on: value = values[k] text = _map_text(info, value, part) cx, cy = grid.points[k, :2] shade = (value - lo) / (hi - lo) if np.isfinite(value) else 0.5 colour = "black" if 0.25 < shade < 0.85 else "white" ax.text(cx, cy, text, ha="center", va="center", fontsize=size, color=colour) if room is not None: _floor_plan(ax, room) for source in room.scene.sources: x, y, _z = source.position if source.extended: corners = source.outline() if len(corners) > 2: corners = np.vstack([corners, corners[:1]]) ax.plot(corners[:, 0], corners[:, 1], "-", color=SOURCE_COLOUR, lw=2.5) ax.plot([x], [y], "o", color=SOURCE_COLOUR, ms=7, mec="white", mew=0.8) ax.annotate( source.name, (x, y), xytext=(5, 5), textcoords="offset points", color="white", fontsize=8, ) ax.set_aspect("equal") ax.set_xlim(min(xs) - margin, max(xs) + margin) ax.set_ylim(min(ys) - margin, max(ys) + margin) ax.set_xlabel(_("x (m)")) ax.set_ylabel(_("y (m)")) if levels > 1: heights = grid.surface[on] ax.set_title( _("level {number}, floor at about {height:.1f} m").format( number=level + 1, height=np.median(heights) ) ) bar = fig.colorbar(image, ax=list(axes), shrink=0.9) bar.set_label(title, color="white") bar.ax.tick_params(colors="white") bar.outline.set_edgecolor("#6b6e7a") fig.suptitle( _("{source}: {title}, {count} points {spacing:g} m apart").format( source=coverage.source, title=title, count=len(grid), spacing=grid.cell ), color="white", ) if path is not None: fig.savefig(str(path), dpi=120, facecolor=fig.get_facecolor()) return fig