[x3d-public] Statement permitted placements

John Carlson yottzumm at gmail.com
Sun Jul 16 16:22:08 PDT 2017 

Roy,

I know little of SAI, and know more of X3DJSAIL.  X3DJSAIL jsail uses addChild().  I think X3DJSAIL sai (SAI) uses addChildren().  See attached ROUTEObject code in X3DJSAIL (Java) for example of jsail package. Thus Group and Transform have addChildren() in SAI (see org.web3d.x3d.sai package in X3DJSAIL). The difference between addChild and addChildren is the return type I believe.


Hope this helps!

John

Sent from Mail for Windows 10

From: Roy Walmsley
Sent: Sunday, July 16, 2017 9:04 AM
To: 'X3D Graphics public mailing list'
Subject: Re: [x3d-public] Statement permitted placements

Hi,

I know that there have been postings where the subject line was amended to "IMPORT/EXPORT Use [was: Statement permitted placements]". However, I want to continue with further observations on the more general theme.

I was thinking about the next stage of the C++/C# language binding work, when I realised that I  needed to look at the SAI, as defined in ISO/IEC 19775-2 V3.3, and see how that aligned with my general findings on statement placing. So, let's take a look.

Reviewing the general layout of ISO/IEC 19775-2 V3.3 we see that the only clause with sufficient detail to pursue this topic is clause 6 Services reference.
Reference: http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.html

What services are relevant? Let's concentrate on those services that would allow us to insert one of these statements (ROUTE, IMPORT, EXPORT, PROTODECLARE, EXTERNPROTODECLARE) into the scene graph. We have the following, and only the following:

1) 6.4.10 namedNodeHandling, see http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.html#NamedNodeHandling
2) 6.4.12 protoDeclarationHandling, see http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.html#ProtoDeclarationHandling
3) 6.4.14 externprotoDeclarationHandling, see http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.html#ExternProtoDeclarationHandling
4) 6.4.17 dynamicRouteHandling, see http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.html#DynamicRouteHandling

Each of these services is an execution context services.

What is an execution context? This is detailed in clause 4.4.10 Execution context.
Reference: http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/concepts.html#ExecutionContext

The first part of the descriptive text reads “An execution context is the run-time semantic equivalent to a name scope described in 4.4.7 Run-time name scope in ISO/IEC 19775-1. It provides a way of containing and firewalling internal interaction code in such a manner as to represent the same restrictions that a name space provides in the file format.”.

Does this permit us to add any of these statements at any location in the scene or name scope?

We find that the text gives no indication of where these are added. Furthermore, it does not provide any way to add these as “children” of a specific node.

So we need to consider not only the abstract standard 19775-1 and the encodings in 19776, but also the SAI in 19775-2, propagating down to the language bindings in 19777.

It might be useful to look at an example here, and try to use the SAI from one of the language bindings to build up a scene node by node programmatically, and create an instance of a scene in memory that has these statements scattered about. A fairly straightforward example  using ROUTEs is the Origami Cranes example, which can be found in the X3D Example Archives, X3D for Advanced Modeling, Animation section.
Reference: http://x3dgraphics.com/examples/X3dForAdvancedModeling/Animation/OrigamiCranesIndex.html

In this example we have ROUTEs as children of a Group node.

How might we proceed to create this example. Here is one attempt at a solution. This solution is not intended to be efficient, merely to illustrate a step by step approach.

A) createScene, to create an empty scene
B) … to add any header info, and META statements, for example
C) rootNodeHandling, to add the first root node, Background
D) rootNodeHandling, to add the second root node, NavigationInfo
E) rootNodeHandling, to add the third root node, PointLight
F) rootNodeHandling, to add the fourth root node, PointLight
G) rootNodeHandling, to add the fifth root node, Group
H) getField, to get the “children” field of the Group node
I) setValue, to add the first child to the children field of the Group node, Viewpoint
J) setValue, to add the second child to the children field of the Group node, TimeSensor
K) setValue, to add the third child to the children field of the Group node, PositionInterpolator
L) ????, to add the “fourth child” to the children field of the Group node, ROUTE

Here we have a difficulty. Set “setValue” service may be an SAINode value. There is an SAI type of SAIRoute, described in 5.2.29.
Reference: http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/dataRef.html#SAIRoute

