Overview
GPS sensors provide global positional information for BeamNG vehicles, in longitude/lattitude. They can be attached to any point on, in, or relative to the vehicle as required, and their update rates can be set up to an accuracy of half a millisecond.
A common use case for GPS sensors is to produce trajectory data for a vehicle journey. If multiple are combined (eg a front GPS unit and a rear GPS unit, as in the image above), directional data may also be determined.
Since the maps in BeamNG.tech have no real-world GPS location in longitude/lattitude, it is left to the user to provide a reference point in this coordinate system. This reference point relates to the origin, i.e. point (0, 0), of the BeamNG.tech map.
Usage
The GPS sensor code is written in Lua directly, rather than C++. It has a very similar API to the other sensors in our suite (eg Advanced IMU).
For other usage examples with this sensor, please look at the BeamNGpy script GPS_Trajectory.py in the BeamNGpy examples folder.
sensorId = extensions.tech_sensors.createGPS(vehicleId, args)
Args:
vehicleID(int): The vehicle ID, to which the GPS sensor is to be attached.
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 GPS sensor with args being an empty table. What follows is a complete list of these arguments:
pos(Point3F): The position of the GPS sensor, in vehicle space.
GFXUpdateTime(float): How often the GPS sensor should update its readings in the simulator (in seconds). This determines how often the user will be able to retrieve a new reading from the sensor.
physicsUpdateTime(float): How often in the simulator’s physics step, we should update the GPS readings (in seconds). This parameter should be smaller than GFXUpdateTime, and can be as small as 1/2000 seconds, since this is currently the rate at which the physics steps cycles. This value determines how often we poll the GPU to get a snapshot of data at a given time, so the smaller this is, the more accurate the readings will be (at the cost of computation load in the simulation - for a small number of sensors this should not matter, either way).
refLon(float): The reference longitude value (see above for more information).
refLat(float): The reference lattitude value (see above for more information).
isVisualised(bool): A flag which indicates if the GPS sensor should be visualised.
isSnappingDesired(bool): True if the GPS 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 sensor on the vehicle itself. False, otherwise, eg if the sensor should be suspended at a fixed point relative to the vehicle.
isForceInsideTriangle(bool): Used with isSnappingDesired. True, if the GPS 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.
readings = extensions.tech_sensors.getGPSReadings(sensorId)
Args:
sensorId(int): The ID number of the GPS sensor.
Returns: readings(vec3): The latest readings from the sensor.
extensions.tech_sensors.setGPSUpdateTime(sensorId, updateTime)
Args:
sensorId(int): The ID number of the GPS sensor.
updateTime(float): The new update time for this sensor.
Returns: nil
extensions.tech_sensors.setGPSIsVisualised(sensorId, isVisualised)
Args:
sensorId(int): The ID number of the GPS sensor.
isVisualised(bool): Whether the GPS should be visualised or not.
Returns: nil
The following three functions can be used to send ad-hoc polling requests to an GPS sensor. This is for when we just want an occasional reading. We need to first send a request using sendGPSRequest, then wait for it. We can check it is complete using isVluaRequestComplete (see below), then retrieve it using collectGPSRequest.
requestId = extensions.tech_sensors.sendGPSRequest(sensorId)
Args:
sensorId(int): The ID number of the GPS sensor.
Returns: The unique Id number of the ad-hoc sensor polling request which is being sent.
isComplete = extensions.tech_sensors.isVluaRequestComplete(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.collectGPSRequest(requestId)
Args:
requestId(int): The ID number of the ad-hoc sensor polling request.
Returns: data(vec3): The ad-hoc GPS reading.
extensions.tech_sensors.removeGPS(sensorId)
Args:
sensorId(int): The ID number of the GPS sensor to remove.
Returns: nil.
