Beamngpy

==============

- New features

- OpenDrive (.xodr) importer added, and new example created in Examples folder.

- OpenStreetMap (.osm) importer and exporter added, and new examples created in Examples folder.

- Eclipse Sumo (.nod.xml and .edg.xml) importer and exporter added, and new examples created in Examples folder.

- BeamNGpy fixes / improvements

- Improved/added documentation

- ``Scenario`` class now has all parameters documented.
- ``BeamNGpy.debug`` API methods are now documented
- ``BeamNGpy.env`` now contains more information about the 'time of day' object
- Added documentation for RADAR and Mesh sensors

- ``Vehicle.set_part_config`` now does not recreate the existing connection to the simulator, as it was not needed

- Small refactor of unit tests, the automated sensor scripts are now also runnable under the ``pytest`` framework

- Invalid vehicle and scene object names produced error in the simulation, now the validation is done on BeamNGpy side

- name cannot start with the ``%`` character or a digit
- name cannot contain the ``/`` character
- Added new options to ``BeamNGpy.scenario.load`` called ``connect_player_vehicle`` and ``connect_existing_vehicles``

- ``connect_player_vehicle`` is ``True`` by default and it connects the player vehicle to the simulation after scenario load
- ``connect_existing_vehicles`` is ``True`` by default and it connects all the already existing vehicles to the simulation after scenario load
- setting these options to ``False`` can reduce the loading time by skipping the connection-establishing part, and these vehicles can still be connected manually using ``Vehicle.connect``

- Added ``crash_lua_on_error`` option to the BeamNGpy constructor

- behaves in the same way as the option of the same name in ``BeamNGpy.open``

============
- RADAR sensor

- Sensor currently works with static scenery but not vehicles. Will be added in later update.
- Sensor comes with standard Lua API and BeamNGpy API.
- Example scripts `provided <https://github.com/BeamNG/BeamNGpy/blob/master/examples/radar_analysis.ipynb>`__ in BeamNGpy.
- Vehicle meshes now available in BeamNGpy

- Can provide data up to 2000 times per second.
- Vehicle nodes and physics triangle data available in BeamNGpy, including for individual vehicle wheels.
- Comes with standard Lua API and BeamNGpy API.
- Post-processing written in BeamNGpy to compute mesh connectivity data and analyse the mesh data (position, mass, force, velocity).
- Example scripts `provided <https://github.com/BeamNG/BeamNGpy/blob/master/examples/vehicle_mesh_data.py>`__ in BeamNGpy.
- IMU sensor

- Added ability to filter gyroscopic readings (as well as acceleration readings). Separate data filtering is used for each.
- Sensor suite bug fixes

- Fix: problem when changing the requested update times/priority parameters after various sensors were already created, sensor would not update correctly/quickly.
- Fix: gravity vector was not being applied correctly in IMU sensor.
- Fix: camera images from static sensors were being rendered upside down.
- Fix: LiDAR sensor was not returning the whole point cloud in BeamNGpy
- Export BeamNG maps as .xodr files (OpenDrive)

- BeamNGpy now provides the option to export our map road networks as .xodr files (OpenDrive). The exported road networks contain elevation and road wideness data, along with junction connectivity. On top of this, BeamNGpy also includes a new `class <https://beamngpy.readthedocs.io/en/latest/beamngpy.html#beamngpy.tools.RoadNetworkExporter>`_ with which to analyse the road network data oneself, and process it as required.
- BeamNGpy fixes / improvements

- Optimized the speed of depth camera processing
- Added new API:

- ``BeamNGpy.env.get_tod`` for getting the information about the time of day
- ``BeamNGpy.env.set_tod`` for setting the time-of-day information, allowing to control the day/night cycle from Python
- ``BeamNGpy.env.get_gravity`` for getting the current value of the strength of gravity in the simulator.
- ``Vehicle.get_center_of_gravity`` for getting the center of gravity of a vehicle.

- Added option to remove procedural meshes
- Added new option to ``BeamNGpy.open`` called ``crash_lua_on_error``

- If ``False`` (the default), then Lua crashes in the simulator will not break the connection between BeamNG.tech and BeamNGpy. Set to ``True`` for getting proper stacktraces and easier debugging.
- Added new option to ``BeamNGpy.scenario.load`` called ``precompile_shaders``

- If ``True`` (the default), asynchronous shader compilation is disabled. That means the first loading of a map will take longer time, but all parts of the map will be preloaded. If ``False``, the camera sensor can have issues shortly after starting the scenario.
- Better handling of errors and crashes in the BeamNGpy TCP protocol.
- Fixed ``vehicle.control`` with zero integer arguments being ignored.
- Re-added ``BeamNGpy.scenario.get_vehicle`` (removed by accident in the last release).
- ``BeamNGpy.settings.set_deterministic`` and ``BeamNGpy.settings.set_steps_per_second`` are not persistent anymore and are applied only for a single run of the simulation.

==============
- fixed in BeamNG.tech v0.27.1.0: converted all vehicle rotations sent to BeamNGpy to be consistent with each other
- if the rotation you are using is 180° rotated across the Y axis, you can use the ``beamngpy.quat.flip_y_axis`` function to flip it
- fixed ``BeamNGpy.vehicles.replace`` to respect vehicle color and license plate text

============
- Added type hints to the whole BeamNGpy codebase
- Updated `documentation <https://beamngpy.readthedocs.io/en/latest/>`_ to be more readable

- Modularized BeamNGpy API

- The functions on the BeamNGpy object are now split into modules for easier navigation:

