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

Don Brutzman brutzman at nps.edu
Sun Apr 30 19:43:46 PDT 2017 

OK further progress, there is a new X3DJSAIL build deployed that seems to handle all of the containerField cases identified so far:

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

_Non-default containerField values_

     CADFace can contain a single Shape, LOD or Transform node with containerField='shape' (rather than default 'children').
     CollidableShape can contain a single Shape node with containerField='shape' (rather than default 'children').
     Collision can contain a single nonrendered proxy Shape (or X3DGroupingNode) node with containerField='proxy' (rather than default 'children').
     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 'texture').
     MetadataSet can contain multiple other X3DMetadataNode nodes by setting containerField='value' (rather than default 'metadata').
     Sound can contain a single MovieTexture node with containerField='source' (rather than default 'texture').
     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 'texture').
=====================================================================================

Based on code inspection and smoke testing, it seems to handle these cases satisfactorily.  ProtoInstance support needs further checking, another day.

Added an informational method to provide information to authors who want it (perhaps for debugging).  But well on our way to not needing it whatsoever.

	X3DConcreteNode.getContainerFieldAlternateValues()
	http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/X3DConcreteNode.html#getContainerFieldAlternateValues--

Example use in HelloWorldProgram.java plus output in HelloWorldProgramOutput.x3d

scene.addChild(new SoundObject()
	.setSource(new MovieTextureObject()
		.setUrl(movieFileUrl))
		.addComments("Scene example fragment from " + movieExampleUrl)
		.addComments("Expected containerField='source', allowed containerField values=" +
			new MFStringObject(new MovieTextureObject().getContainerFieldAlternateValues()).toStringX3D()));
// all finished, go see if the paint is dry

<Sound>
	<MovieTexture containerField='source' url='"mpgsys.mpg" "http://www.web3d.org/x3d/content/examples/ConformanceNist/Appearance/MovieTexture/mpgsys.mpg"'/>
	<!-- Scene example fragment from http://www.web3d.org/x3d/content/examples/ConformanceNist/Appearance/MovieTexture/mpeg1-systems.x3d -->
	<!-- Expected containerField='source', allowed containerField values="texture" "source" "back" "bottom" "front" "left" "right" "top" "backTexture" "bottomTexture" "frontTexture" "leftTexture" "rightTexture" "topTexture" -->
</Sound>

Have fun without worrying about containerField values (I hope!)

On 4/30/2017 12:40 PM, Don Brutzman wrote:
> Thanks John for watching this topic closely, yes it is very important.
> 
> 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:
[... updated above ...]
> 
> 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

More information about the x3d-public mailing list