[x3d-public] Action Needed: Need for acceptableStatements (or types) for children fields in X3DObject Model

John Carlson yottzumm at gmail.com
Sat Jul 29 16:58:37 PDT 2017


Thank you for your analysis Don.   I did add X3DChildNode as a parent of
all statements, but apparently this was incorrect, so I removed it?  Please
let me know.   If X3DChildNode is not the parent of all statements, there
needs to a distinguishing in the object model.

John

On Jul 29, 2017 6:13 PM, "Don Brutzman" <brutzman at nps.edu> wrote:

> Thanks for the close scrutiny of OM4X3D and autogeneration/testing of JSON
> Schema, John.
>
> BLUF recommendation: suggest you use current design patterns in existing
> X3D JSON Schema and we continue refining and improving everything
> together.  In this way, multiple X3D validation designs remain coherent and
> consistent while refining/evolving.  It is much much easier to compare to
> gain insight, and then incrementally improve matching approaches, than it
> is to reconcile divergent approaches.
>
> Detailed analysis follows.
>
> Sounds like you are using Object Model for X3D (OM4X3D) available at
>
>         http://www.web3d.org/specifications/X3DObjectModel-3.3.xml
>
> The content model for contained nodes and statements is generated from the
> content model for X3D XML Schema, and matches both XML Schema and DTD.
>
>         http://www.web3d.org/specifications/x3d-3.3.xsd
>         http://www.web3d.org/specifications/X3dSchemaDocumentation3.3.html
>
>         http://www.web3d.org/specifications/x3d-3.3.dtd
>         http://www.web3d.org/specifications/X3dDoctypeDocumentation3
> .3.html
>
> Example excerpt follows:
>
> <AbstractNodeType name="X3DGroupingNode">
>    <InterfaceDefinition specificationUrl="http://www.w
> eb3d.org/documents/specifications/19775-1/V3.3/Part01/
> components/group.html#X3DGroupingNode"
>                                                 appinfo="Grouping nodes
> can contain other nodes as children, thus making up the backbone of a scene
> graph.">
>           <componentInfo name="Grouping" level="1"/>
>           <Inheritance baseType="X3DChildNode"/>
>           <AdditionalInheritance baseType="X3DBoundedObject"/>
>           <field type="MFNode"
>                          accessType="inputOnly"
>                          name="addChildren"
>                          acceptableNodeTypes="X3DChildNode">
>                  <componentInfo name="Grouping" level="2"/>
>           </field>
>           <field type="SFVec3f"
>                          accessType="initializeOnly"
>                          name="bboxCenter"
>                          default="0 0 0"/>
>           <field type="SFVec3f"
>                          accessType="initializeOnly"
>                          name="bboxSize"
>                          default="-1 -1 -1"
>                          baseType="boundingBoxSizeType"/>
>           <field type="MFNode"
>                          accessType="inputOutput"
>                          name="children"
>                          acceptableNodeTypes="X3DChildNode"/>
>           <field type="SFNode"
>                          accessType="inputOutput"
>                          name="metadata"
>                          default="NULL"
>                          acceptableNodeTypes="X3DMetadataObject"
>                          inheritedFrom="X3DNode"/>
>           <field type="MFNode"
>                          accessType="inputOnly"
>                          name="removeChildren"
>                          acceptableNodeTypes="X3DChildNode">
>                  <componentInfo name="Grouping" level="2"/>
>           </field>
>           <field type="SFString"
>                          accessType="inputOutput"
>                          name="DEF"
>                          inheritedFrom="DEF_USE"/>
>           <field type="SFString"
>                          accessType="inputOutput"
>                          name="USE"
>                          inheritedFrom="DEF_USE"/>
>           <field type="SFString"
>                          accessType="inputOutput"
>                          name="class"
>                          inheritedFrom="globalAttributes"/>
>           <ContentModel>
>                  <GroupContentModel name="ChildContentModel" minOccurs="0"
> maxOccurs="unbounded"/>
>                  <GroupContentModel name="ChildContentModelCore"
> minOccurs="0"/>
>           </ContentModel>
>    </InterfaceDefinition>
> </AbstractNodeType>
>
> Here is a variant example which includes both primary GroupContentModel
> and then specificNodeContentModel  entries:
>
> <ConcreteNode name="CADFace">
>    <InterfaceDefinition specificationUrl="http://www.w
> eb3d.org/documents/specifications/19775-1/V3.3/Part01/
> components/CADGeometry.html#CADFace">
>           <componentInfo name="CADGeometry" level="2"/>
>           <Inheritance baseType="X3DProductStructureChildNode"/>
>           <AdditionalInheritance baseType="X3DBoundedObject"/>
>           <field type="SFVec3f"
>                          accessType="initializeOnly"
>                          name="bboxCenter"
>                          default="0 0 0"/>
>           <field type="SFVec3f"
>                          accessType="initializeOnly"
>                          name="bboxSize"
>                          default="-1 -1 -1"
>                          baseType="boundingBoxSizeType"/>
>           <field type="SFNode"
>                          accessType="inputOutput"
>                          name="metadata"
>                          default="NULL"
>                          acceptableNodeTypes="X3DMetadataObject"
>                          inheritedFrom="X3DNode"/>
>           <field type="SFString"
>                          accessType="inputOutput"
>                          name="name"
>                          inheritedFrom="X3DProductStructureChildNode"/>
>           <field type="SFNode"
>                          accessType="inputOutput"
>                          name="shape"
>                          default="NULL"
>                          acceptableNodeTypes="Shape|LOD|Transform"/>
>           <field type="SFString"
>                          accessType="inputOutput"
>                          name="DEF"
>                          inheritedFrom="DEF_USE"/>
>           <field type="SFString"
>                          accessType="inputOutput"
>                          name="USE"
>                          inheritedFrom="DEF_USE"/>
>           <field type="SFString"
>                          accessType="inputOutput"
>                          name="class"
>                          inheritedFrom="globalAttributes"/>
>           <containerFieldDefault name="children"/>
>           <ContentModel>
>                  <GroupContentModel name="ChildContentModelCore"
> minOccurs="0"/>
>                  <NodeContentModel name="Shape"/>
>                  <NodeContentModel name="LOD"/>
>                  <NodeContentModel name="Transform"/>
>                  <NodeContentModel name="ProtoInstance"/>
>           </ContentModel>
>    </InterfaceDefinition>
> </ConcreteNode>
>
> Here is a particular statement, ROUTE:
>
> <Statement name="ROUTE">
>    <InterfaceDefinition specificationUrl="http://www.w
> eb3d.org/documents/specifications/19775-1/V3.3/Part01/
> concepts.html#ModifyingObjectsRoutes"
>                                                 appinfo="ROUTE connects
> output fields of event-producing nodes to input fields of event-consuming
> nodes.">
>           <componentInfo name="Core" level="1"/>
>           <field type="SFString"
>                          accessType="inputOutput"
>                          name="fromField"
>                          use="required"/>
>           <field type="SFString"
>                          accessType="inputOutput"
>                          name="fromNode"
>                          use="required"/>
>           <field type="SFString"
>                          accessType="inputOutput"
>                          name="toField"
>                          use="required"/>
>           <field type="SFString"
>                          accessType="inputOutput"
>                          name="toNode"
>                          use="required"/>
>    </InterfaceDefinition>
> </Statement>
>
> However "ROUTE" does not appear elsewhere in OM4X3D.  Its presence as a
> legal child node of X3DGroupingNode is implicit and can only be inferred by
> looking at ChildContentModel in X3D XML Schema.
>
> As you have discovered, this appears to be an omission in the OMX3D
> definitions.
>
> We certainly do want to keep everything consistent, and so precise
> treatment to make such a relationship explicit in OM4X3D will require
> further scrutiny of these design patterns, quite possibly according to the
> approach that you suggest.  Since the X3D content model is pretty involved,
> and since we are working across multiple encodings and programming
> languages, it is good to be careful and deliberate about these things.
>
> Of related interest is to look at how X3DJSAIL handles this relationship
> by using class (rather than interface) hierarchy:
> =================================================================
> http://www.web3d.org/specifications/java/javadoc/org/web3d/
> x3d/jsail/Core/ROUTEObject.html
>
> org.web3d.x3d.jsail.Core
> Class ROUTEObject
>     java.lang.Object
>         org.web3d.x3d.jsail.X3DConcreteElement
>             org.web3d.x3d.jsail.X3DConcreteStatement
>                 org.web3d.x3d.jsail.Core.ROUTEObject
>
>     All Implemented Interfaces:
>         X3DChildNode, X3DNode
> =================================================================
>
> Note that since ROUTEObject implements X3DChildNode, it can appear within
> any X3D
>
> First, it maintains the X3D interfaces from the X3D Abstract Specification
> (e.g. X3DChildNode, X3DNode) separate from the object hierarchy.
>
> Second, since the abstract specification does not list interfaces for
> statements (root cause of this current design gap), it creates
> Class X3DConcreteElement which has two concrete subclasses:
> X3DConcreteNode and X3DConcreteStatement.
>
> =================================================================
> http://www.web3d.org/specifications/java/javadoc/org/web3d/
> x3d/jsail/X3DConcreteElement.html
> http://www.web3d.org/specifications/java/javadoc/org/web3d/
> x3d/jsail/package-tree.html
>
> org.web3d.x3d.jsail
> Class X3DConcreteElement
>     java.lang.Object
>         org.web3d.x3d.jsail.X3DConcreteElement
>
>     Direct Known Subclasses:
>         X3DConcreteNode, X3DConcreteStatement
> =================================================================
>
> After considering and trying a number of approaches, I left the X3D
> specification interfaces verbatim/unchanged and handled the necessary
> additions via this class/subclass approach.  It achieves the same content
> model as X3D specification and XML schema with the addition of strong
> typing.  Strong typing of elements (i.e. nodes or statements) means that
> creation of a valid scene graph is easily allowed (indeed with choices
> prompted by IDE).  Meanwhile, creation of an invalid scene graph is not
> permitted since that would violate strong typing requirements and thus fail
> compilation.
>
> Next... Looking closely at Roy's manually created X3D JSON schema is
> particularly important for what you are doing.  Some excerpts:
> =================================================================
> http://www.web3d.org/specifications/x3d-3.3-JSONSchema.json
> http://www.web3d.org/specifications/X3dJsonSchemaDocumentation3.3.html
>
> JSON Schema definition, Group documentation:
> http://www.web3d.org/specifications/X3dJsonSchemaDocumentati
> on3.3/x3d-3.3-JSONSchema.html#Link54
>
> "Group": {
>     "type": "object",
>     "properties": {
>         "@DEF": {
>             "type": "string"
>         },
>         "@USE": {
>             "type": "string"
>         },
>         "IS": {
>             "$ref": "#/definitions/IS"
>         },
>         "@bboxCenter": {
>             "type": "array",
>             "minItems": 3,
>             "maxItems": 3,
>             "items": {
>                 "type": "number",
>                 "default": 0
>             }
>         },
>         "@bboxSize": {
>             "$ref": "#/definitions/@bboxSize"
>         },
>         "-children": {
>             "$ref": "#/definitions/-children"
>         },
>         "-metadata": {
>             "$ref": "#/definitions/-metadata"
>         }
>     },
>     "additionalProperties": false
> }
>
> =================================================================
> JSON Schema definition, CADFace documentation:
>         http://www.web3d.org/specifications/X3dJsonSchemaDocumentati
> on3.3/x3d-3.3-JSONSchema.html#Link12
>
> "CADFace": {
>         "type": "object",
>         "properties": {
>                 "@DEF": {
>                         "type": "string"
>                 },
>                 "@USE": {
>                         "type": "string"
>                 },
>                 "IS": {
>                         "$ref": "#/definitions/IS"
>                 },
>                 "@bboxCenter": {
>                         "type": "array",
>                         "minItems": 3,
>                         "maxItems": 3,
>                         "items": {
>                                 "type": "number",
>                                 "default": 0
>                         }
>                 },
>                 "@bboxSize": {
>                         "$ref": "#/definitions/@bboxSize"
>                 },
>                 "@name": {
>                         "type": "string"
>                 },
>                 "-metadata": {
>                         "$ref": "#/definitions/-metadata"
>                 },
>                 "-shape": {
>                         "type": "object",
>                         "properties": {
>                                 "LOD": {
>                                         "$ref": "#/definitions/LOD"
>                                 },
>                                 "Shape": {
>                                         "$ref": "#/definitions/Shape"
>                                 },
>                                 "Transform": {
>                                         "$ref": "#/definitions/Transform"
>                                 },
>                                 "ProtoInstance": {
>                                         "$ref":
> "#/definitions/ProtoInstance"
>                                 }
>                         },
>                         "additionalProperties": false
>                 },
>                 "-children": {
>                         "$ref": "#/definitions/-commentRoute"
>                 }
>         },
>         "additionalProperties": false
> },
>
> =================================================================
> JSON Schema definition -children
> http://www.web3d.org/specifications/X3dJsonSchemaDocumentati
> on3.3/x3d-3.3-JSONSchema.html#Link107
>
> (scroll down to "source code)
>
> "-children": {
>     "description": "MF X3DChildNode content",
>     "type": "array",
>     "minItems": 1,
>     "items": {
>         "type": "object",
>         "properties": {
>             "#comment": {
>                 "type": "string"
>             },
>             "ProtoInstance": {
>                 "$ref": "#/definitions/ProtoInstance"
>             },
>             "Anchor": {
>                 "$ref": "#/definitions/Anchor"
>             },
>             "AudioClip": {
>                 "$ref": "#/definitions/AudioClip"
>             },
>             "Background": {
>                 "$ref": "#/definitions/Background"
>             },
>
> [... many nodes skipped ...]
>             "VolumePickSensor": {
>                 "$ref": "#/definitions/VolumePickSensor"
>             },
>             "WorldInfo": {
>                 "$ref": "#/definitions/WorldInfo"
>             },
>             "ROUTE": {
>                 "$ref": "#/definitions/ROUTE"
>             },
>             "ProtoDeclare": {
>                 "$ref": "#/definitions/ProtoDeclare"
>             },
>             "ExternProtoDeclare": {
>                 "$ref": "#/definitions/ExternProtoDeclare"
>             },
>             "IMPORT": {
>                 "$ref": "#/definitions/IMPORT"
>             },
>             "EXPORT": {
>                 "$ref": "#/definitions/EXPORT"
>             }
>         },
>         "additionalProperties": false
>     }
> }
> =================================================================
>
> Point worth noting in preceding: we gave comment and ROUTE the prefix key
> "-children".  I think we should take a similar approach for IMPORT and
> EXPORT if they appear within nodes that are not X3DGroupingNode.
>
> So, hope this helps, please advise what you think.
>
> v/r Don
>
>
> On 7/29/2017 1:11 PM, John Carlson wrote:
>
>> Are we assuming that can acceptableNodeTypes in the object model will
>> allow for acceptableStatements?   I'd like to see action on this in the
>> object model (put the statements or abstract types for statements into
>> acceptableNodeTypes) so I can continue with autogeneration of the JSON
>> schema.
>>
>> On Jul 20, 2017 1:22 PM, "John Carlson" <yottzumm at gmail.com <mailto:
>> yottzumm at gmail.com>> wrote:
>>     __ __
>>
>>     I believe we need acceptableStatements to restrict acceptable
>> statements for children fields in the X3D Object Model.  If it’s
>> ProtoInstance we have a acceptable statements which are comments. If no
>> children field is found, then we have -commentRoute in JSON schema
>> (temporarily now -childrenStatements). However if there are children,
>> there’s no way to specify which statements are allowed. Previously, I
>> tacked X3DChildNode above the statement inheritance hierarchy in my schema
>> generator, which was wrong.
>>
>>     __ __
>>
>>     Do we need to extend this extra children field to other nodes so they
>> can accept statements? And then just don’t support any acceptableNodeTypes
>> for those children?____
>>
>>     __ __
>>
>>     Can we separate nodes and statements into separate children arrays in
>> X3DJSON?____
>>
>>     __ __
>>
>>     Things to think about.____
>>
>
>
> 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/brutzma
> n
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20170729/9fd256bf/attachment-0001.html>


More information about the x3d-public mailing list