Contact point and wheel height API extensions

CHANGELOG.md

@@ -10,6 +10,8 @@
  * Improved V2X sensor capabilities: send complex custom user-defined data, support V2I sensors not attached to a vehicle
  * Introduced fine grained ServerSynchronization mechanism: each client decides for its own if it requires synchronization or not and provides its own synchronization window.
    Be aware: some existing code using master/slave sync mechanism might need rework. See also generate_traffic.py.
+ * Added a function to get arbitrary number of contact points (`World.get_contact_points`).
+ * Added functions to get and set the wheel height.
 
 ## CARLA 0.9.16
 

Docs/python_api.md

@@ -802,6 +802,21 @@ Iterate over the [CustomV2XData](#carlacustomv2xdata) retrieved as data.
 
 ---
 
+
+## carla.ContactPoint<a name="carla.ContactPoint"></a>
+Class that represents a contact point with a surface. It exposes the normal vector and the friction coefficient of the surface.
+
+### Instance Variables
+- <a name="carla.ContactPoint.location"></a>**<font color="#f8805a">location</font>** (_[carla.Location](#carla.Location)_)
+Position in 3D space.
+- <a name="carla.ContactPoint.normal"></a>**<font color="#f8805a">normal</font>** (_[carla.Vector3D](#carla.Vector3D)_)
+Normal vector of the surface on which the contact point lies.
+- <a name="carla.ContactPoint.friction"></a>**<font color="#f8805a">friction</font>** (_float_)
+Surface friction coefficient. If the surface material is not defined in the map, the friction coefficient is set to -1.0.
+
+---
+
+
 ## carla.DVSEvent<a name="carla.DVSEvent"></a>
 Class that defines a DVS event. An event is a quadruple, so a tuple of 4 elements, with `x`, `y` pixel coordinate location, timestamp `t` and polarity `pol` of the event. Learn more about them [here](ref_sensors.md).  
 
@@ -3241,6 +3256,16 @@ Returns the physics angle in degrees of a vehicle's wheel.
     - **Return:** _float_  
     - **Note:** <font color="#8E8E8E">_Returns the angle based on the physics of the wheel, not the visual angle.
 _</font>  
+- <a name="carla.Vehicle.get_wheel_pitch_angle"></a>**<font color="#7fb800">get_wheel_pitch_angle</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**wheel_location**</font>)
+Returns the pitch angle in degrees of a vehicle's wheel.
+    - **Parameters:**
+        - `wheel_location` (_[carla.VehicleWheelLocation](#carla.VehicleWheelLocation)_)
+    - **Return:** _float_
+- <a name="carla.Vehicle.get_wheel_height"></a>**<font color="#7fb800">get_wheel_height</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**wheel_location**</font>)
+Returns the height of a vehicle's wheel.
+    - **Parameters:**
+        - `wheel_location` (_[carla.VehicleWheelLocation](#carla.VehicleWheelLocation)_)
+    - **Return:** _float_
 
 ##### Setters
 - <a name="carla.Vehicle.set_autopilot"></a>**<font color="#7fb800">set_autopilot</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**enabled**=True</font>, <font color="#00a6ed">**port**=8000</font>)  
@@ -3259,7 +3284,17 @@ Sets the angle of a vehicle's wheel visually.
         - `wheel_location` (_[carla.VehicleWheelLocation](#carla.VehicleWheelLocation)_)  
         - `angle_in_deg` (_float_)  
     - **Warning:** <font color="#ED2F2F">_Does not affect the physics of the vehicle.
-_</font>  
+_</font>
+- <a name="carla.Vehicle.set_wheel_pitch_angle"></a>**<font color="#7fb800">set_wheel_pitch_angle</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**wheel_location**</font>, <font color="#00a6ed">**angle_in_deg**</font>)
+Sets the pitch angle of a vehicle's wheel visually.
+    - **Parameters:**
+        - `wheel_location` (_[carla.VehicleWheelLocation](#carla.VehicleWheelLocation)_)
+        - `angle_in_deg` (_float_)
+- <a name="carla.Vehicle.set_wheel_height"></a>**<font color="#7fb800">set_wheel_height</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**wheel_location**</font>, <font color="#00a6ed">**height**</font>)
+Sets the height of a vehicle's wheel visually.
+    - **Parameters:**
+        - `wheel_location` (_[carla.VehicleWheelLocation](#carla.VehicleWheelLocation)_)
+        - `height` (_float_)
 
 ##### Dunder methods
 - <a name="carla.Vehicle.__str__"></a>**<font color="#7fb800">\__str__</font>**(<font color="#00a6ed">**self**</font>)  
@@ -3895,6 +3930,14 @@ Projects the specified point downwards in the scene. The functions casts a ray f
         - `location` (_[carla.Location](#carla.Location)_) - The point to be projected.  
         - `search_distance` (_float_) - The maximum distance to perform the projection.  
     - **Return:** _[carla.LabelledPoint](#carla.LabelledPoint)_  
+- <a name="carla.World.get_contact_points"></a>**<font color="#7fb800">get_contact_points</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**locations**</font>, <font color="#00a6ed">**directions**</font>, <font color="#00a6ed">**ignored_actor_ids**</font>, <font color="#00a6ed">**search_distance**</font>)
+Casts rays from the specified locations in the given directions, in order to find the first intersection of each ray with a surface. Intersections with actors defined via the given ids are ignored. For each intersection a [carla.ContactPoint](#carla.ContactPoint) is returned. If no intersection was found in the search_distance range, `None` is returned instead of a [carla.ContactPoint](#carla.ContactPoint).
+    - **Parameters:**
+        - `locations` (_list([carla.Location](#carla.Location))_) - Points to be projected.
+        - `directions` (_list([carla.Vector3D](#carla.Vector3D))_) - A direction in which a ray should be casted for each point in `locations`. If the length of `directions` is smaller than the lenght of `locations`, the last direction vector will be used for all points from `locations` that don't have a corresponding direction vector defined.
+        - `ignored_actor_ids` (_list(int)_) - Actors ignored during ray casting. In most use cases this would be the actor for which the contact point is checked.
+        - `search_distance` (_float_) - The maximum distance to perform the projection.
+    - **Return:** _list([carla.ContactPoint](#carla.ContactPoint) | None)_
 - <a name="carla.World.load_map_layer"></a>**<font color="#7fb800">load_map_layer</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**map_layers**</font>)<button class="SnipetButton" id="carla.World.load_map_layer-snipet_button">snippet &rarr;</button>  
 Loads the selected layers to the level. If the layer is already loaded the call has no effect.  
     - **Parameters:**

LibCarla/source/carla/client/Vehicle.cpp

@@ -3,6 +3,8 @@
 //
 // This work is licensed under the terms of the MIT license.
 // For a copy, see <https://opensource.org/licenses/MIT>.
+//
+// Additional functionality added by AVL List GmbH under the terms of the MIT license.
 
 #include "carla/client/Vehicle.h"
 
@@ -103,6 +105,14 @@ namespace client {
     return GetEpisode().Lock()->GetWheelPitchAngle(*this, wheel_location);
   }
 
+  void Vehicle::SetWheelHeight(WheelLocation wheel_location, float height) {
+    GetEpisode().Lock()->SetWheelHeight(*this, wheel_location, height);
+  }
+
+  float Vehicle::GetWheelHeight(WheelLocation wheel_location) {
+    return GetEpisode().Lock()->GetWheelHeight(*this, wheel_location);
+  }
+
   Vehicle::Control Vehicle::GetControl() const {
     return GetEpisode().Lock()->GetActorSnapshot(*this).state.vehicle_data.GetVehicleControl();
   }

LibCarla/source/carla/client/Vehicle.h

@@ -3,6 +3,8 @@
 //
 // This work is licensed under the terms of the MIT license.
 // For a copy, see <https://opensource.org/licenses/MIT>.
+//
+// Additional functionality added by AVL List GmbH under the terms of the MIT license.
 
 #pragma once
 
@@ -98,6 +100,12 @@ namespace client {
     /// @note The function returns the pitch angle of the vehicle based on the it's physics
     float GetWheelPitchAngle(WheelLocation wheel_location);
 
+    /// Sets the height of a wheel of the vehicle (affects the bone of the car skeleton, not the physics)
+    void SetWheelHeight(WheelLocation wheel_location, float height);
+
+    /// Return the height of a wheel of the vehicle
+    float GetWheelHeight(WheelLocation wheel_location);
+
     /// Return the control last applied to this vehicle.
     ///
     /// @note This function does not call the simulator, it returns the data

LibCarla/source/carla/client/World.cpp

@@ -3,6 +3,8 @@
 //
 // This work is licensed under the terms of the MIT license.
 // For a copy, see <https://opensource.org/licenses/MIT>.
+//
+// Additional functionality added by AVL List GmbH under the terms of the MIT license.
 
 #include "carla/client/World.h"
 
@@ -270,6 +272,27 @@ namespace client {
     return ProjectPoint(location, DownVector, search_distance);
   }
 
+  std::vector<boost::optional<rpc::ContactPoint>> World::GetContactPoints(
+      const std::vector<geom::Location>& locations,
+      const std::vector<ActorId>& ignored_actor_ids,
+      const std::vector<geom::Vector3D>& directions,
+      float search_distance) const {
+    auto result = _episode.Lock()->GetContactPoints(locations, directions, search_distance, ignored_actor_ids);
+
+    std::vector<boost::optional<rpc::ContactPoint>> points;
+    points.reserve(result.size());
+
+    for (auto& p : result) {
+      if (p.first) {
+        points.emplace_back(p.second);
+      } else {
+        points.emplace_back();
+      }
+    }
+
+    return points;
+  }
+
   std::vector<rpc::LabelledPoint> World::CastRay(
       geom::Location start_location, geom::Location end_location) const {
     return _episode.Lock()->CastRay(start_location, end_location);

LibCarla/source/carla/client/World.h

@@ -3,6 +3,8 @@
 //
 // This work is licensed under the terms of the MIT license.
 // For a copy, see <https://opensource.org/licenses/MIT>.
+//
+// Additional functionality added by AVL List GmbH under the terms of the MIT license.
 
 #pragma once
 
@@ -22,6 +24,7 @@
 #include "carla/rpc/EpisodeSettings.h"
 #include "carla/rpc/EnvironmentObject.h"
 #include "carla/rpc/LabelledPoint.h"
+#include "carla/rpc/ContactPoint.h"
 #include "carla/rpc/MapLayer.h"
 #include "carla/rpc/VehiclePhysicsControl.h"
 #include "carla/rpc/WeatherParameters.h"
@@ -196,6 +199,12 @@ namespace client {
     boost::optional<rpc::LabelledPoint> GroundProjection(
         geom::Location location, float search_distance = 10000.0) const;
 
+    std::vector<boost::optional<rpc::ContactPoint>> GetContactPoints(
+        const std::vector<geom::Location>& locations,
+        const std::vector<ActorId>& ignored_actor_ids,
+        const std::vector<geom::Vector3D>& directions,
+        float search_distance = 10000.0f) const;
+
     std::vector<rpc::LabelledPoint> CastRay(
         geom::Location start_location, geom::Location end_location) const;
 

LibCarla/source/carla/client/detail/Client.cpp

@@ -3,6 +3,8 @@
 //
 // This work is licensed under the terms of the MIT license.
 // For a copy, see <https://opensource.org/licenses/MIT>.
+//
+// Additional functionality added by AVL List GmbH under the terms of the MIT license.
 
 #include "carla/client/detail/Client.h"
 
@@ -365,6 +367,19 @@ namespace detail {
     return _pimpl->CallAndWait<float>("get_wheel_pitch_angle", vehicle, wheel_location);
   }
 
+  void Client::SetWheelHeight(
+        rpc::ActorId vehicle,
+        rpc::VehicleWheelLocation vehicle_wheel,
+        float height) {
+    return _pimpl->AsyncCall("set_wheel_height", vehicle, vehicle_wheel, height);
+  }
+
+  float Client::GetWheelHeight(
+        rpc::ActorId vehicle,
+        rpc::VehicleWheelLocation wheel_location){
+    return _pimpl->CallAndWait<float>("get_wheel_height", vehicle, wheel_location);
+  }
+
   rpc::Actor Client::SpawnActor(
       const rpc::ActorDescription &description,
       const geom::Transform &transform) {
@@ -823,6 +838,15 @@ namespace detail {
     return _pimpl->CallAndWait<return_t>("project_point", location, direction, search_distance);
   }
 
+  std::vector<std::pair<bool, rpc::ContactPoint>> Client::GetContactPoints(
+      const std::vector<geom::Location>& locations,
+      const std::vector<geom::Vector3D>& directions,
+      float search_distance,
+      const std::vector<ActorId>& ignored_actor_ids) const {
+    using return_t = std::vector<std::pair<bool, rpc::ContactPoint>>;
+    return _pimpl->CallAndWait<return_t>("contact_points", locations, directions, search_distance, ignored_actor_ids);
+  }
+
   std::vector<rpc::LabelledPoint> Client::CastRay(
       geom::Location start_location, geom::Location end_location) const {
     using return_t = std::vector<rpc::LabelledPoint>;

LibCarla/source/carla/client/detail/Client.h

@@ -3,6 +3,8 @@
 //
 // This work is licensed under the terms of the MIT license.
 // For a copy, see <https://opensource.org/licenses/MIT>.
+//
+// Additional functionality added by AVL List GmbH under the terms of the MIT license.
 
 #pragma once
 
@@ -21,6 +23,7 @@
 #include "carla/rpc/EpisodeInfo.h"
 #include "carla/rpc/EpisodeSettings.h"
 #include "carla/rpc/LabelledPoint.h"
+#include "carla/rpc/ContactPoint.h"
 #include "carla/rpc/LightState.h"
 #include "carla/rpc/MapInfo.h"
 #include "carla/rpc/MapLayer.h"
@@ -354,6 +357,17 @@ namespace detail {
         rpc::VehicleWheelLocation wheel_location
     );
 
+    void SetWheelHeight(
+        rpc::ActorId vehicle,
+        rpc::VehicleWheelLocation vehicle_wheel,
+        float height
+    );
+
+    float GetWheelHeight(
+        rpc::ActorId vehicle,
+        rpc::VehicleWheelLocation wheel_location
+    );
+
     void EnableChronoPhysics(
         rpc::ActorId vehicle,
         uint64_t MaxSubsteps,
@@ -508,6 +522,12 @@ namespace detail {
     std::pair<bool,rpc::LabelledPoint> ProjectPoint(
         geom::Location location, geom::Vector3D direction, float search_distance) const;
 
+    std::vector<std::pair<bool, rpc::ContactPoint>> GetContactPoints(
+        const std::vector<geom::Location>& locations,
+        const std::vector<geom::Vector3D>& directions,
+        float search_distance,
+        const std::vector<ActorId>& ignored_actor_ids) const;
+
     std::vector<rpc::LabelledPoint> CastRay(
         geom::Location start_location, geom::Location end_location) const;
 

LibCarla/source/carla/client/detail/Simulator.h

@@ -3,6 +3,8 @@
 //
 // This work is licensed under the terms of the MIT license.
 // For a copy, see <https://opensource.org/licenses/MIT>.
+//
+// Additional functionality added by AVL List GmbH under the terms of the MIT license.
 
 #pragma once
 
@@ -26,6 +28,7 @@
 #include "carla/rpc/TrafficLightState.h"
 #include "carla/rpc/VehicleLightStateList.h"
 #include "carla/rpc/LabelledPoint.h"
+#include "carla/rpc/ContactPoint.h"
 #include "carla/rpc/VehicleWheels.h"
 #include "carla/rpc/Texture.h"
 #include "carla/rpc/MaterialParameter.h"
@@ -300,6 +303,14 @@ namespace detail {
       return _client.ProjectPoint(location, direction, search_distance);
     }
 
+    std::vector<std::pair<bool, rpc::ContactPoint>> GetContactPoints(
+        const std::vector<geom::Location>& locations,
+        const std::vector<geom::Vector3D>& directions,
+        float search_distance,
+        const std::vector<ActorId>& ignored_actor_ids) const {
+      return _client.GetContactPoints(locations, directions, search_distance, ignored_actor_ids);
+    }
+
     std::vector<rpc::LabelledPoint> CastRay(
         geom::Location start_location, geom::Location end_location) const {
       return _client.CastRay(start_location, end_location);
@@ -633,6 +644,14 @@ namespace detail {
       return _client.GetWheelPitchAngle(vehicle.GetId(), wheel_location);
     }
 
+    void SetWheelHeight(Vehicle &vehicle, rpc::VehicleWheelLocation wheel_location, float height) {
+      _client.SetWheelHeight(vehicle.GetId(), wheel_location, height);
+    }
+
+    float GetWheelHeight(Vehicle &vehicle, rpc::VehicleWheelLocation wheel_location) {
+      return _client.GetWheelHeight(vehicle.GetId(), wheel_location);
+    }
+
     void EnableCarSim(Vehicle &vehicle, std::string simfile_path) {
       _client.EnableCarSim(vehicle.GetId(), simfile_path);
     }

LibCarla/source/carla/rpc/ContactPoint.h

@@ -0,0 +1,31 @@
+// Copyright (c) 2025 AVL List GmbH
+//
+// This work is licensed under the terms of the MIT license.
+// For a copy, see <https://opensource.org/licenses/MIT>.
+
+#pragma once
+
+#include "carla/MsgPack.h"
+#include "carla/rpc/Location.h"
+#include "carla/rpc/Vector3D.h"
+
+namespace carla {
+namespace rpc {
+
+  struct ContactPoint {
+
+    ContactPoint () {}
+    ContactPoint(Location location, Vector3D normal, float friction)
+     : _location(location), _normal(normal), _friction(friction)
+     {}
+
+    Location _location;
+    Vector3D _normal;
+    float _friction = -1.0f;
+
+    MSGPACK_DEFINE_ARRAY(_location, _normal, _friction);
+
+  };
+
+}
+}

PythonAPI/carla/source/libcarla/Actor.cpp

@@ -3,6 +3,8 @@
 //
 // This work is licensed under the terms of the MIT license.
 // For a copy, see <https://opensource.org/licenses/MIT>.
+//
+// Additional functionality added by AVL List GmbH under the terms of the MIT license.
 
 #include <carla/client/Actor.h>
 #include <carla/client/TrafficLight.h>
@@ -206,6 +208,8 @@ void export_actor() {
       .def("get_wheel_steer_angle", &cc::Vehicle::GetWheelSteerAngle, (arg("wheel_location")))
       .def("set_wheel_pitch_angle", &cc::Vehicle::SetWheelPitchAngle, (arg("wheel_location")), (arg("angle_in_deg")))
       .def("get_wheel_pitch_angle", &cc::Vehicle::GetWheelPitchAngle, (arg("wheel_location")))
+      .def("set_wheel_height", &cc::Vehicle::SetWheelHeight, (arg("wheel_location")), (arg("height")))
+      .def("get_wheel_height", &cc::Vehicle::GetWheelHeight, (arg("wheel_location")))
       .def("get_light_state", CONST_CALL_WITHOUT_GIL(cc::Vehicle, GetLightState))
       .def("apply_physics_control", &cc::Vehicle::ApplyPhysicsControl, (arg("physics_control")))
       .def("get_physics_control", CONST_CALL_WITHOUT_GIL(cc::Vehicle, GetPhysicsControl))