audiblelight.worldstate.WorldState

audiblelight.worldstate.WorldState#

class audiblelight.worldstate.WorldState#

Bases: object

Represents a 3D space defined by a room, microphone position(s), and emitter position(s).

Should not be used directly: instead, a child class (e.g., WorldStateRIR, WorldStateSOFA) should be used.

__init__()#

Methods

__init__()

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 WorldState 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 state

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_valid_position()

Get a valid position to place an object inside the state

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()

Simulates audio propagation in the state with the current listener and sound emitter positions.

to_dict()

Returns metadata for this object as a dictionary

Attributes

irs

(N_capsules, N_emitters, N_samples), mic001: (...)}

name

num_emitters

Returns the number of emitters in the state.
__eq__(other)#

Compare two WorldState objects for equality.

Returns:

True if two WorldState objects are equal, False otherwise

Return type:

bool

Parameters:

other (Any)

__getitem__(alias)#

An alternative for self.get_emitters(alias) or `self.emitters[alias]

Parameters:

alias (str)

Return type:

list[Emitter]

__len__()#

Returns the number of objects in the mesh (i.e., number of microphones + emitters)

Return type:

int

__repr__()#

Returns a JSON-formatted string representation of the WorldState

Return type:

str

__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 (int | float | complex | integer | floating | None)

Return type:

None

add_emitters(positions=None, aliases=None, mics=None, n_emitters=None, keep_existing=False, ensure_direct_path=False, raise_on_error=True)#

Add emitters to the state.

Parameters:

  • positions (list | ndarray | None)

  • aliases (list[str] | None)

  • mics (list[str] | str | None)

  • n_emitters (int | None)

  • keep_existing (bool | None)

  • ensure_direct_path (bool | list | str | None)

  • raise_on_error (bool | None)

Return type:

None

add_microphone(microphone_type=None, position=None, alias=None, keep_existing=True)#

Add a microphone to the space.

Parameters:

  • microphone_type (str | Type[MicArray] | None)

  • position (list | ndarray | None)

  • alias (str | None)

  • keep_existing (bool | None)

Return type:

None

add_microphone_and_emitter(position=None, polar=True, microphone_type=None, mic_alias=None, emitter_alias=None, keep_existing_mics=True, keep_existing_emitters=True, ensure_direct_path=True, max_place_attempts=1000)#

Add both a microphone and emitter with specified relationship.

Parameters:

  • position (ndarray | float | None)

  • polar (bool | None)

  • microphone_type (str | Type[MicArray] | None)

  • mic_alias (str | None)

  • emitter_alias (str | None)

  • keep_existing_mics (bool | None)

  • keep_existing_emitters (bool | None)

  • ensure_direct_path (bool | None)

  • max_place_attempts (int | None)

Return type:

None

add_microphones(microphone_types=None, positions=None, aliases=None, keep_existing=True, raise_on_error=True)#

Add multiple microphones to the state.

Parameters:

  • microphone_types (list[str | Type[MicArray]] | None)

  • positions (list[list | ndarray] | None)

  • aliases (list[str] | None)

  • keep_existing (bool | None)

  • raise_on_error (bool | None)

Return type:

None

clear_emitter(alias)#

Given an alias for an emitter, clear that emitter and update the state.

Parameters:

alias (str)

Return type:

None

clear_emitters()#

Removes all current emitters.

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.

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)

Return type:

ndarray

classmethod from_dict(input_dict)#

Instantiate a WorldState from a dictionary.

Parameters:

input_dict (dict[str, Any])

get_emitter(alias, emitter_idx=0)#

Given a valid alias and index, get a single Emitter object, as in self.emitters[alias][emitter_idx]

Parameters:

  • alias (str)

  • emitter_idx (int | None)

Return type:

Emitter

get_emitters(alias)#

Given a valid alias, get a list of associated Emitter objects, as in self.emitters[alias]

Parameters:

alias (str)

Return type:

list[Emitter]

get_irs()#

Get the IRs from the state

Return type:

OrderedDict[str, ndarray]

get_microphone(alias)#

Given a valid alias, get an associated Microphone object, as in self.microphones[alias].

Parameters:

alias (str)

Return type:

Type[MicArray]

get_microphones()#

Get all microphones associated with the current State

Return type:

list[Type[MicArray]]

get_valid_position()#

Get a valid position to place an object inside the state

Returns:

the random position to place an object inside the mesh

Return type:

np.ndarray

property irs: OrderedDict[str, ndarray]#

(N_capsules, N_emitters, N_samples), mic001: (…)}

Type:

Returns a dictionary of IRs in the shape {mic000

name = '_default'#
property num_emitters: int#

Returns the number of emitters in the state.

Note that this is not the same as calling len(self.emitters): the total number of emitters is equivalent to the length of ALL lists inside this dictionary

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.

Parameters:

  • point_a (ndarray)

  • point_b (ndarray)

Return type:

bool

simulate()#

Simulates audio propagation in the state with the current listener and sound emitter positions.

Return type:

None

to_dict()#

Returns metadata for this object as a dictionary

Return type:

dict

Contents