gwexpy.interop.pyroomacoustics_

Interoperate with pyroomacoustics simulation results.

Interoperability with pyroomacoustics room acoustics simulation library.

Provides conversion from pyroomacoustics Room simulation results (RIR, microphone signals, source signals, STFT) and ScalarField grid data to GWexpy TimeSeries, Spectrogram, and ScalarField types.

Functions

from_pyroomacoustics_field(cls, room, *, ...)

Create ScalarField from pyroomacoustics room with grid-placed microphones.

from_pyroomacoustics_mic_signals(cls, room, *)

Create TimeSeries or TimeSeriesDict from pyroomacoustics microphone signals.

from_pyroomacoustics_rir(cls, room, *[, ...])

Create TimeSeries or TimeSeriesDict from pyroomacoustics room impulse responses.

from_pyroomacoustics_source(cls, room, *[, ...])

Create TimeSeries from a pyroomacoustics sound source signal.

from_pyroomacoustics_stft(cls, stft_obj, *)

Create Spectrogram or SpectrogramDict from a pyroomacoustics STFT object.

to_pyroomacoustics_source(ts)

Export TimeSeries as a signal and sample rate tuple for pyroomacoustics.

to_pyroomacoustics_stft(spec, *[, hop, ...])

Export Spectrogram as a pyroomacoustics STFT object.
gwexpy.interop.pyroomacoustics_.from_pyroomacoustics_rir(cls: type, room: Any, *, source: int | None = None, mic: int | None = None, unit: Any | None = None) → Any[source]

Create TimeSeries or TimeSeriesDict from pyroomacoustics room impulse responses.

Parameters:

  • cls (type) – The TimeSeries (or TimeSeriesDict) class to instantiate.

  • room (pyroomacoustics.Room) – The room object after compute_rir() or simulate() has been called. room.rir must follow the pyroomacoustics convention rir[mic_index][source_index] (outer index = microphone).

  • source (int, optional) – Source index to extract. If None and mic is also None, all source-mic pairs are returned.

  • mic (int, optional) – Microphone index to extract. If None and source is also None, all source-mic pairs are returned.

  • unit (str or astropy.units.Unit, optional) – Unit to assign to the result.

Returns:

  • TimeSeries – When a single source-mic pair is selected.

  • TimeSeriesDict – When multiple pairs are returned.

Raises:

ValueError – If RIR has not been computed yet.

gwexpy.interop.pyroomacoustics_.from_pyroomacoustics_mic_signals(cls: type, room: Any, *, mic: int | None = None, unit: Any | None = None) → Any[source]

Create TimeSeries or TimeSeriesDict from pyroomacoustics microphone signals.

Parameters:

  • cls (type) – The TimeSeries (or TimeSeriesDict) class to instantiate.

  • room (pyroomacoustics.Room) – The room object after simulate() has been called.

  • mic (int, optional) – Microphone index to extract. If None, all microphones are returned.

  • unit (str or astropy.units.Unit, optional) – Unit to assign to the result.

Returns:

  • TimeSeries – When a single microphone is selected.

  • TimeSeriesDict – When multiple microphones are returned.

Raises:

ValueError – If signals have not been computed yet.

gwexpy.interop.pyroomacoustics_.from_pyroomacoustics_source(cls: type, room: Any, *, source: int = 0, unit: Any | None = None) → Any[source]

Create TimeSeries from a pyroomacoustics sound source signal.

Parameters:

  • cls (type) – The TimeSeries class to instantiate.

  • room (pyroomacoustics.Room) – The room object with at least one source added.

  • source (int, default 0) – Source index to extract.

  • unit (str or astropy.units.Unit, optional) – Unit to assign to the result.

Return type:

TimeSeries

gwexpy.interop.pyroomacoustics_.from_pyroomacoustics_stft(cls: type, stft_obj: Any, *, channel: int | None = None, fs: float | None = None, unit: Any | None = None) → Any[source]

Create Spectrogram or SpectrogramDict from a pyroomacoustics STFT object.

Parameters:

  • cls (type) – The Spectrogram (or SpectrogramDict) class to instantiate.

  • stft_obj (pyroomacoustics.stft.STFT or similar) – Object with .X (complex STFT data), .hop, and .N attributes.

  • channel (int, optional) – Channel index to extract from multi-channel STFT. If None, all channels are returned.

  • fs (float, optional) – Sample rate in Hz. Required if stft_obj does not have an fs attribute.

  • unit (str or astropy.units.Unit, optional) – Unit to assign to the result.

Returns:

  • Spectrogram – When a single channel is selected or the STFT is single-channel.

  • SpectrogramDict – When multiple channels are present and no channel is selected.

gwexpy.interop.pyroomacoustics_.from_pyroomacoustics_field(cls: type, room: Any, *, grid_shape: tuple[int, ...], source: int = 0, mode: str = 'rir', unit: Any | None = None) → Any[source]

Create ScalarField from pyroomacoustics room with grid-placed microphones.

When microphones are placed on a regular spatial grid, this function converts the RIR or microphone signals into a 4D ScalarField with shape (nt, nx, ny, nz).

Parameters:

  • cls (type) – The ScalarField class to instantiate.

  • room (pyroomacoustics.Room) – Room object with microphones placed on a regular grid.

  • grid_shape (tuple of int) – Spatial grid shape (nx, ny, nz) for 3D rooms or (nx, ny) for 2D rooms. Must satisfy prod(grid_shape) == n_mics.

  • source (int, default 0) – Source index (used only when mode='rir').

  • mode ({'rir', 'signals'}) –

    Which data to extract:

    • 'rir': Room impulse responses for the given source.

    • 'signals': Simulated microphone signals.

  • unit (str or astropy.units.Unit, optional) – Unit to assign to the data.

Returns:

4D field with shape (nt, nx, ny, nz).

Return type:

ScalarField

Raises:

ValueError – If prod(grid_shape) does not match the number of microphones, or if the requested data has not been computed.

gwexpy.interop.pyroomacoustics_.to_pyroomacoustics_source(ts: Any) → tuple[ndarray, int][source]

Export TimeSeries as a signal and sample rate tuple for pyroomacoustics.

The returned tuple can be used to add a source to a pyroomacoustics room:

signal, fs = ts.to_pyroomacoustics_source()
room = pra.ShoeBox([5, 4, 3], fs=fs)
room.add_source([1, 2, 1.5], signal=signal)
Parameters:

ts (TimeSeries) – The time series to export.

Returns:

  • signal (numpy.ndarray) – 1D float64 array of the signal samples.

  • fs (int) – Sample rate in Hz.

gwexpy.interop.pyroomacoustics_.to_pyroomacoustics_stft(spec: Any, *, hop: int | None = None, analysis_window: ndarray | None = None) → Any[source]

Export Spectrogram as a pyroomacoustics STFT object.

Parameters:

  • spec (Spectrogram) – The spectrogram to export. Shape (n_frames, n_freq_bins).

  • hop (int, optional) – Hop size in samples. If None, estimated from the spectrogram’s time resolution and frequency resolution.

  • analysis_window (numpy.ndarray, optional) – Analysis window to set on the STFT object.

Returns:

STFT object with .X set to the spectrogram data.

Return type:

pyroomacoustics.stft.STFT