22.1 Introduction

22.1.1 Name

The name of this component is "EnvironmentalSensor". This name shall be used when referring to this component in the COMPONENT statement (see 7.2.5.4 Component statement).

22.1.2 Overview

This clause describes the Environmental Sensor component of this part of ISO/IEC 19775. Table 22.1 provides links to the major topics in this clause.

22.2 Concepts

Environment sensors are nodes which emit events based on some event which occurs within the environment, usually an interaction between two elements within the world. Most environment sensors events occur because of an interaction between the viewer and the world. However, an environment sensor event may also occur because of an interaction between a non-manipulable piece of hardware (e.g., a clock) and the world, between two objects in the world, or an event over the network.

Environmental sensors include:

• Collision
• ProximitySensor
• TransformSensor
• VisibilitySensor

The Collision grouping node detects when the user collides with objects in the virtual world. Proximity, collision, and visibility sensors are each processed independently of whether others exist or overlap. See 23 Navigation component for more information.

The ProximitySensor detects when the user navigates into a specified region in the world.

The TransformSensor detects when for the target object specified enters, exits, or is transformed within a specified rectangular parallelepiped.

The VisibilitySensor detects when a specific part of the world becomes visible to the user.

When environmental sensors are inserted into the transformation hierarchy and before the presentation is updated (i.e., read from file or created by a script), they shall generate events indicating any conditions which the sensor is intended to detect. The conditions for individual sensor types to generate these initial events are defined in the individual node specifications in 22.4 Node reference.

22.3 Abstract types

22.3.1 X3DEnvironmentalSensorNode

 
X3DEnvironmentalSensorNode : X3DSensorNode {
  SFVec3f [in,out] center    0 0 0 (-∞,∞)
  SFBool  [in,out] enabled   TRUE
  SFNode  [in,out] metadata  NULL  [X3DMetadataObject]
  SFVec3f [in,out] size      0 0 0 (-∞,∞)
  SFTime  [out]    enterTime
  SFTime  [out]    exitTime
  SFBool  [out]    isActive
}

X3DEnvironmentalSensorNode is the base type for the environmental sensor nodes ProximitySensor and VisibilitySensor.

22.4 Node reference

22.4.1 ProximitySensor

ProximitySensor : X3DEnvironmentalSensorNode {
  SFVec3f    [in,out] center                   0 0 0 (-∞,∞)
  SFBool     [in,out] enabled                  TRUE
  SFNode     [in,out] metadata                 NULL  [X3DMetadataObject]
  SFVec3f    [in,out] size                     0 0 0 [0,∞)
  SFTime     [out]    enterTime
  SFTime     [out]    exitTime
  SFVec3f    [out]    centerOfRotation_changed
  SFBool     [out]    isActive
  SFRotation [out]    orientation_changed
  SFVec3f    [out]    position_changed
}

The ProximitySensor node generates events when the viewer enters, exits, and moves within a region in space (defined by a box). A proximity sensor is enabled or disabled by sending it an enabled event with a value of TRUE or FALSE. A disabled sensor does not send events.

A ProximitySensor node generates isActive TRUE/FALSE events as the viewer enters and exits the rectangular box defined by its center and size fields. Browsers shall interpolate viewer positions and timestamp the isActive events with the exact time the viewer first intersected the proximity region. The center field defines the centre point of the proximity region in object space. The size field specifies a vector which defines the width (x), height (y), and depth (z) of the box bounding the region. The components of the size field shall be greater than or equal to zero. ProximitySensor nodes are affected by the hierarchical transformations of their parents.

The enterTime event is generated whenever the isActive TRUE event is generated (user enters the box), and exitTime events are generated whenever an isActive FALSE event is generated (user exits the box).

The centerOfRotation_changed field sends events whenever the user is contained within the proximity region and the center of rotation of the viewer for EXAMINE mode changes with respect to the ProximitySensor node's coordinate system. This may result when the bound Viewpoint nodes's center of rotation changes, when a new viewpoint is bound, when the user changes the center of rotation through the browser's user interface, or from changes to the ProximitySensor node's coordinate system. centerOfRotation_changed events are only generated when the currently bound NavigationInfo node includes LOOKAT navigation. For more information, see 23.3.1 X3DViewpointNode and 23.4.4. NavigationInfo.

