What is LiveGraphics3D?
What to Read Next?

Quick Start
Trouble Shooting
Details

Quick Start
Trouble Shooting
Attributes and Parameters
Interfacing with J/Link

Producing Graphics with Mathematica
Converting Graphics3D Objects
Converting Animations
Converting Two-Dimensional Graphics
Converting Other Graphical Objects
Parametrized Graphics
Formatting Text

Limitations
Revision History

What Is LiveGraphics3D?

LiveGraphics3D is a non-commercial applet to display and rotate three-dimensional graphics produced by Mathematica 5.x in HTML pages. LiveGraphics3D was developed in Java 1.1, but it is recommended to use the JavaScript version compiled by CheerpJ since most modern web browsers do not support Java applets. LiveGraphics3D may be used without charge for any non-commercial purposes. Mathematica is a program for symbolic and numeric mathematics by Wolfram Research, Inc..

LiveGraphics3D allows Mathematica users to put three-dimensional graphics computed by Mathematica directly onto a HTML page, such that everyone with a web browser supporting JavaScript can view and interactively rotate the graphics without additional software.

Additionally, LiveGraphics3D is able to show animations, calculate stereo graphics, integrate hyperlinks, render basic mathematical symbols, and display bitmap backgrounds.

Since version 1.00 LiveGraphics3D supports parametrized graphics, i.e. simple Mathematica expressions instead of coordinates, and animations with Animate. An introduction to these features is given in some examples and my talk at the Mathematica Developer Conference 2001.

What to Read Next?

If you want to use LiveGraphics3D in your own HTML pages, you do not have to know anything about Java or JavaScript programming, as the applet is already compiled. However, you have to install the JavaScript package live.jar.js and the Java archive live.jar on your web server as described in the Installation section.

The section Preparing Graphics with Mathematica provides additional information and tips about producing and converting three-dimensional graphics with Mathematica.

If you have any comments, critisism, bug reports, or ideas regarding this software or its documentation please e-mail me.

Quick Start

In order to view LiveGraphics3D applets you will usually use a web browser supporting JavaScript. (An alternative is to call the Java applet from within Mathematica via J/Link, see below.)

After a LiveGraphics3D applet has successfully initialized itself the following interactions are always supported.

The META key is usually mapped to the ALTERNATE (ALT) or COMMAND key; on some systems it is emulated by the right mouse button. The CONTROL key (CTRL) does not work with all web browsers (e.g. Safari). You might be able to use CONTROL plus right(!) mouse button instead. Rotation about an axis perpendicular to the picture is not possible if a rotating background is included.

Several additional interactions are supported for animations.

Trouble Shooting

This subsection is about problems possibly appearing when a web page containing a LiveGraphics3D applet is viewed. (Problems with the integration of the LiveGraphics3D applet in your own web pages are discussed in the Trouble Shooting subsection of the Installation section.)

Many problems with LiveGraphics3D (and applets in general) can be solved by reloading the web page. In order to do so you usually have to hold down SHIFT or CONTROL (depending on your web browser) when clicking the reload button.

Please report any unsolvable problems with LiveGraphics3D.

Details

This subsection presents some details of the user interface. First the determination of the axis of rotation is described and then a way to find suitable values for some parameters is discussed.

The axis of rotation is usually in the plane of the two-dimensional picture and perpendicular to the virtual line you moved with the mouse (starting from the point on which you clicked). The angle of rotation is determined by the length of that line. This allows you to view the graphics from all directions. However, the presence of rotating bitmap backgrounds changes this prescription. In this case, horizontal dragging will rotate about the fixed vertical axis and vertical dragging about the horizontal axis in the plane of the picture

Pressing SHIFT and dragging vertically will change the value of the parameter MAGNIFICATION. Pressing CONTROL and dragging horizontally will change the parameter STEREO_DISTANCE. (Negative values indicate the need to cross fuse while positive values are appropriate for diverge fusing.) The current settings of MAGNIFICATION, STEREO_DISTANCE and the Graphics3D options ViewPoint and ViewVertical can be printed to the JavaScript or Java console by pressing the "o" key while the mouse cursor is in the region of the Java applet. If you are using LiveGraphics3D on your own HTML page, you can copy the line containing MAGNIFICATION or STEREO_DISTANCE from the JavaScript or Java console into the applet call and/or the settings of ViewPoint and ViewVertical into the Graphics3D definition to use them as initial values. This is probably the best way to find appropriate values for these parameters.

There is no need to install anything in order to view and rotate graphics on other web pages using LiveGraphics3D, as your web browser automatically loads and executes the needed JavaScript package.

