10.1 Introduction

10.1.1 Name

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

10.1.2 Overview

This clause describes the Grouping component of this part of ISO/IEC 19775. This includes how nodes are organized into groups to establish a transformation hierarchy for the X3D scene graph. Table 10.1 provides links to the major topics in this clause.

10.2 Concepts

10.2.1 Grouping and children node types

Grouping nodes have a field that contains a list of children nodes. Each grouping node defines a coordinate space for its children. This coordinate space is relative to the coordinate space of the node of which the group node is a child. Such a node is called a parent node. This means that transformations accumulate down the scene graph hierarchy.

This part of ISO/IEC 19775 defines several grouping nodes, including the following:

• Anchor
• Billboard
• Collision
• Group
• Inline
• LOD
• Switch
• Transform

Other components may add to the list of grouping node types.

The node types in Table 10.2 are node types that may be used as children:

Other components may add to the list of node types that may be used as children.

The node types in Table 10.3 are not valid as children nodes:

Other components may add the list of node types that may not be used as children.

All grouping nodes except GeoLOD, Inline, LOD, and Switch also have addChildren and removeChildren inputOnly fields. The addChildren event appends nodes to the children field of a grouping node. Any nodes passed to the addChildren inputOnly field that are already in the children list of the grouping node are ignored. For example, if the children field contains the nodes Q, L and S (in order) and the group receives an addChildren event containing (in order) nodes A, L, and Z, the result is a children field containing (in order) nodes Q, L, S, A, and Z.

The removeChildren event removes nodes from the children fieldof the grouping node . Any nodes in the removeChildren event that are not in the children list of the grouping node are ignored. For example, if the children field contains the nodes Q, L, S, A and Z and it receives a removeChildren event containing nodes A, L, and Z, the result is Q, S.

Note that a variety of node types reference other node types through fields. Some of these are parent-child relationships, while others are not (there are node-specific semantics). Table 10.4 lists all node types that reference other nodes through fields.

All grouping nodes shall have a children field of type MFNode. Adding a node to this field will add that node to the grouping node's set of children. Adding any node to a grouping node's children field that is already in that group's child list is illegal. Adding any node to a grouping node's children field that is an ancestor of that grouping node is illegal. 

A variety of node types reference other node types through fields. Some of these are parent-child relationships (e.g., the children field of the Transform node) while others are not (e.g., the appearance field of the Shape node). The field type specifies which type of node may be placed in them. For instance, the node type of the children field of the Transform node is MFNode where all nodes shall be derived for ChildNodeType. Therefore, only node types derived from ChildNodeType may be placed there. Shape is legal in the children field because it is derived from ChildNodeType, while Appearance is not. See 4.4.2.3 Object hierarchy for a complete derivation hierarchy.

New nodes types may be defined using the extension mechanisms. These new node types can be placed in a node field as long as the node field's type is in the new type's derivation hierarchy.

10.2.2 Bounding boxes

Several node types include a bounding box specification comprised of two fields, bboxSize and bboxCenter. A bounding box is a rectangular parallelepiped of dimension bboxSize centred on the location bboxCenter in the local coordinate system. This is typically used by grouping nodes to provide a hint to the browser on the group's approximate size for culling optimizations. The default size for bounding boxes (-1, -1, -1) indicates that the user did not specify the bounding box and the effect shall be as if the bounding box were infinitely large. A bboxSize value of (0, 0, 0) is valid and represents a point in space (i.e., an infinitely small box). Specified bboxSize field values shall be >= 0.0 or equal to (-1, -1, -1). The bboxCenter fields specify a position offset from the local coordinate system.

The bboxCenter and bboxSize fields may be used to specify a maximum possible bounding box for the objects inside a grouping node (e.g., Transform). These are used as hints to optimize certain operations such as determining whether or not the group needs to be drawn. The bounding box shall be large enough at all times to enclose the union of the group's children's bounding boxes; it shall not include any transformations performed by the group itself (i.e., the bounding box is defined in the local coordinate system of the children). Results are undefined if the specified bounding box is smaller than the true bounding box of the group.

10.3 Abstract types

10.3.1 X3DBoundedObject

X3DBoundedObject : X3DObject { 
  SFVec3f [] bboxCenter 0 0 0    (-∞,∞)
  SFVec3f [] bboxSize   -1 -1 -1 (0,∞)
}

