3.21 DistanceSensor
Derived from Device.
DistanceSensor { |
3.21.1 Description
The DistanceSensor node can be used to model an infra-red sensor, a sonar sensor, or a laser range-finder. This device simulation is performed by detecting the collisions between one or several sensor rays and the bounding objects of Solid nodes in the environment.
The rays of the DistanceSensor nodes can be displayed by checking the menu View > Optional Rendering > Show Distance Sensor Rays. The red/green transition on the rays indicates the points of intersection with the bounding objects.
3.21.2 Field Summary
-
lookupTable: a table used for specifying the desired response curve and noise of the device. This table indicates how the ray intersection distances measured by Webots must be mapped to response values returned by the function wb_distance_sensor_get_value(). The first column of the table specifies the input distances, the second column specifies the corresponding desired response values, and the third column indicates the desired noise. The noise on the return value is computed according to a uniform random number distribution whose range is calculated as a percent of the response value. Let us consider an example:
lookupTable [ 0 1000 0,
0.1 1000 0.1,
0.2 400 0.1,
0.3 50 0.1,
0.37 30 0 ]The above lookup table means that for a distance of 0 meters, the sensor will return a value of 1000 without noise (0); for a distance of 0.1 meter, the sensor will return 1000 with a noise of up to 10 percent (100); for a distance value of 0.2 meters, the sensor will return 400 plus or minus up to 10 percent (40), etc. Distance values not directly specified in the lookup table will be linearly interpolated. This can be better understood in the figure below. Note that the input values of a lookup table must always be positive and sorted in increasing order.

Figure 3.9: Sensor response versus obstacle distance
-
type: one of "infra-red" (the default), "sonar" or "laser". Sensors of type "infra-red" are sensitive to the objects' colors; light and red (RGB) obstacles have a higher response than dark and non-red obstacles (see below for more details). Sensors of type "sonar" and "laser" return the distance to the nearest object while "infa-red" computes the average distance of all rays. Sensors of type "laser" can have only one ray and they have the particularity to draw a red spot at the point where this ray hits an obstacle. This red spot is visible on the camera images.
-
numberOfRays: number of rays cast by the sensor. The number of rays must be equal to, or greater than 1 for "infra-red" and "sonar" sensors. numberOfRays must be exactly 1 for "laser" sensors. If this number is larger than 1, then several rays are used and the sensor measurement value is computed from the weighted average of the individual rays' responses. By using multiple rays, a more accurate model of the physical infra-red or ultrasound sensor can be obtained. The sensor rays are distributed inside 3D-cones whose opening angles can be tuned through the aperture parameter. See figure 3.10 for the ray distributions from one to ten rays. The spacial distribution of the rays is as much as possible uniform and has a left/right symmetry. There is no upper limit on the number of rays; however, Webots' performance drops as the number of rays increases.

Figure 3.10: Predefined configurations for 1 through 10 sensor rays
-
aperture: sensor aperture angle or laser beam radius. For the "infra-red" and "sonar" sensor types, this parameter controls the opening angle (in radians) of the cone of rays when multiple rays are used. For the "laser" sensor type, this parameter specifies (in meters) the radius of the red spot drawn where the laser beam hits an obstacle.

Figure 3.11: Weight distribution formulas
-
gaussianWidth: width of the Gaussian distribution of sensor ray weights (for "infra-red" sensors). When averaging the sensor's response, the individual weight of each sensor ray is computed according to a Gaussian distribution as described in figure 3.11. where wi is the weight of the ith ray, ti is the angle between the ith ray and the sensor axis, a is the aperture angle of the sensor, g is the Gaussian width, and n is the number of rays. As depicted in figure 3.12, rays in the center of the sensor cone are given a greater weight than rays in the periphery. A wider or narrower distribution can be obtained by tuning the gaussianWidth parameter. An approximation of a flat distribution is obtained if a sufficiently large number is chosen for the gaussianWidth. This field is ignored for the "sonar" and "laser" DistanceSensor types.

Figure 3.12: Example distribution for 10 rays using a Gaussian width of 0.5
|
|
3.21.3 DistanceSensor types
This table summarizes the difference between the three types of DistanceSensor.
| type (field) | "infra-red" | "sonar" | "laser" |
| numberOfRays (field) | > 0 | > 0 | must be exactly 1 |
| Distance calculation | Average of all rays | Nearest collision of any ray | Nearest collision of the ray |
| gaussianWidth (field) | Used | Ignored | Ignored |
| Sensitive to red objects | Yes | No | No |
| Draws a red spot | No | No | Yes |
Table 3.3: Summary of DistanceSensor types
3.21.4 Infra-Red Sensors
In the case of an "infra-red" sensor, the value returned by the lookup table is modified by a reflection factor depending on the color properties of the object hit by the sensor ray. In fact, if the object is a Solid node with a bounding object, the color of the bounding object is used for computing the reflection factor rather that the actual color of the object. The reflection factor is computed as follows: f = 0.2 + 0.8 * red_level where red_level is the level of red color (diffuseColor) of the object hit by the sensor ray. The distance value computed by the simulator is divided by this factor before the lookup table is used to compute the output value. This reflection factor is not taken into consideration in fast2d mode, so in this case, an infra-red sensor behaves like the other types of sensors.
3.21.5 Line Following Behavior
Some support for DistanceSensor nodes used for reading the red color level of a textured floor is implemented. This is useful to simulate line following behaviors. This feature is demonstrated in the rover.wbt example (see in the projects/robots/mindstorms/worlds directory of Webots). The ground texture must be placed in a Plane.
3.21.6 DistanceSensor Functions
NAME
wb_distance_sensor_enable, wb_distance_sensor_disable, wb_distance_sensor_get_sampling_period, wb_distance_sensor_get_value - enable, disable and read distance sensor measurementsSYNOPSIS [C++] [Java] [Python] [Matlab]
#include <webots/distance_sensor.h>void wb_distance_sensor_enable(WbDeviceTag tag, int ms);
void wb_distance_sensor_disable(WbDeviceTag tag);
int wb_distance_sensor_get_sampling_period(WbDeviceTag tag);
double wb_distance_sensor_get_value(WbDeviceTag tag);
DESCRIPTION
wb_distance_sensor_enable() allows the user to enable a distance sensor measurement each ms milliseconds.
wb_distance_sensor_disable() turns the distance sensor off, saving computation time.
The wb_distance_sensor_get_sampling_period() function returns the period given into the wb_distance_sensor_enable() function, or 0 if the device is disabled.
wb_distance_sensor_get_value() returns the last value measured by the specified distance sensor. This value is computed by the simulator according to the lookup table of the DistanceSensor node. Hence, the range of the return value is defined by this lookup table.