Overview
BeamNG.tech ships with a simulated Ultrasonic sensor which measures distances to nearby surfaces, commonly as an aid to vehicle parking. The range and detection sensitivity are physically-based and customisable by the user. Single or multiple ultrasonic sensors can be attached to vehicles or places at fixed locations.
Usage
Ultrasonic sensors are exposed to Lua through the sensors extension in the tech folder. Using this API, an ultrasonic sensor can be created with various range and detection properties, and either attached to a vehicle or to a fixed point on the map.
sensorId = extensions.tech_sensors.createUltrasonic(vehicleId, args)
Args:
vehicleID(int): The vehicle ID. This can be nil if the ultrasonic sensor is not to be attached to any vehicle.
The args parameter is a Lua table containing as many of the following properties as required. If any property is not set manually then a default value is used, so it is entirely possible to create the ultrasonic sensor with args being an empty table. What follows is a complete list of these arguments:
updateTime(float): How often the ultrasonic sensor should update its readings in the simulator (in seconds).
updatePriority(float): A scheduling priority value for this ultrasonic sensor, in range 0 to 1. 0 is highest priority, 1 is least.
pos(Point3F): The position of the ultrasonic sensor either in vehicle space (if attached to vehicle) or in world space (if fixed to the map).
dir(Point3F): The forward direction in which the ultrasonic sensor points.
up(Point3F): The up direction of the ultrasonic sensor.
size(table): The horizontal and vertical resolution of the ultrasonic sensor.
fovY(float): The vertical field of view of the ultrasonic sensor, in degrees.
nearFarPlanes(table): The near and far plane distances of the ultrasonic sensor, in metres.
rangeRoundness(float): The general roundness of the ultrasonic sensors range shape. Can be negative.
rangeCutoffSensitivity(float): A cutoff sensitivity parameter for the ultrasonic sensor range-shape.
rangeShape(float): The shape of the ultrasonic sensor range-shape in the range [0, 1], going from conical to spherical.
rangeFocus(float): The focus parameter for the ultrasonic sensor range-shape.
rangeMinCutoff(float): The minimum cut-off distance for the ultrasonic sensor range-shape. Nothing closer than this will be detected.
rangeDirectMaxCutoff(float): The maximum cut-off distance for the ultrasonic sensor range-shape. This parameter is a hard cutoff - nothing further than this will be detected, although other parameters can also control the maximum distance.
sensitivity(float): The sensitivity of the ultrasonic sensor detection.
fixedWindowSize(float): Used with sensitivity to set how sharply the ultrasonic sensor detects surfaces.
isVisualised(bool): A flag which indicates if the ultrasonic sensor should be visualised.
isStatic(bool): True if the ultrasonic sensor is fixed to a point on the map, false if it is attached to a vehicle.
isSnappingDesired(bool): True if the ultrasonic sensor position should be forced onto the surface of the vehicle, at its closest vehicle point. This is useful if finding it hard to have the ultrasonic sensor on the vehicle itself. False, otherwise, eg if the ultrasonic sensor should be suspended at a fixed point relative to the vehicle.
isForceInsideTriangle(bool): Used with isSnappingDesired. True, if the ultrasonic sensor should be forced to be inside its nearest vehicle triangle. Otherwise false.
Returns: sensorId(int): The unique Id number of this sensor, in order to refer to it later eg when closing it.
distance = extensions.tech_sensors.getUltrasonicDistanceMeasurement(sensorId)
Args:
sensorId(int): The ID number of the ultrasonic sensor.
Returns: distance(float): The most-recent distance measurement from the ultrasonic sensor, in metres.
windowMin = extensions.tech_sensors.getUltrasonicWindowMin(sensorId)
Args:
sensorId(int): The ID number of the ultrasonic sensor.
Returns: windowMin(float): The most-recent minimum value of the detection window (used to detect surfaces).
windowMax = extensions.tech_sensors.getUltrasonicWindowMax(sensorId)
Args:
sensorId(int): The ID number of the ultrasonic sensor.
Returns: windowMax(float): The most-recent maximum value of the detection window (used to detect surfaces).
activeSensors = extensions.tech_sensors.getUltrasonicActiveSensors()
Args:
sensorId(int): The ID number of the ultrasonic sensor.
Returns: activeSensors(table(int)): The ID numbers of all currently active ultrasonic sensors in the simulation.
isVisualised = extensions.tech_sensors.getUltrasonicIsVisualised(sensorId)
Args:
sensorId(int): The ID number of the ultrasonic sensor.
Returns: isVisualised(bool): True if the ultrasonic sensor is being visualised, otherwise false.
extensions.tech_sensors.setUltrasonicIsVisualised(sensorId, isVisualised)
Args:
sensorId(int): The ID number of the ultrasonic sensor.
isVisualised(bool): A flag which indicates if the ultrasonic sensor should be visualised or not.
Returns: nil.
sensorPosition = extensions.tech_sensors.getUltrasonicSensorPosition(sensorId)
Args:
sensorId(int): The ID number of the ultrasonic sensor.
Returns: sensorPosition(Point3F) The current position of the ultrasonic sensor, in world space.
sensorDirection = extensions.tech_sensors.getUltrasonicSensorDirection(sensorId)
Args:
sensorId(int): The ID number of the ultrasonic sensor.
Returns: sensorDirection(Point3F): The current direction of the ultrasonic sensor.
radius = extensions.tech_sensors.getUltrasonicSensorRadius(sensorId, distanceFromSensor)
Args:
sensorId(int): The ID number of the ultrasonic sensor.
distanceFromSensor(float): The distance from the ultrasonic sensor, at which the radius should be computed.
Returns: radius(float): The radius of the range shape at the given distance from the ultrasonic sensor.
maxPendingGpuRequests = extensions.tech_sensors.getUltrasonicMaxPendingGpuRequests(sensorId)
Args:
sensorId(int): The ID number of the Ultrasonic sensor.
Returns: maxPendingGpuRequests(int): The maximum number of pending GPU requests for this Ultrasonic sensor.
requestedUpdateTime = extensions.tech_sensors.getUltrasonicRequestedUpdateTime(sensorId)
Args:
sensorId(int): The ID number of the Ultrasonic sensor.
Returns: requestedUpdateTime(float): The current requested update time used by this Ultrasonic sensor.
updatePriority = extensions.tech_sensors.getUltrasonicUpdatePriority(sensorId)
Args:
sensorId(int): The ID number of the Ultrasonicsensor.
Returns: updatePriority(float): The current update priority used by this Ultrasonic sensor.
extensions.tech_sensors.setUltrasonicMaxPendingGpuRequests(sensorId, maxPendingGpuRequests)
Args:
sensorId(int): The ID number of the Ultrasonic sensor.
maxPendingGpuRequests(int): The new maximum number of pending GPU requests for this Ultrasonic sensor.
extensions.tech_sensors.setUltrasonicRequestedUpdateTime(sensorId, requestedUpdateTime)
Args:
sensorId(int): The ID number of the Ultrasonic sensor.
requestedUpdateTime(float): The new requested update time for this Ultrasonic sensor.
extensions.tech_sensors.setUltrasonicUpdatePriority(sensorId, updatePriority)
Args:
sensorId(int): The ID number of the Ultrasonic sensor.
updatePriority(float): The new update priority for this Ultrasonic sensor.
The following three functions can be used to send ad-hoc polling requests to an Ultrasonic sensor. This is when we just want an occasional reading. We need to first send a request using sendUltrasonicRequest, then wait for it. We can check it is complete using isRequestComplete (see below), then retrieve it using collectUltrasonicRequest.
requestId = extensions.tech_sensors.sendUltrasonicRequest(sensorId)
Args:
sensorId(int): The ID number of the Ultrasonic sensor.
Returns: The unique Id number of the ad-hoc sensor polling request which is being sent.
isComplete = extensions.tech_sensors.isRequestComplete(requestId)
Args:
requestId(int): The ID number of the ad-hoc sensor polling request to check on.
Returns: isComplete(bool): True if the ad-hoc polling request has been completed, otherwise false.
data = extensions.tech_sensors.collectUltrasonicRequest(requestId)
Args:
requestId(int): The ID number of the ad-hoc sensor polling request.
Returns: data(table): The Ultrasonic readings.
extensions.tech_sensors.removeSensor(sensorId)
Args:
sensorId(int): The ID number of the Lidar sensor to remove.
Returns: nil.
