[x3d-public] X3D JSON encoding: refactoring, simplifying handling of #comment and #ROUTE

Roy Walmsley roy.walmsley at ntlworld.com
Sun Dec 20 04:13:41 PST 2015


Don,

On looking at your last example of alternative encoding for the earth image scene it seems to me to be inconsistent in its use of a -children field. For example, the Shape node, although you have given it #comments, hasn't got a -children field. Or, perhaps I'm just misunderstanding ...

Then I got to thinking - why call it "-children". Why not "-comment"? There is no comment field in any node, so no conflict. But then I see that in an earlier example you are adding all child content into a -children field ...

So, inconclusive ... But I would like to see the last example fully generated in your alternative format.

Regards,

Roy

-----Original Message-----
From: Don Brutzman [mailto:brutzman at nps.edu] 
Sent: 19 December 2015 21:09
To: John Carlson; Roy Walmsley (roy.walmsley at ntlworld.com)
Cc: X3D Graphics public mailing list
Subject: X3D JSON encoding: refactoring, simplifying handling of #comment and #ROUTE

1.  Am thinking about how we might improve the X3D JSON encoding by treating #comment and #ROUTE as objects in an array that is contained by parent.  This would reduce problems with the partial resorting that currently occurs.

Doing it as part of "-children" isn't particularly difficult; the trick will be doing it cleanly inside of nodes that contain other non-children nodes, e.g. Shape, Appearance, singleton nodes, etc.  The path to success may lead through always treating any child content as part of an array.

Continuing this line of inquiry: we could put them inside of a "-children" JSON field consistently throughout the scene graph. Use cases:
a. Within "-children":[array] of Scene (which is already produced) b. Within "-children":[array] of grouping nodes (which is already produced) c. Within "-children":[array] of any node, even when they don't have a /children/ field

2.  So let's look at an example, in detail.

Example scene created is named HelloWorldCommented.x3d with XML source, current (original) JSON encoding, and alternative JSON encoding all attached.

First excerpt follows, with the focus just for regular children (use cases 1.a and 1.b from above).

=========================================
*XML encoding*
=========================================
<X3D>
   <Scene>
     <!-- Example scene to illustrate comments interspersed among X3D nodes and fields (XML elements and attributes) -->
     <!-- WorldInfo begin -->
     <WorldInfo title='Hello world!'/>
     <!-- WorldInfo complete, Group begin -->
     <Group>
       <!-- Viewpoint begin -->
       <Viewpoint DEF='ViewUpClose' centerOfRotation='0 -1 0' description='Hello world!' position='0 -1 7'/>
       <!-- Viewpoint complete, Transform begin -->
       <Transform/>
       <!-- Transform complete, Transform begin -->
       <Transform/>
       <!-- Transform complete -->
     </Group>
     <!-- Group complete -->
   </Scene>
</X3D>
=========================================

Now two corresponding JSON examples using #comment attached.  (Net effect with #ROUTE would be the same.)

Notice how comments are pulled up together in the current encoding (which partially re-sorts and thus changes the original order), but then comments are interspersed as expected in the second encoding:
=========================================
*current JSON encoding*
=========================================
{ "X3D": {
     "Scene": {
         "#comment":[
           "Example scene to illustrate comments interspersed among X3D nodes and fields (XML elements and attributes)",
           "WorldInfo begin",
           "WorldInfo complete, Group begin",
           "Group complete"
         ],
         "-children":[
           { "WorldInfo":
             {
               "@title":"Hello world!"
             }
           },
           { "Group":
             {
               "#comment":[
                 "Viewpoint begin",
                 "Viewpoint complete, Transform begin",
                 "Transform complete, Transform begin",
                 "Transform complete"
               ],
               "-children":[
                 { "Viewpoint": { }
                 },
                 { "Transform": { }
                 },
                 { "Transform": { }
                 }
               ]
             }
           }
         ]
     }
   }
}
=========================================
*alternative JSON encoding*
=========================================
{ "X3D": {
     "Scene": {
         "-children":[
           { "#comment":"Example scene to illustrate comments interspersed among X3D nodes and fields (XML elements and attributes)"},
           { "#comment":"WorldInfo begin"},
           { "WorldInfo":
             {
               "@title":"Hello world!"
             }
           },
           { "#comment":"WorldInfo complete, Group begin"},
           { "Group":
             {
               "-children":[
                 { "#comment":"Viewpoint begin"},
                 { "Viewpoint": { }
                 },
                 { "#comment":"Viewpoint complete, Transform begin"},
                 { "Transform": { }
                 },
                 { "#comment":"Transform complete, Transform begin"},
                 { "Transform": { }
                 },
                 { "#comment":"Transform complete"}
               ]
             }
           },
           { "#comment":"Group complete"}
         ]
     }
   }
}
=========================================

