Derived from Solid.

LightSensor {   MFVec3f     lookupTable   [ 0 0 0, 1 1000 0 ]   V_SFColor   colorFilter   1 1 1    # [0,1]   V_SFBool    occlusion     FALSE }

3.29.1 Description

LightSensor nodes are used to model phototransistors, photodiodes or any type of device that measures the irradiance of light in a given direction. Irradiance represents the radiant power incident on a surface in Watts per square meter (W/m²), and is sometimes called intensity. The simulated irradiance is computed by adding the irradiance contributed by every light source (PointLights and DirectionalLights) in the world. Then the total irradiance is multiplied by a color filter and fed into a lookup table that returns the corresponding user-defined value.

The irradiance contribution of each light source is divided into direct and ambient contributions. The direct contribution depends on the orientation of the sensor, the direction field of DirectionalLight sources and (optionally) on the possible occlusion of the light sources. The ambient contribution cannot, however, be occluded, and it is not affected by the orientation of the sensor nor by the direction of DirectionalLights. Both the direct and ambient light radiated by a PointLight are attenuated according to the distance between the sensor and the light source, according to specified attenuation coefficients. The light radiated by a DirectionalLight is not attenuated. See also PointLight and DirectionalLight node descriptions.

Note that the Webots lighting model does not take reflected light nor object colors into account.

3.29.2 Field Summary

• lookupTable: this table allows Webots to map simulated irradiance values to user-defined sensor output values and to specify a noise level. The first column contains the input irradiance values in W/m². The second column represents the corresponding sensor output values in user-defined units. The third column specifies the level of noise in percent of the corresponding output value. See the section on the DistanceSensor node for more explanation on how a lookupTable works.

• colorFilter: specifies an RGB filter that can be used to approximate a physical color filter or spectral response. The total RGB irradiance is multiplied by this filter (see formula below) in order to obtain a scalar irradiance value E that is then used as the input to the lookup table. The colorFilter field can, for example, be used to selectively detect light sources according to color.

• occlusion: specifies whether or not obstacles between the sensor and light sources should be taken into account in the calculation of irradiance. If the occlusion field is FALSE (the default), all potential obstacles (Walls, other Robots, etc.) are ignored and Webots behaves as if they were transparent. If the occlusion field is TRUE, Webots will detect which light sources are occluded (from the sensor's viewpoint) and it will ignore their direct contributions. Note that the occlusion flag affects only the direct light measurement, not the ambient light which is always added in. By default, the occlusion field is disabled because the occlusion detection is computationally expensive and should be avoided whenever possible. For example, in a setup where it is obvious that there will never be an obstacle between a particular sensor and the various light sources, the occlusion flag can be left set to FALSE.

Before being interpolated by the lookupTable, the total irradiance E [W/m²] seen by a sensor is computed according to the equation shown is figure 3.12:

Figure 3.12: Light sensor irradiance formula

The F vector corresponds to the sensor's colorFilter field, N is the total number of lights in the simulation, on[i] corresponds to the on field of light i (TRUE=1, FALSE=0), the C[i] vector is the color field of light i, and Ia[i] is the ambientIntensity field of light i. The value att[i] is the attenuation of light i, and is calculated as shown in figure 3.13.

Figure 3.13: Light attenuation

Variables a1, a2 and a3 correspond to the attenuation field of light i, and d is the distance between the sensor and this PointLight. Finally, Id[i] is the direct irradiance contributed by light i, and is calculated as shown in figure 3.14.

Figure 3.14: Direct irradiance

The value I[i] corresponds to the intensity field of light i, and N is the normal axis (x-axis) of the sensor (see figure 3.15). In the case of a PointLight, L is the sensor-to-light-source vector. In the case of a DirectionalLight, L corresponds to the negative of the light's direction field. The * operation is a modified dot product: if dot < 0, then 0, otherwise, dot product. Hence, each light source contributes to the irradiance of a sensor according to the cosine of the angle between the N and the L vectors, as shown in the figure. The contribution is zero if the light source is located behind the sensor. This is derived from the physical fact that a photo-sensitive device is usually built as a surface of semiconductor material and therefore, the closer the angle of incidence is to perpendicular, the more photons will actually hit the surface and excite the device. When a light source is parallel to (or behind) the semiconductor surface, no photons actually reach the surface.

Figure 3.15: The irradiance (E) depends on the angle (phi) between the N and L vectors

The "occlusion" condition is true if the light source is hidden by one or more obstacles. More precisely, "occlusion" is true if (1) the occlusion field of the sensor is set to TRUE and (2) there is an obstacle in the line of sight between the sensor and the light source. Note that DirectionalLight nodes don't have location fields; in this case Webots checks for obstacles between the sensor and an imaginary point located 1000m away in the direction opposite to the one indicated by the direction field of this DirectionalLight.

Like any other type of collision detection in Webots, the LightSensor occlusion detection is based on the boundingObjects of Solid nodes (or derived nodes). Therefore, even if it has a visible geometric structure, a Solid node cannot produce any occlusion if its boundingObject is not specified.

Note: The default value of the attenuation field of PointLight is 1 0 0. These values correspond to the VRML default, and are not appropriate for modeling the attenuation of a real point light. If a point light radiates uniformly in all directions and there is no absorption, then the irradiance drops off in proportion to the square of the distance from the object. Therefore, for realistic modeling, the attenuation field of a light source should be changed to 0 0 4*pi. If, in addition, the intensity field of the PointLight is set to the radiant power [W] of a real point source (e.g. a light bulb), then the computed sensor irradiance E will approximate real world values in [W/m²]. Finally, if the sensor's lookupTable is filled with correct calibration data, a fairly good approximation of the real world should be achieved.

Note: If the calibration data for the lookupTable was obtained in lux (lx) or lumens per square meter (lm/m²) instead of W/m², it makes sense to substitute the radiometry terms and units in this document with their photometry equivalents: irradiance becomes illuminance, radiant power becomes luminous power and W becomes lm (lumen), etc.

3.29.3 LightSensor Functions

NAME

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

DESCRIPTION

wb_light_sensor_enable() enables a light sensor measurement each ms milliseconds.

wb_light_sensor_disable() turns off the light sensor to save CPU time.

NAME

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

DESCRIPTION

wb_light_sensor_get_value() returns the most recent value measured by the specified light sensor. The returned value is the result of interpolating the irradiance E as described above with the sensor's lookupTable.

^ page top ^