This abstract node type is basis for all node types that have bounds specified as part of the definition.

The bboxCenter and bboxSize fields specify a bounding box that encloses the Group node's children. This is a hint that may be used for optimization purposes. The results are undefined if the specified bounding box is smaller than the actual bounding box of the children at any time. A default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, is calculated by the browser. A description of the bboxCenter and bboxSize fields is contained in 10.2.2, Bounding boxes.

10.3.2 X3DChildNode

X3DChildNode : X3DNode { 
}

This abstract node type indicates that the concrete nodes which are instantiated based on it may be used in children, addChildren, and removeChildren fields.

More details on the children, addChildren, and removeChildren fields can be found in 10.2.1, Grouping and children node types.

10.3.3 X3DGroupingNode

X3DGroupingNode : X3DChildNode { 
  MFNode [in]     addChildren
  MFNode [in]     removeChildren
  MFNode [in,out] children        [] [X3DChildNode]
}

This abstract node type indicates that concrete node types derived from it contain children nodes and is the basis for all aggregation.

More details on the children, addChildren, and removeChildren fields and eventIns can be found in 10.2.1, Grouping and children node types.

10.3.4 X3DInfoNode

X3DInfoNode : X3DChildNode { 
}

This is the base node type for all nodes that contain only information without visual semantics.

10.4 Node reference

10.4.1 Group

Group : X3DGroupingNode, X3DBoundedObject {
  MFNode  [in]     addChildren             [X3DChildNode]
  MFNode  [in]     removeChildren          [X3DChildNode]
  MFNode  [in,out] children       []       [X3DChildNode]
  SFVec3f []       bboxCenter     0 0 0    (-∞,∞)
  SFVec3f []       bboxSize       -1 -1 -1 (0,∞) or -1 -1 -1
}

A Group node contains children nodes without introducing a new transformation. It is equivalent to a Transform node containing an identity transform.

More details on the children, addChildren, and removeChildren fields and eventIns can be found in 10.2.1, Grouping and children node types.

The bboxCenter and bboxSize fields specify a bounding box that encloses the Group node's children. This is a hint that may be used for optimization purposes. The results are undefined if the specified bounding box is smaller than the actual bounding box of the children at any time. A default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, is calculated by the browser. A description of the bboxCenter and bboxSize fields is contained in 10.2.2, Bounding boxes.

10.4.2 StaticGroup

StaticGroup : X3DChildNode, X3DBoundedObject {
  MFNode  [] children   []       [X3DChildNode]
  SFVec3f [] bboxCenter 0 0      (-∞,∞)
  SFVec3f [] bboxSize   -1 -1 -1 (0,∞) or -1 -1 -1
}

The StaticGroup node contains children nodes which cannot be modified. StaticGroup children are guaranteed to not change, send events, receive events or contain any USE references outside the StaticGroup. This allows the browser to optimize this content for faster rendering and less memory usage.

A browser shall prevent all illegal attempts to modify the StaticGroup and its children. Children of the StaticGroup are guaranteed not to generate events.

Implementations are free to rearrange or remove nodes inside a StaticGroup as long as the final rendering is the same. These optimizations might include flattening a series of transformations into one transform, performing appearance bundling or heavy analysis of the scene graph for maximal rendering speed. A StaticGroup does not need to maintain its children's VRML representations (such as field data), as they cannot be accessed after creating time.

10.4.3 Switch

Switch : X3DGroupingNode, X3DBoundedObject {
  MFNode  [in]     addChildren             [X3DChildNode]
  MFNode  [in]     removeChildren          [X3DChildNode]
  MFNode  [in,out] children       []       [X3DChildNode]
  SFInt32 [in,out] whichChoice    -1       [-1,∞)
  SFVec3f []       bboxCenter     0 0 0    (-∞,∞)
  SFVec3f []       bboxSize       -1 -1 -1 (0,∞) or -1 -1 -1
}

The Switch grouping node traverses zero or one of the nodes specified in the choice field.

10.2.1, Grouping and children node types, describes details on the types of nodes that are legal values for children.

The whichChoice field specifies the index of the child to traverse, with the first child having index 0. If whichChoice is less than zero or greater than the number of nodes in the choice field, nothing is chosen.

