audiblelight.worldstate.WorldStateSOFA

audiblelight.worldstate.WorldStateSOFA#

class audiblelight.worldstate.WorldStateSOFA(sofa, sample_rate=44100, mic_alias=None)#

Bases: WorldState

A WorldState where audio propagation is simulated using pre-rendered RIRs saved in a .SOFA file.

Functionally equivalent to SpatialScaper and compatible with .SOFA files generated using it.

Parameters:

sofa (str | Path)
sample_rate (int | float | complex | integer | floating | None)
mic_alias (str | None)

__init__(sofa, sample_rate=44100, mic_alias=None)#

Parameters:

sofa (str | Path)
sample_rate (int | float | complex | integer | floating | None)
mic_alias (str | None)

Methods

`__init__`(sofa[, sample_rate, mic_alias])
`add_emitter`([position, alias, mic, ...])	Add an emitter to the state.
`add_emitters`([positions, aliases, mics, ...])	Add emitters to the state.
`add_microphone`([microphone_type, position, ...])	Add a microphone to the space.
`add_microphone_and_emitter`([position, ...])	Add both a microphone and emitter with specified relationship.
`add_microphones`([microphone_types, ...])	Add multiple microphones to the state.
`clear_emitter`(alias)	Given an alias for an emitter, clear that emitter and update the state.
`clear_emitters`()	Removes all current emitters.
`clear_microphone`(alias)	Given an alias for a microphone, clear that microphone if it exists and update the state.
`clear_microphones`()	Removes all current microphones.
`define_trajectory`(duration[, ...])	Defines a trajectory for a moving sound event with specified spatial bounds and event duration.
`from_dict`(input_dict)	Instantiate a WorldStateSOFA from a dictionary.
`get_emitter`(alias[, emitter_idx])	Given a valid alias and index, get a single Emitter object, as in self.emitters[alias][emitter_idx]
`get_emitters`(alias)	Given a valid alias, get a list of associated Emitter objects, as in self.emitters[alias]
`get_irs`()	Get the IRs from the WorldState
`get_listener_positions`()	Retrieves the XYZ coordinates of listeners in the room.
`get_microphone`(alias)	Given a valid alias, get an associated Microphone object, as in self.microphones[alias].
`get_microphones`()	Get all microphones associated with the current State
`get_nearest_source_idx`(candidate_position)	Maps a set of trajectory points to their nearest neighbors in a given set of coordinates using a k-d tree.
`get_random_valid_position_idx`()	Get the index of a random valid position to place an object inside the state.
`get_room_min_max`()	Determines the minimum and maximum XYZ coordinates for the current room setup.
`get_source_positions`()	Retrieves the XYZ coordinates of impulse response positions in the room.
`get_valid_position`()	Get a valid position to place an object inside the state
`get_valid_position_with_max_distance`(ref, ...)	Grab a valid position to reference that is less than max_distance away
`path_exists_between_points`(point_a, point_b)	Returns True if a direct point exists between point_a and point_b in the mesh, False otherwise.
`simulate`()	Grabs all required IRs for Emitters in the WorldState, resampling if necessary
`sofa`()	Context manager for loading and safely closing a .SOFA file.
`to_dict`()	Returns metadata for this object as a dictionary

Attributes

`WARN_WHEN_DISTANCE_EXCEEDS`
`irs`	(N_capsules, N_emitters, N_samples), mic001: (...)}
`name`
`num_emitters`	Returns the number of emitters in the state.

WARN_WHEN_DISTANCE_EXCEEDS = 0.1#

__str__()#

Returns a string representation of the WorldState

Return type:: str

add_emitter(position=None, alias=None, mic=None, keep_existing=False, ensure_direct_path=False, max_place_attempts=1000)#

Add an emitter to the state.

Parameters:

position (list | ndarray | None)
alias (str | None)
mic (str | None)
keep_existing (bool | None)
ensure_direct_path (bool | list | str | None)
max_place_attempts (Optional)

Return type:

None

clear_microphone(alias)#

Given an alias for a microphone, clear that microphone if it exists and update the state.

Parameters:: alias (str)
Return type:: None

clear_microphones()#

Removes all current microphones.

Return type:: None

define_trajectory(duration, starting_position=None, velocity=0.75, resolution=1.5, shape=None, max_place_attempts=1000, ensure_direct_path=False)#

Defines a trajectory for a moving sound event with specified spatial bounds and event duration.

Returns:

the sanitised trajectory, with shape (n_points, 3)

Return type:

np.ndarray

Parameters:

duration (int | float | complex | integer | floating)
starting_position (list | ndarray | None)
velocity (int | float | complex | integer | floating | None)
resolution (int | float | complex | integer | floating | None)
shape (str | None)
max_place_attempts (int | float | complex | integer | floating | None)
ensure_direct_path (bool | list | str | None)

classmethod from_dict(input_dict)#

Instantiate a WorldStateSOFA from a dictionary.

Parameters:: input_dict (dict) – Dictionary that will be used to instantiate the WorldStateSOFA.
Returns:: WorldStateSOFA instance.

get_irs()#

Get the IRs from the WorldState

The output will have shape: {mic_alias: (N_capsules, N_emitters, N_samples)}

Return type:: OrderedDict[str, ndarray]

get_listener_positions()#

Retrieves the XYZ coordinates of listeners in the room.

Returns:: An array of XYZ coordinates for the listener positions.
Return type:: np.ndarray

get_nearest_source_idx(candidate_position)#

Maps a set of trajectory points to their nearest neighbors in a given set of coordinates using a k-d tree.

This function builds a k-d tree from a set of 3D coordinates and finds the nearest neighbor in these coordinates for each point in candidate_position

Parameters:: candidate_position (np.ndarray) – A 2D array of points for which nearest neighbors are to be found.
Returns:: A 2D array of nearest neighbour points, with shape (candidate_position.shape[0], 3)
Return type:: np.ndarray

get_random_valid_position_idx()#

Get the index of a random valid position to place an object inside the state.

Returns:: the random position to place an object inside the mesh
Return type:: np.ndarray

get_room_min_max()#

Determines the minimum and maximum XYZ coordinates for the current room setup.

Returns:: A tuple containing the minimum and maximum XYZ coordinates for the room.
Return type:: tuple

get_source_positions()#

Retrieves the XYZ coordinates of impulse response positions in the room.

Returns:: An array of XYZ coordinates for the impulse response positions.
Return type:: np.ndarray

get_valid_position_with_max_distance(ref, max_distance)#

Grab a valid position to reference that is less than max_distance away

Parameters:

ref (ndarray)
max_distance (float)

Return type:

ndarray

name = 'SOFA'#

simulate()#: Grabs all required IRs for Emitters in the WorldState, resampling if necessary

sofa()#

Context manager for loading and safely closing a .SOFA file.

Usage:

>>> with self.sofa() as sofa:
>>>     # do something
>>> # sofa file is now closed

Return type:: SOFAFile

to_dict()#

Returns metadata for this object as a dictionary

Return type:: dict

audiblelight.worldstate.WorldStateSOFA

Contents

audiblelight.worldstate.WorldStateSOFA#