[x3d-public] "deep dive" on containerField and value fields for Metadata* node examples
Brutzman, Donald (Don) (CIV)
brutzman at nps.edu
Sun Jul 2 16:32:16 PDT 2023
John, there are several issues with your mail that can be confusing. Am trying here to untangle them. You likely understand all this, but email can be tricky to follow.
Summary: here is a "deep dive" on containerField and value fields for Metadata* node examples.
1. First, the url that you have is not current. The latest specification (International Standard proof version) url follows.
Please use the latest url, and stop using other urls.
X3D Architecture reference:
* https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-IS.proof/Part01/Architecture.html
1. Next, when you look at Shape node, there is no “value” field. There are fields defined for appearance, bboxDisplay, castShadow, geometry, metadata, visible, bboxCenter and bboxSize.
X3D Architecture reference:
* https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-IS.proof/Part01/components/shape.html#Shape
Shape : X3DShapeNode {
SFNode [in,out] appearance NULL [X3DAppearanceNode]
SFBool [in,out] bboxDisplay FALSE
SFBool [in,out] castShadow TRUE
SFNode [in,out] geometry NULL [X3DGeometryNode]
SFNode [in,out] metadata NULL [X3DMetadataObject]
SFBool [in,out] visible TRUE
SFVec3f [] bboxCenter 0 0 0 (-∞,∞)
SFVec3f [] bboxSize -1 -1 -1 [0,∞) or −1 −1 −1
}
1. Next. Every single node in X3D includes a field named “metadata”, where is allowed to have a single Metadata* node (MetadataBoolean, MetadataFloat, etc.).
X3D Architecture reference:
* 7.3.5 X3DNode
* https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-IS.proof/Part01/components/core.html#X3DNode
X3DNode {
SFNode [in,out] metadata NULL [X3DMetadataObject]
}
This abstract node type is the base type for all nodes and node types in the X3D system.
The metadata field provides information about the current node contents, as described in 7.2.4 Metadata<https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-IS.proof/Part01/components/core.html#Metadata>.
1. The X3D XML encoding uses containerField as a way to explicitly set the relationship of a given node to its parent node.
* X3D Scene Authoring Hints: containerField
* https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#containerField
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<https://www.web3d.org/specifications/X3dSchemaDocumentation4.0/x3d-4.0.html>, X3D DTD<https://www.web3d.org/specifications/X3dDoctypeDocumentation4.0.html> and X3D Tooltips<https://www.web3d.org/x3d/content/X3dTooltips.html> each define all default containerField values, which are optional and typically can be omitted for scene terseness.
o Usually ignorable. Default containerField values for each node are correct in most cases, so the need to override default containerField values is relatively rare.
o Terse match to other X3D encodings. 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.
o Examples. Example values include containerField='geometry' for Box node, containerField='children' for Group node, containerField='proxy' for hidden proxy shape within a Collision node, etc.
o USE node flexibility. 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.
o ProtoInstance node flexibility. ProtoInstance nodes are similarly allowed to have a containerField value that is different than default for their node type, again since the containerField attribute describes each node's relationship with its parent.
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 the correct parent-child field relationship with its parent node.
Additional guidance and detail follow there, trying to explain the specification with examples. It is simply offered as helpful information. The X3D Architecture remains the controlling normative reference.
1. Only the various Metadata* nodes have a field called “value”. Like every other X3D node, they also have a field called “metadata” too.
X3D Architecture reference:
* 7.4 Node reference
* https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-IS.proof/Part01/components/core.html#NodeReference
7.4.1 MetadataBoolean
MetadataBoolean : X3DNode, X3DMetadataObject {
SFNode [in,out] metadata NULL [X3DMetadataObject]
SFString [in,out] name ""
SFString [in,out] reference ""
MFBool [in,out] value []
}
The value field provides a list of Boolean metadata whose meaning is specified by the name field.
7.4.2 MetadataDouble
MetadataDouble : X3DNode, X3DMetadataObject {
SFNode [in,out] metadata NULL [X3DMetadataObject]
SFString [in,out] name ""
SFString [in,out] reference ""
MFDouble [in,out] value []
}
The value field provides a list of double-precision floating-point metadata whose meaning is specified by the name field.
7.4.3 MetadataFloat
MetadataFloat : X3DNode, X3DMetadataObject {
SFNode [in,out] metadata NULL [X3DMetadataObject]
SFString [in,out] name ""
SFString [in,out] reference ""
MFFloat [in,out] value []
}
The value field provides a list of single-precision floating-point metadata whose meaning is specified by the name field.
7.4.4 MetadataInteger
MetadataInteger : X3DNode, X3DMetadataObject {
SFNode [in,out] metadata NULL [X3DMetadataObject]
SFString [in,out] name ""
SFString [in,out] reference ""
MFInt32 [in,out] value []
}
The value field provides a list of integer metadata whose meaning is specified by the name field.
7.4.5 MetadataSet
MetadataSet : X3DNode, X3DMetadataObject {
SFNode [in,out] metadata NULL [X3DMetadataObject]
SFString [in,out] name ""
SFString [in,out] reference ""
MFNode [in,out] value [] [X3DMetadataObject]
}
The value field provides a list of X3DMetadataObject nodes whose meaning is specified by the name field.
7.4.6 MetadataString
MetadataString : X3DNode, X3DMetadataObject {
SFNode [in,out] metadata NULL [X3DMetadataObject]
SFString [in,out] name ""
SFString [in,out] reference ""
MFString [in,out] value []
}
The value field provides a list of string metadata whose meaning is specified by the name field.
1. As shown above in the specification, only the MetadataSet node can contain Metadata* nodes in either a metadata field, a value field, or both. So MetadataSet is the tricky node to watch out for.
Example:
<Shape>
<MetadataSet DEF=’TripleTroubleExample’ containerField=’metadata’>
<MetadataBoolean DEF=’SomeBooleanArray’ value=”true false true” containerField=’metadata’/>
<MetadataInteger DEF=’SomeIntegerArray’ value=’-1 -2 0 1 2 3 4’ containerField=’value’/>
<MetadataDouble DEF=’SomeDoubleArray’ value=’5.0 6.28 777.7’ containerField=’value’/>
</MetadataSet>
</Shape
Because MetadataSet can only contain one node in its metadata field, only one of these contained nodes can be containerField=’metadata’ and still be correct.
1. Remember, all of this containerField business is only for terseness of the XML encoding. It has nothing to do with equivalent X3D representations in ClassicVRML, JSON, Python, Java, Turtle, etc.
Easy to forget… Uh, did you remember that?
1. Evolutionary trickiness is next (as if all this weren’t tricky enough already).
Experience in X3D3 showed that multiple metadata nodes were used, complex metadata sets became extremely verbose because containerField values were listed everywhere. In fact, they were so verbose that it became hard to read and process the sets of metadata being collected together! Ouch.
After much debate and experimentation, we decided to lean towards the future where there might be inclusion of quite a lot of metadata sets when converting from CAD, converting from other model formats, expressing new X3D node values, etc. etc.
As a result we changed the default containerField values (for Metadata* nodes only) in the X3D version 4 XML encoding. This had no impact on the vast majority of X3D scenes out there.
Thus, if containerField is omitted for terseness in a given scene fragment, the XML might look different for X3D3 versus X3D4. The X3D being modeled is not different.
The above TripleTroubleExample will always be correct in every version of X3D, because the containerField field names are explicitly defined. Including containerField is never wrong.
Here are two variations on the above example that omit default containerField entries, for X3D 3.3 and X3D 4.0 respectively.
<Shape>
<MetadataSet DEF=’TripleTroubleExampleX3D3’ >
<MetadataBoolean DEF=’SomeBooleanArray’ value=”true false true” />
<MetadataInteger DEF=’SomeIntegerArray’ value=’-1 -2 0 1 2 3 4’ containerField=’value’/>
<MetadataDouble DEF=’SomeDoubleArray’ value=’5.0 6.28 777.7’ containerField=’value’/>
<!- - containerField always necessary in subsequent MetadataSet subtree values - ->
</MetadataSet>
</Shape
or
<Shape>
<MetadataSet DEF=’TripleTroubleExampleX3D4’ containerField=’metadata’>
<MetadataBoolean DEF=’SomeBooleanArray’ value=”true false true” containerField=’metadata’/>
<MetadataInteger DEF=’SomeIntegerArray’ value=’-1 -2 0 1 2 3 4’ />
<MetadataDouble DEF=’SomeDoubleArray’ value=’5.0 6.28 777.7’ />
<!- - containerField not necessary in subsequent MetadataSet subtree values - ->
</MetadataSet>
</Shape
1. As before, the XML terseness has nothing to do with equivalent X3D representations in ClassicVRML, JSON, Python, Java, Turtle, etc.
Yes, it is good to remember that.
So, any X3D JSON representations will always have the field name defined.
Hopefully this explanation helps determine whether the X3dToJSON.xslt stylesheet is correct already. If not, we will fix it, just as your latest testing has identified some necessary fixes in the X3dToJava.xslt stylesheet.
Having good repeatable examples in the X3D Example Archives to test things is always helpful. Perhaps the above example snippets can help.
1. Your mileage may vary (YMMV).
Nevertheless the X3D scene graph defined by the X3D Architecture international specification is unambiguous.
As ever, improving our XML/JSON schema validation, and diagnostic/conversion tools, and unit-test examples all helps.
Have fun with X3D – or else! 8)
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 https://faculty.nps.edu/brutzman
From: John Carlson <yottzumm at gmail.com>
Sent: Friday, June 30, 2023 11:22 PM
To: Brutzman, Donald (Don) (CIV) <brutzman at nps.edu>
Cc: X3D Graphics public mailing list <x3d-public at web3d.org>
Subject: Re: Is https://www.web3d.org/specifications/java/examples/HelloWorldProgramOutput.json valid?
I'm not too worried about JSON schema, I just want to make sure that the X3D JSON is right, per the X3D4 standard architecture, with my own eyeballs. I may just have a misunderstanding of the following Shape standard. I don't see a value field, just a metadata field. I realize value may be otherwise specified, but it's not in X3D tooltips either, under Shape.
https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/shape.html#Shape
I'm not seeing that Shape has a value field, but I'm not too clear on whether containerField equal to "metadata" or "value" should be used on MetadataXxx statements in Shape and Text nodes in JSON. It's highly possible that I'm totally misunderstanding.
I understand that both -value and @value are likely possible at some point!
Here are my diffs to the HelloWorldProgramOutput.json to make it pass:
--- a/src/main/data/HelloWorldProgramOutput.json
+++ b/src/main/data/HelloWorldProgramOutput.json
@@ -156,7 +156,7 @@
},
{
"@name":"translated",
- "@content":"29 June 2023"
+ "@content":"30 June 2023"
},
{
"@name":"generator",
@@ -950,15 +950,14 @@
"-children":[
{ "Shape":
{
- "-value":[
+ "-metadata":
{ "MetadataString":
{
"@name":"findThisNameValue",
"@DEF":"FindableMetadataStringTest",
"@value":["test case"]
}
- }
- ],
+ },
"-appearance":
{ "Appearance":
{
@@ -2206,15 +2205,14 @@
"-children":[
{ "Shape":
{
- "-value":[
+ "-metadata":
{ "MetadataString":
{
"@name":"findThisNameValue",
"@DEF":"FindableMetadataStringTest",
"@value":["test case"]
}
- }
- ],
+ },
"-appearance":
{ "Appearance":
{
Here's the diff to XML I have locally to make the JSON pass. See the blue containerField.
diff --git a/src/main/data/HelloWorldProgramOutput.x3d b/src/main/data/HelloWorldProgramOutput.x3d
index 99b309451..0d47bfed3 100644
--- a/src/main/data/HelloWorldProgramOutput.x3d
+++ b/src/main/data/HelloWorldProgramOutput.x3d
@@ -246,7 +246,7 @@ function clockTrigger (timeValue)
<!-- Test success: declarative statement createDeclarativeShapeTests() -->
<Group DEF='DeclarativeGroupExample'>
<Shape>
- <MetadataString DEF='FindableMetadataStringTest' name='findThisNameValue' value='"test case"'/>
+ <MetadataString DEF='FindableMetadataStringTest' containerField='metadata' name='findThisNameValue' value='"test case"'/>
<Appearance DEF='DeclarativeAppearanceExample'>
<!-- DeclarativeMaterialExample gets overridden by subsequently added MaterialModulator ProtoInstance -->
<ProtoInstance DEF='MyMaterialModulator' name='MaterialModulator' containerField='material'/>
Thanks for a second set of eyeballs on this.
My guess is that X3DJSAIL is not reporting a containerField when it should, to produce a processable HelloWorldProgramOutput.x3d that will produce good JSON. I do not have intermediate code right now.
So actually, it has nothing to do with JSON and everything to do with X3DJSAIL XML output. But yeah, if you want to fix it in X3DJSAIL instead of X3dToJson.xslt, that would probably be easier, and very cool.
John
On Sat, Jul 1, 2023 at 12:28 AM Brutzman, Donald (Don) (CIV) <brutzman at nps.edu<mailto:brutzman at nps.edu>> wrote:
Hi John. All of the JSON that you find is produced by our X3dToJson.xslt stylesheet, which hopefully meets all patterns we derived and documented at
* X3D to JSON Stylesheet Converter
* https://www.web3d.org/x3d/stylesheets/X3dToJson.html
Well-formed JSON can be checked. All of our online examples have a link to check via JSONLint, though tonight it is saying “unable to connect” (while providing plenty of advertising).
* X3D Example Archives: X3D4WA, X3D for Web Authors, Chapter 01 Technical Overview, Hello World
* https://x3dgraphics.com/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorldIndex.html
* upper-right inset box of links: .json<https://x3dgraphics.com/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.json> (check<https://jsonlint.com/?json=https://X3dGraphics.com/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.json>)
* https://jsonlint.com/?json=https://X3dGraphics.com/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.json
If there are mistakes in our X3D .xml -> .json pattern or the conversion stylesheet, they can be fixed.
Strict JSON validation isn’t possible until a JSON Schema is approved. If you think that there is a Java-based implementation of the draft JSON Schema that is mature and stable enough to deserve our time, we can try adding that to our various build tools for X3D Example Archives and X3DJSAIL.
* http://json-schema.org<http://json-schema.org/>
all the best, Don
--
Don Brutzman Naval Postgraduate School, Code USW/Br brutzman at nps.edu<mailto:brutzman at nps.edu>
Watkins 270, MOVES Institute, Monterey CA 93943-5000 USA +1.831.656.2149
X3D graphics, virtual worlds, navy robotics https://faculty.nps.edu/brutzman
From: John Carlson <yottzumm at gmail.com<mailto:yottzumm at gmail.com>>
Sent: Friday, June 30, 2023 8:24 PM
To: Brutzman, Donald (Don) (CIV) <brutzman at nps.edu<mailto:brutzman at nps.edu>>
Cc: X3D Graphics public mailing list <x3d-public at web3d.org<mailto:x3d-public at web3d.org>>
Subject: Is https://www.web3d.org/specifications/java/examples/HelloWorldProgramOutput.json valid?
Don, if
https://www.web3d.org/specifications/java/examples/HelloWorldProgramOutput.json
is supposed to be valid X3D JSON, please inform me. Thanks!
To ensure that -value is not a field of Shape in JSON, I have added the following exception in x3djsonld.py.
if parent in ("Text", "Shape") and key in ("value"): # don't have value yet, sorry
# do value later
raise "-value not a supported field of Text or Shape, try -metadata?"
continue
I can revert the code if necessary. I'm trying to follow the standard as I see it.
If -value under Shape is correct, then X3DJSAIL needs to support addValue (as I have it in Java) or setValue. That's my opinion.
John
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20230702/b55c8633/attachment-0001.html>
More information about the x3d-public
mailing list