Webots Reference Manual - chapter 3 - section 34

Webots Reference Manual


3.34 LightSensor

Derived from Device.

LightSensor {
  MFVec3f     lookupTable   [ 0 0 0, 1 1000 0 ]
  SFColor     colorFilter   1 1 1    # [0,1]
  SFBool      occlusion     FALSE
}

3.34.1 Description

LightSensor nodes are used to model photo-transistors, photo-diodes 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/m2), and is sometimes called intensity. The simulated irradiance is computed by adding the irradiance contributed by every light source (DirectionalLight, SpotLight and PointLight) 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 position and the orientation of the sensor, the location and the direction of the light sources and (optionally) on the possible occlusion of the light sources. The ambient contribution ignores the possible occlusions, and it is not affected by the orientation of the sensor nor by the direction of a light source. The direct and ambient contributions of PointLights and SpotLights are attenuated according to the distance between the sensor and the light, according to specified attenuation coefficients. The light radiated by a DirectionalLight is not attenuated. See also DirectionalLight, SpotLight and PointLight node descriptions.

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

3.34.2 Field Summary

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

light_intensity

Figure 3.18: 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.19.

light_attenuation

Figure 3.19: Light attenuation

Variables a1, a2 and a3 correspond to the attenuation field of light i, and d is the distance between the sensor and the light. There is no attenuation for DirectionalLights. Id[i] is the direct irradiance contributed by light i, and is calculated as shown in figure 3.20.

direct_light

Figure 3.20: Direct irradiance

Finally, spot[i] is a factor used only in case of a SpotLight, and that depends on its cutOffAngle and beamWidth fields, and is calculated as shown in figure 3.21, where the alpha angle corresponds to the angle between -L and the direction vector of the SpotLight.

spot_contribution

Figure 3.21: SpotLight factor

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.22). 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.

light_sensor

Figure 3.22: 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.

The default value of the attenuation field of PointLights and SpotLights is 1 0 0. These values correspond to the VRML default, and are not appropriate for modeling the attenuation of a real lights. If a point or spot 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*π. If, in addition, the intensity field of the light 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/m2]. Finally, if the sensor's lookupTable is filled with correct calibration data, a fairly good approximation of the real world should be achieved.
If the calibration data for the lookupTable was obtained in lux (lx) or lumens per square meter (lm/m2) instead of W/m2, 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.34.3 LightSensor Functions



NAME

   wb_light_sensor_enable, wb_light_sensor_disable, wb_light_sensor_get_sampling_period, wb_light_sensor_get_value - enable, disable and read light sensor measurement

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/light_sensor.h>

  void wb_light_sensor_enable(WbDeviceTag tag, int ms);
  void wb_light_sensor_disable(WbDeviceTag tag);
  int wb_light_sensor_get_sampling_period(WbDeviceTag tag);
  double light_sensor_get_value(WbDeviceTag tag);

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.

The wb_light_sensor_get_sampling_period() function returns the period given into the wb_light_sensor_enable() function, or 0 if the device is disabled.

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.

release 7.0.2
Copyright © 2012 Cyberbotics Ltd. All right reserved.