[x3d-public] Prototype Expander, Question on design of instance expansions

Thu Jul 7 10:43:34 PDT 2016

John, Roy and I discussed the design of prototype expander today on weekly JSON teleconference.

We paid particular attention to the design pattern below, steps 1-3.

Improvement:  Switch whichChoice="-1" is good to ensure extra nodes remain hidden, but then inserting an intermediate child Group that collects all of the extra non-rendering nodes.

We discussed the example scene MaterialModulator.x3d and illustrating the prototype expander design pattern by refining the expected result, new scene MaterialModulatorPrototypeExpanded.x3d

Today's version attached, in X3D source and also pretty-print to make inspection easy.  Online at

	http://X3dGraphics.com/examples/X3dForWebAuthors/Chapter14-Prototypes/#MaterialModulatorPrototypeExpanded

TODO:
* Create corresponding web page describing Prototype Expander design.
* Create stylesheet converter matching this Prototype Expander design pattern.
* Add external ROUTEs to original example as a further test case for Prototype Expander design.

Of course any player can implement prototypes any way they like (and many already have).  No specification changes or additions are foreseen.  We are happy to figure out a thorough design for 2 more implementations that can provide open-source solutions for parsing and preprocessing prototypes.  Work will likely continue after the upcoming Web3D and SIGGRAPH conferences.

Having serious fun with X3D prototypes!  8)