The text quite clearly states “A ROUTE is not a node in the scene graph …”. So we can’t use setValue again.

The only service available to us is 6.4.17 dynamicRouteHandling. We pass the executionContext (which in this example is the scene), ROUTE properties, and “AddRoute” action. Where will it go? How do we specify we want it to be added to the Group node as the next child?

All the best,

Roy


-----Original Message-----
From: Don Brutzman [mailto:brutzman at nps.edu] 
Sent: 14 July 2017 18:19
To: Roy Walmsley <roy.walmsley at ntlworld.com>; 'X3D Graphics public mailing list' <x3d-public at web3d.org>
Subject: Re: [x3d-public] Statement permitted placements

Great analysis, thanks for performing and sharing Roy.

Based on their functionality, we might also consider placing
-  IMPORT/AS within the corresponding Inline, and
- EXPORT at the top level of a scene

However, we should be wary about that.  Since scenes can be constructed programmatically, a tool might append an IMPORT or EXPORT at run time at other places in the scene graph.

We probably should also be deliberate whether to allow statements like (EXTERN)PROTODECLARE, ROUTE, IMPORT/EXPORT inside of Appearance and other non-children kinds of locations.  Doesn't necessarily have to be there, but let's be consistent across encodings.

On 7/14/2017 8:45 AM, Roy Walmsley wrote:
> Hi,
> 
> We were recently discussing the permitted placement of the following statements:
> 
> ROUTE
> 
> IMPORT
> 
> EXPORT
> 
> PROTODECLARE
> 
> EXTERNPROTODECLARE
> 
> The original discussion centred on the draft JSON encoding. However, I have now been looking at this in the XML and Classic VRML encodings.
> 
> Let’s take a look at what is permitted by these encodings, and also compare what the abstract standard says.
> 
> Let’s take the Classic VRML encoding first, i.e. ISO/IEC 19776-2 V3.3. The most comprehensive description is the grammar in Annex A.2.
> 
> Reference: 
> http://www.web3d.org/documents/specifications/19776-2/V3.3/Part02/gram
> mar.html#General
> 
> A non-terminal “statement” is defined as:
> 
> /nodeStatement/|
> /importStatement/ |
> /exportStatement /|
> 
> /protoStatement/|
> 
> /routeStatement/;
> 
> The non-terminal “nodeStatement” can be followed down to “node”, “nodeBody”, and “nodeBodyElement”. This last non-terminal has the definition:
> 
> /initializeOnlyId fieldValue/|
> /inputOutputId fieldValue |/
> 
> /initializeOnlyId /*IS*/initializeOnlyId/|
> 
> /inputOnlyId /*IS*/inputOnlyId/|
> 
> /outputOnlyId /*IS*/outputOnlyId/|
> 
> /inputOutputId /*IS*/inputOutputId/|
> 
> /routeStatement/|
> 
> /protoStatement/;
> 
> Notice the lack or importStatement and exportStatement.
> 
> This has been pointed out previously. In fact, Mantis issue 698 covers this very point.
> 
> Reference: http://www.web3d.org/member-only/mantis/view.php?id=698
> 
> Now let’s take the XML encoding, ISO/IEC 19776-1 V3.3. Let’s look at an example node, say Group, defined at 6.2.81.
> 
> Reference: 
> http://www.web3d.org/documents/specifications/19776-1/V3.3/Part01/Enco
> dingOfNodes.html#Group
> 
> Notice that this Node has a content model denoted by 
> “ChildContentModel”. The description of this is given in 6.3.3 
> ChildContentModel
> 
> Reference: 
> http://www.web3d.org/documents/specifications/19776-1/V3.3/Part01/Enco
> dingOfNodes.html#ChildContentModel
> 
> The text states: “ChildContentModel is the child-node content model corresponding to X3DChildNode, combining all profiles. ChildContentModel can contain most nodes, other Grouping nodes, Prototype declarations and ProtoInstances in any order and any combination.”. Note that there is no mention of ROUTES, or IMPORT/EXPORT.
> 
> We should also note the text in 6.3.5 ChildContentModelSceneGraphStructure.
> 
> Reference: 
> http://www.web3d.org/documents/specifications/19776-1/V3.3/Part01/Enco
> dingOfNodes.html#ChildContentModelSceneGraphStructure
> 
> This states “Child-node content model corresponding to SceneGraphStructure elements, which are not specific X3D nodes. These are ProtoDeclare, ExternProtoDeclare, IMPORT, EXPORT or ROUTE statements.”. This content model covers all the statements of interest. Where is it used? This content model is not listed in any  node definition. In fact, it is not mentioned anywhere else in the standard.
> 
> Turning to the XML schema V3.3 now.
> 
> Reference: http://www.web3d.org/specifications/x3d-3.3.xsd
> 
> Looking at the “Group” node, we see that the content model is derived from X3DGroupingNode. Looking at the definition for X3DGroupingNode, the following definition can be extracted:
> 
> <xs:complexContent>
> 
> <xs:extensionbase="X3DChildNode">
> 
> <xs:sequenceminOccurs="0"maxOccurs="unbounded">
> 
> <xs:annotation>
> 
> <xs:documentation>children</xs:documentation>
> 
> </xs:annotation>
> 
> <xs:groupref="ChildContentModel"minOccurs="0"maxOccurs="unbounded"/>
> 
> <xs:groupref="ChildContentModelSceneGraphStructure"minOccurs="0"maxOcc
> urs="unbounded"/>
> 
> </xs:sequence>
> 
> <xs:attributename="bboxCenter"type="SFVec3f"default="0 0 0"/>
> 
> <xs:attributename="bboxSize"type="boundingBoxSizeType"default="-1 -1 
> -1"/>
> 
> </xs:extension>
> 
> </xs:complexContent>
> 
> So any node derived from X3DGroupingNode will be passed as valid of it has any of the statements we are considering. Where else if this content model used? The XML schema has six instances of this term, as follows:
> 
>  1. In the definition of X3DGroupingNode  2. In the definition of the 
> content model group ChildContentModelSceneGraphStructure
>  3. In the definition of the content model group 
> GroupingNodeChildContentModel  4. In the definition of the content 
> model group SceneGraphFragmentWithPrototypeDeclarationsContentModel
>  5. In the definition of the StaticGroup node  6. In the definition of 
> the GeoLOD node
> 
> The GroupingNodeChildContentModel is only used in the definition of the Scene element.
> 
> So, we see that in the XML schema these statements are only permitted in grouping nodes.
> 
> Finally, let us turn to the abstract standard ISO/IEC 19775-1 V3.3. What does it tell us about the placements of statements. There is no general text covering all the statements, so we need to look at each one in turn. We will start with ROUTEs and Prototypes, 7.2.5.7 ROUTE statement, 7.2.5.8 PROTO statement, and 7.2.5.9 EXTERNPROTO statement.
> 
> Reference: 
> http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/comp
> onents/core.html#ROUTEStatement
> 
> Reference: 
> http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/comp
> onents/core.html#PROTOStatement
> 
> Reference: 
> http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/comp
> onents/core.html#EXTERNPROTOStatement
> 
> All three of these clauses have the words “xxxxxx statements may appear anywhere in the file”
> 
> Now look at 9.2.5 IMPORT statement, and 9.2.6 EXPORT statement.
> 
> Reference: 
> http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/comp
> onents/networking.html#IMPORTStatement
> 
> Reference: 
> http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/comp
> onents/networking.html#EXPORTStatement
> 
> Neither of these clauses has any comment on the placement within the file.
> 
> So, what do we conclude?
> 
>  1. ROUTEs and prototypes are permitted anywhere.
>  2. IMPORT and EXPORT need a statement on placement in the abstract 
> standard
> 
> If we assume that A) is correct, then:
> 
>  3. In the XML encoding the content models need to be amended to 
> permit placement of these statements anywhere  4. In the Classic VRML 
> encoding the grammar needs to be amended
> 
> Of course, we might want to restrict the usage, in which case these needs proper definition in the abstract standard, and propagation to the encodings.
> 
> All the best,
> 
> Roy
> 
> 
> 
> _______________________________________________
> x3d-public mailing list
> x3d-public at web3d.org
> http://web3d.org/mailman/listinfo/x3d-public_web3d.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 http://faculty.nps.edu/brutzman

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20170716/85cff8ee/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: X3dHeaderPrototypeSyntaxExamples.java
Type: application/octet-stream
Size: 14255 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20170716/85cff8ee/attachment-0001.obj>

More information about the x3d-public mailing list