X3Dl is an X3D model viewer intended for mobile devices. It was developed in three months by one person as a project for a virtual reality course. The project fits the theme of "Semantic Virtual Environments with Adaptive Multimodal Interfaces." As such, it is intended to be a component in a larger virtual reality system that can understand a virtual environment and reconfigure the user experience for different access devices (i.e. if you only have a cellphone, you will see and interact with an environment in one way; whereas, someone with a HMD and data glove will be provided with richer interactions). Although virtual environments can be prerendered into videos or still images for mobile devices, X3Dl allows for the possibility of displaying virtual environments directly on mobile devices. By supporting X3D (the U3D specification was not available when this project was started), X3Dl allows a multimodal virtual reality system to use X3D tools for encoding and manipulating models and to avoid having to deal with incompatible and propriety mobile 3d file formats. When not used as part of a larger virtual reality system, X3Dl is able to stand on its own as a simple X3D model viewer.
Since X3Dl was developed as part of a course project, it is currently not under active development; however, if you e-mail me, I can probably make some modifications to the source code if I am not too busy. X3Dl currently implements only a subset of X3D functionality. Here is a list of some of the things that are (and are not) in X3Dl:
Implemented
|
Not Implemented
|
Basically, X3Dl implements enough X3D primitives so that simple 3d models can be examined on a mobile device (which is the purpose of X3Dl).
JSR-184 compliant mobile devices that support Java OTA provisioning can access the binaries of X3Dl here.
When X3Dl is run, it will ask the user to provide the URL of an X3D model. After a URL is inputted, X3Dl will download that model and display it. Buttons on the number pad of the mobile device can be used to navigate around the scene.
 |
 |
