elieve it or not, the Jet Propulsion Laboratory (JPL) from NASA is actually developing Java capabilities. The JPL is a division of NASA responsible for the robotic exploration of the solar system. Household names such as the Mars Pathfinder and the Voyager explorers are products of JPL.
One of their Java capabilities is the FastScript3D library for Java3D, and it is a technology that really shows some promise.
FastScript3D is a Web-friendly extensible scripting interface to Java3D. It allows you to quickly harness the power of 3D Web graphics using JavaScript or VBScript to add interactive 3D applets to your pages. There are a number of free examples on the JPL Web site. But in essence FastScript is an applet to which you can pass simple script commands in order to make it generate 3D Web objects automatically.
This technology could be used to render and display three-dimensional models on your Web site, in much the same way that VRML (Virtual Reality Modeling Language) did. The nice thing about FastScript3D is that it doesn’t have a proprietary file format, and that it can load the model description files from a variety of 3D modeling applications.
Getting Started
In this article you will step through the basics of the FastScript3D API, and build some Web pages that render different 3D models. You will begin by looking at how to install the API, and from there will build three-dimensional models using the built in primitives. Then you’ll see how to load and render a 3D model from the popular Lightwave 3D modeling application. By the end of the tutorial you will have covered the basic operations offered by the API and will be prepared to look into some of the more complex aspects, such as extending the API and animating your 3D worlds.
You will need a J2SE SDK version 1.4 or later, and the Java 3D API version 1.3.1 or later. These may be downloaded from http://java.sun.com. Make sure that you are using the correct Java plug-in for your browser by opening Control Panel and selecting the ‘Java Plug-in’ Applet. On the ‘Advanced’ tab, select the correct runtime. This should read something like ‘SDK 1.4.2_01 in C:j2sdk1.4.2_01.’
Close down and restart your browser, and then browse to http://fastscript3d.jpl.nasa.gov/HelloUniverse.html. You should see a spinning multicolored cube. If you do, then you are ready to go with fastScript3D.
Setting Up Your Development System
Fastscript3D uses the LiveConnect classes from Sun to communicate between JavaScript and Java. LiveConnect is a technology that allows JavaScript to interface with Java applets. With it you can access Java variables, methods, events, and packages directly and gain full control over your applets.
![]() | |
Figure 1. Picture This: Here’s the easy FastScript3D application in action. |
On the PC platform the JAR file containing LiveConnect is called jaws.jar, and on the Sun platform it is called java40.jar. Find the appropriate jar for your platform and add it to your classpath.
The next thing you will need is the JAR file containing the supporting files for FastScript, fs.jar, which is available for download on the JPL site. This needs to be placed in the directory on your Web server where the HTML files containing the 3D applets will reside. Under this directory create the following subdirectories: FS_MODEL, FS_TEXTURE, FS_SIM, and FS_DEMO.
The JPL has provided a very basic example which has three cubes?a red one, a green one, and a blue one?floating in 3D space. The source code for which (easy.java) is included in the download for this article. To compile this you must have references to the java3d JARs (usually found in jrelibextj3dutils.jar) and the FastScript JAR that you downloaded earlier.
Once this is compiled into easy.class, place it in the directory on your Web server that you created earlier. Finally, take the HTML file from the download with this article (easy.htm) and put it in the same directory. Browse to the HTML, and you should see something like that shown in Figure 1.
Author’s Note: If you follow the example on the JPL site directly you will get an error, as the JAR file for FastScript3D that you download is newer than the one referenced in their example. Use the ones in the download with this article and it should work easily. |
Developing in FastScript3D
Examine the HTML page for the example in this article and you’ll find the following script.
this.document.fs3d.parse("MODELCLEAR");this.document.fs3d.parse("NAME redbox");this.document.fs3d.parse("COLOR red");this.document.fs3d.parse("HINGE 1 0 0");this.document.fs3d.parse("MOVABLE");this.document.fs3d.parse("OFFSET -0.5 0 0");this.document.fs3d.parse("GEOMBOX 0.25");this.document.fs3d.parse("NAME greenbox");this.document.fs3d.parse("COLOR green");this.document.fs3d.parse("GEOMBOX 0.25");this.document.fs3d.parse("NAME bluebox");this.document.fs3d.parse("HINGE 1 0 0");this.document.fs3d.parse("MOVABLE");this.document.fs3d.parse("COLOR blue");this.document.fs3d.parse("OFFSET 0.5 0 0");this.document.fs3d.parse("GEOMBOX 0.25");this.document.fs3d.parse("MODELBUILD");
Fastscript3D commands are constructed as a string and passed to the ‘parse’ method of the applet. The command string is always constructed in the same way with the keyword in capitals followed by the parameters that the keyword requires. It is in this form:
KEYWORD
For example:
OFFSET -0.5 0 0
(Note that parameters are space delimited.)
The command always returns a string containing the status of the command. If your command was successfully passed to the engine and successfully parsed, the return string will be “1” followed by the command, otherwise it will be “0” followed by the command and an error message detailing the problem.
Objects in your 3D world are called models in FastScript3D. To begin a new application you use the MODELCLEAR command, to clear up space and ready it for new drawings.
After that define your models and their attributes. Your models are defined using the commands that are prefixed GEOM. Table 1 lists the available models and their associated commands.
Command | Description |
GEOMNULL | No shape or erase current shape |
GEOMBOX | Draw a cube |
GEOMRECT | Draw a 3d Rectangle |
GEOMSPHERE | Draw a Sphere |
GEOMELLIPSE | Create an ellipse |
GEOMAXIS | Create a new co-ordinate axis |
GEOMCYL | Create a cylinder |
GEOMTEXT | Create some 3D Text |
GEOMLABEL | Create a label, this is similar to text except that it faces forward at all times |
GEOMOBJ | Implemented to interface with SUN WaveFront technology. |
Table 1.GEOM Commands
Once you have your model, you can specify its appearance using a variety of commands. The most basic command for configuring your model is the COLOR command, which takes two overloaded parameter sets. The first is simply the textual description of the color such as:
COLOR blue
The second allows you to specify normalized RGB colors such as:
COLOR 0 0.5 1
In addition to colors, different materials and textures may be added to your model. There are many different materials built into the language, including MATGOLD, MATBRASS, MATCHROME, MATEMERALD, and MATCOPPER. The language is also extensible to allow you to add your own materials.
If you use both COLOR and MAT commands to enhance your model, you can make the colors and materials blend into each other with the MATSEEPON command. The model may also be made transparent using the OPACITY command where a parameter value of 0 is opaque and 1 is totally transparent, but you can use any decimal in between for partial transparency.
Your object may also be textured using a JPEG file. This file should be placed in the FS_TEXTURE directory.
TEXTURE me.jpg
Movement
In addition to defining how your object appears, there are many other commands for how your object behaves. For example movement can be defined. You specify the object as being movable with the MOVABLE command. A neat command for defining how the object moves is the HINGE command. This takes parameters defining the axis on which the object will move. For example, if you want your object to move on the Y axis, simulating, for example, a rotating planet where the spin axis is generally seen as the vertical one, you would issue the following command:
HINGE 0 1 0
The code below contains an example of putting a few of these commands together. This is implemented in the download as earth.htm and creates a rotating globe. The Earth.JPG file is necessary, and should be placed in the FS_TEXTURE directory.
this.document.fs3d.parse("MODELCLEAR");this.document.fs3d.parse("NAME Earth");this.document.fs3d.parse("HINGE 0 1 0");this.document.fs3d.parse("MOVABLE");this.document.fs3d.parse("TEXTURE Earth.jpg");this.document.fs3d.parse("GEOMSPHERE 0.5");this.document.fs3d.parse("MODELBUILD");
The output of this script is shown in Figure 2. You can see that the API has handled wrapping the texture around the sphere and has added default lighting. Because the model has been declared as MOVEABLE, you can also drag on it with the mouse to affect its behavior.
![]() | |
Figure 2. Spanning the Globe: This rotating Earth is rendered with FastScript3D. |
Animation
There are a number of commands available for animating your models. First you must select which model you want to animate. This is done with the REFER command. In the above example, there is only one object, called Earth, so to initialize it for animation you would use the REFER Earth command. Once you have a reference to an object you can animate it with commands such as TA, which translates the object to an absolute set of coordinates; TR, which translates the object to a relative set of coordinates; RA, which rotates it to an absolute position; and RR, which rotates to a relative position. Examples of these are:
- TA 1 1 1?Move the object to location {1,1,1}
- TR 1 1 1?Move the location from its present location {x,y,z} to {x+1, y+1, z+1}
- RA 90 ?Rotate the object to 90 degrees rotation
- RR 5?Rotate the object by 5 degrees.
Animations can be aggregated into simulations, which can then be activated using the appropriate simulation/playlist commands. Check the FastScript3D documentation for more details.
Using Complex Models
One of the most exciting features of FastScript is the ability to import and render models from CAD or modeling packages and display them. To do this you need to write a wrapper class around any of the file loaders that are available within Java3D. A full listing of these files along with API details is available on the Java3D site.
One of the more famous and popular 3D scene creation packages is LightWave, which has been used in many television and movie special effects. FastScript3D comes with an example page that loads and renders a LightWave scene, and it does this by creating a wrapper for LightWave files. Java3D provides a LightWave loader class called Lw3dLoader in the com.sun.j3d.loaders.lw3d package. This encapsulates the loading and basic parsing of LightWave-format objects.
The code to load a 3D scene from LightWave is very straightforward:
Scene threedsscene = null;loader = new Lw3dLoader();loader.setBaseUrl(http://localhost/fs3d/FS_MODEL);threedsscene = loader.load(http://localhost/fs3d/FS_MODEL/run.lws);
The file lightwave.java, available in the download was taken from the JPL site and edited to change the urlbase and urlname variables to http://localhost/fs3d/FS_MODEL directory as that is where the examples have been installed for the creation of this article. In addition, the download includes the LightWave files to generate a Star Trek spacecraft (a runabout from Deep Space Nine to be precise) make sure that you place these files in the FS_MODEL directory.
![]() | |
Figure 3. Use the Force: Here, FastScript3D is rendering a LightWave object. |
Extending the Language
FastScript3D is open source and fully extensible. It is designed so that new commands may be easily integrated. If you create a command that is not part of the core set of FastScript3D commands, and the engine receives this command, it starts calling the extension parsers that it knows about. The method addparser allows you to add parsers to the core engine.
A good example of where you may want to add new commands and parsers to the language is in extending the limited number of materials that are available with the MAT commands. This would simply be done by amending the Java class that you use to place the applet on the Web page (in the above examples easy.class and lightwave.class) to add a class that intercepts the new commands (e.g. MATPLASTIC and MATRUBBER), and in the init() method of your applet you would create an instance of this call as pass it to the addparser method.
This example is discussed in detail with source code in the FastScript documentation.
FastScript3D is a great technology that empowers you to develop in Java3D without getting into all the low-level programming that would normally be required for generating and manipulating 3D objects and scenes. Its extensibility allows you to generate your own scenes, commands, and object types for powerful customization. Because it is a simple scripting language, it opens up a new box of tricks for JavaScript (or indeed VBScript) developers. This is most useful in that it can offer simple, firewall friendly access to complicated applications. The API is far more detailed than can be gone into on this site, and is certainly worth a detailed look. If you want to make your pages stand out from the crowd, then this is certainly a great place to start!
Author’s Note: FastScript3D was created and written by Patti Koenig, Ph.D. of NASA Jet Propulsion Laboratory (JPL) for the California Institute of Technology. |