Extensible 3D (X3D)

Part 1: Architecture and base components

10 Grouping component

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

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.

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:

Components may add the following:

- new grouping node types,
- new node types that may be used as children, and
- node types that may not be used as children.

All grouping nodes 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*
field of 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).

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. A *children* field is not allowed to directly contain multiple
instances of the same node. A *children* field is not allowed to contain
nodes that are ancestors of the grouping node.

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 from *X3DChildNode*. Therefore, only node types
derived from *X3DChildNode *may be placed there. Shape is legal in the
children field because it is derived from *X3DChildNode*, while Appearance
is not. See Figure 4.2 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.

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 (EXAMPLE 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.

X3DBoundedObject { SFVec3f [] bboxCenter 0 0 0 (-∞,∞) SFVec3f [] bboxSize -1 -1 -1 [0,∞) or −1 −1 −1 }

This abstract node type is the 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 grouping 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.

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

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 can be found in 10.2.1
Grouping and children node types.

Group : X3DGroupingNode { MFNode [in] addChildren [X3DChildNode] MFNode [in] removeChildren [X3DChildNode] MFNode [in,out] children [] [X3DChildNode] SFNode [in,out] metadata NULL [X3DMetadataObject] 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 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.

StaticGroup : X3DChildNode, X3DBoundedObject { SFNode [in,out] metadata NULL [X3DMetadataObject] MFNode [] children [] [X3DChildNode] SFVec3f [] bboxCenter 0 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 X3D representations (such as field data), as they cannot be accessed after creation time.

Switch : X3DGroupingNode { MFNode [in] addChildren [X3DChildNode] MFNode [in] removeChildren [X3DChildNode] MFNode [in,out] children [] [X3DChildNode] SFNode [in,out] metadata NULL [X3DMetadataObject] 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
*children* 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 *children* 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.

Transform : X3DGroupingNode { MFNode [in] addChildren [X3DChildNode] MFNode [in] removeChildren [X3DChildNode] SFVec3f [in,out] center 0 0 0 (-∞,∞) MFNode [in,out] children [] [X3DChildNode] SFNode [in,out] metadata NULL [X3DMetadataObject] SFRotation [in,out] rotation 0 0 1 0 [-1,1] or (-∞,∞) SFVec3f [in,out] scale 1 1 1 (-∞, ∞) 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.

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):

- a (possibly) non-uniform scale about an arbitrary point;
- a rotation about an arbitrary point and axis;
- 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 may have any value: positive, negative
(indicating a reflection), or zero. A value of zero indicates that any child
geometry shall not be displayed.
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 [ # Point P (or children holding other geometry) ] }

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 [ # Point P (or children holding other geometry) ] }}}}}}}

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

Table 10.2 — Grouping component support levels

Level | Prerequisites | Nodes/Features | Support |
---|---|---|---|

1 |
Core 1 | ||

X3DBoundedObject (abstract) |
n/a | ||

X3DGroupingNode (abstract) |
n/a | ||

Group | addChildren optionally supported. removeChildren
optionally supported. Otherwise as for all groups. |
||

Transform | addChildren optionally supported. removeChildren
optionally supported. Otherwise as for all groups. |
||

2 |
Core 1 | ||

All Level 1 Grouping nodes | All fields fully supported. | ||

Switch | All fields fully supported. | ||

3 |
Core 1 |
||

All Level 2 Grouping nodes | All fields fully supported. | ||

StaticGroup | All fields fully supported. |