Metadata-Version: 2.1
Name: SumoSound
Version: 1.0.2
Summary: A python library to add 3D sound to a Sumo traffic simulation.
Home-page: https://github.com/patmalcolm91/SumoSound
Author: Patrick Malcolm
Author-email: patmalcolm91@gmail.com
License: MIT
Download-URL: https://github.com/patmalcolm91/SumoSound/archive/v_1.0.2.tar.gz
Description: # SumoSound
        SumoSound is a Python package which uses Sumo's TraCI API and PyOpenAL to generate
        vehicle sounds in a 3D environment. PyOpenAL calculates the proper volume, doppler
        shift, and stereo (or surround sound) output. The package comes with some built-in 
        default sound effects, but is fully customizable, and can calculate the sounds from
        the point of view of either a stationary ego position or one of the vehicles in the
        simulation.
        
        ## Installation
        SumoSound can be installed using pip:
        ```
        pip install SumoSound
        ```
        
        Or, you can simply clone the GitHub repository and add it to your Python path.
        
        You can then import the library.
        ```python
        import SumoSound
        ```
        
        ### Dependencies
        * Sumo TraCI
        * PyOpenAL
        
        ## Usage
        See the example script [sound_test.py](sound_test.py) for an example.
        
        In general, you just need to define an ```Ego``` object (either of the ```Ego``` class or a
        subclass of it), pass this ```Ego``` object to a ```Simulation``` object, and then call 
        ```update()``` on the ```Simulation``` object once per simulation step. Everything else 
        should be handled automatically.
        
        ## Documentation
        
        ### Ego
        An ```Ego``` object defines the position, velocity, and orientation of the listener.
        There are 3 ego types: Stationary Ego, Ego Vehicle, and Ego Vehicle with Manually-Calculated Speed.
        
        #### Stationary Ego (```Ego```)
        The position, velocity, and orientation of a stationary ego are controlled with the methods ```set_position()```,
        ```set_velocity()```, and ```set_angle()```. The ego will default to a location of (0, 0, 0) facing east with
        zero velocity.
        ```python
        ego = SumoSound.Ego()
        ```
        
        #### Ego Vehicle (```EgoVehicle```)
        The position, velocity, and orientation of an ego vehicle are synced via TraCI with the vehicle with the given ID.
        These properties are automatically updated every time step by the ```Simulation``` object.
        ```python
        ego = SumoSound.EgoVehicle("vehicleID")
        ```
        
        #### Ego Vehicle with Manually-Calculated Speed (```EgoVehicleManualSpeed```)
        The same as an ```EgoVehicle```, but the vehicle speed is calculated based on the ego position in the previous and
        current simulation time steps. This is useful if the ego vehicle is being controlled externally and the speed property
        is incorrect or undefined.
        ```python
        ego = SumoSound.EgoVehicleManualSpeed("vehicleID")
        ```
        
        ### Simulation
        A ```Simulation``` object keeps track of all of the vehicles in the Sumo simulation via TraCI, updating the sound
        sources and listener position as necessary. An ego must be passed to the constructor of the ```Simulation``` object.
        ```python
        simulation = SumoSound.Simulation(ego)
        ```
        Additional parameters are available as well. Most notably, the argument ```vehicle_class_map``` can be used to tell
        SumoSound which subclass of ```Vehicle``` to use for each Sumo vehicleClass. By default, the dict
        ```DEFAULT_VEHICLE_CLASS_MAP``` is used. For more information on defining custom vehicle types, see the next section.
        
        The method ```update()``` must be called every simulation step.
        ```python
        while True:
            traci.simulationStep()
            simulation.update()
        ```
        
        ### Vehicle
        A ```Vehicle``` object keeps track of one or more sound sources associated with the vehicle type. SumoSound comes with a
        number of pre-defined vehicle types which are selected automatically by the ```Simulation``` object based on the Sumo
        vehicleClass property of each vehicle. Custom vehicle types can be created by simply sub-classing the ```Vehicle```
        class. The gain of each vehicle sound can be automatically actuated by a signal. By default, the speed and acceleration
        of the vehicle are available as signals, but custom signals can also be created.
        
        ```python
        class CustomVehicle(SumoSound.Vehicle):
            def __init__(self, id, engine_sound_file="path/to/file.wav",
                         tire_sound_file="path/to/file.wav",
                         horn_sound_file="path/to/file.wav"):
                super().__init__(id)
                self.horn = False  # define a custom signal called "horn"
                # add an engine sound to the vehicle, actuated by the vehicle acceleration
                engine_sound = SumoSound.VehicleSound(engine_sound_file, base_gain=0.5)
                self.add_sound(engine_sound, "acceleration", response_curve=[(0, 0.5), (2.5, 1)])
                # add a tire sound to the vehicle, actuated by the vehicle speed
                tire_sound = SumoSound.VehicleSound(tire_sound_file, base_gain=2)
                self.add_sound(tire_sound, "speed", response_curve=[(0, 0), (28, 1)])
                # add a horn sound to the vehicle, actuated by the custom signal "horn"
                horn_sound = SumoSound.VehicleSound(horn_sound_file, base_gain=2)
                self.add_sound(horn_sound, "horn", response_curve=[(False, 0), (True, 1)])
        ```
        
        The argument ```response_curve``` of the method ```add_sound()``` may either be a callable with the signature
        ```fun(signal_value) -> gain``` or a list of ```(signal_value, gain)``` tuples, which are interpolated as necessary to
        calculate the sound gain from the signal value.
        
        To associate the custom vehicle type with a vehicle class, the ```vehicle_class_map``` argument of the ```Simulation```
        constructor must be passed a custom dict containing the desired mapping, or the default dict can be modified before
        creating the Simulation object.
        ```python
        # map the custom vehicle type to the Sumo vehicleClass "passenger"
        SumoSound.DEFAULT_VEHICLE_CLASS_MAP["passenger"] = CustomVehicle
        simulation = SumoSound.Simulation(ego)
        ```
        
        In order to use the custom signal to actuate the sound, simply set the signal to the desired value, and everything will
        be automatically handled the next time the simulation is updated.
        ```python
        simulation.vehicles["vehicleID"].horn = True
        ```
        
        ## Contribution
        Issues and pull requests are welcome.
Keywords: sumo,TraCI,sound,sound effects,3D sound,OpenAL,traffic
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Description-Content-Type: text/markdown
