[x3d-public] Statement permitted placements

Sun Jul 16 06:03:03 PDT 2017

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.ht
ml

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.ht
ml#NamedNodeHandling
2.	6.4.12 protoDeclarationHandling, see
http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.ht
ml#ProtoDeclarationHandling
3.	6.4.14 externprotoDeclarationHandling, see
http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.ht
ml#ExternProtoDeclarationHandling
4.	6.4.17 dynamicRouteHandling, see
http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.ht
ml#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.h
tml#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
<http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/reference
s.html#[I19775_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/OrigamiCran
esIndex.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.ht
ml#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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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

>  <mailto:x3d-public at web3d.org> x3d-public at web3d.org

>  <http://web3d.org/mailman/listinfo/x3d-public_web3d.org>
http://web3d.org/mailman/listinfo/x3d-public_web3d.org

> 

all the best, Don

-- 

Don Brutzman  Naval Postgraduate School, Code USW/Br
<mailto:brutzman at nps.edu> 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> http://faculty.nps.edu/brutzman

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20170716/02d50e2a/attachment-0001.html>