On 7/2/2016 2:09 PM, Don Brutzman wrote:
> Thank you for bringing up this really important issue John.  I think you have uncovered an excellent implementation challenge.
>
> On 7/1/2016 1:36 PM, John Carlson wrote:
>>
>> I have an -material object in JSON which accepts a ProtoInstance. The ProtoBody has -children, the first of which is Material.  There are more nodes including Script nodes.  The question is, how do I create prototype expanded JSON?
>
> Specifically, since the first node of a ProtoBody is what gets rendered, and the following top-level sibling nodes are active but non-rendered, how do they get handled when expanding the prototype?
>
> X3D Tooltips: ProtoBody
> http://www.web3d.org/x3d/content/X3dTooltips.html#ProtoBody
> ===========================================================
> ProtoBody collects ProtoDeclare body nodes.
> Warning: only the first top-level node and its children are rendered, subsequent nodes (such as Scripts and ROUTEs) are active but are not drawn.
> ===========================================================
>
> 4.4.4.3 PROTO definition semantics
> http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/concepts.html#PROTOdefinitionsemantics
> ===========================================================
> A prototype definition consists of one or more nodes, nested PROTO statements, and ROUTE statements. The first node type determines how instantiations of the prototype can be used in an X3D file. An instantiation is created by filling in the parameters of the prototype declaration and inserting copies of the first node (and its scene graph) wherever the prototype instantiation occurs.
>
> EXAMPLE  If the first node in the prototype definition is a Material node, instantiations of the prototype can be used wherever a Material node can be used. Any other nodes and accompanying scene graphs are not part of the transformation hierarchy, but may be referenced by ROUTE statements or Script nodes in the prototype definition.
> ===========================================================
>
> Important to note:  this challenge is not about the X3D JSON encoding per se.  We are able to produce a 1::1 correspondence between .json and .x3d .x3dv etc.
>
> This implementation challenge is about how to implement the Prototype Expander so that ProtoInstance nodes might get replaced with cookie-cutter instantiations of a prototype declaration template.
>
> This question was likely answered in similar but slightly different ways by each X3D player that has implemented Prototypes.  So there should be some good example implementations visible in Xj3D, freewrl, view3dscene, Cobweb ("Cobweb supports custom shaders, clip planes, reflection mapping, script nodes, prototyping capabilities"), etc.
>
> Given their excellent implementation of prototypes in InstantReality, and their design of X3DOM, it would be a good thing if Fraunhofer might release their IR prototype implementation as an open-source fragment to facilitate these kinds of efforts.
>
>> Included are the original JSON and the JSON with the current expansion.  I can’t just take the first node, because then the script would be left off.  Ideas?  What most faithfully represents the original?  What about other cases (I have more)?
>
> I saved your example conversions as MaterialModulatorPrototypeInstance.json and MaterialModulatorPrototypeExpanded.json, respectively.  Re-attached.
>
>> It would be really nice if JSON schema handled arrays for -material, -geometry and -appearance at least, so we can add the non-rendered nodes without invalidating the file.
>>
>> How would VRML handle this?
>
> For the moment I think that we are mostly in implementation space, not language design.  Let's first work through with what we have already.  After that, gap analysis can tell us if additional specification support is needed.
>
> So at present, a better question for integrating prototype capabilities in in X3DOM might be "How can a prototype expander be used as a preprocessor to generate internal X3DOM javascript source emulating the scene graph?"  That is certainly an appropriate goal for the x3dom-developer community (cc:ed).
>
> Meanwhile, let's press ahead separately with also trying to produce a general-case solution with your expander.  Since the solution must work for any of the X3D encodings, likely no encoding-specific workarounds are needed.
>
> First-pass design follows.  All review & improvement welcome:
>
> 1. Goal: convert valid X3D with ProtoInstance nodes to corresponding valid X3D without ProtoInstance nodes, substituting nodes found in ProtoDeclare (possibly via ExternProtoDeclare).
>
> 2. Requirements:
> a. Legal scene graph results which can pass all X3D validity tests.
> b. Maintain all ROUTE and IS/connect pathways for events correctly.  May require some renaming.
> c. Repeatable examples (MaterialModulator is a good place to start).
>
> 3. Approach:
> a. Substitute the first node (along with contained scene subgraph) of Protobody as replacement for ProtoInstance.
> b. Handle follow-on nodes by also inserting them, in a scene-valid manner.
> b.1. When the first node in the ProtoBody is an X3DChildNode, any follow-on nodes can be wrapped in a Switch (with whichChoice="-1") to ensure they are non-rendering.
> b.2. When first node in the ProtoBody is not an X3DChildNode, any follow-on nodes are still wrapped in a Switch which follows at the closest subsequent point in the scene graph that can accept children nodes.
> c. External routing: field names within ROUTEs are modified, and DEF names adjusted if needed, and IS/connect statements are removed, to preserve event-passing semantics.
> d. External routing: field names within ROUTEs are modified, and DEF names adjusted if needed, to preserve event-passing semantics.
> e. Naming convention needed for steps c and d, which are quite similar.  Needs to be able to handle more than one copy of a ProtoInstance getting expanded.
> f. Assign initial values to field definitions where appropriate.
> g.Nice to have: possibility that an expanded ProtoInstance block of nodes might be reconverted later into the original ProtoInstance, perhaps simply by containing the original as a comment.
>
> Looking at your MaterialModulatorPrototypeExpanded.json above, it appears that your approach accomplishes most of these steps already.  Only significant difference would be step b.2, handling incompatible follow-on nodes within a Shape.
>
> Next attachment is original scene with ProtoDeclare and ProtoInstance: MaterialModulator.x3d
>
> Attached please find an attempt MaterialModulatorExpanded that follows a quite similar pattern to yours.  Only intended difference is to put the hiding Switch following the Shape node - thus it includes restructuring for step b.2.  This expansion works in BS Contact, Instant Reality, FreeWrl, Octaga, Cobweb.
>
> There is still a bit more trickiness to sort out here with the renaming, but it looks like a general pattern is possible.
>
> Am also optimistic that we might be able to create an XSLT stylesheet that accomplishes the identical task of converting ProtoInstance nodes into expanded nodes.
>
> ... so, seems pretty promising.  A few more rocks and shoals to navigate but appears that we can get there from here.  What do you think?
>
> all the best, Don

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/20160707/b05eedcc/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: MaterialModulatorPrototypeExpanded.x3d
Type: model/x3d+xml
Size: 4620 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20160707/b05eedcc/attachment-0001.x3d>