Xj3D's SAI support

I. Forward
I had spent some time dealing with x3d and SAI these days. As web3d web site said:

X3D is an Open Standards XML-enabled 3D file format to enable real-time communication of 3D data across all applications and network applications. It has a rich set of features for use in engineering and scientific visualization, CAD and Architecture, Medical visualization, Training and simulation, multimedia, entertainment, educational, and more.

3D modeling is not my major, and what I dealt with was not about 3D modeling, either. I mainly focus on the scene access interface (SAI) and trying to make it work on x3d browsers.

In x3d specification, we can write a special kind of node named "script." Usually these scrpts are written in javascript or so called ECMAscript. But as specification said, java byte code is also a valid choose. After several trials, I found that one of the commercial product -- maybe the most widely used one -- BS Contact does not fully support those feature. In fact, in version 6.1, the "url" field is not implemented so that it's impossible to write external script. In version 6.2, external script is supported but java byte code is still absent.

Another x3d browser implementation, Xj3D, is an open source software written in Java. As itself is written is Java, support of java byte code is great and complete. A shortage is that it hasn't support some complex node and can't process some x3d files. Another shortage is lake of documentation. Even though there are some implementation details and architecture documents, comments in source code is also well written, I found only few documents on using and hardly found any document on written SAI code. So this article is about these issues.

II. Xj3D usage
Installation of Xj3D version M10 is easy and smooth. After
download the installing jar file, simply run

  java -jar Xj3D-M10-RC2-platform.jar

and every will be fine. Not quite sure if it's necessary (since Xj3D can run with OpenGL scene), I installed Java3D before installing Xj3D.

To run the browser itself, using browser.bat on Windows or browser.sh on Unix. Don't be surprise that it spends all your CPU time and make your fan running faster -- it always does on my computer, either Windows or Linux. On Windows, it makes system slow down and makes me unable to do any thing else. It seems that it can have some improvement in this issue since on BS Contact, the same script needs little CPU time.

III. SAI and java byte code script for script node
The way to write java scripts is fairly simple -- compare to the effort I took on discovering it. The javadoc of the library Xj3D provided is available
online. According to x3d specification, all the compononts about SAI are defined in package org.web3d.x3d.sai.

First of all, in order to make Xj3D accept the byte code, the class should implement interface org.web3d.x3d.sai.X3dSriptImplementation, and, quite obvious but I forgot at first, should be public. As the javadoc said, there are several motheds should be implemented but only one of them is important

  public void setField(X3DScriptNode externalView, java.util.Map fields)

Where 'fields' will be a map from string to object, with the name of each field mapped to it's corresponding value class -- classes who implemented X3DField.

To use the fields we get from the parameter of setField, Xj3D provided a EventListener architecture. Interface X3DField defined a method

  public void addX3DEventListener(X3DFieldEventListener l)

So we can make our class implement X3DFieldEventListener as well as X3dScriptImplementation to handle the value changing.

Below is a sample code:
(X3d file)

 <script DEF="MoverUsingExternalScriptFile" url="Script.class">
   <field name="set_fraction" type="SFFloat" accessType='inputOnly'/>
   <field name='value_changed' type='SFVec3f' accessType='outputOnly'/>
 </script>

(Script.java)

public class Script implements X3DScriptImplementation, X3DFieldEventListener{
 public void readableFieldChanged(X3DFieldEvent evt){
   value_changed.setValue(new float[]{
     set_fraction.getValue(), 0.0f, 0.0f
   });
 }
 public void setFields(X3DScriptNode externalView, Map map){
   set_fraction = (SFFloat) map.get("set_fraction");
   value_changed = (SFVec3f) map.get("value_changed");
   set_fraction.setX3DEventListener(this);
 }
 public void eventProcessed(){}
 public void initializet(){}
 public void setBrowser(Browser browser){}
 public void shutdown(){}

 private SFFloat set_fraction;
 private SFVec3f value_changed;
}