[x3d-public] Which of these are necessary containerFields in XML?

[Don Brutzman]

Hi John.  I took some time last year to work through all of the containerField variations, in order to offer only valid choices within X3D-Edit node editors.

The summary of issues and ambiguous children (i.e. child nodes that might have varied relationships to parents) is online as follows.  If you see additional candidates, please advise.

===========================================================================
===========================================================================
X3D Scene Authoring Hints: containerField
http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#containerField

*containerField*

Each containerField value is the field name from the X3D Specification that indicates a contained node's relationship to its parent node.

Addition of containerField values only occurs in the XML encoding of .x3d scenes. For example: <Transform><Shape containerField='children'/></Transform> indicates that the Shape node is one of the children of the Transform node.

The X3D XML Schema, X3D DTD and X3D Tooltips each define all default containerField values, which are optional and can be omitted for scene terseness.

- Default containerField values for each node are correct in most cases, so the need to override default containerField values is rare.
- The containerField attribute is part of XML encoding for X3D scenes, and corresponds to the always-declared field labels in the ClassicVRML and VRML97 file encodings.
- Example values include containerField='geometry' for Box node, containerField='children' for Group node, containerField='proxy' for hidden proxy shape within a Collision node, etc.
- USE nodes are allowed to have a containerField value that is different than the corresponding DEF declaration of that node, since the containerField attribute describes each node's relationship with its parent.

*Non-default containerField values*

Disambiguation of parent-child field relationships is sometimes necessary, since a few parent nodes have more than one child field that can accept the same node type. In those ambiguous cases, the child node must have a correct containerField value in order to precisely define parent-child field relationships.

Specifically, care must be taken with the following non-default child containerField values.

1. CADFace can contain a single Shape, LOD or Transform node with containerField='shape' (rather than default containerField='children').
2. CollidableShape can contain a single Shape node with containerField='shape' (rather than default containerField='children').
3. Collision can contain a single nonrendered proxy Shape (or X3DGroupingNode) node with containerField='proxy' (rather than default containerField='children').
4. ComposedCubeMapTexture can contain up to six X3DTexture2DNode (e.g. ImageTexture) nodes, each with a unique containerField value: back, bottom, front, left, right, or top (rather than default containerField='texture').
5. GeoLOD can contain multiple X3DChildNode nodes with containerField='rootNode'. Curiously GeoLOD is not allowed to have child nodes with default containerField=children defined in a scene, since that field is defined differently with accessType outputOnly and thus is only able to send MFNode events at run time.
6. MetadataSet can contain multiple other child X3DMetadataNode nodes by setting their containerField='value' (rather than default containerField='metadata'). Similar to the other metadata nodes, MetadataSet can also contain a single X3DMetadataNode node describing itself (with default containerField='metadata').
7. Sound can contain a single MovieTexture node with containerField='source' (rather than default containerField='texture').
8. TextureBackground can contain up to six X3DTexture2DNode (e.g. ImageTexture) nodes, each with unique containerField values: backTexture, bottomTexture, frontTexture, leftTexture, rightTexture, or topTexture (rather than default containerField='texture').

All X3D encodings define parent-child relationships.  Only 8 nodes in .x3d XML encoding might require a non-default containerField value, so that encoding is actually much more terse than other encodings.

Quality Assurance (QA): the X3D Validator checks default and defined containerField values for logical correctness.
===========================================================================
===========================================================================

Of note, looking ahead to potential abstract specification improvements in X3D v4:

a. we might make the special case of CADFace  go away in X3D v4 by sticking to conventional default 'children' field.
b. with a little work we might be able to combine Background and TextureBackground into a single node, simplifying the X3D language.
c. field names for TextureBackground (front back etc.) and TextureBackground (frontTexture backTexture etc.) have no need to be different, further simplification possible.

all the best, Don
-- 
Don Brutzman  Naval Postgraduate School, Code USW/Br       brutzman at nps.edu
Watkins 270,  MOVES Institute, Monterey CA 93943-5000 USA   +1.831.656.2149
X3D graphics, virtual worlds, navy robotics http://faculty.nps.edu/brutzman