- ``BeamNGpy.camera`` - configuring the in-game camera
- ``BeamNGpy.control`` - controlling the simulator state (pausing, stepping, quitting the simulator)
- ``BeamNGpy.debug`` - drawing debug objects
- ``BeamNGpy.env`` - controlling the environment state (time of day, gravity)
- ``BeamNGpy.scenario`` - loading/starting/stopping a BeamNG scenario
- ``BeamNGpy.settings`` - changing the simulator's settings
- ``BeamNGpy.system`` - info about the host system
- ``BeamNGpy.traffic`` - controlling the traffic
- ``BeamNGpy.ui`` - controlling the GUI elements of the simulator
- ``BeamNGpy.vehicles`` - controlling vehicles
- Some of the functions on the ``Vehicle`` object are also moved into modules for easier navigation:

- ``Vehicle.ai`` - controlling the AI of the vehicle
- ``Vehicle.logging`` - controlling the in-game logging
- the previous, not modularized API is still available for backwards compatibility reasons
- see more in the `documentation <https://beamngpy.readthedocs.io/en/latest/>`_

- Advanced IMU sensor

- replaces the accelerometer sensor from last release
- improves upon the existing IMU sensor by using a more advanced algorithm, and provides readings at up to 2000 Hz
- Powertrain sensor

- new sensor for analysing powertrain properties at high frequency (up to 2000 Hz)
- new test/demo scripts are available to show execution of this sensor

- New BeamNGpy functionality

- added support for a custom binary name in BeamNGpy constructor
- ``BeamNGpy.traffic.spawn`` to spawn traffic without a set of predefined vehicles
- ``BeamNGpy.traffic.reset`` to reset all traffic vehicles from the player (teleport them away).
- ``Vehicle.teleport`` now supports changing rotation without resetting the vehicle
- ``BeamNGpy.open`` now always tries to connect to already running simulator no matter the value of the launch argument
- ``Vehicle.switch``, ``Vehicle.focus`` to switch the simulator's focus to the selected vehicle
- ``BeamNGpy.vehicles.spawn`` now has a new argument ``connect`` to allow for not connecting the newly spawned vehicle to BeamNGpy
- ``Vehicle.recover`` to repair a vehicle and teleport it to a drivable position
- ``BeamNGpy.vehicles.replace`` to replace a vehicle with another one at the same position
- ``beamngpy.quat.quat_multiply`` utility function to multiply two quaternions
- optimized the ``Camera`` sensor decoding to be faster
- updated the required Python packages to newer versions
- ``Vehicle.set_license_plate`` to set a license plate text for a vehicle
- ``Vehicle.sensors.poll`` now allows also polling only a specified list of sensor names
- ``BeamNGpy.disconnect`` to disconnect from the simulator without closing it
- changed ``Camera`` sensor default parameters to not include annotation and depth data (for faster polling)
- added the optional ``steps_per_second`` parameter to ``BeamNGpy.settings.set_deterministic``
- ``BeamNGpy.control.return_to_main_menu`` to exit the currently loaded scenario
- added the parameter ``quit_on_close`` to the BeamNGpy constructor. If set to ``False``, ``BeamNGpy.close`` will keep the simulator running.

- Bugfixes

- ``Vehicle.state['rotation']`` now returns vehicle rotation consistent with the rest of the simulator. Previously, this rotation was rotated 180° around the Y axis.

- ⚠️ if you are using ``Vehicle.state['rotation']`` in your existing scripts, you may need to flip it back for your intended use. You can use ``beamngpy.quat.quat_multiply((0, 0, 1, 0), <your_rotation>)`` for that purpose.
- fixed the issue with BeamNGpy scenarios sometimes resetting and not working properly after loading
- fixed ``Camera.extract_bounding_boxes`` not to crash on non-Windows systems
- fixed ``beamng.scenario.start()`` not working when the simulator was paused with ``beamng.control.pause()`` before
- fixed vehicle color and license plate text not being applied to dynamically spawned vehicles

- BeamNGpy protocol: added support for out-of-order protocol messages
- Deprecations

- the ``remote`` argument of the ``BeamNGpy`` class is not used anymore

============
- Major changes to the protocol communicating between BeamNG.tech and BeamNGpy

- Be aware that versions of BeamNG.tech older than 0.26 are not compatible with BeamNGpy 1.24
and older versions of BeamNGpy will not work with BeamNG.tech 0.26.
- Major updates to BeamNGpy sensor suite and its API

- The public API of the ``Camera``, ``Lidar`` and ``Ultrasonic`` sensors changed heavily, please see
the ``examples`` folder to see their usage.
- Accelerometer sensor now available
- Add support for loading TrackBuilder tracks
- Add support for loading Flowgraph scenarios
- Fix: multiple vehicles now do not share color in instance annotations
- Add ``Vehicle.teleport`` helper function which allows to teleport a vehicle directly through its instance
- ``BeamNGpy.open`` now tries to (re)connect to already running local instance
- Removed deprecated BeamNGpy functionality

- ``setup_logging`` (superseded by ``set_up_simple_logging`` and ``config_logging``)
- ``rot`` argument used for setting rotation of objects and vehicles in Euler angles, use ``rot_quat`` which expects quaternions
(you can use the helper function ``angle_to_quat`` to convert Euler angles to quaternions)
- ``update_vehicle`` function is removed
- the ``requests`` argument in ``Vehicle.poll_sensors`` is removed
- ``poll_sensors`` now does not return a value
- the ``deploy`` argument of ``BeamNGpy.open`` is removed

==============
- Add Feature Overview notebook
- Add argument checking to the IMU sensor
- Add support for Mesh Roads
- Add option to log BeamNGpy protocol messages
- Fix duplicate logging when calling ``config_logging`` multiple times