What Is LiveGraphics3D?
LiveGraphics3D is a non-commercial Java 1.1 applet to display and rotate three-dimensional graphics produced by Mathematica in HTML pages. It may be used without charge for any non-commercial purposes. Mathematica is a program for symbolic and numeric mathematics by Wolfram Research, Inc.. Wolfram Research is also responsible for licensing LiveGraphics3D for commercial purposes.
LiveGraphics3D enables all Mathematica users to put almost any three-dimensional graphics computed by Mathematica directly onto a HTML page, such that everyone with a web browser supporting Java 1.1 (e.g. Communicator 4.0 or Internet Explorer 4.0 or higher) can view and interactively rotate the graphics without any additional software.
Additionally LiveGraphics3D is able to show animations, calculate stereo graphics, integrate hyperlinks, 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.
What to Read Next?
In order to learn how to rotate, zoom, strip, and animate graphics displayed by LiveGraphics3D you should read the User Interface section. (A subsection about Trouble Shooting is included.)If you want to use LiveGraphics3D in your own HTML pages, you do not have to know anything about Java programming, as all needed classes are already compiled. However, you have to install the Java archive live.jar on your local computer as described in the Installation section.
The section Preparing Graphics with Mathematica gives additional information and tips about producing and converting three-dimensional graphics with Mathematica.
If you have any comments, critisism, bug reports, or ideas concerning this software or its documentation please e-mail me.
Quick Start
In order to view LiveGraphics3D applets you have to use a web browser supporting Java 1.1 (e.g. Communicator 4.0 or Internet Explorer 4.0) and activate Java in the options or preferences menu (if not activated already).
After a LiveGraphics3D applet has successfully initialized itself the following interactions are always supported.
user action | applet reaction |
---|---|
dragging (left mouse button pressed) | rotating about an axis in the picture |
releasing left mouse button while dragging | spinning about an axis in the picture |
SHIFT key pressed plus vertical dragging | zooming |
SHIFT key pressed plus horizontal dragging | rotating about an axis perpendicular to the picture |
CONTROL key pressed plus vertical dragging | changing focal length |
CONTROL key pressed plus horizontal dragging | changing strength of stereo effect |
META (ALT) key (or right mouse button) pressed plus vertical dragging | stripping parts of the graphics |
"o" key | printing parameter settings to the Java console (aka Java messages window) |
"s" key | toggling between single picture, stereo pictures for diverge fusing and stereo pictures for cross fusing |
HOME key | restoring original perspective (no spinning) |
The META key is usually mapped to the ALTERNATE or COMMAND key. However, on some systems it is emulated by the right mouse button. Rotation about an axis perpendicular to the picture is not possible if a rotating background is included.
Several additional interactions are supported for animations.
user action | applet reaction |
---|---|
entering applet region | starting animation |
leaving applet region | stopping animation |
double clicking | stopping or restarting animation |
META (ALT) key (or right mouse button) pressed plus horizontal dragging | switching through frames |
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 Java applets in general) can be solved by reloading the applet. In order to do so you have to hold down SHIFT (Netscape) or CONTROL (Internet Explorer) when clicking the reload button (otherwise only the HTML code but not the Java code of the applet is reloaded).
problem | solution |
---|---|
no applet visible (not even a gray box) | Please use a web browser supporting Java and activate Java in the preferences/options menu. |
only a gray box visible (together with a Java error message by the browser) | If the error message is something about not finding "Live.class",
then you should update your web browser, as Java 1.1 has to be
supported. (Communicator 4.0 (or higher), IE 4.0 (or higher) or any
browser using MRJ 2.1 do support Java 1.1.) Otherwise you should reload the web page. |
only initialization picture visible (together with a Java error message by the browser) | Reload the web page. If possible, deactivate the JIT compiler in the preference menu of you browser. |
LiveGraphics3D error message | Make sure to use Java 1.1 (see above). Then deactivate any proxy, restart your web browser and reload the page. If the problem remains, contact the owner of the page. |
special characters not displayed | Unfortunately many popular web browser do not support special characters in Java applets. (Though this was already part of the definition of Java 1.0.) Under MacOS you can use MRJ 2.1 together with IE or iCab. |
remaining problems | Try pressing SHIFT (Netscape) or CONTROL (Internet Explorer) when clicking the reload button and do not interact with the browser while loading the page; empty all caches, deactivate any proxy, and restart your web browser; try different web browsers, operating systems, or machines; ask other people to try the URL on their machine. |
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.
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 to view the graphics from all directions. However, the presence of rotating bitmap backgrounds changes this prescription as 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 Java console by pressing the "o" key while the mouse cursor is in the region of the Java applet. Web browsers supporting Java should be (and usually are) able to display the Java console. If you are using LiveGraphics3D on your own HTML page, you may copy the line containing MAGNIFICATION or STEREO_DISTANCE 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 pages using LiveGraphics3D, as your web browser automatically loads and executes the needed Java archive if necessary.
However, in order to use LiveGraphics3D in one of your own web pages you need 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 Java archive is that Java code is not displayed but executed!
Quick Start
You should be able to download the Java archive live.jar with your web browser and save it on your local computer. (Usually you will have to press SHIFT when clicking on the link above or click with the right mouse button and save the file as "binary" or "source".) MacOS users should download the BinHex version live.hqx and decode it to live.jar on their local file system.
Note that LiveGraphics3D is free for non-commercial purposes only. Please contact the author if you want to use it for commercial purposes.
After copying live.jar you may start to create HTML pages including LiveGraphics3D applets. The corresponding HTML files should be placed in the same directory as the live.jar file. 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... *)]Then we need an HTML page. Here is a simple example:
<HTML> <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"> </APPLET> </HTML>
Please note that all texts in quotation marks are case sensitive! (I also recommend to use upper case letters for the NAMEs of PARAMeters, though, lower case letters work with most web browsers.)
If placed in the directory of the Java archive live.jar together with the file test.m on your computer this HTML page should produce the following LiveGraphics3D applet:
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
If the Java archive does not work as described, it was probably corrupted during the transmission. In this case please empty all caches, disable any proxy, restart your web browser and download the Java archive live.jar again (MacOS users should download live.hqx and decode it on their local file system) and restart your web browser once again, as it might use the corrupted archive otherwise. If this does not solve the problem, you might try to use another web browser or even switch to another operating system if possible. In any case reports of problems are always welcomed.
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 or HTML 3.2 Reference Specification for the official list of attributes.)
attribute | explanation |
---|---|
ALT | alternate text for text-only display |
ALIGN | where to place the applet within the page: LEFT, RIGHT, TOP, TEXTTOP, MIDDLE, ABSMIDDLE, BASELINE, BOTTOM, ABSBOTTOM . |
ARCHIVE | name of the Java archive, must be "live.jar" for LiveGraphics3D |
CODE | name of the class file, must be "Live.class" for LiveGraphics3D |
CODEBASE | directory name or URL, specifying where to find the class file |
HEIGHT | height of the applet's box in pixels |
HSPACE | space to leave around the applet horizontally |
NAME | name of the applet (not used in LiveGraphics3D) |
VSPACE | space to leave around the applet vertically |
WIDTH | width of the applet's box in pixels |
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.)
parameter | explanation |
---|---|
AUDIO_ENTER | file name of an audio file (".au" format); played whenever the mouse enters the applet |
AUDIO_LOOP_ENTER | same as AUDIO_ENTER but played in a loop |
AUDIO_FIRST_FRAME | same as AUDIO_ENTER but played whenever the first frame of an animation is displayed |
BACKGROUND | file name of a JPEG or GIF image to be displayed as fixed background |
BGCOLOR | background color in hexadecimal form |
CYLINDRICAL_BACKGROUND | file name of a JPEG or GIF image to be displayed as a cylindrical background |
DEPENDENT_VARIABLES | a list of replacement rules for dependent variables of the form {variable->expression, ...}. |
INDEPENDENT_VARIABLES | a list of replacement rules for initialization values of independent variables of the form {variable->number, ...}. |
INITIAL_ROTATION | one angle in degrees (or two angles separated by a comma), specifying an initial rotation or a label for the angle(s) which has to be defined in the reference part of the URL |
INPUT | string containing an InputForm of a Graphics3D or ShowAnimation object enclosed in quotation marks (") |
INPUT_ARCHIVE | name of a zip archive (created for example with the zip program, see Info-ZIP) containing the INPUT_FILE. (INPUT_FILE has to be set to the name of the file inside the zip archive.) |
INPUT_FILE | name of a file containing an InputForm of a Graphics3D or ShowAnimation object. (This file may be inside a zip archive, see INPUT_ARCHIVE.) |
MAGNIFICATION | zoom factor (interactively modified by pressing SHIFT and dragging vertically) (see above) |
MOUSE_DRAG_ACTION | applet reaction initiated by dragging the mouse. (Default is rotating, use NONE in order to disable rotating, which is useful for 2D graphics.) |
POINT_EDGE_COLOR | color for edges of all points in hexadecimal form |
PRELOAD_BACKGROUND | file name of a JPEG or GIF image to be displayed while other files are loaded and parsed |
RIGHT_BACKGROUND | file name of a second background image for the right eye (should have the same size) |
SPHERICAL_BACKGROUND | file name of a JPEG or GIF image to be displayed as a spherical background |
SPIN_X | default spinning velocity about a vertical axis, specified by the corresponding mouse movement in pixels per frame. The frame rate is either 0.05 sec or defined by the AnimationDisplayTime option in an animation. |
SPIN_Y | same as SPIN_X for a default spinning velocity about a horizontal axis. |
STEREO_DISTANCE | distance between the two stereo view points in units of the length of the diagonal of the bounding box (positive values for diverge fusing, negative values for cross fusing; see above) |
VISIBLE_FACES | determines which faces of polygons to draw. (Default is to draw both; the value FRONT will draw only front faces, the value BACK only back faces.) |
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. Please note: Some web browser do not allow Java applets like LiveGraphics3D to load images from the local file system. (Thus, do not use these web browsers.) If LiveGraphics3D cannot load an image it gets stuck in an endless loop.
If the value of the parameter INITIAL_ROTATION is a label instead of a number, the applet will look in the reference part of the URL (the part following a "#") for a definition of the form "label=number" or "label=number,number". In any case the first number is interpreted as a rotation angle in degrees about a vertical axis, the optional second number defines a rotation about a horizontal axis.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 in the below.
Interfacing with J/Link (new in version 0.30)
J/Link is a toolkit from Wolfram Research which allows Mathematica users to call Java applets from within Mathematica. Assuming you have installed J/Link correctly and that the file live.jar is in the CLASSPATH the following code will open a new window containing a LiveGraphics3D applet:
g = Graphics3D[Plot3D[Sin[x y], {x, -2, 2}, {y, -2, 2}]]; << JLink` InstallJava[] liveApplet = JavaNew["Live"] liveFrame = JavaNew["com.wolfram.jlink.MathAppletFrame", liveApplet, {"INPUT=" <> ToString[InputForm[N[g]]], "WIDTH=400", "HEIGHT=400"}];
These commands should call the Java interpreter and display the applet in a new window. Converting a Graphics3D object like g is simply done by ToString[InputForm[N[g]]] because the number of digits per number is less important in this context.
You can now control the applet from within Mathematica by calling Java methods. For example, we can change the magnification not only by dragging but also with a Mathematica command:
liveApplet@setMagnification[1.5]
There is a 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. The syntax of the call within Mathematica is always as in the example above: applet-variable@method-name[values-for-arguments].
method | explanation | parameter/mouse action |
---|---|---|
boolean setFrame(int new_frame_index) | sets the frame index for animations | ALT + dragging horizontally |
boolean setGraphics3D(String input_text) | sets a new Graphics3D object | INPUT |
boolean setMagnification(double new_magnification) | sets the magnification factor | MAGNIFICATION, SHIFT + dragging vertically |
boolean setSpin(double new_spin_x, double new_spin_y) | sets the spin velocity | SPIN_X, SPIN_Y |
boolean setStereoDistance(double new_stereo_distance) | sets the stereo distance (0: no stereo) | STEREO_DISTANCE, CTRL + dragging horizontally |
boolean setStrippedPrimitives(int new_stripped_primitives_count) | sets the number of stripped primitives | ALT + dragging vertically |
boolean setVariable(String name, double value) | sets an independent variable | dragging points |
boolean setViewPointAndViewVertical(double vpx, vpy, vpz, vvx, vvy, vvz) | sets the view point | ViewPoint and ViewVertical option, simple dragging |
There are also methods to query the current values.
method | explanation |
---|---|
int getFrame() | gets the frame index of animations |
double getMagnification() | gets the magnification factor |
double getSpinY(), double getSpinY() | gets the spin velocity |
double getStereoDistance() | gets the stereo distance |
int getStrippedPrimitives() | gets the number of stripped primitives |
double getVariable(String name) | gets the value of any variable |
double getVersion() | gets the version number of the applet |
double getViewPointX(), double getViewPointY(), ... | gets the view point |
double getViewVerticalX(), double getViewVerticalY(), ... | gets the view vertical |
If you want to open several applets, you have to create new instances of both, the Live class and the MathAppletFrame class.
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 some cases a preprocessing of the Mathematica graphics is appropriate, e.g. when there are intersections of polygons. Together with Eric W. Weisstein I have written a Mathematica package LiveGraphics3D.m which attacks these problems. Eric has also written a small demo for it: LiveGraphics3DDemo.nb.
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 this function (which also converts lists of Graphics3D objects to animations):
LiveForm[graphics_, animOpts___] := Module[{graphics3d = Switch[graphics, _ContourGraphics, Graphics3D[SurfaceGraphics[graphics]], _DensityGraphics, Graphics3D[SurfaceGraphics[graphics]], _SurfaceGraphics, Graphics3D[graphics], _, graphics]}, Switch[graphics3d, _List, HoldForm[ShowAnimation][NumberForm[InputForm[N[graphics3d]], 5], InputForm[N[Flatten[{animOpts}]]]], _, NumberForm[InputForm[N[graphics3d]], 5]]];
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 function 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][NumberForm[InputForm[N[graphics]], 4], 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 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.)
function | return type | command to convert object g |
---|---|---|
ContourPlot ListContourPlot |
ContourGraphics | Graphics3D[SurfaceGraphics[g]] |
DensityPlot ListDensityPlot |
DensityGraphics | Graphics3D[SurfaceGraphics[g]] |
Plot3D ListPlot3D |
SurfaceGraphics | Graphics3D[g] |
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 occures 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.
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.
operator form | full form | grouping |
---|---|---|
expr! | Factorial[expr] | |
expr!! | Factorial2[expr] | |
expr1^expr2 | Power[expr1, expr2] | e^(e^e) |
-expr | Times[-1, expr] | |
+expr | expr | |
expr1 / expr2 | expr1 (expr2)^-1 | (e / e) / e |
expr1 expr2 expr3 | Times[expr1, expr2, expr3] | e e e |
expr1 * expr2 * expr3 | Times[expr1, expr2, expr3] | e * e * e |
expr1 + expr2 + expr3 | Plus[expr1, expr2, expr3] | e + e + e |
expr1 - expr2 | expr1 + (-1 expr2) | (e - e) - e |
expr1 == expr2 | Equal[expr1, expr2] | e == e == e |
expr1 != expr2 | Unequal[expr1, expr2] | e != e != e |
expr1 > expr2 | Greater[expr1, expr2] | e > e > e |
expr1 >= expr2 | GreaterEqual[expr1, expr2] | e >= e >= e |
expr1 < expr2 | Less[expr1, expr2] | e < e < e |
expr1 <= expr2 | LessEqual[expr1, expr2] | e <= e <= e |
!expr | Not[expr] | !(!e) |
expr1 && expr2 && expr3 | And[expr1, expr2, expr3] | e && e && e |
expr1 || expr2 || expr3 | Or[expr1, expr2, expr3] | e || e || e |
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.
Basic Arithmetic | |
---|---|
Plus[expr1, expr2, ...] | expr1 + expr2 + ... |
Subtract[expr1, expr2, ...] | expr1 - expr2 - ... |
Minus[expr] | -expr |
Times[expr1, expr2, ...] | expr1 expr2 ... |
Subtract[expr1, expr2] | expr1 - expr2 |
Divide[expr1, expr2] | expr1 / expr2 |
Power[expr1, expr2, ...] | expr1 ^ expr2 ^ ... |
Mathematical Constants | |
Pi | 3.141592653589793238462643 |
E | 2.718281828459045235360287 |
Degree | 0.017453292519943295769237 |
GoldenRatio | 1.618033988749894848204587 |
EulerGamma | 0.577215664901532860606512 |
Catalan | 0.915965594177219015054604 |
Khinchin | 2.685452001065306445309715 |
Glaisher | 1.282427129100622636875343 |
I, Infinity, Indeterminate, ComplexInfinity |
in LiveGraphics3D: NaN (not a number) |
Numerical Functions | |
Abs[expr] | |
Sign[expr] | |
Round[expr] | |
IntegerPart[expr] | |
FractionalPart[expr] | |
Floor[expr] | |
Ceiling[expr] | |
Chop[expr] | |
Max[expr1, expr2, ...] | |
Min[expr1, expr2, ...] | |
Re[expr] | in LiveGraphics3D: expr |
Im[expr] | in LiveGraphics3D: 0 |
Conjugate[expr] | in LiveGraphics3D: expr |
Arg[expr] | in LiveGraphics3D: 0 or Pi |
Mod[expr1, expr2] | |
Quotient[expr1, expr2] | |
Random Numbers | |
Random[] | |
SeedRandom[] | |
SeedRandom[expr] | |
Elementary Functions | |
Log[expr] | |
Log[expr1, expr2] | |
Exp[expr] | |
Power[expr1, expr2, ...] | expr1 ^ expr2 ^ ... |
Sqrt[expr] | |
Sin[expr] | |
Cos[expr] | |
Tan[expr] | |
Csc[expr] | |
Sec[expr] | |
Cot[expr] | |
ArcSin[expr] | |
ArcCos[expr] | |
ArcTan[expr] | |
ArcTan[expr1, expr2] | |
ArcCsc[expr] | |
ArcSec[expr] | |
ArcCot[expr] | |
Sinh[expr] | |
Cosh[expr] | |
Tanh[expr] | |
Csch[expr] | |
Sech[expr] | |
Coth[expr] | |
ArcSinh[expr] | |
ArcCosh[expr] | |
ArcTanh[expr] | |
ArcCsch[expr] | |
ArcSech[expr] | |
ArcCoth[expr] | |
Factorial Related | |
Factorial[expr] | expr! |
Factorial2[expr] | expr!! |
Binomial[expr1, expr2] | |
Multinomial[expr1, expr2, ...] | |
Pochhammer[expr1, expr2] | |
Gamma[expr] | |
Beta[expr1, expr2] | |
LogGamma[expr] | |
Number Theory | |
Mod[expr1, expr2] | |
PowerMod[expr1, expr2, expr3] | |
Quotient[expr1, expr2] | |
Hypergeometric Related | |
Erf[expr] | |
Erf[expr1, expr2] | |
Erfc[expr] | |
Erfi[expr] | |
Gamma[expr] | |
Beta[expr1, expr2] | |
Generalized and Related Functions | |
DiscreteDelta[expr1, expr2, ...] | |
KroneckerDelta[expr1, expr2, ...] | |
UnitStep[expr1, expr2, ...] |
Numerical Computation | |
---|---|
N[expr] | in LiveGraphics3D: expr |
Programming > Tests | |
Equal[expr1, expr2, ...] | expr1 == expr2 == ... |
Unequal[expr1, expr2, ...] | expr1 != expr2 != ... |
Less[expr1, expr2, ...] | expr1 < expr2 < ... |
Greater[expr1, expr2, ...] | expr1 > expr2 > ... |
LessEqual[expr1, expr2, ...] | expr1 <= expr2 <= ... |
GreaterEqual[expr1, expr2, ...] | expr1 >= expr2 >= ... |
NumberQ[expr] | in LiveGraphics3D: True (1.0) |
NumericQ[expr] | in LiveGraphics3D: True (1.0) |
IntegerQ[expr] | |
EvenQ[expr] | |
OddQ[expr] | |
Positive[expr] | |
Negative[expr] | |
NonPositive[expr] | |
NonNegative[expr] | |
TrueQ[expr] | |
ValueQ[expr] | in LiveGraphics3D: True (1.0) |
Programming > Logical Operations | |
Not[expr] | !expr |
And[expr1, expr2, ...] | expr1 && expr2 && ... |
Or[expr1, expr2, ...] | expr1 || expr2 || ... |
Xor[expr1, expr2, ...] | |
Implies[expr1, expr2] | |
True | in LiveGraphics3D: 1.0 |
False | in LiveGraphics3D: 0.0 |
Programming > Flow Control | |
If[expr1, expr2] | |
If[expr1, expr2, expr3] | |
If[expr1, expr2, expr3, expr4] | |
Which[expr1, expr2, ...] | (even number of arguments!) |
Switch[expr1, expr2, expr3, ...] | (uneven number of arguments!) |
Programming > Functional Programming | |
Identity[expr] | |
Programming > Evaluation Control | |
Evaluate[expr] | in LiveGraphics3D: expr |
Hold[expr] | in LiveGraphics3D: expr |
HoldComplete[expr] | in LiveGraphics3D: expr |
HoldForm[expr] | in LiveGraphics3D: expr |
ReleaseHold[expr] | in LiveGraphics3D: expr |
Input and Output > Format Types | |
StandardForm[expr] | in LiveGraphics3D: expr |
TraditionalForm[expr] | in LiveGraphics3D: expr |
InputForm[expr] | in LiveGraphics3D: expr |
OutputForm[expr] | in LiveGraphics3D: expr |
DisplayForm[expr] | in LiveGraphics3D: expr |
FullForm[expr] | in LiveGraphics3D: expr |
Input and Output > Number Formatting | |
NumberForm[expr] | in LiveGraphics3D: expr |
ScientificForm[expr] | in LiveGraphics3D: expr |
EngineeringForm[expr] | in LiveGraphics3D: expr |
PaddedForm[expr] | in LiveGraphics3D: expr |
System Interface > Time and Date | |
AbsoluteTime[] |
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.
The usage of the Text primitive is quite limited. First of all the first argument has to be a string enclosed in double quotes, e.g. Text["hello", {0,0,0}], or a StyleForm object containing a string enclosed in double quotes, e.g. Text[StyleForm["big hello", FontSize->24], {0,0,0}]. The second argument has to be a three-dimensional point and the optional third argument a two-dimensional point. Following arguments or options are ignored. The following options to StyleForm are supported: FontFamily (should be "Courier", "TimesRoman" or "Helvetica"), FontSize, FontWeight (only "Plain" and "Bold"), FontSlant (only "Plain" and "Italic"), FontColor and Background. Additionally the non-Mathematica option URL might be set to a string containing a URL and therefore changing the text into a hyperlink. 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->"TimesRoman", FontSlant->"Italic", FontSize->20, URL->"http://www.wolfram.com,target=_self"], {1,1,0}, {0,-1}]
FontForm objects and the option DefaultFont are obsolete in Mathematica 3.0; thus, LiveGraphics3D does not support them.
There is another limitation concerning the primitive Cuboid. In fact it is quite subtle and difficult to explain. In short the following four forms are not supported:
Cuboid[{..., ..., ...}, Scaled[{..., ..., ...}]] Cuboid[Scaled[{..., ... , ...}], {..., ..., ...}] Cuboid[Scaled[{..., ..., ...}], Scaled[{..., ..., ...}, {..., ..., ...}]] Cuboid[Scaled[{..., ..., ...}, {..., ..., ...}], Scaled[{..., ..., ...}]]
More important are the not supported graphics directives:
AbsoluteDashing[...] Dashing[...]
(The scapegoat Java does not support dashed lines.)
Here is the list of ignored options:
AspectRatio | ImageSize | Shading |
ColorOutput | Plot3Matrix | SphericalRegion |
DisplayFunction | PlotRegion | ViewCenter |
Epilog | PolygonIntersections | |
FaceGrids | Prolog | |
FormatType | RenderAll |
These options might be imagined to be set to their default values automatically. With the exception of SphericalRegion which is set to True and ImageSize which is set to the values of the applet's attributes WIDTH and HEIGHT.
If specified the option TextStyle has to be set to a list of font options. (See the remark on StyleForm above.)
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.)
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 concerning 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 lengthes 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 spectator, which is quite reasonable for three-dimensional graphics. On the other hand AbsoluteThickness and AbsolutePointSize specify constant lengthes 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.
version | new |
---|---|
-1.90 | improved calculation of normals of polygons scanning of integers with integer arithmetic FaceForm with one argument |
-1.80 | improved PlotRange implemented ShowAnimation incompatible change of MAGNIFICATION if Ticks or AxesLabel are used |
-1.70 | animations accelerated double clicking to stop/restart animations default value of AnimationDisplayTime now 0.05 |
-1.60 | improved double clicking implemented stereo graphics changed effect of CONTROL + horizontal dragging |
-1.55 | removed problem with first click on animations implemented INITIAL_ROTATION |
-1.54 | corrected Hue improved drawing of thin lines |
-1.50 | additional default light source |
-1.40 | implemented VISIBLE_FACES |
-1.25 | implemented spinning including SPIN_X and
SPIN_Y improved calculation of normals of polygons (once again) implemented identification of lines which are edges of polygons |
-1.00 | implemented AUDIO_... parameters |
-0.90 | implemented PlotLabel improved dragging interface |
-0.75 | switched to Java 1.1 and Java archive
live.jar reimplemented spinning interface implemented INPUT_ARCHIVE added start-up picture |
-0.74 | improved spinning interface improved work-around for IE applet size bug parameter INPUT is now obsolete |
-0.70 | implemented PRELOAD_BACKGROUND |
0.01 | implemented third argument of Polygon implemented HOME key improved parsing of real parameters SPIN_X and SPIN_Y are now reals "o" key is printing SPIN_X and SPIN_Y debugged INITIAL_ROTATION implemented stopping |
0.30 | implemented ",target=" extension of URL option implemented control methods for J/Link INPUT parameter no longer obsolete |
0.50 | included work around for bug in the JIT compiler of the Microsoft Java Virtual Machine |
1.00 | implemented parametrized graphics, including Animate, INDEPENDENT_VARIABLES, DEPENDENT_VARIABLES, and MOUSE_DRAG_ACTION. |
1.10 | fixed n-gon bug (n > 4) implemented more control and query methods |
1.20 | introduced a serious bug (don't use this version!) fixed IE problem with small points fixed problem with Scaled coordinates replaced deprecated String() constructor |
1.30 | fixed the bug introduced in 1.20 |