38.1 Introduction

38.1.1 Name

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

38.1.2 Overview

This component provides the ability to test for arbitrary object collision in a somewhat limited form. In traditional 3D graphics terminology, this is termed picking. The intention is to not support full n-body object collision, but to provide an extended set of basic capabilities to provide some limited custom interactions, such as terrain following. Table 38.1 provides links to the major topics in this clause.

38.2 Concepts

38.2.1 Event model interaction

Picking notification is performed at the start of the frame when all other sensors are processed. This allows the user to manipulate geometry and have the pick results returned at the start of the frame, thus guaranteeing a fixed, known state at all times.

38.3 Abstract types

38.3.1 X3DPickableObject

X3DPickableObject {
  MFString [in,out] objectType "ALL" ["ALL"|"NONE"|"TERRAIN"|...]
  SFBool   [in,out] pickable
}

The X3DPickableObject abstract object type marks a node as being capable of having customized picking performed on the its contents or children.

The pickable field is used to independently control whether picking may be performed on this node or its children. Setting the value to FALSE will remove the children from the list of potential matches for picking. This only effects children that are accessed through the transformation hierarchy of the parent. If one or more of the children of this instance is accessible through another transformation hierarchy through DEF/USE that still has picking enabled, they shall still be pickable through that path only.

The objectType field specifies a label that is used in the picking process. Each string specified is treated as an independent label that needs to be matched against the same type in one of the picking node instances. For example, labeling a group with the value "WATER" and then attempting to intersect a picker with the objectType "GROUND" would fail as the types are not matching. The special type "ALL" means that it is available for picking regardless of the type specified by the picking node. The "NONE" field value or empty field declaration effectively disables all picking for this node and is the equivalent of setting the pickable field to FALSE. The user may define any value for flags.

38.3.2 X3DPickingNode

X3DPickingNode : X3DSensorNode { 
  SFBool   [in,out] enabled
  SFNode   [in,out] metadata         NULL      [X3DMetadataObject]
  MFString [in,out] objectType       "ALL"     ["ALL","NONE","TERRAIN",...]
  SFNode   [in,out] pickingGeometry  NULL      [X3DGeometryNode]
  MFNode   [in,out] pickTarget       []        [X3DGroupingNode|X3DShapeNode]
  MFNode   [out]    pickedGeometry
  SFBool   [out]    isActive
  SFString []       intersectionType "BOUNDS"  ["GEOMETRY"|"BOUNDS"]
  SFString []       sortOrder        "CLOSEST" ["CLOSEST"|"ALL"|"ALL_SORTED"]
}

The X3DPickingNode abstract node type is the base node type that represents the lowest common denominator of picking capabilities. An X3DPickingNode is a type of X3DSensorNode. isActive is TRUE whenever there is a picked item available. If the intersecting object is not picked by the picking geometry, the sensor is not active.

The intersectionType field specifies the precision of the collision computation. The intersectionType constants may be extended by the individual concrete node to provide addtional options.

EXAMPLE 1  An intersectionType may be used to specify the specific algorithm used for the detection.

The objectType field lists the types of object that are to be tested for intersections. An arbitrary label may be specified here in addition to the predefined types.

The pickingGeometry field specifies the exact coordinates of the geometry that will be performing the intersection testing. The acceptable range of node types and how they are to be interpreted shall be defined by the individual concrete nodes.

The pickTarget field specifies the list of nodes against which the picking operation should be performed. If a the descendent of the nodes declared in this field include another X3DPickingNode instance, the children of the descendent X3DPickingNode are not considered for picking.

The pickedGeometry field communicates the node or nodes that have been found to intersect with the picking geometry from the last time this node performed a picking operation. The values provided shall be dependent on the setting of the sortOrder field.

EXAMPLE 2  If the sortOrder is "CLOSEST", the values in the pickedGeometry field will be ordered in the array starting with the closest intersecting object first proceeding to the farthest last.

This node is not considered to be part of the transformation hierarchy. Children nodes of this node shall not be visible on screen. Children of this node are not eligible for picking from any other node.

38.4 Node reference

38.4.1 LinePicker

LinePicker : X3DPickingNode { 
  SFBool   [in,out] enabled                 TRUE
  SFNode   [in,out] metadata                NULL      [X3DMetadataObject]
  MFString [in,out] objectType              "ALL"     ["ALL","NONE","TERRAIN",...]
  SFNode   [in,out] pickingGeometry         NULL      [IndexedLineSet|LineSet]
  MFNode   [in,out] pickTarget              []        [X3DGroupingNode|X3DShapeNode]
  SFBool   [out]    isActive
  MFNode   [out]    pickedGeometry
  MFVec3f  [out]    pickedNormal
  MFVec3f  [out]    pickedPoint
  MFVec2f  [out]    pickedTextureCoordinate
  SFString []       intersectionType        "BOUNDS"  ["GEOMETRY"|"BOUNDS"]
  SFString []       sortOrder               "CLOSEST" ["CLOSEST"|"ALL"|"ALL_SORTED"]
}