2.  So far so good.  Now let's look at how this approach ripples through a Shape node, as an example of use case 1.c above.

=========================================
*XML encoding*
=========================================
<!-- Shape begin -->
<Shape>
   <!-- Text begin -->
   <Text DEF='TextMessage' string='"Hello" "world!"'>
     <!-- FontStyle begin -->
     <FontStyle justify='"MIDDLE" "MIDDLE"'/>
     <!-- FontStyle complete -->
   </Text>
   <!-- Text complete, Appearance begin -->
   <Appearance>
     <!-- Material begin -->
     <Material USE='MaterialLightBlue'/>
     <!-- Material complete -->
   </Appearance>
   <!-- Material complete -->
</Shape>
<!-- Shape complete -->
=========================================

Once again the current/original X3D JSON encoding partially re-sorts the comments:
=========================================
*current JSON encoding*
=========================================
"#comment":[
"Shape begin",
"Shape complete"
],
"-children":[
   { "Shape":
     {
       "#comment":[
         "Text begin",
         "Text complete, Appearance begin",
         "Material complete"
       ],
       "-geometry":[
         { "Text":
           {
             "@DEF":"TextMessage",
             "@string":["Hello","world!"],
             "#comment":[
               "FontStyle begin",
               "FontStyle complete"
             ],
             "-fontStyle":[
               { "FontStyle":
                 {
                   "@justify":["MIDDLE","MIDDLE"]
                 }
               }
             ]
           }
         }
       ],
       "-appearance":[
         { "Appearance":
           {
             "#comment":[
               "Material begin",
               "Material complete"
             ],
             "-material":[
               { "Material":
                 {
                   "@USE":"MaterialLightBlue"
                 }
               }
             ]
           }
         }
       ]
     }
   }
]
=========================================

And once again the alternative intersperses the comments as part of a "-children" JSON key.   Not so very different.

Notable is that Shape and Appearance do not have /children/ fields, but they do have child ("-children") comments.  Thus scene graph structure is better (though not perfectly) preserved.

Some re-sorting of comments prior to peer nodes still appears to be unavoidable, but it is reduced overall.

The pattern for encoding comments (and ROUTEs) is fully consistent, so parsing should still be straightforward.
=========================================
*alternative JSON encoding*
=========================================
"-children":[
   { "#comment":"Shape begin"},
   { "Shape":
     {
       "#comment":[
         "Sphere begin",
         "Sphere complete, Appearance begin",
         "Appearance complete"
       ],
       "-geometry":[
         { "Sphere":
           {
           }
         }
       ],
       "-appearance":[
         { "Appearance":
           {
             "-children":[
              { "#comment":"Viewpoint begin"},
              { "#comment":"Material begin"},
              { "#comment":"Material complete, ImageTexture begin"},
              { "#comment":"ImageTexture complete"}
             ],
             "-material":[
               { "Material":
                 {
                   "@DEF":"MaterialLightBlue",
                   "@diffuseColor":[0.1,0.5,1]
                 }
               }
             ],
             "-texture":[
               { "ImageTexture":
                 {
                   "@DEF":"ImageCloudlessEarth",
                   "@url":["earth-topo.png","earth-topo.jpg","earth-topo-small.gif","http://www.web3d.org/x3d/content/examples/Basic/earth-topo.png","http://www.web3d.org/x3d/content/examples/Basic/earth-topo.jpg","http://www.web3d.org/x3d/content/examples/Basic/earth-topo-small.gif"]
                 }
               }
             ]
           }
         }
       ]
     }
   },
   { "#comment":"Shape complete"}
]
=========================================

3.  Analysis and next steps.

I think that this alternative approach further reduces the special-case handling of #comment and #ROUTE which exists in the current/original JSON encoding.

A more consistent JSON encoding simplifies parsing rules and hopefully makes production/consumption easier to accomplish.

Treating #comment and #ROUTE in the same fashion as other nodes, rather than as field keys, also is more consistent with the primary design pattern of the overall X3D JSON encoding.

The alternative-encoding example was manually edited and validated using jslint in X3D-Edit.  If group review indicates that this approach looks superior, I'll work on a refactoring of the X3dToJson.xslt stylesheet and re-build all the examples to support continued in-depth testing, implementation and evaluation.

Thanks in advance for all scrutiny and review.

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