Note: The web3d.org site does not allow for browsing by mobile devices. As such, the X3D models on that website cannot be viewed by X3Dl (it is possible to copy the models to a web server that does allow browsing by mobile devices and to view the models from there). Since there are not many X3D models available besides those on the web3d.org site, an alternative way to get access to X3D models is to simply take VRML models, convert them to X3D, and then upload them to a web server that supports browsing by mobile devices.
X3Dl is written in Java and works on mobile devices compliant with the JSR-184 standard for 3d graphics. This platform was chosen because it was the most portable option at the time (other possibilities such as OpenGL ES have limited deployments and might require recompiling to work on different devices etc.).
The only existing X3D viewer written in Java with source code available was Xj3D. Although it would have been possible to modify Xj3D to work on mobile devices (in fact, it already has some limited support for this), I decided that Xj3D wasn't the best base to work from for these reasons:
Instead X3Dl was written from scratch. It is based on a modern architecture that should be easily extensible.
As is standard practice, all X3D scene graph node types are represented by Java classes. Due to my misunderstanding of the X3D specification, the internal representation of these nodes are SAI-compliant (in actuality, only the external representation of these nodes need to be SAI-compliant). Although this means that the class definitions are a little more verbose than necessary, since X3D's SAI is well-documented, using these nodes should be fairly straight-forward. This means that all nodes defined in an X3D file will map to corresponding SAI scene graph nodes when loaded. All fields and variables of these nodes follow the SAI field specification as well.
Traversing the scene graph nodes is done through a standard Visitor design pattern. So, for example, rendering of a scene graph using JSR-184 uses a visitor that traverses all of the nodes in the scene graph, interprets the node fields, and renders the nodes to the screen. Rendering to OpenGL involves creating a different visitor object that walks the scene graph and renders the nodes to OpenGL instead of JSR-184. In all of these cases, the scene graph nodes simply serve as holders of data and do not change.
JSR-184 only supports the rendering of triangles defined using 8-bit or 16-bit integer coordinates. The X3Dl renderer converts all geometric shapes to a series of triangles using floating point coordinates. It then converts these triangles to use an integer coordinate system (with appropriate scaling so that the full range of integer coordinates is used). Since X3D supports arbitrary concave and convex polygons, the X3Dl renderer supports triangulation of these polygons using an inefficient algorithm. These triangles are cached by the JSR-184 so that they do not have to be recalculated each time the scene is displayed.
A simple OpenGL renderer is also included with X3Dl. This renderer is not as complete as the JSR-184 renderer (in particular, it does not support navigation through a scene), and it simply takes the triangles used by the JSR-184 renderer and displays them using OpenGL.
Because mobile devices are currently too resource limited to support SAX and DOM and because standardized mobile Java web services frameworks are not widely deployed, X3Dl uses the kxml 2 XML pull parser to parse X3D files. All the XML nodes in a X3D file are walked and the X3D SAI interface is used to create the appropriate scene graph nodes and to link them together.
A lot of the X3Dl code is verbose, boring, and repetitious. This characterization particularly applies to the parser and the SAI scene graph nodes. Since the writing of this code is potentially time-consuming and error-prone, all of this code is auto-generated instead of being written by hand.
Java supports only limited meta-language facilities, so different code generation possibilities were examined during the development of X3Dl including the use of C preprocessing or custom Java/Perl solutions. In the end, XSLT was chosen as the language of the code generator. Although XSLT is a little verbose and sometimes has problems with indentation, it is powerful, is standardized, and has good support for handling special cases (which is usually what causes code generation systems to break down and become unwieldy). Its main shortcoming is that the current XSLT specification does not support the output of multiple files from a single XSLT file, meaning that a Java harness was needed to invoke a separate XSLT instance for each source file being auto-generated.
The main input to the auto-generation process is a specification file that describes the X3D abstract node types and fields for which code should be generated. By modifying this specification file, it is easy to add new node types to X3Dl. This specification file is used by different XSLT files to generate different Java classes. For example, there are different XSLT files for outputting SAI node interfaces, SAI node implementations, SAI field interfaces, SAI field implementations, SAI exception classes, and the other miscellaneous files.
This zip file contains the source code needed to compile the X3Dl model viewer for a JSR-184 device. To compile the code, download and install a copy of Sun's JDK 1.4.2. Then, download and install a copy of Sun's Wireless Toolkit WTK 2.2. In the WTK apps directory (i.e. \WTK22\apps), unzip the contents of the zip file. A directory called X3Dl should be created. Create a "lib" directory inside of this X3Dl directory. Download a copy of kxml2-min.jar from kxml.org (click on the Releases link) and put it into this lib directory. To then compile the code, start the KToolbar application of the Wireless Toolkit, open the X3Dl project, then choose Project/Build and Project/Run from the menu bar.
This zip file contains the source code needed to compile the X3Dl model viewer for the JOGL OpenGL library. Simply unzip the code and link in the JOGL jars (go to the main JOGL site and click on the Precompiled Binaries and Documentation link) and kxml2-min.jar (can be found on the kxml.org site).
The above two code drops contain the source code needed to compile a working X3Dl model viewer. The auto-generated code needed to handle scene graph nodes has already been generated and included in the zip files. The XSLT files needed to auto-generate that code is not included in those zip files though.
To compile the X3Dl implementation from scratch (i.e. to auto-generate the scene graph node code etc.), you need to use the code provided in this section and follow the instructions from this section.
First download the source code for the automated code generator. Unzip the file somewhere. Run the following command from within the X3Dl directory to invoke the generator:
java -jar generator.jar
When the generator has finished generating the source code, erase generator.jar, the xml and xslt files, and the ch/epfl/ic/iu/x3d/generator directory.
Secondly, download the source code for converting X3D geometry into triangles and unzip it to the same location.
Then, depending on which device you are targeting, download the source code for either the JSR-184 renderer or the JOGL renderer. Unzip the file into the same directory.
Finally, if you take all of the code that you now have, and combine it with the appropriate libraries (as described in the sections for the JSR-184 Final Source Code or JOGL Final Source Code), you can then compile the final X3Dl model viewer.