However, in order to use LiveGraphics3D in one of your own web pages you need the JavaScript package live.jar.js and the Java archive live.jar in the directory of your HTML file. This is like the way pictures are included in web pages: HTML pages contain instructions to load encoded image files and web browsers read, decode and display them. The only difference with a JavaScript package is that JavaScript code is not displayed but executed.

Quick Start

You should be able to download the JavaScript package live.jar.js and the Java archive live.jar with your web browser and save it on your local computer. (Usually you will have to press CONTROL when clicking on the link above or click with the right mouse button and save the file.) Please note that LiveGraphics3D is free for non-commercial purposes only.

After copying live.jar.js and live.jar, you may start to create HTML pages including LiveGraphics3D applets. The corresponding HTML files should be placed in the same directory on a web server as the live.jar.js and live.jar files. (It is not possible to use the files locally.) A complete example follows.

First a file containing the Graphics3D object is needed. Let's call it test.m with the following contents:

Graphics3D[{ (* ...primitives and directives... *) },
   BoxRatios->{1,4,9} (* ...options... *)]

<!DOCTYPE html>
<HTML>
 <HEAD>
  <SCRIPT SRC="https://cjrtnc.leaningtech.com/2.1/loader.js"></SCRIPT>
 </HEAD>
 <BODY ONLOAD="cheerpjInit()">
  <CHEERPJ-APPLET ARCHIVE="live.jar" CODE="Live.class" WIDTH=150 HEIGHT=150 ALIGN=LEFT>
   <PARAM NAME="BGCOLOR" VALUE=#FFFFFF>
   <PARAM NAME="MAGNIFICATION" VALUE=1.>
   <PARAM NAME="INPUT_FILE" VALUE="test.m">
  </CHEERPJ-APPLET>
 </BODY>
</HTML>

Please note that file names are case sensitive, that all files need appropriate read permissions, and that some firewalls might not allow access to local ".m" files.

If this HTML pages is placed in the same directory as live.jar.js, live.jar and test.m on your web server, it should produce the following LiveGraphics3D applet:

If you are upgrading from the legacy Java version of LiveGraphics3D to the JavaScript version, the main changes to the HTML file are:

• the new line <SCRIPT SRC="https://cjrtnc.leaningtech.com/2.1/loader.js"></SCRIPT> between <HEAD> and </HEAD>
to load the CheerpJ functions
• the initialization call cheerpjInit() in <BODY ONLOAD="cheerpjInit()">
• the change of the <APPLET> and </APPLET> tags to <CHEERPJ-APPLET> and </CHEERPJ-APPLET> to avoid problems with any installed Java machines

and the new file live.jar.js has to be in the same directory as live.jar.

If this example works, you might whish to skip the next subsection and jump to the subsection Attributes and Parameters which discusses the attributes and parameters of the LiveGraphics3D APPLET tag or to the section Preparing Graphics with Mathematica for information about converting Graphics3D (and other graphical) objects to an InputForm appropriate for LiveGraphics3D.

Trouble Shooting

Remember that you cannot run LiveGraphics3D from the local file system; you have to access it via a web server. Make sure that the files are publicly accessible. Also, some web severs might not allow to access .m files, thus, using a different extension might be necessary. If you get stuck, e-mail me the URL of your web page and I might be able to see what is missing.

Attributes and Parameters

The LiveGraphics3D applet can be controlled by setting several attributes and parameters, as demonstrated in the Quick Start subsection. Most of the attributes and parameters are optional, however the attributes ARCHIVE, CODE, WIDTH, and HEIGHT and the parameter INPUT_FILE has to be specified. (The parameter INPUT may be used instead of INPUT_FILE.)

The applet's attributes primarily control how the applet appears within the HTML page. (See the HMTL 4.0 Reference Specification for the official list of attributes of the APPLET tag.)

Apart from these attributes the LiveGraphics3D applet offers additional parameters controling the applet itself. These parameters have to be set with PARAM tags as shown in the Quick Start subsection. (I recommend using upper case letters for the names of these parameters.)

By default background images will always be "centered". (ViewPoint will only change the appearance of the Graphics3D object and does not affect the background image; however in the cases of CYLINDRICAL_BACKGROUND and SPHERICAL_BACKGROUND the background can be rotated initially with INITIAL_ROTATION.) There are some restrictions on rotatable images, which are explained on the page of the birds example.

In order to display stereo graphics instead of a single picture define STEREO_DISTANCE with an appropriate value (for example with the default value of 0.05).

The production of InputForms of Graphics3D objects within Mathematica is explained below.

Interfacing with J/Link

