How To Install and Compile Xj3D

Required Libs | PATH/CLASSPATH | Building Xj3D |


What is Xj3D

Xj3D is an example implementation for the X3D specification. Specifically, Xj3D is a Java3D-based open-source loader, browser and exporter for Extensible 3D (X3D) graphics.

This page is intended to help software developers examine and contribute to the source code. This is beta source code under active development. If you are just interested in using the codebase you do not need this document! We have a user install available here. This install includes everything you need to use Xj3D as a Java3D loader and includes a sample VRML97/X3D Browser.


Setting up your Windows PC to compile the Xj3D Source


This section will take you through the steps needed to setup your system to compile Xj3D. It will help you locate all the required utilities/libraries and detail which versions have been tested to work. This version will provide a checklist view. If you would like a more detailed version check here: Detailed Install Notes

Install the packages to whatever directories you like, but record their locations. We recommend a directory location that will be used in example paths. You will use these locations later to setup your CLASSPATH and PATH environment variables. If a package is mentioned as residing in the lib directory then we suggest you use that version. Some of these are hard to find, tracking at a different version or we have modified them.

  1. Cygwin: Obtain a UNIX box, or turn your PC into a UNIX box via: GNU Utilities for PCs are available at sourceware.cygnus.com/cygwin
    Provides Unix command line and utilities on Windows 95/98/NT/2000.

    Notes:

  2. CVS is the Concurrent Versioning System, which is widely used for software management projects shared among multiple individuals.

    CVS is included in the Cygwin distribution. The next steps will take you through downloading the Xj3D code. At this point you have a decision to make. You can either download the latest stable release or jump into the raw development stream. I'd recommend going for the latest stable release, you've got enough to do for now without worring about our untested changes!

    Checking out the Code:

    Troubleshooting CVS:

  3. Java 2 SDK 1.3.1 is available at java.sun.com/j2se/.

    We have successfully used the latest 1.4 Beta3 as well.

  4. Java 3D (version 1.2.1_02) is available at http://java.sun.com/products/java-media/3D
    Select the SDK for the JDK format. Usually the OpenGL-based version of Java3D is much preferred.

    We have successfully used the latest 1.3 Beta1 release as well.

  5. The Java API for XML Parsing (JAXP) is the package that we currently use for our XML/DOM interfaces. This package is installed by default with the JDK 1.4 releases.

    The Java XML Pack is available at http://java.sun.com/xml/downloads/javaxmlpack.html.

  6. JavaCC by WebGain/Metamata is available at http://www.webgain.com/download/index.html. JavaCC is under the Freeware and Other Downloads.

    Note: When installing make sure you select the UNIX shell scripts version of scripts

  7. Junit is used for creating a unit test framework. It originally came from the Extreme Programming people, but is now used more widely than that. Unit tests start by testing smaller pieces and then you can build them up to provide larger tests.

    Download JUnit 3.7 from:

    www.junit.org

    We recommend installing this package to c:/javaapis/junit3.7

  8. Rhino is a ECMAScript/JavaScript interpreter. It is needed for the ECMAScript code in the Script node. You can download it from: www.mozilla.org/rhino/download.html. We have tested the code with Rhino 1.5R2. We recommend installing this api into the directory c:/javaapis/rhino1_5R2
  9. The J3D.org library is a low level package for 3d development in Java3D. The latest version is included in the lib directory of the codebase. This codebase consists of j3d-org.jar and j3d-org-images.jar. You can also download it at: http://code.j3d.org/download.html
  10. GNU Regular Expression is located in the lib directory. We are currently using version 1.0.8(gnu-regexp-1.0.8.jar). You can download the original at: http://www.cacas.org/~wes/java/
  11. HTTP Client - A complete http client library. Based off the 0.3-1 release. We have slightly modified this version. You can find our version in the lib directory. The original can be found at: http://www.innovation.ch/java/HTTPClient/
  12. URILib - Provides a URL/URN/URL resolver replacement for java.net. It is located in the lib directory(uri.jar, vlc_uri.jar). The project pages are located at http://www.vlc.com.au/urilib/
