[x3d-public] "deep dive" on containerField and value fields for Metadata* node examples
John Carlson
yottzumm at gmail.com
Sun Jul 2 22:21:39 PDT 2023
While JSON does not have "containerField" it does have container fields.
Namely, there is a -value container field for MetadataXxx children of
MetadataSet, and -metadata container field for a direct MetadataXxx
descendant of a non-MetadataXxx nodes. I agree that most nodes do not
contain a value field in the standard, but do contain a metadata field. In
the above, replace "Xxx" to make the appropriate Metadata... type of node.
So having a Shape node with a -value container field is not legal X3D4 JSON.
I'm open to other names besides container fields, it's just confusing to
have two different names for the same thing between encodings.
Please double check web3d.org standards page for updating architecture
document:
[image: image.png]
[image: image.png]
On Sun, Jul 2, 2023 at 6:32 PM Brutzman, Donald (Don) (CIV) <
brutzman at nps.edu> wrote:
> 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> 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
>
>
>
> 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 8:24 PM
> *To:* Brutzman, Donald (Don) (CIV) <brutzman at nps.edu>
> *Cc:* X3D Graphics public mailing list <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/20230703/28b09786/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image.png
Type: image/png
Size: 109901 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20230703/28b09786/attachment-0002.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image.png
Type: image/png
Size: 92757 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20230703/28b09786/attachment-0003.png>
More information about the x3d-public
mailing list