[x3d-public] X3dToJava.xslt and setting correct containerField values to match parent-child node relationships

[Don Brutzman]

Thanks John for watching this topic closely, yes it is very improtant.

On 4/29/2017 11:08 PM, yottzumm at gmail.com wrote:
> > [i wrote]
> > Also added test to validate() method prohibiting DEF USE css or containerField as nodeField value.  Similarly included that warning in X3D Tooltips and X3D Schematron.

X3D Tooltips: connect
http://www.web3d.org/x3d/tooltips/X3dTooltips.html#connect
nodeField: "Warning: do not define a nodeField connection to an internal DEF, USE, class or containerField, since they are not fields in a node that can be modified by events at run time."

X3D Tooltips: ROUTE
http://www.web3d.org/x3d/tooltips/X3dTooltips.html#ROUTE
fromField, toField: "Warning: do not define an event connection using DEF, USE, class or containerField as literal values, since they are not fields in a node that can be modified by events at run time."

Similar diagnostic warnings added to draft X3D Schematron.

Looking ahead.  Upcoming issue as part of X3Dv4 HTML5 and DOM: accepting DOM events (e.g. HTML5 JavaScript callbacks) to modify the 'class' attribute, and also defining appropriate semantics.  As usual, the excellent experience being gained with Cobweb and X3DOM will give us an excellent starting point: can we "let X3D ROUTEd events follow the X3D event model, and let DOM events follow the DOM event model" ?

> Wait!  What about ComposedCubeMapTexture’s ImageTextures?

Very important (containerField field names: back front left right top bottom).  Also TextureBackGround field relationships to its ImageTexture children (containerField field names: backTexture, bottomTexture, frontTexture, leftTexture, rightTexture, or topTexture).

X3D Tooltips: ComposedCubeMapTexture
http://www.web3d.org/x3d/tooltips/X3dTooltips.html#ComposedCubeMapTexture
"Warning: child ImageTexture nodes must have unique containerField values for back, bottom, front, left, right, or top."

X3D Tooltips: TextureBackground
http://www.web3d.org/x3d/tooltips/X3dTooltips.html#TextureBackground
"Warning: child ImageTexture nodes must have unique containerField values for backTexture, bottomTexture, frontTexture, leftTexture, rightTexture, or topTexture."

A collection of these situations can be found in the following list.  Please advise if anyone encounters further omissions.  Clarifications and improvements are certainly welcome.

=====================================================================================
=====================================================================================
X3D Scene Authoring Hints: containerField
http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#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> shows 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.

Disambiguation sometimes remains necessary nevertheless: a few nodes have more than one field that can accept the same node type. In those ambiguous cases, a non-default containerField value must be provided. Specifically, care must be taken with the following non-default child fields:

     CADFace can contain a single default Shape node by setting containerField='shape'. Furthermore, CADFace can instead contain an LOD or Transform node as this SFNode field.
     CollidableShape can contain a single default Shape node by setting containerField='shape'.
     Collision can contain multiple nodes with default containerField='children', and can also have a single nonrendered Shape (or X3DGroupingNode) by setting containerField='proxy'.
     ComposedCubeMapTexture can contain up to 6 ImageTexture nodes, each with unique containerField values: back, bottom, front, left, right, or top.
     MetadataSet can contain a single X3DMetadataNode node with default containerField='metadata', or multiple other X3DMetadataNode nodes by setting containerField='value'.
     MovieTexture has default containerField='texture' when inside a parent Appearance node, or containerField='source' when inside a parent Sound node.
     TextureBackground can contain up to 6 ImageTexture nodes, each with unique containerField values: backTexture, bottomTexture, frontTexture, leftTexture, rightTexture, or topTexture.

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

> How do we specify the containerFields in JSON if they aren’t in the XML?

Well actually there is always a value available from XML; if omitted from the XML source, then the (identical) default from DTD or Schema should be used.  For example, default <ImageTexture containerField='texture'/>.

JSON is structured more like ClassicVRML encoding: the field name is always explicitly defined as a quoted key.

Examples of JSON syntax with comparisons to .x3d XML syntax can be found at

X3D to JSON Stylesheet Converter
http://www.web3d.org/x3d/stylesheets/X3dToJson.html

>  Is there some order to the ImageTextures?

No implications can be drawn from ImageTexture ordering.  Definition of those ImageTexture nodes can be in any order, since each individual containerField value defines the parent-child node relationships.

Regarding X3DJSAIL, as discussed separately:  the intended software design is to let the programmer ignore it insofar as possible, since addition of a node to the scene graph defines an unambiguous parent-child relationship.  Not fully there yet, this is TODO work in progress..

Meanwhile there is a setContainerField(value) for ProtoInstance, and there is a setContainerFieldOverride(value) (and get/reset methods also) for the programmer if needed.  Hopefully with continued theory-to-practice progress we might make the need to use that a rarity too.

http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Core/ProtoInstanceObject.html#setContainerField-java.lang.String-

http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/X3DConcreteNode.html#setContainerFieldOverride-java.lang.String-
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/X3DConcreteNode.html#getContainerFieldOverride--
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/X3DConcreteNode.html#resetContainerFieldOverride--

The code in X3DJSAIL always provides XML serialization output for non-default containerField values, and will also show all field values if ConfigurationProperties are overridden to do so.

ConfigurationProperties.setShowDefaultAttributes(boolean newShowDefaultAttributes)
"Set whether default attributes (and their values) are shown when serializing scene output."
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/ConfigurationProperties.html#setShowDefaultAttributes-boolean-

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