All nodes under a Switch continue to receive and send events regardless of the value of whichChoice. For example, if an active TimeSensor is contained within an inactive choice of an Switch, the TimeSensor sends events regardless of the Switch's state.

The bboxCenter and bboxSize fields specify a bounding box that encloses the Switch node's children. This is a hint that may be used for optimization purposes. The results are undefined if the specified bounding box is smaller than the actual bounding box of the child with the largest bounding box at any time. A default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, is calculated by the browser. A description of the bboxCenter and bboxSize fields is contained in 10.2.2, Bounding boxes.

10.4.4 Transform

Transform : X3DGroupingNode, X3DBoundedObject {
  MFNode     [in]     addChildren               [X3DChildNode]
  MFNode     [in]     removeChildren            [X3DChildNode]
  SFVec3f    [in,out] center           0 0 0    (-∞,∞)
  MFNode     [in,out] children         []       [X3DChildNode]
  SFRotation [in,out] rotation         0 0 1 0  [-1,1] or (-∞,∞)
  SFVec3f    [in,out] scale            1 1 1    (0,∞)
  SFRotation [in,out] scaleOrientation 0 0 1 0  [-1,1] or (-∞,∞)
  SFVec3f    [in,out] translation      0 0 0    (-∞,∞)
  SFVec3f    []       bboxCenter       0 0 0    (-∞,∞)
  SFVec3f    []       bboxSize         -1 -1 -1 (0,∞) or -1 -1 -1
}

The Transform node is a grouping node that defines a coordinate system for its children that is relative to the coordinate systems of its ancestors. See 4.3.5, Transformation hierarchy, and 4.3.6, Standard units and coordinate system, for a description of coordinate systems and transformations.

10.2.1, Grouping and children node types, provides a description of the children, addChildren, and removeChildren fields and eventIns.

The bboxCenter and bboxSize fields specify a bounding box that encloses the children of the Transform node. This is a hint that may be used for optimization purposes. The results are undefined if the specified bounding box is smaller than the actual bounding box of the children at any time. A default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, shall be calculated by the browser. The bounding box shall be large enough at all times to enclose the union of the group's children's bounding boxes; it shall not include any transformations performed by the group itself (i.e., the bounding box is defined in the local coordinate system of the children). The results are undefined if the specified bounding box is smaller than the true bounding box of the group. A description of the bboxCenter and bboxSize fields is provided in 10.2.2, Bounding boxes.

The translation, rotation, scale, scaleOrientation and center fields define a geometric 3D transformation consisting of (in order):

1. a (possibly) non-uniform scale about an arbitrary point;
2. a rotation about an arbitrary point and axis;
3. a translation.

The center field specifies a translation offset from the origin of the local coordinate system (0,0,0). The rotation field specifies a rotation of the coordinate system. The scale field specifies a non-uniform scale of the coordinate system. scale values shall be greater than zero. The scaleOrientation specifies a rotation of the coordinate system before the scale (to specify scales in arbitrary orientations). The scaleOrientation applies only to the scale operation. The translation field specifies a translation to the coordinate system.

Given a 3-dimensional point P and Transform node, P is transformed into point P' in its parent's coordinate system by a series of intermediate transformations. In matrix transformation notation, where C (center), SR (scaleOrientation), T (translation), R (rotation), and S (scale) are the equivalent transformation matrices,

  P' = T * C * R * SR * S * -SR * -C * P

The following Transform node:

Transform {
  center           C
  rotation         R
  scale            S
  scaleOrientation SR
  translation      T
  children         [...]
}

is equivalent to the nested sequence of:

Transform {
  translation T 
  children Transform {
    translation C
    children Transform {
      rotation R
      children Transform {
        rotation SR 
        children Transform {
          scale S 
          children Transform {
            rotation -SR 
            children Transform {
              translation -C
              children [...]
}}}}}}}

10.4.5 WorldInfo

WorldInfo : X3DInfoNode { 
  MFString [] info  []
  SFString [] title ""
}

The WorldInfo node contains information about the world. This node is strictly for documentation purposes and has no effect on the visual appearance or behaviour of the world. The title field is intended to store the name or title of the world so that browsers can present this to the user (perhaps in the window border). Any other information about the world can be stored in the info field, such as author information, copyright, and usage instructions.

10.5 Support levels

The Grouping component provides four levels of support as specified in Table 10.5.