If you are not going to use the X3D XML encoding then you can stop here.
  1. DTD Parser: The DTDParser code allows us to build information automatically from profiles supplied by the X3D document creator. The standard JAXP code does not provide this support (Note that once XML Schemas are properly supported this code will no longer be needed).

    We have modified the publically available version(submitted but not available yet) so the library is available in the lib directory(dtdparser113a.jar)

    If you want the original files they can be downloaded here: DTD Parser

  2. W3C DOM2 bindings These are the Java bindings provided by W3C for DOM level 2 compliance. Get the file dom2.jar from the link titled: Dom Level 2 - Jar File. The link to this area is: http://www.w3c.org/DOM/DOMTMhttp://www.w3c.org/DOM/DOMTM

    We recommend you place this file in the directory c:/javaapis/dom2

  3. Script Authoring Interface:
  4. The Xj3D codebase implements the new SAI developed by the X3D group.

    Currently we have not updated to the latest SAI released. So please download the currently supported verson from here: www.web3d.org/TaskGroups/source/jars/SaiX3d.jar and place it in your x3d/lib directory.

    For reference the latest is located at SaiX3d.jar


Environment Variable Setup

PATH and CLASSPATH settings are always a bit tricky. The easiest way to setup the system environment variables is to modify the .bashrc file located in c:/cygwin/home/$userid. Where $user is your system userid.

All the examples here assume you have installed the Xj3D codebase into "c:/xj3d". Modify these as needed for your local setup. Here is a sample .bashrc that you can use. Type:

x3d
to setup your paths for x3d development.

Here are the paths you will need. All locations assume the default install directories specified above.

   export PATH="c:/jdk1.3.1/bin;c:/javacc2.1/bin;$PATH"
   export CLASSPATH="c:/xj3d;c:/xj3d/x3d"
   export PROJECT_CLASSPATH="c:/xj3d/x3d/lib/j3d-org.jar;c:/javaapis/rhino1_5R2/js.jar;c:/javaapis/junit3.7/junit.jar;c:/xj3d/x3d/lib/dtdparser113a.jar;c:/xj3d/x3d/lib/gnu_regexp-1.0.8.jar;c:/xj3d//x3d/lib/httpclient.jar;c:/xj3d/x3d/lib/j3d-org-images.jar;c:/xj3d/x3d/lib/uri.jar;c:/xj3d/x3d/lib/vlc_uri.jar;c:/xj3d/x3d/lib/SaiX3d.jar;c:/javaapis/dom2/dom2.jar"

The final step in the setup is to ready your personal environment so that our build scripts work. Building is provided using Make. For make to work correctly you will need to set the PROJECT_ROOT environment variable. This points to the directory that you downloaded CVS into. For example, if you put the CVS code into c:/Xj3D/x3d, then you will need the following (including quotes):
   export PROJECT_ROOT="c:/Xj3D/x3d"
Note that this all assumes you are running in the cygwin environment. All the slashes are unix style, yet we need to put DOS style directories. If you are running on a unix machine, then put your normal unix style path here eg:
   export PROJECT_ROOT=/home/username/Xj3D/x3d
You will also need to set the JAVA_HOME environment variable. This should point to the location you installed java. So for JDK1.3.1 you would use:
export JAVA_HOME=c:/jdk1.3.1


Building the Xj3D source

Copy the file Makefile from the make directory into this directory.
    cp make/Makefile .
Now, to compile the code, simply change to this xj3d directory and type:
    make
This will build all of the classes and package them into JAR files for you. The JAR files can be found in the newly created jar directory. To automatically install these in the right place, type
    make install
The make system provides a number of other options. These are listed below: To test that you have the codebase compiling correctly try the following:
    cd examples/browser
    java DIYBrowser
    in location append "..\..\parsetest\geometry\box.wrl"
    hit the Go! button
    see box, rejoice!

At this point you might want to look at the "How to Use Xj3D Tutorial" to see how you can use Xj3d in your projects.


Many thanks for developing this document goto:
Don Brutzman (NPS) and Joe Williams (HyperMultiMedia) and Alan Hudson(Yumetech)

Last Revised: $Date: 2002-02-06 18:42:24 $

The Uniform Resource Locator (URL) for this home page is www.web3D.org/TaskGroups/x3d/Xj3D/HowToInstall.html