Overview of Graphics 3D Syntax

Introduction

This document is a brief introduction to a way to specifiy three dimensional graphics. The Graphics3D commands can be placed into a file and used by other programs (JavaApplets such as JavaView or LiveGraphics3D) to make interactive web pages. (See the Reference section at the very bottom of this document to see the source of this document.)

Lists

A list is one of the basic objects in Mathematica. Elements of a list are separated by commas and are surrounded by curly brackets:

{1,2,3}

In this article we will use two different types of lists. The first is a list of three numbers, like the example above; this is how Mathematica represents coordinates in three-dimensions. The second is a list of graphical objects to be plotted on the screen; more on that below.

Graphics3D Objects

A three-dimensional picture is represented with the following syntax.

Graphics3D[ list of graphics primitives, list of graphics options ]

Graphics primitive is a name given to objects such as points and polygons. These are all defined in terms of coordinates which, as mentioned above, are represented by a list of three numbers. Hence the origin in three-dimensional space is written:

{0, 0, 0}

The rest of this overview covers the most common graphics primitives and options.

Graphics Primitives

This article uses four basic graphics primitives: points, lines, polygons and text. Each is described below.

Points

To draw a three-dimensional point, use the Point primitive. The only argument is the list of coordinates.

Point[{1,2,3}]

Lines

A line segment between two points is created using the Line primitive, together with a list of at least the two points.

Line[{{0,0,0}, {1,2,3}}]

A longer list of points, e.g.

Line[{{1,1,-1},{-1,1,-1},{-1,-1,-1},{1,-1,-1},{1,1,-1}}]

will draw segments between each pair of adjacent points in the list. Take a look at the square in the example below.

Polygons

A filled-in polygon is described by the Polygon primitive, together with an ordered list of its vertices. The following primitive represents the unit square in the plane z=0.

Polygon[{{0,0,0}, {1,0,0}, {1,1,0}, {0,1,0}}]

Graphics Directives

The appearance of a graphics primitive can be altered using special functions known as graphics directives. The most common of these include:

RGBColor[r,g,b]: represents a color using the standard Red-Green-Blue color model. The arguments represent the percentage of red, green and blue light, respectively, and are given as a decimal between 0 and 1.
PointSize[value]: adjusts the size of a Point. The default value is 0.01, and 0.05 is already quite large.
Thickness[value]: adjusts the thickness of a Line. The default value is 0.01.

There are complicated issues involving lists and the "scope" of a directive, but at the most basic level you use them by replacing a primitive (such as Point[{1,2,3}] with a list. The last element of the list should be the primitive; the preceding elements are directives. For example,

{RGBColor[1,0,0], PointSize[0.05], Point[{1,2,3}]}.

Graphics3D Options

Options for Graphics3D objects are invoked using the format OptionName -> Setting. While there are too many options to mention here, we can describe a few of the more commonly used ones.

PlotRange: specifies the bounding box of the graphics. The minimum and maximum values for the x, y, and z axes are specified in the form {{xmin, xmax}, {ymin, ymax}, {zmin, zmax}}. While Mathematica clips all objects at this bounding box, LiveGraphics3D performs no clipping. In both cases, the bounding box (in particular its center) is crucial for projecting, rotating, and zooming the graphics. The default value Automatic determines the bounding box based on the primitives of the graphics.
BoxRatios: specifies the ratios of the edge lengths of the diplayed bounding box. A value of {sx, sy, sz} will scale the edges in x, y, and z direction such that the ratios between displayed edge lengths are sx : sy : sz. For example, a value of {1, 1, 1} will display any bounding box as a cube. The default value Automatic determines these ratios according to the coordinate ranges covered by the bounding box as specified by the PlotRange option.
Boxed: specifies whether or not the bounding box should be drawn. Can be set to True or False.
Lighting: specifies whether or not to use the default lighting for polygons. (See the saddle-shaped surface in the Polygon section to see an example with this lighting model.) By default this option is set to True. Enabled lighting will use colors specified with SurfaceColor and light sources specified with LightSources to light polygons. I suggest you set this to False
ViewPoint specifies the view point {x, y, z} at which the viewer is located. The magnitude of this vector determines the strength of perspective warping, i.e., a large magnitude will reduce the perspective warping. The default magnitude is about 3.4.
ViewVertical specifies the "up direction" of the viewer. The default {0, 0, 1} describes viewers whose head is pointing into z direction.

Putting Everything Together

Compare the input for JavaView shown here to the picture you see in the applet. If you can see how the primitives, directives and options lead the displayed picture, you know enough about Graphics3D's syntax to create your own material with JavaView. Don't worry about the Lighting is (set to False) option.


Graphics3D[{
      RGBColor[1., 0., 0],
      Polygon[{{1,1,1},{-1,1,1},{-1,-1,1},{1,-1,1},{1,1,1}}],
      RGBColor[0., 0., 1.],
      Thickness[0.02],
      Line[{{1,1,-1},{-1,1,-1},{-1,-1,-1},{1,-1,-1},{1,1,-1}}]
      RGBColor[0., 1., 0.],
      Line[{{1,1,1},{1,1,-1}}],
      Line[{{-1,1,1},{-1,1,-1}}],
      Line[{{1,-1,1},{1,-1,-1}}],
      Line[{{-1,-1,1},{-1,-1,-1}}],
      {PointSize[.03], RGBColor[.5,.5,0], Point[{0,0,0}]},
      {PointSize[.05], RGBColor[.5,.5,0], Point[{0,1,0}]}
      } ,
     {Lighting -> False, Boxed -> False}]

A copy of the file cube-example.m can be downloaded.

Reference

This document is an edited version of part of an article written by Martin Kraus and Jonathan Rogness about about how to create mathlets using LiveGraphics3D.