Introduction

Name

The name of this component is "xj3d_PickingUtilities". This name shall be used when referring to this component in the COMPONENT statement (see ISO FDIS 19775-1:200x 7.2.5.4 Component statement).

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.

The first level provides for simple line and point intersections against arbitrary geometry.

At the second level general geometry primitives are accepted as part of the input and finally, at level 3, any arbitrary geometry can be supported and is closest to the idea object-to-object collision detection mechanism.

Concepts

Event Model Interaction

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

Abstract Types

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"|"ANY"]
}

Base type represents the lowest common demoninator of pciking capabilities. It is a sensor node. isActive is true whenever there is a picked item available. If the intersecting object is not picked by the picking geometry, then the sensor is not active.

The interection type constants may be extended by the individual concrete node to provide addtional options. For example, it may be used to specify the specific algorithm used for the detection.

The objectType field is used to list the types of object that are to be tested for intersections. The user may provide an arbitrary label here in addition to the predefined types specified.

The pickingGeometry field is used to specify 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 is used to provide the listing of nodes that the picking operation should be performed against. If a the descendent of the nodes declared in this field include another X3DPickingNode instance, the children of the descendent are not considered for picking.

The pickedGeometry field is used to comminicate 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. For example, if the sortOrder is "CLOSEST" then the values will be ordered in the array with the closest intersecting object first, and the farthest last.

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

X3DPickableObject

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

Marks a node as being capable of having customised 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 it's 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 heirarchy of the parent. If one or more of the children of this instance is accessible through another transformation heirarchy through DEF/USE that still has picking enabled, then they shall still be pickable through that path only.

The objectType field allows the user to specify 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, labelling 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.

Node reference

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 X3DPickableObject

LinePicker

LinePicker : X3DPickingNode {
  SFBool   [in,out] enabled
  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]
  SFString []       intersectionType   "BOUNDS" ["GEOMETRY"|"BOUNDS"]
  SFString []       sortOrder          "CLOSEST" ["CLOSEST"|"ALL"|"ALL_SORTED"]
  MFNode   [out]    pickedGeometry
  MFVec3f  [out]    pickedPoint
  MFVec3f  [out]    pickedNormal
  MFVec2f  [out]    pickedTextureCoordinate
  SFBool   [out]    isActive
}

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

PointPicker

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

Test one or more points in space as lying inside the provided target geometry. For each point that lies inside the geometry, return the point coordinate in the output array and the corresponding geometry the point lay inside.

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

PrimitivePicker

PrimitivePicker : X3DPickingNode {
  SFBool   [in,out] enabled
  SFBool   [out]    isActive
  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]
  SFString []       intersectionType   "BOUNDS" ["GEOMETRY"|"BOUNDS"]
  SFString []       sortOrder          "CLOSEST" ["CLOSEST"|"ALL"|"ALL_SORTED"]
  MFNode   [out]    pickedGeometry
}

Pick one of the basic primitive object types against the target geometry. Arbitrary geometry cannot be used at this level, only the 3D primitive types may be used.

Boolean fields used to control visibility of subsections of a primitive are ignored when evaluating the picking routines. For example, a cylinder missing the end caps is still treated as an enclosed cylinder.

Sorting is defined based on the primitive type. For cone, it is closest to the vertex point,for sphere and box, the closest to the origin. Cylinder is not defined yet.

VolumePicker

VolumePicker : X3DPickingNode {
  SFBool   [in,out] enabled
  SFBool   [out]    isActive
  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]
  SFString []       intersectionType   "BOUNDS" ["GEOMETRY"|"BOUNDS"]
  SFString []       sortOrder          "CLOSEST" ["CLOSEST"|"ALL"|"ALL_SORTED"]
  MFNode   [out]    pickedGeometry
}

Any arbitrary volume defined by the geometry. The volume should consist of the convex hull defined by the enclosing planes of the provided geometry.

Support Levels

This component defines 3 levels of conformance. The nodes are specified by the following levels:

Level	Prequisites	Nodes/Features	Support
Level 1	Core 1 Grouping 1 Shape 1 Rendering 1
		X3DPickingNode	n/a
		X3DPickableObject	n/a
		LinePicker	All fields fully supported
		PickableGroup	All fields fully supported
		PointPicker	All fields fully supported
Level 2	Core 1 Grouping 1 Shape 1 Rendering 1
		PrimitivePicker	All fields fully supported
Level 3	Core 1 Grouping 1 Shape 1 Rendering 1
		VolumePicker	All fields fully supported

Examples