[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