The position_changed and orientation_changed fields send events whenever the user is contained within the proximity region and the position and orientation of the viewer changes with respect to the ProximitySensor node's coordinate system including enter and exit times. The viewer movement may be a result of a variety of circumstances resulting from browser navigation, ProximitySensor node's coordinate system changes, or bound Viewpoint node's position or orientation changes.

Each ProximitySensor node behaves independently of all other ProximitySensor nodes. Every enabled ProximitySensor node that is affected by the viewer's movement receives and sends events, possibly resulting in multiple ProximitySensor nodes receiving and sending events simultaneously. Unlike TouchSensor nodes, there is no notion of a ProximitySensor node lower in the scene graph "grabbing" events.

Instanced (DEF/USE) ProximitySensor nodes use the union of all the boxes to check for enter and exit. A multiply instanced ProximitySensor node will detect enter and exit for all instances of the box and send enter/exit events appropriately. For non-overlapping bounding boxes, position_changed and orientation_changed events are calculated relative to the coordinate system associated with the bounding box in which the proximity was detected. However, the results are undefined if the any of the boxes of a multiply instanced ProximitySensor node overlap.

A ProximitySensor node that surrounds the entire world has an enterTime equal to the time that the world was entered and can be used to start up animations or behaviours as soon as a world is loaded. A ProximitySensor node with a box containing zero volume (i.e., any size field element of 0.0) cannot generate events. This is equivalent to setting the enabled field to FALSE.

A ProximitySensor read from an X3D file shall generate isActive TRUE, position_changed, orientation_changed and enterTime events if the sensor is enabled and the viewer is inside the proximity region. A ProximitySensor inserted into the transformation hierarchy shall generate isActive TRUE, position_changed, orientation_changed and enterTime events if the sensor is enabled and the viewer is inside the proximity region. A ProximitySensor removed from the transformation hierarchy shall generate isActive FALSE, position_changed, orientation_changed and exitTime events if the sensor is enabled and the viewer is inside the proximity region.

22.4.2 TransformSensor

TransformSensor : X3DEnvironmentalSensorNode {
  SFVec3f    [in,out] center              0 0 0 (-∞,∞)
  SFBool     [in,out] enabled             TRUE
  SFNode     [in,out] metadata            NULL  [X3DMetadataObject]
  SFVec3f    [in,out] size                0 0 0 [0,∞)
  SFNode     [in,out] targetObject        NULL  [X3DGroupingNode|X3DShapeNode]
  SFTime     [out]    enterTime
  SFTime     [out]    exitTime
  SFBool     [out]    isActive
  SFRotation [out]    orientation_changed
  SFVec3f    [out]    position_changed
}

The TransformSensor node generates events when its target object enters, exits, and moves within a region in space (defined by a box). The target object can be any valid X3DShapeNode or X3DGroupingNode node. A TransformSensor is enabled or disabled by sending it an enabled event with a value of TRUE or FALSE. A disabled sensor does not send events.

A TransformSensor node generates isActive TRUE/FALSE events as the target object enters and exits the rectangular box defined by its center and size fields. Browsers shall timestamp the isActive events with the exact time the target object first intersected the proximity region. The center field defines the centre point of the proximity region in object space. The size field specifies a vector that defines the width (x), height (y), and depth (z) of the box bounding the region. The components of the size field shall be greater than or equal to zero. TransformSensor nodes are affected by the hierarchical transformations of their parents.

The enterTime event is generated whenever the isActive TRUE event is generated (target object enters the box), and exitTime events are generated whenever an isActive FALSE event is generated (target object exits the box).

The position_changed and orientation_changed fields send events whenever the target object is contained within the proximity region and the position and orientation of the target object changes with respect to the TransformSensor node's coordinate system including enter and exit times. The object movement may be a result of a variety of circumstances resulting from the TransformSensor node's coordinate system changes, changes to the target object's position or orientation, or changes to the coordinate system of any of the ancestors or the target object.

