utils

DataKey

class DataKey(*values)[source]

Bases: str, Enum

Enumeration of simulation data keys used for system-wide communication.

This class defines the standardized keys used by the SoundModel to identify simulation variables received from the CARLA client. By inheriting from str, these members act as validated constants that ensure consistency between the network layer, the EventBus, and the various sound adapters.

ACCELERATION = 'acceleration'

Key for vehicle acceleration.

Type:

str

BRAKE = 'brake'

Key for brake pedal input state.

Type:

str

COLLISION_EVENT = 'collision_event'

Trigger key for vehicle impact detections.

Type:

str

GEAR = 'gear'

Key for transmission gear index.

Type:

str

MESSAGE = 'message'

Key for general purpose system or debug messages.

Type:

str

RAIN_INTENSITY = 'rain_intensity'

Key for precipitation

Type:

str

SPEED = 'speed'

Key for vehicle velocity.

Type:

str

SPEED_LIMIT = 'speed_limit'

Key for local speed limit of the current road segment.

Type:

str

THROTTLE = 'throttle'

Key for throttle pedal input state.

Type:

str

WIND_INTENSITY = 'wind_intensity'

Key for wind speed percentage.

Type:

str

HONK = 'honk'

Key for state of the vehicle’s horn trigger.

Type:

str

HANDBRAKE = 'handbrake'

Key for state of the manual parking brake engagement.

Type:

str

EventBus

class EventBus[source]

Bases: object

Centralized Publish-Subscribe (Pub/Sub) system for decoupled communication.

The EventBus facilitates the flow of simulation data from the SoundModel to various audio adapters. By using this pattern, the data source remains agnostic of the specific sound logic, allowing for a highly modular and extensible architecture.

__init__()[source]

Initializes the EventBus with a default dictionary of subscribers.

subscribe(key: DataKey, callback: Callable[[Any], None]) → None[source]

Registers a listener for a specific simulation data key.

Parameters:

  • key (DataKey) – The specific data channel to subscribe to.

  • callback (Callable) – The function to be executed when data is published.

unsubscribe(key: DataKey, callback: Callable[[Any], None]) → None[source]

Removes a previously registered listener from a data key.

Parameters:

  • key (DataKey) – The data channel to detach from.

  • callback (Callable) – The specific function to remove from the registry.

publish(key: DataKey, data: Any) → None[source]

Broadcasts simulation data to all listeners of a specific key.

This method iterates through the subscriber list for the provided key and executes each callback, passing the new simulation data as an argument.

Parameters:

  • key (DataKey) – The data channel to broadcast on.

  • data (Any) – The simulation value (speed, torque, etc.) to distribute.

RangeLevel

class RangeLevel(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Generic base class for level definitions with range bounds and output mapping.

This utility allows for the categorization of continuous numeric simulation data into discrete states. It is primarily used to map percentages (like rain or wind intensity) into specific integer values required by FMOD Studio parameters.

__init__(lower, upper, mapped_value)[source]

Initializes a range level with specific boundaries.

Parameters:

  • lower (float) – The bottom threshold of this level.

  • upper (float) – The top threshold of this level.

  • mapped_value (int) – The discrete value to be sent to FMOD.

lower

The lower boundary of the range.

Type:

float

upper

The upper boundary of the range.

Type:

float

mapped_value

The integer value used for FMOD parameter modulation.

Type:

int

contains(value)[source]

Checks whether the given value falls within this level’s range.

The logic implements a specific boundary rule: the lower bound is inclusive only if it is 0.0, otherwise it is treated as exclusive to prevent overlap between adjacent levels.

Parameters:

value (float) – The numeric value to test against the range.

Returns:

True if the value is within the bounds, False otherwise.

Return type:

bool

classmethod from_value(value)[source]

Factory method to find the matching level for a given numeric input.

Iterates through all members of the Enum and returns the level where contains() evaluates to True.

Parameters:

value (float) – The simulation value to be categorized.

Returns:

The matching Enum member, or None if no match is found.

Return type:

RangeLevel