[x3d-public] @isOver not in JSON schema 3.3 for TouchSensor, but in object Model; correct. Grand tour of OM4X3D.
Don Brutzman
brutzman at nps.edu
Sun May 14 08:28:50 PDT 2017
[summary: how to trace consistency among X3D references for a given X3D node and field... all the way through Object Model for X3D (OM4X3D) autogeneration.]
On 5/13/2017 9:12 PM, John Carlson wrote:
> @isOver as a field of TouchSensor (but may be in a super class), is in ObjectModel, but not in JSON schema 3.3
1. *Good observation.* I think that is correct. Let's trace it out and cross-check everything.
Continuing to follow this trail illustrates how Object Model for X3D (OM4X3D) gets assembled.
For the following plain-text sections, ==== surrounds content quote blocks.
2. *X3D Abstract Specification*
20.4.4 TouchSensor
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#TouchSensor
==================================
TouchSensor : X3DTouchSensorNode {
SFString [in,out] description ""
SFBool [in,out] enabled TRUE
SFNode [in,out] metadata NULL [X3DMetadataObject]
SFVec3f [out] hitNormal_changed
SFVec3f [out] hitPoint_changed
SFVec2f [out] hitTexCoord_changed
SFBool [out] isActive
SFBool [out] isOver
SFTime [out] touchTime
}
==================================
The X3D Abstract Specification is authoritative and confirms accessType, since [out] means outputOnly. Thus isOver is a transient event that can only occur at run time.
3. *JSON Schema*
JSON Schema: TouchSensor
http://www.web3d.org/specifications/X3dJsonSchemaDocumentation3.3/x3d-3.3-JSONSchema_TouchSensor.html
Since isOver event has accessType outputOnly, I would not expect a TouchSensor node to include an isOver event in a file encoding. Sure enough, that is the case.
The preceding link is easily found by going to the X3D Tooltips, which include cross-links to the various types of documentation available.
4. *X3D Tooltips* provide summary descriptions and authoring hints for each X3D node (XML element) and field (XML attribute) found in the X3D Specification.
X3D Tooltips: TouchSensor
http://www.web3d.org/x3d/tooltips/X3dTooltips.html#TouchSensor
Looking at isOver field which appears under TouchSensor, and then following the _accessType outputOnly_ link:
http://www.web3d.org/x3d/tooltips/X3dTooltips.html#accessType
===========================================
accessType Definitions
accessType determines whether a field corresponds to event input, event output, or persistent state information. Events are strictly typed values with a corresponding timestamp. ROUTE connections must match accessType between source field and target field.
* initializeOnly: can be initialized, but cannot send or receive events. This is usually the case for fields that are considered too computationally expensive to change at run time.
* inputOutput: can be initialized, and can also send or receive events.
* inputOnly: cannot be initialized or included in a scene file, but can receive input event values via a ROUTE.
* outputOnly: cannot be initialized or included in a scene file, but can send output event values via a ROUTE.
X3D accessType design keeps 3D graphics rendering fast and interactive, also helping to keep X3D players small and lightweight.
===========================================
Next:
5. *X3D validation using XML DTD and XML Schema.* When we look at X3D DTD and X3D XML Schema documentation, similar file-validation constructs are found.
Generated DTD Grammar Documentation for: x3d-3.3 - TouchSensor
http://www.web3d.org/specifications/X3dDoctypeDocumentation3.3.html#TouchSensor
===========================================
Declared Attributes
#IMPLIED CDATA description
#DEFAULT ENUMERATION ( true | false ) enabled = true
#DEFAULT NMTOKEN containerField = children
#IMPLIED NMTOKENS class
#IMPLIED ID DEF
#IMPLIED IDREF USE
===========================================
Note that isOver is not present here. Thus if it appears in file content, something like <TouchSensor isOver='false'/> will fail validation.
Similarly for X3D XML Schema validation
X3D XML Schema x3d-3.3.xsd documentation: TouchSensor
http://www.web3d.org/specifications/X3dSchemaDocumentation3.3/x3d-3.3_TouchSensor.html
once again shows description and enabled fields, but no isOver field.
6. *X3D XML Schema annotations.* So how does isOver find its way into OM4X3D? Answer: information regarding inputOnly/outputOnly fields is put into each node's annotation/appinfo section in the X3D XML Schema. There it is similar to a comment - actually structured metadata - that can be read and converted when creating OM4X3D. Continuing the journey:
X3D XML Schema file
http://www.web3d.org/specifications/x3d-3.3.xsd
===========================================
<xs:element name="TouchSensor">
<xs:annotation>
<xs:appinfo>
<xs:attribute name="hitNormal_changed" type="SFVec3f" fixed="outputOnlyField"/>
<xs:attribute name="hitPoint_changed" type="SFVec3f" fixed="outputOnlyField"/>
<xs:attribute name="hitTexCoord_changed" type="SFVec2f" fixed="outputOnlyField"/>
<xs:attribute name="componentName" type="xs:NMTOKEN" fixed="PointingDeviceSensor"/>
<xs:attribute name="componentLevel" type="xs:positiveInteger" fixed="1"/>
</xs:appinfo>
<xs:documentation source="http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#TouchSensor"/>
</xs:annotation>
<xs:complexType>
<xs:complexContent>
<xs:extension base="X3DTouchSensorNode">
<xs:attribute name="containerField" type="xs:NMTOKEN" default="children"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
===========================================
Hmm, now what? Well, in addition to decorating each node in the X3D XML Schema with inputOnly/outputOnly fields, we have to deal with inheritance. As you noted, superclass information.
7. *Object oriented relationships.* O-O constructs appear throughout X3D Abstract Specification, X3D XML Schema, and XML Schema guidance.
Inspection of the preceding XML shows how the XML Schema takes advantage of object-oriented inheritance, matching the node types found in the X3D Abstract Specification.
For example: as we saw far above, TouchSensor implements the X3DTouchSensorNode interface. It looks like the following:
20.3.3 X3DTouchSensorNode
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#X3DTouchSensorNode
===========================================
X3DTouchSensorNode : X3DPointingDeviceSensorNode {
SFString [in,out] description ""
SFBool [in,out] enabled TRUE
SFNode [in,out] metadata NULL [X3DMetadataObject]
SFBool [out] isActive
SFBool [out] isOver
SFTime [out] touchTime
}
===========================================
Similarly, the X3D XML Schema includes this abstract node type:
<xs:complexType name="X3DTouchSensorNode" abstract="true">
<xs:annotation>
<xs:appinfo>
<xs:attribute name="touchTime" type="SFTime" fixed="outputOnlyField"/>
<xs:attribute name="componentName" type="xs:NMTOKEN" fixed="PointingDeviceSensor"/>
<xs:attribute name="componentLevel" type="xs:positiveInteger" fixed="1"/>
Base type for all touch-style pointing device sensors.
</xs:appinfo>
<xs:documentation source="http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#X3DTouchSensorNode"/>
</xs:annotation>
<xs:complexContent>
<xs:extension base="X3DPointingDeviceSensorNode"/>
</xs:complexContent>
</xs:complexType>
All well and good. But object-oriented relationships can be difficult to work with if you want to process that information yourself. There are a lot of sophisticated constructs in XML Schema that we usually don't have to worry about. Multiple authoritative references for XML Schema validation of XML content can be found at:
W3C XML Schema
https://www.w3.org/XML/Schema
Assessment: XML Schema works great for XML validation of scenes. It also works well for formal codification of additional non-XML information in the X3D Abstract Specification, such as X3D accessType values for each field. However the object-oriented inheritance within that schema .xsd XML file it is pretty difficult to use if you want to take advantage of the information for other purposes.
So we kept going...
8. *Object Model for X3D (OM4X3D)* construction and result.
We want a single XML file that codifies all the X3D Abstract Specification information, but lists all information for each node in one place for easier processing.
So, we have produced an XSLT stylesheet that reads the X3D XML Schema (itself in XML) to create the OM4X3D file.
BuildObjectModelXmlFile.xslt
http://www.web3d.org/x3d/stylesheets/BuildObjectModelXmlFile.xslt
https://sourceforge.net/p/x3d/code/HEAD/tree/www.web3d.org/x3d/stylesheets/BuildObjectModelXmlFile.xslt
As with all other resources here, each asset is placed in version control for explicit/easy/shared editing.
The resulting OM4X3D file can be found at
X3DObjectModel-3.3.xml
http://www.web3d.org/specifications/X3DObjectModel-3.3.xml
https://sourceforge.net/p/x3d/code/HEAD/tree/www.web3d.org/specifications/X3DObjectModel-3.3.xml
And here is the TouchSensor entry, in all its complete and verbose glory:
<ConcreteNode name="TouchSensor">
<InterfaceDefinition specificationUrl="http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#TouchSensor">
<componentInfo name="PointingDeviceSensor" level="1"/>
<Inheritance baseType="X3DTouchSensorNode"/>
<field type="SFString"
accessType="inputOutput"
name="description"
inheritedFrom="X3DPointingDeviceSensorNode"/>
<field type="SFBool"
accessType="inputOutput"
name="enabled"
default="true"
inheritedFrom="X3DSensorNode"/>
<field type="SFVec3f" accessType="outputOnly" name="hitNormal_changed"/>
<field type="SFVec3f" accessType="outputOnly" name="hitPoint_changed"/>
<field type="SFVec2f" accessType="outputOnly" name="hitTexCoord_changed"/>
<field type="SFBool"
accessType="outputOnly"
name="isActive"
inheritedFrom="X3DSensorNode"/>
<field type="SFBool"
accessType="outputOnly"
name="isOver"
inheritedFrom="X3DPointingDeviceSensorNode"/>
<field type="SFNode"
accessType="inputOutput"
name="metadata"
default="NULL"
acceptableNodeTypes="X3DMetadataObject"
inheritedFrom="X3DNode"/>
<field type="SFTime"
accessType="outputOnly"
name="touchTime"
inheritedFrom="X3DTouchSensorNode"/>
<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"/>
</ContentModel>
</InterfaceDefinition>
</ConcreteNode>
Note that all information appears to be present regarding TouchSensor.
9. *Applying OM4X3D to build X3DJSAIL.* To verify that all of the information in here is indeed correct and complete is beyond the ability of us mere mortals. However tools can help.
The OM4X3D is used, in turn, to autogenerate a complete API for X3D. Subsequent compilation and unit-test verification of thousands of X3D example scenes really puts it through the wringer to confirm correctness and completeness.
X3D Java Scene Access Interface Library (X3DJSAIL)
http://www.web3d.org/specifications/java/X3DJSAIL.html
How did TouchSensor and come out? Two ways. First the original X3D SAI interfaces are generated, then compatible concrete classes are generated.
abstracts:
org.web3d.x3d.sai.PointingDeviceSensor
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/sai/PointingDeviceSensor/X3DTouchSensorNode.html
org.web3d.x3d.sai.PointingDeviceSensor.TouchSensor
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/sai/PointingDeviceSensor/TouchSensor.html
concrete:
org.web3d.x3d.jsail.PointingDeviceSensor.TouchSensorObject
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/PointingDeviceSensor/TouchSensorObject.html
TouchSensorObject isOver
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/PointingDeviceSensor/TouchSensorObject.html#method.summary
http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/PointingDeviceSensor/TouchSensorObject.html#getIsOver--
"Provide boolean value from outputOnly SFBool field named isOver."
and in a pair of loop-de-loops, the original X3D Schema descriptive annotations and corresponding X3D Tooltip are each extracted and inserted into the Javadoc documentation. Excerpt:
"Tooltip: Hover over geometry by aiming the mouse (or pointing device) to generate isOver events. Sensor sends output event isOver=true event when pointing device moves over sensor's geometry, and later sends output event isOver=false event when pointing device moves off."
So it looks like a huge round trip is completed and cross-verifying itself. Win win win win win win.
10. *OM4X3D milestones.* Lots of excellent milestones are about to tick off, further enabling X3D v4 progress.
We are now checking edge conditions and corner cases, as well as correspondingly autogenerated JSON-encoded scenes, to verify that indeed all of this is hanging together satisfactorily.
I am optimistic that we can collaboratively agree on the following this month:
a. OM4X3D and X3D XML Schema correctly capture X3D Abstract Specification relationships.
b. X3D Java SAI implementation by X3DJSAIL beta testing is satisfactorily complete, and codebase is ready for initial release v1.0.
c. X3D JSON encoding design is complete and correct, again as verified by extensive unit testing with X3D Example Archives.
This code-tracing message can get slide-ified and serve as part of our upcoming tutorial in a few weeks:
Web3D 2017 Conference, Brisbane Australia, 5-7 June 2017
http://web3d2017.web3d.org/program
"Masterclass 4: Object Model for X3D (OM4X3D) and Scene Access Interface (SAI) for X3D, including JSONLD and X3DJSAIL"
Looking ahead. Given that all of the version-control autogeneration capabilities described here currently (or easily can) work for all versions of X3D versions 3.0 through 3.3, it is a straightforward task to extend every single asset to X3D version 4.
This will greatly accelerate our ability to produce a rigorously grounded X3D v4 specification.
X3D Version 4
http://www.web3d.org/x3d4
Thanks for many many efforts by many many contributors, all coming together in grand style. Special thanks especially to you John and to Roy Walmsley, all this was only possible as a team effort.
All feedback and improvements welcome. Thank you for considering the possibilities. Have fun with OM4X3D! 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 http://faculty.nps.edu/brutzman
More information about the x3d-public
mailing list