[x3d-public] event utility usage, and event tracing techniques

Sat Oct 29 11:25:36 PDT 2016

On 10/29/2016 8:19 AM, Andreas Plesch wrote:
> I updated
>
> https://rawgit.com/andreasplesch/cobweb_dom/proto/tests/interactiveTransformations.xhtml
>
> to show a fade-in/out effect for the rotor handles when hovering over the teapot, and decided to use event utilities rather than scripting.

looks great, works well!  8)

> It was quick to see that TimeTrigger could be used to trigger the fade animation as TouchSensor does not generate a time event for just hovering. It was harder for me to recognize that BooleanFilter would allow for invoking the different interpolators for fading in and fading out.

For anyone looking to learn more: in addition to tooltips, there are also examples, slideset, video and quick-reference sheet on Event Utilities.

tooltips
	http://www.web3d.org/x3d/content/X3dTooltips.html#BooleanFilter
	http://www.web3d.org/x3d/content/X3dTooltips.html#BooleanSequencer
	http://www.web3d.org/x3d/content/X3dTooltips.html#BooleanToggle
	http://www.web3d.org/x3d/content/X3dTooltips.html#BooleanTrigger
	http://www.web3d.org/x3d/content/X3dTooltips.html#IntegerSequencer
	http://www.web3d.org/x3d/content/X3dTooltips.html#IntegerTrigger
	http://www.web3d.org/x3d/content/X3dTooltips.html#TimeTrigger

examples
	_X3D for Web Authors_, Chapter 9 Event Utilities and Scripting
	http://x3dgraphics.com/examples/X3dForWebAuthors/Chapter09-EventUtilitiesScripting

slideset
	http://x3dgraphics.com/slidesets/X3dForWebAuthors/Chapter09-EventUtilitiesScripting.pdf

videos
	https://www.movesinstitute.org/Video/Courses/X3dForWebAuthors/X3dForWebAuthorsVideo.html#9
	https://www.youtube.com/playlist?list=PLuSIsM-86sik26mcDz0w_wdFXOUp56FTr

Quick-reference sheet
	X3D Event Utility Nodes: Field Event Diagrams
	http://x3dgraphics.com/examples/X3dForWebAuthors/Chapter09-EventUtilitiesScripting/X3dEventUtilityNodeEventDiagrams.pdf

and book chapter 9
	_X3D: Extensible 3D Graphics for Web Authors_
	Brutzman, Don, and Daly, Leonard, Morgan Kaufmann Publishing, 2007. 468 pages.
	http://x3dgraphics.com
	http://dl.acm.org/citation.cfm?id=1214715 (free online to ACM SIGGRAPH members)

> Here is the relevant animation section:
>
> <!-- fade gizmo in and out -->
> <TimeSensor DEF='timerIn' cycleInterval='1' enabled='true' />
> <TimeSensor DEF='timerOut' cycleInterval='1' enabled='true' />
> <TimeTrigger DEF='getTimeIn' />
> <TimeTrigger DEF='getTimeOut' />
> <BooleanFilter DEF='splitBool' />
> <ROUTE fromNode='bandsSensor' fromField='isOver' toNode='splitBool' toField='set_boolean' />
> <ROUTE fromNode='splitBool' fromField='inputTrue' toNode='getTimeIn' toField='set_boolean' />
> <ROUTE fromNode='splitBool' fromField='inputFalse' toNode='getTimeOut' toField='set_boolean' />
> <ROUTE fromNode='getTimeIn' fromField='triggerTime' toNode='timerIn' toField='startTime' />
> <ROUTE fromNode='getTimeOut' fromField='triggerTime' toNode='timerOut' toField='startTime' />
> <ScalarInterpolator DEF='fadeIn' key='0 0.5 1' keyValue='0.9 0.25 0' />
> <ScalarInterpolator DEF='fadeOut' key='0 0.5 1' keyValue='0 0.75 0.9' />
> <ROUTE fromNode='timerIn' fromField='fraction_changed' toNode='fadeIn' toField='set_fraction' />
> <ROUTE fromNode='timerOut' fromField='fraction_changed' toNode='fadeOut' toField='set_fraction' />
> <ROUTE fromNode='fadeIn' fromField='value_changed' toNode='RED_APP_Mat' toField='transparency' />
> <ROUTE fromNode='fadeOut' fromField='value_changed' toNode='RED_APP_Mat' toField='transparency' />
>
>
> It looks rather verbose and I am wondering if there is a more concise way to achieve the same effect without scripting ? The answer may well be to use a script.