Each TransformSensor node behaves independently of all other TransformSensor nodes. Every enabled TransformSensor node that is affected by the target object's movement receives and sends events, possibly resulting in multiple TransformSensor nodes receiving and sending events simultaneously. Unlike TouchSensor nodes, there is no notion of a TransformSensor node lower in the scene graph "grabbing" events.

Instanced (DEF/USE) TransformSensor nodes use the union of all the boxes to check for enter and exit. A multiply instanced TransformSensor node will detect enter and exit for all instances of the box and send enter/exit events appropriately. For non-overlapping bounding boxes, position_changed and orientation_changed events are calculated relative to the coordinate system associated with the bounding box in which the proximity was detected. However, the results are undefined if the any of the boxes of a multiply instanced TransformSensor node overlap.

A TransformSensor node with a box containing zero volume (i.e., any size field element of 0.0) cannot generate events. This is equivalent to setting the enabled field to FALSE.

A TransformSensor read from an X3D file shall generate isActive TRUE, position_changed, orientation_changed and enterTime events if the sensor is enabled and the target object is inside the proximity region. A TransformSensor inserted into the transformation hierarchy shall generate isActive TRUE, position_changed, orientation_changed and enterTime events if the sensor is enabled and the target object is inside the proximity region. A TransformSensor removed from the transformation hierarchy shall generate isActive FALSE, position_changed, orientation_changed and exitTime events if the sensor is enabled and the target object is inside the proximity region.

22.4.3 VisibilitySensor

VisibilitySensor : X3DEnvironmentalSensorNode {
  SFVec3f [in,out] center    0 0 0 (-∞,∞)
  SFBool  [in,out] enabled   TRUE
  SFNode  [in,out] metadata  NULL  [X3DMetadataObject]
  SFVec3f [in,out] size      0 0 0 [0,∞)
  SFTime  [out]    enterTime
  SFTime  [out]    exitTime
  SFBool  [out]    isActive
}

The VisibilitySensor node detects visibility changes of a rectangular box as the user navigates the world. VisibilitySensor is typically used to detect when the user can see a specific object or region in the scene in order to activate or deactivate some behaviour or animation. The purpose is often to attract the attention of the user or to improve performance.

The enabled field enables and disables the VisibilitySensor node. If enabled is set to FALSE, the VisibilitySensor node does not send events. If enabled is TRUE, the VisibilitySensor node detects changes to the visibility status of the box specified and sends events through the isActive field. A TRUE event is output to isActive when any portion of the box impacts the rendered view. A FALSE event is sent when the box has no effect on the view. Browsers shall guarantee that, if isActive is FALSE, the box has absolutely no effect on the rendered view. Browsers may err liberally when isActive is TRUE. For example, the box may affect the rendering.

The fields center and size specify the object space location of the box centre and the extents of the box (i.e., width, height, and depth). The VisibilitySensor node's box is affected by hierarchical transformations of its parents. The components of the size field shall be greater than or equal to zero.

The enterTime event is generated whenever the isActive TRUE event is generated, and exitTime events are generated whenever isActive FALSE events are generated. A VisibilitySensor read from an X3D file shall generate isActive TRUE and enterTime events if the sensor is enabled and the visibility box is visible. A VisibilitySensor inserted into the transformation hierarchy shall generate isActive TRUE and enterTime events if the sensor is enabled and the visibility box is visible. A VisibilitySensor removed from the transformation hierarchy shall generate isActive FALSE and exitTime events if the sensor is enabled and the visibility box is visible.

Each VisibilitySensor node behaves independently of all other VisibilitySensor nodes. Every enabled VisibilitySensor node that is affected by the user's movement receives and sends events, possibly resulting in multiple VisibilitySensor nodes receiving and sending events simultaneously. Unlike TouchSensor nodes, there is no notion of a VisibilitySensor node lower in the scene graph "grabbing" events. Multiply instanced VisibilitySensor nodes (i.e., DEF/USE) use the union of all the boxes defined by their instances. An instanced VisibilitySensor node shall detect visibility changes for all instances of the box and send events appropriately.

22.5 Support levels

The Environmental Sensor component provides two levels of support as specified in Table 22.2. Level 1 is intended to enable automatic animations by supporting a simplified ProximitySensor node. Level 2 provides full environment sensing support.