Metadata-Version: 2.4
Name: acoustic-spaces
Version: 4.2.1
Summary: Open-source room acoustics simulator: geometric acoustics, spatial impulse responses and auralisation
Keywords: acoustics,room acoustics,ray tracing,auralization,ambisonics,binaural
Author: acoustic_spaces contributors
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Scientific/Engineering :: Physics
Project-URL: Documentation, https://naelolaiz.github.io/acoustic-spaces/
Project-URL: Repository, https://github.com/naelolaiz/acoustic-spaces
Project-URL: Changelog, https://github.com/naelolaiz/acoustic-spaces/blob/main/CHANGELOG.md
Requires-Python: >=3.10
Requires-Dist: ezdxf>=1.1
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.11
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: trimesh>=4.0
Provides-Extra: viz
Requires-Dist: matplotlib>=3.6; extra == "viz"
Requires-Dist: pyvista>=0.43; extra == "viz"
Requires-Dist: imageio>=2.31; extra == "viz"
Requires-Dist: imageio-ffmpeg>=0.5; extra == "viz"
Provides-Extra: measure
Requires-Dist: sounddevice>=0.4; extra == "measure"
Provides-Extra: gui
Requires-Dist: PySide6-Essentials>=6.6; extra == "gui"
Requires-Dist: pyvistaqt>=0.11; extra == "gui"
Requires-Dist: pyvista>=0.43; extra == "gui"
Requires-Dist: matplotlib>=3.6; extra == "gui"
Provides-Extra: sofa
Requires-Dist: h5py>=3.8; extra == "sofa"
Provides-Extra: sketchup
Requires-Dist: openskp>=1.3; extra == "sketchup"
Provides-Extra: ifc
Requires-Dist: ifcopenshell>=0.8; extra == "ifc"
Requires-Dist: mapbox-earcut>=1.0; extra == "ifc"
Provides-Extra: gpu
Requires-Dist: wgpu>=0.31; extra == "gpu"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: h5py>=3.8; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: h5py>=3.8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=2.4; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.2; extra == "docs"
Requires-Dist: furo>=2024.1; extra == "docs"
Requires-Dist: myst-parser>=3; extra == "docs"
Requires-Dist: pypdf>=5; extra == "docs"
Description-Content-Type: text/markdown

# acoustic_spaces

Open-source room acoustics simulator and auralisation toolkit, in the spirit of
CATT-Acoustic and ODEON: load a 3D model of a space, place sources and listeners,
compute impulse responses, and listen to the result in binaural, Ambisonics or
loudspeaker formats.

