Source code for acoustic_spaces.examples

"""Example scenes that come with the package.

They are the scenes in the repository's ``examples`` folder, which wheels carry as
``acoustic_spaces/example_scenes``::

    from acoustic_spaces import Room
    from acoustic_spaces.examples import example_path, list_examples

    for example in list_examples():
        print(example.name, example.title)
    room = Room.from_yaml(example_path("concert_hall"))

``acoustic-spaces examples`` lists them, and ``--copy DIR`` copies them to a folder you
can edit; the editor opens them from its File menu, in the groups of :data:`GROUPS`.
"""

from __future__ import annotations

import shutil
from dataclasses import dataclass
from importlib import resources
from pathlib import Path

import yaml

from acoustic_spaces.geometry.io import extra_for, missing_extra
from acoustic_spaces.i18n import N_

SCENE_FILE = "scene.yaml"

#: The groups the examples are shown in, in order, each with its examples (folder names)
#: from the simplest. The titles are English; the editor translates them.
GROUPS: tuple[tuple[str, tuple[str, ...]], ...] = (
    (
        N_("Rooms"),
        ("shoebox", "room_modes", "studio", "listening_room", "apartment", "archway", "workshop"),
    ),
    (
        N_("Halls and churches"),
        ("lecture_hall", "concert_hall", "orchestra", "church", "gallery"),
    ),
    (N_("Sound systems"), ("town_hall_pa", "concert_stage", "stadium_concert")),
    (
        N_("Outdoors"),
        (
            "street",
            "roadside",
            "railway",
            "tree_belt",
            "hillside",
            "open_air_stage",
            "lakeside_concert",
            "helicopter_flyover",
            "airport",
        ),
    ),
    (N_("Models from CAD and BIM files"), ("rehearsal_room", "bim_office", "leaky_classroom")),
    (N_("Measurements and material libraries"), ("fitting", "material_libraries")),
)
#: The group of an example that :data:`GROUPS` leaves out.
OTHER_GROUP = N_("Other examples")


[docs] @dataclass(frozen=True) class Example: #: Folder name, used to pick the example. name: str #: The scene's ``name``. title: str #: The comment at the top of the scene file. description: str #: The scene file. path: Path #: Its model file, or None for a room built from dimensions. model: Path | None = None #: The group it is shown in (English: see :data:`GROUPS`). group: str = OTHER_GROUP @property def extra(self) -> str | None: """The extra its model is read with (``ifc`` for an IFC file), or None.""" return None if self.model is None else extra_for(self.model) @property def missing_extra(self) -> str | None: """The extra its model needs when that is not installed, or None.""" return None if self.model is None else missing_extra(self.model)
[docs] def examples_dir() -> Path: """The folder that holds one sub-folder per example. Installed packages carry it as ``acoustic_spaces/example_scenes``; a source checkout (an editable install) uses the repository's ``examples`` folder. """ installed = _installed_dir() if installed.is_dir(): return installed checkout = Path(__file__).resolve().parents[2] / "examples" if checkout.is_dir(): return checkout raise FileNotFoundError("the example scenes are missing from this installation")
def _installed_dir() -> Path: """Where an installed package keeps its examples (``acoustic_spaces/example_scenes``), whether or not it is there.""" return Path(str(resources.files("acoustic_spaces"))) / "example_scenes"
[docs] def is_installed_example(path: str | Path) -> bool: """Whether ``path`` lies among the examples of an installed package, which an upgrade or an uninstall replaces or removes: nothing is to be written there, even where the folder can be written (a virtual environment). A source checkout's ``examples`` folder is not.""" installed = _installed_dir() if not installed.is_dir(): return False return Path(path).resolve().is_relative_to(installed.resolve())
def _description(scene_file: Path) -> str: lines = [] for line in scene_file.read_text(encoding="utf-8").splitlines(): if not line.startswith("#"): break lines.append(line.lstrip("#").strip()) return " ".join(lines)
[docs] def list_examples() -> list[Example]: """Every example scene, sorted by folder name.""" out = [] for folder in sorted(examples_dir().iterdir()): scene_file = folder / SCENE_FILE if not scene_file.is_file(): continue data = yaml.safe_load(scene_file.read_text(encoding="utf-8")) model = (data.get("geometry") or {}).get("file") out.append( Example( name=folder.name, title=str(data.get("name", folder.name)), description=_description(scene_file), path=scene_file, model=None if model is None else folder / model, group=_GROUP_OF.get(folder.name, OTHER_GROUP), ) ) return out
_GROUP_OF = {name: group for group, names in GROUPS for name in names}
[docs] def example_groups(examples: list[Example] | None = None) -> list[tuple[str, list[Example]]]: """The examples (default: all) by group, in the order of :data:`GROUPS` and within a group from the simplest; those it leaves out last, in :data:`OTHER_GROUP`. Groups with no example are left out.""" examples = list_examples() if examples is None else examples rank = {name: k for _, names in GROUPS for k, name in enumerate(names)} order = [group for group, _ in GROUPS] + [OTHER_GROUP] out = [] for group in order: members = [e for e in examples if e.group == group] if members: out.append((group, sorted(members, key=lambda e: (rank.get(e.name, 0), e.name)))) return out
[docs] def example_path(name: str) -> Path: """The scene file of the example ``name`` (a folder name from :func:`list_examples`).""" scene_file = examples_dir() / name / SCENE_FILE if not scene_file.is_file(): names = ", ".join(e.name for e in list_examples()) raise ValueError(f"no example named {name!r}; examples: {names}") return scene_file
[docs] def example_of(scene_file: str | Path) -> str | None: """The example the scene file ``scene_file`` is, or is a copy of: its folder's name when that names an example, else the example whose scene has the same ``name``, so that a copy saved anywhere keeps its example; None for any other scene, or one that cannot be read.""" path = Path(scene_file) folder = path.parent.name if (examples_dir() / folder / SCENE_FILE).is_file(): return folder try: data = yaml.safe_load(path.read_text(encoding="utf-8")) except (OSError, UnicodeDecodeError, yaml.YAMLError): return None name = data.get("name") if isinstance(data, dict) else None if name is None: return None return next((e.name for e in list_examples() if e.title == str(name)), None)
[docs] def copy_examples(destination: str | Path, names: list[str] | None = None) -> list[Path]: """Copy examples (all, or ``names``) into ``destination``, one folder each, and return their scene files. Raises ``FileExistsError`` rather than overwrite a folder.""" destination = Path(destination) chosen = list_examples() if names is not None: chosen = [e for e in chosen if e.name in names] found = {e.name for e in chosen} missing = [name for name in names if name not in found] if missing: raise ValueError(f"no example named {', '.join(missing)}") destination.mkdir(parents=True, exist_ok=True) copied = [] for example in chosen: target = destination / example.name if target.exists(): raise FileExistsError(f"{target} already exists") shutil.copytree(example.path.parent, target) copied.append(target / SCENE_FILE) return copied
__all__ = [ "GROUPS", "OTHER_GROUP", "Example", "copy_examples", "example_groups", "example_of", "example_path", "examples_dir", "is_installed_example", "list_examples", ]