The LinePicker node picks one or more line segments as the test object with which to pick. As a line is a known point in space, normal, geometry and texCoord information can be returned that is useful.

38.4.2 PickableGroup

PickableGroup : X3DGroupingNode, X3DPickableObject { 
  MFNode   [in]     addChildren
  MFNode   [in]     removeChildren
  MFNode   [in,out] children       []       [X3DChildNode]
  SFNode   [in,out] metadata       NULL     [X3DMetadataObject]
  MFString [in,out] objectType     "ALL"    ["ALL","NONE","TERRAIN",...]
  SFBool   [in,out] pickable       TRUE
  SFVec3f  []       bboxCenter     0 0 0    (-inf,inf)
  SFVec3f  []       bboxSize       -1 -1 -1 [0,inf) or -1 -1 -1
}

A PickableGroup node contains children that can be marked as being of a given classification of picking types, as well as the ability to enable or disable picking of the children.

For field definitions, see 38.3.1 X3DPickableObject.

38.4.3 PointPicker

PointPicker : X3DPickingNode { 
  SFBool   [in,out] enabled          TRUE
  SFNode   [in,out] metadata         NULL      [X3DMetadataObject]
  MFString [in,out] objectType       "ALL"     ["ALL","NONE","TERRAIN",...]
  SFNode   [in,out] pickingGeometry  NULL      [PointSet]
  MFNode   [in,out] pickTarget       []        [X3DGroupingNode|X3DShapeNode]
  SFBool   [out]    isActive
  MFNode   [out]    pickedGeometry
  MFVec3f  [out]    pickedPoint
  SFString []       intersectionType "BOUNDS"  ["GEOMETRY"|"BOUNDS"]
  SFString []       sortOrder        "CLOSEST" ["CLOSEST"|"ALL"|"ALL_SORTED"]
}

Because points are just a location in space, the "CLOSEST" and "ALL_SORTED" sort orders are defined to mean "ANY" and "ALL" respectively.

38.4.4 PrimitivePicker

PrimitivePicker : X3DPickingNode { 
  SFBool   [in,out] enabled          TRUE
  SFNode   [in,out] metadata         NULL      [X3DMetadataObject]
  MFString [in,out] objectType       "ALL"     ["ALL","NONE","TERRAIN",...]
  SFNode   [in,out] pickingGeometry  NULL      [Cone|Cylinder|Sphere|Box]
  MFNode   [in,out] pickTarget       []        [X3DGroupingNode | X3DShapeNode]
  SFBool   [out]    isActive
  MFNode   [out]    pickedGeometry
  SFString []       intersectionType "BOUNDS"  ["GEOMETRY"|"BOUNDS"]
  SFString []       sortOrder        "CLOSEST" ["CLOSEST"|"ALL"|"ALL_SORTED"]
}

Boolean fields used to control visibility of subsections of a primitive are ignored when evaluating the picking routines.

EXAMPLE  A cylinder missing the end caps is still treated as an enclosed cylinder.

Sorting is defined based on the primitive type, as follows:

1. For cone, the picked primitive is closest to the vertex point.
2. For cylinder, box, and sphere, the picked primitive is closest to the center.

38.4.5 VolumePicker

VolumePicker : X3DPickingNode { 
  SFBool   [in,out] enabled          TRUE
  SFNode   [in,out] metadata         NULL      [X3DMetadataObject]
  MFString [in,out] objectType       "ALL"     ["ALL","NONE","TERRAIN",...]
  SFNode   [in,out] pickingGeometry  NULL      [X3DGeometryNode]
  MFNode   [in,out] pickTarget       []        [X3DGroupingNode | X3DShapeNode]
  SFBool   [out]    isActive
  MFNode   [out]    pickedGeometry
  SFString []       intersectionType "BOUNDS"  ["GEOMETRY"|"BOUNDS"]
  SFString []       sortOrder        "CLOSEST" ["CLOSEST"|"ALL"|"ALL_SORTED"]
}

The VolumePicker picks against an arbitrary volume defined by the geometry. The volume is defined by the convex hull of the enclosing planes of the provided geometry.

38.5 Support levels

The Pointing Device Sensor component provides one level of support as specified in Table 38.2.