![The church example in 3D: the stone nave with its early reflection paths from the altar to the front of the nave, coloured by order up to the third](https://raw.githubusercontent.com/naelolaiz/acoustic-spaces/main/docs/images/church_paths.png)

**Status: 4.2** (see the [roadmap](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/roadmap.md) and the
[known issues](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/validation.md#known-issues)).

## What it does

- **Rooms** from CAD and BIM models (OBJ, DXF, glTF, STL, IFC, Collada, SketchUp), from
  their dimensions or from a floor plan, with a material database and the material
  libraries of CATT-Acoustic and ODEON, walls and doors between rooms, audience seating,
  and directional, line, surface and array sources; a leak finder shows where a model
  is open: [scene files](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/scenes.md).
- **Simulation**, in octave or third-octave bands: ray-traced early reflections with
  edge diffraction, added in pressure at low frequencies, a stochastic late tail and,
  for the lowest bands, a wave solver, both on the CPU or a GPU; ISO 3382-1 parameters
  with their standard errors, the STI and echo criteria for every source and listener,
  and the parameters' uncertainty from the materials' absorption and the rays by Monte
  Carlo (GUM Supplement 1): [simulation](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/simulation.md),
  [materials' uncertainty](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/scenes.md#materials).
- **Outdoors**: the ground and its impedance, terrain, buildings from a map, barriers
  and trees, wind, temperature and turbulence, behind barriers and buildings too; road
  vehicles by CNOSSOS-EU, trains and trams by Schall 03, construction plant from Defra's
  database, helicopters from their rotors, aircraft by ECAC Doc 29, ground-borne
  vibration by the US FTA's manual and sound through a closed window by EN ISO 12354-3:
  [outdoor scenes](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/outdoor.md).
- **Coverage maps** of the parameters and of the speech transmission index over the
  audience: [coverage maps](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/coverage-maps.md).
- **Listening**: impulse responses in mono, binaural, Ambisonics (AmbiX) and loudspeaker
  formats, or through a listener's microphone (first-order patterns, XY, Blumlein and MS
  pairs), as WAV files; dry recordings run through them offline or in real time on the
  sound card, head-tracked on headphones, or heard along a walk through the room:
  [spatial audio and listening](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/spatial-audio.md).
- **Demos**, binaural for headphones: an orchestra in the concert hall, a choir and an
  organ in the church, a band in the stadium and across a lake, a walk through the
  gallery, road vehicles with sirens and horns, trains and a tram passing by, road works
  in a street, a helicopter over a meadow and over the stadium, and a jet taking off and
  landing; any scene makes a demo of its own: [demos](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/demos.md), and videos in one
  [playlist](https://www.youtube.com/playlist?list=PLWz5JDREfod8).
- **Measuring real rooms** with sine sweeps, comparing them with their model in just
  noticeable differences, and fitting the model's absorption to them:
  [measurements](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/measurements.md).
- **A graphical editor** that does all of this in one window, starting from the bundled
  [example rooms](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/examples.md); reflection paths and sound particles in 3D, animated
  and exported to Blender: [graphical editor](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/editor.md).
- **Validation** against theory, against pyroomacoustics and against measured rooms,
  with the numbers and the scripts to reproduce them: the
  [validation report](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/validation.md) says how far the results can be trusted,
  and its [known issues](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/validation.md#known-issues) what is still wrong.

## Install

```sh
pip install acoustic-spaces                # simulation, rendering and the command line
pip install "acoustic-spaces[viz,gui]"     # with the 3D view and the graphical editor
pip install "acoustic-spaces[viz,gui,measure,sofa,gpu,ifc,sketchup]"  # every optional part
```

What each extra in brackets adds is listed in
[Getting started](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/getting-started.md#extras).

PyPI and every [GitHub release](https://github.com/naelolaiz/acoustic-spaces/releases)
have wheels for Linux (x86-64), macOS (Apple silicon and Intel) and Windows (x86-64),
CPython 3.10 to 3.14; elsewhere pip builds the package from source, which needs a C++17
compiler.
From a source checkout, with [uv](https://docs.astral.sh/uv/), a C++17 compiler and
CMake:

```sh
git clone https://github.com/naelolaiz/acoustic-spaces
cd acoustic-spaces
uv sync --extra viz --extra gui
```

[Getting started](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/getting-started.md) has the same with pip and a tour of the
command line and the Python API.

## Quick start

```sh
acoustic-spaces examples                                   # the example rooms
acoustic-spaces simulate examples/shoebox/scene.yaml --out results --plot
acoustic-spaces view examples/gallery/scene.yaml --paths --listener "round the corner"
acoustic-spaces                                            # alone: the graphical editor
```

```python
from acoustic_spaces import Room, simulate

room = Room.from_yaml("examples/shoebox/scene.yaml")
response = simulate(room)["talker", "seat-a"]
print(response.parameters().table())
```

## Documentation

- [User manual](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/manual.md): a path through these pages, from a first simulation
  to the advanced workflows, with an example to try at each step.
- [Getting started](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/getting-started.md): installing, the command line and the
  Python API.
- [Graphical editor](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/editor.md): editing scenes, drawing rooms, results and
  listening, export to Blender.
- [Example scenes](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/examples.md): the bundled rooms and what each shows.
- [Scene files](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/scenes.md): geometry, materials, walls and openings, audience
  seating, sources and directivity.
- [Outdoor scenes](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/outdoor.md): the ground and the open sky, terrain, buildings,
  barriers and trees, wind and turbulence, passing vehicles, aircraft and vibration
  through the ground.
- [Simulation](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/simulation.md): early reflections, the late part, scattering,
  frequency bands, edge diffraction, low frequencies and the wave solver.
- [Coverage maps](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/coverage-maps.md): parameters and the STI over the audience area.
- [Spatial audio and listening](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/spatial-audio.md): binaural, Ambisonics and
  loudspeaker outputs, convolution, real-time playback and head tracking.
- [Demos](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/demos.md): what each demo plays, its recordings and its options.
- [Measurements](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/measurements.md): measuring impulse responses, comparing them with
  simulations, and fitting materials to them.
- [Running on another computer](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/remote.md): a scene and its files in one pack, and
  a container image to run it on a GPU server or a cloud job.
- [Validation report](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/validation.md): how the results compare with theory, another
  simulator and measured rooms.
- [Roadmap](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/roadmap.md),
  [changelog](https://github.com/naelolaiz/acoustic-spaces/blob/main/CHANGELOG.md)
  and [repository layout](https://github.com/naelolaiz/acoustic-spaces/blob/main/docs/development.md).

The same pages, with an API reference generated from the docstrings, are online at
[naelolaiz.github.io/acoustic-spaces](https://naelolaiz.github.io/acoustic-spaces/), and
the user manual and the reference make one
[PDF](https://naelolaiz.github.io/acoustic-spaces/acoustic-spaces-manual.pdf), also
attached to every release (to build either, see
[CONTRIBUTING.md](https://github.com/naelolaiz/acoustic-spaces/blob/main/CONTRIBUTING.md)).

## Design in one paragraph

Python is the main language; a C++ core (bound with nanobind) carries the parts that
must be fast: the ray tracer, the wave solver and the real-time convolver. Every
simulation runs in two stages with selectable methods: deterministic ray tracing (or
image sources) for the early reflections and stochastic processing for the late
reverberation. Both write a format-independent *directional reflectogram*, from which
binaural, Ambisonics and loudspeaker impulse responses are encoded, so one simulation
serves every output format. For the lowest bands a wave solver can take over; it
records the pressure and its gradient, so the bass keeps its direction (to first order)
in every format.

## Contributing

Pull requests are welcome.
[CONTRIBUTING.md](https://github.com/naelolaiz/acoustic-spaces/blob/main/CONTRIBUTING.md)
covers the development setup, the checks to run before opening one (ruff, mypy, the
translation catalogs and `pytest -W error`), the documentation, the validation scripts
and releases. CI runs the tests on all three platforms, and ruff and mypy on Linux.

## License

GPL-3.0-or-later. See [LICENSE](https://github.com/naelolaiz/acoustic-spaces/blob/main/LICENSE).

The built-in material table comes from
[pyroomacoustics](https://github.com/LCAV/pyroomacoustics) (MIT, see
[`materials/data/LICENSE-pyroomacoustics.txt`](https://github.com/naelolaiz/acoustic-spaces/blob/main/src/acoustic_spaces/materials/data/LICENSE-pyroomacoustics.txt)).
That table does not cite a source for most entries; check values that matter
against manufacturer data or a measured database.
