LiveGraphics3D is a non-commercial Java 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..
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.0 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.
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 class files on your local computer as described in the Installation section.
The section Converting 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.
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 |
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 key pressed plus vertical dragging | stripping parts of the graphics |
"o" key | printing parameter settings to Java console |
"s" key (new in version -1.60) | toggling between single picture, stereo pictures for diverge fusing and stereo pictures for cross fusing |
The META key is usually mapped to the ALTERNATE or COMMAND key. 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 key 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.)
problem | solution |
---|---|
no applet visible (not even a gray box) | Please use a web browser supporting Java 1.0 (or higher) and activate Java in the preferences/options menu. |
only a gray box visible (together with a Java error message by the browser) | Reload the web page. (Try pressing SHIFT together with the reload button and do not interact with the browser while loading the page.) |
LiveGraphics3D error message | First 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 | Please use a web browser supporting full Java 1.0 and ensure correct installation of fonts on your system. |
remaining problems | Empty all caches, deactivate any proxy, restart your web browser, try different web browsers or ask other people to try the URL. |
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 applet parameter MAGNIFICATION. Pressing CONTROL and dragging horizontally will change the applet 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.
However in order to use LiveGraphics3D in one of your own web pages you need the five compiled class files of LiveGraphics3D 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 compiled Java classes is that Java code is not displayed but executed!
Quick Start
You should be able to download the following five class files with your web browser and save same them on your local computer. (Please note: These files contain compiled, i. e. encoded Java instructions, thus you will not be able to read them. Nonetheless all web browsers supporting Java can read and execute them as soon as they get the HTML instruction to do so.)
class file | description |
---|---|
Live.class | the applet class |
Graphics3D.class | the internal representation of Mathematica's Graphics3D objects |
Parser.class | a parser for the syntax of Graphics3D objects |
Primitive3D.class | the internal representation of Graphics3D primitives |
Quaternion.class | a useful data type to specify rotations in three dimensions |
After copying these class files you may start to create HTML pages including LiveGraphics3D applets. The corresponding HTML files should be placed in the same directory as the Java class files. Here is a complete example:
<HTML> <APPLET CODE="Live.class" WIDTH=150 HEIGHT=150 ALIGN=LEFT> <PARAM NAME=BGCOLOR VALUE=#FFFFFF> <PARAM NAME=MAGNIFICATION VALUE=1.> <PARAM NAME=INPUT VALUE=" Graphics3D[{ (* ...primitives and directives... *) }, BoxRatios->{1,4,9} (* ...options... *)] "> </APPLET> </HTML>If placed in the directory of the class files 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 Applet Parameters which discusses the parameters of the LiveGraphics3D APPLET tag or to the section Converting Graphics with Mathematica for informations about converting Graphics3D (and other) objects to an InputForm appropriate for LiveGraphics3D.
Trouble Shooting
If the Java classes do not work as described, they were probably corrupted during the transmission. In this case please empty all caches, disable any proxy, download the class files again and restart your web browser, as it will use the corrupted class files 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.
Applet Parameters
The LiveGraphics3D applet can be controlled by setting several parameters, as demonstrated in the Quick Start subsection. Most of the parameters are optional, however CODE, WIDTH, HEIGHT and either INPUT or INPUT_FILE have to be specified.
The standard applet parameters 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 standard applet parameters.)
parameter | 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 . |
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 parameters the LiveGraphics3D applet offers additional
parameters controling the applet itself.
parameter | explanation |
---|---|
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 |
INITIAL_ROTATION | one angle in degrees (or two angles separated by a colon), 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_FILE | name of a file containing an InputForm of a Graphics3D or ShowAnimation object |
MAGNIFICATION | zoom factor (interactively modified by pressing SHIFT and dragging vertically) (see above) |
POINT_EDGE_COLOR | color for edges of all points in hexadecimal form |
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 |
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 applet 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 next section.
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 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 object with LiveGraphics3D, it has to be converted into an appropriate InputForm. This is most easily done with this function:
LiveForm[g_] := NumberForm[InputForm[N[g]], 5]If g is a Graphics3D object (for example returned by ParametricPlot3D) then the InputForm is generated by LiveForm[g]. The result can be used as a value of the LiveGraphics3D applet parameter INPUT (see the example above).
However this will not work with Graphics3D objects containing any double quotation marks ("). In these cases all the double quotes have to be replaced by two single quotes (''). Additionally spaces in strings might be lost with this convertion, as a space after a line break is ignored by LiveGraphics3D. The alternative use of the INPUT_FILE applet parameter (see above) instead of INPUT does avoid these problems.
The value of INPUT_FILE is expected to be the name of a file containing an InputForm of a LiveGraphics3D object. Here is a function to write such a file:
WriteLiveForm[filename_, g_] := ( WriteString[filename, ToString[NumberForm[InputForm[N[g]], 5]]]; Close[filename];)If g is again a Graphics3D object then WriteLiveForm["test.g3d", g] will write an appropriate InputForm of g into a file called test.g3d 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 Graphics3D objects accepted by Mathematica and converted as described above should work without difficulties (apart from the problems with strings which are avoided by using INPUT_FILE).
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
LiveGraphics3D is able to show a list of Graphics3D objects in an animation, while the user may rotate the system. (Therefore animations which just rotate static objects are not very sensible!) The syntax used by LiveGraphics3D 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.)
This function will return an appropriate InputForm:
LiveAnimationForm[gl_, opts_] := HoldForm[ShowAnimation][LiveForm[gl], LiveForm[opts]];(This definition uses the function LiveForm from above. opts must be a list of options, but may be empty.)
The following function (also using LiveForm from above) writes an animation to a file:
WriteLiveAnimationForm[filename_, gl_, opts_] := ( WriteString[filename, ToString[HoldForm[ShowAnimation][LiveForm[gl], LiveForm[opts]]]]; Close[filename];)
Converting Other Objects
As the use of Graphics3D objects with LiveGraphics3D is described in the previous subsections, this subsection will only discuss how to convert other types of graphics into the Graphics3D format with the help of Mathematica.
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] |
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.
Double quotes cannot be used, if the InputForm of the Graphics3D object is put into an HTML page. However double quotes appear usually only in Text primitives, thus you need not worry about them if you do not use text. Otherwise you have to replace each double quote (") by two single quotes ('') or use a separate file for the Graphics3D object as explained above.
The usage of the Text primitive is quite limited. First of all the first argument has to be a string enclosed in doubled single quotes (or double quotes in a separate file), e.g. Text[''hello'', {0,0,0}], or a StyleForm object containing a string enclosed in doubled single 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. Here is a real-life example:
Text[StyleForm[''Mathematica\.ae'', FontFamily->''TimesRoman'', FontSlant->''Italic'', FontSize->20, URL->''http://www.wolfram.com/''], {1,1,0}, {0,-1}](You may use double quotes if the Graphics3D description is in a separate file.)
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 | RenderAll |
ColorOutput | Plot3Matrix | Shading |
DisplayFunction | PlotLabel | SphericalRegion |
Epilog | PlotRegion | ViewCenter |
FaceGrids | PolygonIntersections | |
FormatType | Prolog |
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 parameters 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 much 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 formular 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.
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
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 |