With the help of J/Link, which is a part of Mathematica, you can call the Java version of LiveGraphics live.jar from within Mathematica. Calling an applet is discussed in the Mathematica documentation. The following summary was written for Mathematica 5.x and is probably outdated. The reader is assumed to have a basic knowledge of Mathematica and the possibility to execute Mathematica commands including J/Link.

First you have to download the Java archive live.jar to a directory on your computer, let's call it dir.

Then you can start Mathematica and from within Mathematica start J/Link and tell J/Link about the directory dir where it can find the file live.jar. (For other ways to tell J/Link about new Java code, see the J/Link documentation.)

<< JLink`

InstallJava[];

AddToClassPath[dir];

Here dir has to be replaced by a string specifying the directory of the file live.jar. We need a small function to produce appropriate strings describing three-dimensional Mathematica graphics. The function LiveForm (discussed below) almost performs this task; we only have to convert the returned value to a string and then replace double quotes by pairs of single quotes because they would otherwise cause problems. Here is the definition of LiveForm:

LiveForm[graphics_, animOpts___] := 
   Module[{graphics3d = Switch[graphics, _ContourGraphics, 
   Graphics3D[SurfaceGraphics[graphics]], _DensityGraphics, 
   Graphics3D[SurfaceGraphics[graphics]], _SurfaceGraphics, 
   Graphics3D[graphics], _, graphics]//.SequenceForm[x___]:>
   StringForm[StringJoin[Table["``", {Length[{x}]}]], x]}, 
   Switch[graphics3d, _List, HoldForm[ShowAnimation][
   Map[LiveForm, graphics3d], InputForm[N[Flatten[{animOpts}]]]], 
   _, InputForm[N[graphics3d]]]];

Now let's make some graphics and call LiveGraphics3D with it:

g = Graphics3D[Plot3D[Re[Exp[x + I y]], 
   {x, -2, 2}, {y, -10, 10}, PlotRange->All, 
   PlotLabel->SequenceForm["Re", 
   StyleForm["(", FontSize->24], 
   Superscript["e", SequenceForm["x + ", "i y"]], 
   StyleForm[")", FontSize->24]], 
   AxesLabel->{"x", "y", None}, 
   TextStyle->{FontSize->18, FontFamily->"Times"}]];

We can call the Live.class of LiveGraphics3D with the J/Link function AppletViewer:

AppletViewer["Live", {"INPUT="<>
   StringReplace[ToString[LiveForm[g]],"\""->"''"], 
   "WIDTH=400", "HEIGHT=400"}]

This will open a new window showing the applet. You can get some information from the applet by opening the Java console with

ShowJavaConsole[]

and then pressing the "o" key in the applet viewer. LiveGraphics3D will print most of the current option values to the Java console.

For more interaction with the LiveGraphics3D applet, we need an instance of the Java object. This is achieved this way:

applet = JavaNew["Live"];

AppletViewer[applet, {"INPUT="<>
   StringReplace[ToString[LiveForm[g]],"\""->"''"], 
   "WIDTH=400", "HEIGHT=400"}]

Now we can call public methods of the applet, e.g.

applet@setMagnification[0.5]

When an applet instance is no longer needed, we can release it with:

ReleaseJavaObject[applet]

There is in fact a set of public methods available for controlling the applet. All methods return a boolean, i.e. either True or False indicating whether they were successful or not. Some of the methods are related to parameters of the applet or mouse actions as listed in the table. Another table summarizes the functions for querying the current values. The syntax of the call within Mathematica is always as in the example above: applet-variable@method-name[values-for-arguments].

Note: Calling these methods from JavaScript is possible but relatively complicated. (I'm not sure how it works and what the limitations are.)

Parametrized graphics are a special kind of graphics which include variables. They are discussed in detail below. Here I will only give a small example to show how parametrized graphics are called with J/Link. The (very simple) example is constructed within Mathematica this way:

independentVariables = {x->3, y->2, z->1};

dependentVariables = {mx->x/2, my->y/2, mz->z/2};

g = Graphics3D[{Line[{{0, 0, 0}, {x, y, z}}], 
   PointSize[0.05], Point[{mx, my, mz}], 
   PointSize[0.1], Point[{x, y, z}], 
   Text[SequenceForm["x=", x], {x, y, z}, {0, 3}]}, 
   TextStyle->{FontSize->24}];

Show[g //. Join[independentVariables, dependentVariables]];

After starting J/Link, adding the directory of the file live.jar with AddToClassPath and defining the function LiveForm as above, we create and display a Java object with:

applet = JavaNew["Live"];

AppletViewer[applet, {"INPUT="<>
   StringReplace[ToString[LiveForm[g]],"\""->"''"], 
   "INDEPENDENT_VARIABLES="<>
   ToString[InputForm[N[independentVariables]]], 
   "DEPENDENT_VARIABLES="<>
   ToString[InputForm[N[dependentVariables]]],   
   "WIDTH=400", "HEIGHT=400"}];

It is now possible to drag the larger point by clicking it with the left mouse button and moving the mouse while holding the mouse button pressed. Current values of variables can be obtained with the help of the Java console and the "o" key or with the help of the public Java function getVariable:

applet@getVariable["x"]

Independent variables can also be set to new values with the help of the function setVariable. As always, the applet should be released when you no longer need it:

ReleaseJavaObject[applet]

This section is about using Mathematica to prepare and convert graphics produced with the help of Mathematica. Therefore, the reader is assumed to have a basic knowledge of Mathematica and the possibility to execute Mathematica commands.

Producing Graphics with Mathematica

There are some built-in commands to produce three-dimensional graphics with Mathematica: Plot3D, ParametricPlot3D and ListPlot3D. Three-dimensional graphics may also be built by combining graphics primitives like Point, Line, Polygon etc. in a Graphics3D object. There are also several standard packages like Graphics`ContourPlot3D`, Graphics`Graphics3D`, Graphics`PlotField3D`, Graphics`Polyhedra`, Graphics`Shapes` or Graphics`SurfaceOfRevolution` with more commands and three-dimensional objects.

Anyway, in many cases a Graphics3D object is produced, which has to be converted into an appropriate InputForm in order to be displayed by LiveGraphics3D. This convertion is explained in the subsection Converting Graphics3D Objects, while the subsection Converting Animations describes the combination of several Graphics3D objects in an animation. Finally the subsection Converting Other Graphical Objects discusses how to convert other types of graphical objects of Mathematica into Graphics3D objects. (This covers ContourGraphics, DensityGraphics and SurfaceGraphics.)

In general LiveGraphics3D will only be used to display graphics computed by Mathematica. However, the Graphics3D definition for a LiveGraphics3D applet can also be modified (or even created) manually. Additionally LiveGraphics might also be used to find good values for the Graphics3D options ViewPoint and ViewVertical (see above).

Converting Graphics3D Objects

In order to display any Graphics3D, ContourGraphics, DensityGraphics, or SurfaceGraphics object with LiveGraphics3D, it has to be converted into an appropriate InputForm. This is can be done with the function LiveForm as defined below. The function also converts lists of Graphics3D objects to animations and replaces all SequenceForms into StringForms to avoid problems with the formatting of SequenceForm.

LiveForm[graphics_, animOpts___] := 
   Module[{graphics3d = Switch[graphics, _ContourGraphics, 
   Graphics3D[SurfaceGraphics[graphics]], _DensityGraphics, 
   Graphics3D[SurfaceGraphics[graphics]], _SurfaceGraphics, 
   Graphics3D[graphics], _, graphics]//.SequenceForm[x___]:>
   StringForm[StringJoin[Table["``", {Length[{x}]}]], x]}, 
   Switch[graphics3d, _List, HoldForm[ShowAnimation][
   Map[LiveForm, graphics3d], InputForm[N[Flatten[{animOpts}]]]], 
   _, InputForm[N[graphics3d]]]];

If g is a Graphics3D object (for example returned by ParametricPlot3D) then the InputForm is generated by LiveForm[g]. The result can be pasted into a file, whose name is used as the value of the LiveGraphics3D parameter INPUT_FILE (see the example above).

The value of INPUT_FILE is expected to be the name of a file containing an InputForm of a LiveGraphics3D object. Certainly we can write such a file within Mathematica. Here is a function to do so:

WriteLiveForm[filename_, graphics_, animOpts___] := 
    Module[{ps,x}, ps=Unprotect[Real]; Format[x_Real, InputForm] := 
    OutputForm[NumberForm[x, 5, NumberFormat -> (If[#3 == "", #1, 
    SequenceForm[#1, "*^", #3]] &)]]; Protect@@ps;
    WriteString[filename, ToString[LiveForm[graphics, animOpts],
    CharacterEncoding->None]]; Close[filename];
    ps=Unprotect[Real]; Format[x_Real, InputForm] =.; Protect@@ps;];

If g is again a Graphics3D object then WriteLiveForm["test.m", g] will write an appropriate InputForm of g into a file called test.m in the current directory. (The Mathematica function Directory[] will display the name of the current directory, FileNames[] will list the names of the files in it and SetDirectory["directoy name"] will change it.)

If LiveGraphics3D does not accept an input it will display an error message including the critical part of the InputForm. However all correct Graphics3D objects accepted by Mathematica and converted as described above should work without difficulties.

However, in some cases LiveGraphics3D will not display the graphics in exactly the same way as Mathematica does. All differences and limitations are listed in the appendix Limitations.

Converting Animations

There are two different kinds of animations in LiveGraphics3D. (Simple spinning does not count as an animation here!) One is to animate a list of Graphics3D objects similarly to the Mathematica command ShowAnimation. The syntax to specify this list is ShowAnimation[gl, opts] with gl being a list of Graphics3D objects and opts a list (or sequence) of Graphics3D options or Mathematica's Cell options AnimationDirection and AnimationDisplayTime. (Lists of Graphics3D objects can be easily produced with the Table command of Mathematica.) AnimationDirection may be Forward, Backward, or ForwardBackward; AnimationDisplayTime specifies the minimum time each frame is displayed in seconds.

The function LiveForm[gl, opts] from above will produce the needed form; the function WriteLiveForm[filename, gl, opts] from above will write it to a file.

Since version 1.00 there is another way to specify an animation, which is the animation of a Graphics3D object that is parametrized by a time parameter. This is similar to the Animate command in Mathematica. Details about parametrized graphics are discussed below. The syntax of the Animate command in LiveGraphics3D is Animate[g, {var, from, to, step}, opts] where g is a parametrized Graphics3D object, var is the time variable, from is its starting value, to the maximum value, step the size of the time steps, and opts a list or sequence of animation options as discussed above. Note that the time parameter var has to be declared in the applet parameter INDEPENDENT_VARIABLES, although the initial value is specified by from. (See below for an explanation of INDEPENDENT_VARIABLES.)

The following definition (in addition to the previous definition for LiveForm) will produce an appropriate form when called with LiveForm[g, {var, from, to, step}, opts]. (Correspondingly, WriteLiveForm will use this function to write the expression to a file.)

LiveForm[graphics_, {var_, from_, to_, step_}, animOpts___] := 
    Module[{},HoldForm[Animate][LiveForm[graphics], 
    InputForm[N[{var,from,to,step}]],InputForm[N[Flatten[{animOpts}]]]]];

Converting Two-Dimensional Graphics

Simple two-dimensional graphics (Graphics objects) can be converted to three-dimensional graphics with the Mathematica command StackGraphics of the Graphics`Graphics3D` package and an appropriate setting of the ViewPoint option. However, in order to avoid any complications, even two-dimensional graphics should be constructed in three-dimensions with all z-coordinates being 0. In order to avoid rotations of two-dimensional graphics the applet parameter MOUSE_DRAG_ACTION should be set to NONE.

Converting Other Graphical Objects

ContourGraphics, DensityGraphics, and SurfaceGraphics have to be converted to Graphics3D objects before they can be used with LiveGraphics3D. This is done automatically by the functions LiveForm and WriteLiveForm defined above.

The following table includes several standard Mathematica functions, the type of their returned graphics and the command to convert an object called g of this type into a Graphics3D object. (ParametricPlot3D returns Graphics3D objects, thus it is not listed here.)

Parametrized Graphics (new in version 1.00)

Parametrized graphics are Graphics3D objects which contain mathematical expressions with undefined variables, e.g. Graphics3D[{Point[{x, y, 0.5*x}]}]. The display and interactive manipulation of such graphics is supported by LiveGraphics3D since version 1.00. The basic benefit of parametrized graphics is the possibility to interact with them by dragging points, i.e. when a user drags certain points, LiveGraphics3D will update the whole scene accordingly. An introduction to parametrized graphics with LiveGraphics3D is given in my talk Direct Manipulation of Parametrized Graphics, which was presented at the Mathematica Developer Conference 2001. There are also several documented examples of parametrized graphics available. The rest of this section covers (in this order) the initialization and definition of variables and details about the evaluation and specification of expressions in LiveGraphics3D.

As mentioned, parametrized graphics may contain expressions with variables, e.g. the x and y in our example Graphics3D[{Point[{x, y, 0.5*x}]}]. All variables have to be initialized or defined with the help of the applet parameters INDEPENDENT_VARIABLES and DEPENDENT_VARIABLES. (These declarations are required because the initial display of the graphics requires values for all variables in order to evaluate all expressions.)

The difference between independent and dependent variables is that independent variables may be manipulated by the user, while each dependent variable has a defined dependency on other variables, which is always enforced; thus the user may not manipulate dependent variables directly. The manipulation of independent variables is possible by dragging Point primitives with at least one coordinate that is specified directly by an independent variable. When the user drags such points, the corresponding independent variable changes its value according to the new position.

The applet parameter INDEPENDENT_VARIABLES has to be set to a list of rules of the form {identifier->number, ...}, e.g. {x->0, hello->3.1415}. This lists defines initial values for all independent variables. DEPENDENT_VARIABLES defines the dependent variables and their dependencies. Its value has to be a list of rules of the form {identifier->expression, ...}, e.g. {y->2*x, siny->Sin[y], aConstant->5, x->If[x<0,0,x]}. The expressions are simple Mathematica expressions as described below. Note that any dependent variable may depend on any independent variable, e.g. in this example the dependent variable y depends on the independent variable x. A dependent variable may also depend on preceding dependent variables, e.g. the second dependent variable siny depends on the first dependent variable y. A dependent variable may also be set to a constant value, e.g. aConstant->5. As dependent variables may not be manipulated by the user, such variables are in fact constants.

Advanced usage of DEPENDENT_VARIABLES: The rules in DEPENDENT_VARIABLES are actually used to assign new values to all dependent variables after any of the independent variables has been manipulated by the user. These assignments are performed sequentially by evaluating the expression of the right-hand side of each rule and setting the variable on the left-hand side to the result. In some cases it is convenient to use these assignments also for independent variables, e.g. in our example the rule x->If[x<0,0,x] sets x to 0 whenever the user tries to "drag" it to a negative value. (Note that x occurs also in INDEPENDENT_VARIABLES.) There may be any number of rules for an independent variable in the list of DEPENDENT_VARIABLES; however, there may only be one rule for each dependent variable. (It is just convenient to have multiple rules for an independent variable, while there is no reason to permit this for dependent variables.)

Parametrized graphics may contain simple Mathematica expressions instead of coordinates within some primitives and on the right-hand side of the rules in the DEPENDENT_VARIABLES, but nowhere else. In particular, you may use an expression instead of any coordinate in a Point, Polygon, or Line primtive. You may also use expressions in the second argument of the Text primitive. However, you may not put an expression around the mentioned primitives, or within the Cuboid primitive or in any directive, e.g. RGBColor, or option, e.g. ViewPoint.

Special expressions: The first argument of the Text primitive may not be an expression; however, you may specify the name of a variable. This variable is then evaluated and its numeric value is printed. (For general expressions, define a new dependent variable. If you want to specify the variable name itself, use quotation marks.) The primitive-level If is the only function that may be used outside of a primitive; e.g., If[x < 0, {RGBColor[1,0,0], Point[{x,0,0}]}, {RGBColor[0,0,1], Point[{x,1,0}]}]. There are two important restrictions for the primitive-level If: First, the first argument has to be a (Boolean) expression and all other arguments have to be lists of primitives and directives. (A single primitive or directive is automatically converted to a list of one element; thus, no directive in an argument can have an effect outside of this argument. Recursive lists and recursive primitive-level Ifs are permitted.) Second, any primitives that are in the "false" branches of a primitive-level If are not removed; rather they are just not displayed; however, all other computations are still performed even if this is not necessary. (Thus, there is almost no speed-up compared to displaying all primitives of all branches.)

Expressions in parametrized graphics have to be rather simple. All variables have to be floating-point numbers. (Boolean values are represented by 0. (False) and 1. (True).) This implies that variables cannot be complex or rational numbers, or other objects, e.g. Lists. If any expression evaluates to a complex value (or an undefined result), the whole evaluation fails and LiveGraphics3D uses a prior set of values for independent variable that leads to a successful evaluation. The syntax of expressions is restricted to very few elements: numbers, variables, operators, and built-in functions.

The lexical rules for numbers and variables follow the usual Mathematica conventions. Any variable has to be either an independent variable, i.e. it occurs in the list specified by INDEPENDENT_VARIABLES, or a dependent variable, i.e. it occurs in the list specified by DEPENDENT_VARIABLES, or it is one of the built-in mathematical constants. (The time parameter of an Animate object has to be included in the list of independent variables.)

The operators of Mathematica supported by LiveGraphics3D are listed in the table below.

LiveGraphics3D supports quite a few of Mathematica's functions, especially functions listed in the help browser's category "Mathematical Functions". In particular, most of the functions included in the subcategories "Basic Arithmetic", "Mathematical Constants", "Numerical Functions", and "Elementary Functions" are supported. A few other mathematical and non-mathematical functions are also supported. Note that all arguments and results are restricted to real values, i.e. if any argument or result is complex, the function will fail. The tables below list the supported functions. Note that only the indicated number of arguments is supported. Also note that some functions are only roughly approximated, in particular the factorial-related functions.

Formatting Text

In LiveGraphics3D the first argument of the Text primitive is restricted to a very small subset of Mathematica expressions. This subset allows for simple annotations of graphics with mathematical notation but does not support type-setting of complex equations. The same restrictions also apply for text expressions specified in the PlotLabel, AxesLabel and Ticks options. Basically, a text expression may be a string (enclosed in double-quotes: "..."; or enclosed in two pairs of single quotes: ''...''), a number, an identifier (which is evaluated to a number in cases of variables specified by the applet parameters INDEPENDENT_VARIABLES or DEPENDENT_VARIABLES), or one of the formatting functions StyleForm, HoldForm, SequenceForm, StringForm, Subscript, Superscript, Subsuperscript, Underscript, Overscript, Underoverscript, UnderBar, OverBar, OverVector, OverHat, OverTilde, and OverDot. The arguments of most of these functions may also be text expressions. A more formal description of the grammar for text expressions in LiveGraphics3D is given in the table below, which also includes the valid options for StyleForm (and for the Graphics3D option TextStyle). For more information about these functions, please consult the documentation of Mathematica. Here we will only discuss differences specific to LiveGraphics3D.

Note on text formatting functions within Mathematica: In order to use text formatting functions such as StringForm, Subscript, etc. within Mathematica for LiveGraphics3D, you should not use the Format function because the text formatting functions will not appear in the InputForm of a symbol formatted this way. Instead, you should define a separate symbol directly with text formatting functions, e.g.:

symB[i_,t_] := StringForm["`1`(`2`)", Subscript["B", i], t]

With this definition, symB[n, x] will usually be printed as B_n(x) within Mathematica but the InputForm will be StringForm["`1`(`2`)", Subscript["B", n], x]. This InputForm should be sent to LiveGraphics3D, which will print it as B_n(x).

Note on overscripts, underscripts, and baseline shifts: All formatting functions and in particular UnderBar, OverBar, etc. can only approximate the corresponding Mathematica functions. The first reason is that the implementation in LiveGraphics3D uses other characters than Mathematica to support more platforms and fonts. Another reason is the applet's unability to determine the height of an individual character; therefore, Overscript and Underscript will choose baseline shifts that are too large in order to guarantee non-overlapping characters with the default setting ScriptBaselineShifts->{0.6, 0.9, Automatic, Automatic} For UnderBar, OverBar, etc. LiveGraphics3D chooses different baseline shifts (default in these cases: ScriptBaselineShifts->{0.6, 0.9, 0.9, 1.2}) to better approximate the rendering in Mathematica. These shifts might be too small or too large depending on the specific platform, the chosen font, and the characters. In order to correct this, LiveGraphics3D allows you to specify a third and fourth number in the list given to the option ScriptBaselineShifts. These numbers have the same meaning as the first and second element but for underscripts and overscripts instead of subscripts and superscripts. The units of all four numbers are supposed to be the height of an "x", which is approximated by half the maximum height (ascent) of any character in the current font.

Examples: OverVector["v"] is represented internally as

StyleForm[Overscript["v","\[RightArrow]"], ScriptBaselineShifts->{0.6, 0.9, 0.9, 1.2}]

StyleForm[OverVector["v"], ScriptBaselineShifts->{0.6, 0.9, 0.9, 1.0}]

StyleForm[Overscript["v","\[RightVector]"],ScriptBaselineShifts->{0.6, 0.9, 0.9, 1.0}]

Note on special characters: There are many special characters in Mathematica which cannot be rendered by LiveGraphics3D. Nonetheless, LiveGraphics3D will send the correct unicode for most of these special characters to the Java Virtual Machine. If the particular unicode is supported by the font employed by the Java Virtual Machine, then at least a similar character will be rendered. However, many characters of Mathematica are application-specific unicode characters; thus, there is almost no chance to render them correctly.

Note on font subsitutions: The StyleForm option FontSubstitutions maps font names without trying the original names. The default is {"Times"->"TimesRoman", "TimesNewRoman"->"TimesRoman", "Roman"->"TimesRoman", "Arial"->"Helvetica", "Geneva"->"Helvetica", "System"->"Helvetica", "CourierNew"->"Courier", "Typewriter"->"Courier", "Monotype"->"Courier"}. "TimesRoman", "Helvetica", and "Courier" are the standard font families for Java 1.0. In Java 1.1 the standard font families are "Serif", "SansSerif", and "Monospaced"; but the Java 1.0 names are probably supported by more Java Virtual Machines. If you specify other FontSubstitions make sure to consider at least the substitution of "Times" by "TimesRoman" because the Mathematica documentation recommends the name "Times" for a serif font, while some Java Virtual Machines will actually use a sansserif font when an applet asks for the "Times" font. Since LiveGraphics3D performs no checking of the font returned by the Java Virtual Machine, it is quite unsafe to ask for any font except "TimesRoman", "Helvetica", and "Courier"; thus, all FontSubstitutions should map names to one of these three names (or one of the three Java 1.1 alternatives "Serif", "SansSerif", and "Monospaced").

Note on URLs: The non-Mathematica option URL may be set to a string containing a URL. If specified it changes the text primitive into a hyperlink. (If multiple URL options occur in one text primitive, one option is chosen by the applet.) Moreover, the string ",target=" may be appended followed by a "target" specification (as in the TARGET attribute of the HTML A tag). Here is a real-life example:

Text[StyleForm["Mathematica\.ae", 
FontFamily->"Times", 
FontSlant->"Italic",
FontSize->20,
URL->"http://www.wolfram.com,target=_self"], 
{1,1,0}, {0,-1}]

Limitations

This appendix describes most of the limitations of LiveGraphics3D compared to Mathematica.

All kinds of non-decimal numbers are not allowed. This is, however, no problem as all numbers have to be "numeric" anyway, thus it is always possible to use N[...] in order to make things work.

FontForm objects and the option DefaultFont are obsolete in Mathematica 3.0; thus, LiveGraphics3D does not support them. The first argument of the Text primitive is restricted as discussed above. All options to the Text primitive are ignored; please use an option of a StyleForm function instead. If specified, the Graphics3D option TextStyle has to be set to a list of StyleForm options.

There is subtle limitation of the primitive Cuboid. In short, the following four forms are not supported:

Cuboid[{..., ..., ...}, Scaled[{..., ..., ...}]]
Cuboid[Scaled[{..., ... , ...}], {..., ..., ...}]
Cuboid[Scaled[{..., ..., ...}], 
       Scaled[{..., ..., ...}, {..., ..., ...}]] 
Cuboid[Scaled[{..., ..., ...}, {..., ..., ...}], 
       Scaled[{..., ..., ...}]]

More important are the graphics directives that are not supported by LiveGraphics3D:

AbsoluteDashing[...]
Dashing[...]

(The scapegoat Java does not support dashed lines.)

Here is the list of ignored Graphics3D options:

These options are always set to their default values; except SphericalRegion, which is set to True, and ImageSize which is set to the values of the applet's attributes WIDTH and HEIGHT.

LiveGraphics3D does not "break" intersecting polygons, thus they are displayed incorrectly. In fact a quite simple painter algorithm is used to hide surfaces, which is far from being as good as the algorithms used in Mathematica. (Mathematica does offer to do this "breaking" for programs like LiveGraphics3D via the option PolygonIntersections, but it seems to produce always far too many polygons to be of any use.)

Because of this simple painter algorithm, occlusions of (in particular, large) graphical primitives are often incorrect. Sometimes it is possible to reduce or avoid these problems by breaking primitives into smaller ones within Mathematica (in particular, long lines should be avoided).

LiveGraphics3D does not clip primitives which are outside of the PlotRange.

In some situations the color of the wrong face of a polygon is used. The reason is the simple (but fast) alogrithm being used to decide which face is painted.

The shading is fixed, i.e. light sources are rotating with the graphics. Furthermore there are differences between the shading of Mathematica and LiveGraphics3D regarding the coordinate system in which light sources are defined and the formula for specular shading. There are also differences between Mathematica and its documentation, thus I do not take this point too seriously.

Thickness and PointSize specify lengths in units of the length of the diagonal of the bounding box (not in units of the width of the whole plot; however with SphericalRegion->True, which is always enforced by LiveGraphics3D, and a not too small ViewPoint vector there is almost no difference). Thus the thickness of lines and the size of points depends on the distance to the viewer, which is quite reasonable for three-dimensional graphics. On the other hand AbsoluteThickness and AbsolutePointSize specify constant lengths in pixels (not in printer points).

Text primitives may be hidden by other primitives.

PlotLabels appear at the top of the graphics (and not above the graphics). The value is restricted in the same way as the first argument of the Text primitive. (See above.)

There are some other small syntactical differences. For example EdgeForm is not allowed to have more than one argument (as documented in the Mathematica Book), while Mathematica seems to accept any number of arguments.

Revision History

This project was started on August 8th, 1997 as "Live.java". It was renamed to LiveGraphics3D with version -2.02. All changes since version -2.00 are listed here.