[x3d-public] "deep dive" on containerField and value fields for Metadata* node examples
John Carlson
yottzumm at gmail.com
Mon Jul 3 00:50:35 PDT 2023
When I say container field (in JSON),I mean something like "-value" ...
(not that I'm advocating for this, but it is used for children of Metadata*
nodes), not @value. Let's be really clear on that. Let's come up with a
term for "-metadata" "-geometry", "-appearance", etc., so I can be
perfectly clear. I prefer "{metadata, geometry, appearance}
container field", but others may have another choice. I think Roy had a
term for it, but I forget. I realize one cannot use -value as a field of
Shape. That's what I'm advocating against in HelloWorldProgramOutput.json.
Just look at this incorrect example:
https://sourceforge.net/p/x3d/code/HEAD/tree/www.web3d.org/x3d/stylesheets/java/examples/HelloWorldProgramOutput.json
Search for a few examples for -value (use CTRL-f to search),
especially under the Shape property value.
I realize I may have a different style of communication.
John
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/9eff12d2/attachment-0001.html>
More information about the x3d-public
mailing list