Yes it can be verbose.  Scripts can be terser but also need to be debugged in their own way (usually println statements).  When I do that, it is often helpful to add a boolean trace variable so that such code can be turned on/off.  Example technique shown in tracePrint method for this default script template:

	http://www.web3d.org/x3d/content/examples/newECMAscript.js

I have found that arranging nodes in reverse order of flow, top-to-bottom showing destination-to-resource, allows ROUTEs to appear immediately after the node where they are actionable.  If actually printing out a pretty print version of the scene, it lets you draw the ROUTE lines without nearly so much criss-crossing of the lines.  This is a helpful technique for animation-chain design and manual debugging.

> I also learned that it can be useful to 'debug' the flow of x3d events. One way is to have a script log things to the console.

Yes exceedingly important.  Often this is the only approach that can successfully debug a tricky problem, since "your eyes see what they want to see" and since an implementation problem inside a scene (or even player) might not be evident.

Tracing events via inputs/outputs/ROUTEs provides "ground truth" on what is actually happening.

Additional quality assurance (QA) for events:
- X3D DTD and XML Schema will report errors if a DEF name (for a node or in a ROUTE) is incorrect or malformed.
- X3D Schematron rules will provide a warning if an event-producing node is not connected to any event-receiving node.
- X3D Validator provides all of these reports at once:

	https://savage.nps.edu/X3dValidator

>  Are there builtin tools in x3d editors to help with tracing events (perhaps as they happen) ?

X3D-Edit offers such a feature for X3D authors as part of many node editing panels.

	https://savage.nps.edu/X3D-Edit/#New

	"_Trace outputs_ are available for ROUTE, sensors, interpolators and other nodes that produce or consume events. Results are logged on the browser console to show the timing and values passed events. When Trace is selected by the author, a Script node is inserted to accomplish this task. This is a useful debugging technique."
	https://savage.nps.edu/X3D-Edit/images/TraceFeatureReportsRoutedEventValuesOnBrowserConsoleViaScriptOutput.png

This check-box feature is offered for event-producing nodes and also the ROUTE editor.  (TODO: need to add this feature to Script and ProtoInstance editing panes, iterating over fields.)

Something especially helpful for authors is that the trace statements are inserted in your debug scene.  This content-based approach lets you test any X3D player independently.  You can turn trace statements on/off by moving comments around (or simply deleting them).  Simple but effective.

I believe that some X3D development environments have offered integrated trace/debugging features, but am unfamiliar with any in common use.  Certainly powerful when they work!

Attached is your example with a few trace-script blocks inserted by X3D-Edit.  (Note that the derivative DEF names inside the added tracing scripts permit uniqueness.)  Once I copied/pasted/created the new scene with your fragment, adding the traces (i.e. selecting 4 'Trace' checkboxes) took about a minute.  Pretty-print html versions also generated (by button push) and attached for convenience.

Summary: agreed that event tracing and debugging are essential for serious X3D authoring.

Have fun with X3D event animation!  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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: TraceFeatureReportsRoutedEventValuesOnBrowserConsoleViaScriptOutput.png
Type: image/png
Size: 101387 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20161029/77198775/attachment-0001.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: newECMAscript.js
Type: application/x-javascript
Size: 5347 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20161029/77198775/attachment-0001.js>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: GizmoFaderOriginal.x3d
Type: model/x3d+xml
Size: 2317 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20161029/77198775/attachment-0002.x3d>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20161029/77198775/attachment-0002.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: GizmoFaderWithTracing.x3d
Type: model/x3d+xml
Size: 13755 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20161029/77198775/attachment-0003.x3d>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20161029/77198775/attachment-0003.html>