Waterman polyhedra

MuPAD® notebooks will be removed in a future release. Use MATLAB® live scripts instead.

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.


plot::Waterman(r, <a = amin .. amax>, options)


plot::Waterman(r) creates the Waterman polyhedron of radius r.

Waterman polyhedra, invented around 1990 by Steve Waterman, form a vast family of polyhedra. Some of them have a number of nice properties like multiple symmetries, or very interesting and regular shapes. Some other are just a bunch of faces formed out of irregular convex polygons.

Waterman polyhedra result from the examination of balls in face-centered cubic close packing (which is one of the two densest packings of equally sized balls in 3D space, according to the Kepler Conjecture, proofed by Hales and Ferguson, 1997-2005). A single layer of spheres (of radius ) in this packing looks like this:

The close packing results from placing several of these layers over one another, shifted to optimally fill the gaps (in very much the same way your grocery store puts apples and oranges on display):

Given a radius r and a center c (which we let default to [0, 0, 0]), now consider all those centers of spheres in this packing which fall into the sphere of radius r around c:

The convex hull of these points is the Waterman polyhedron of the given radius and center:


AttributePurposeDefault Value
AffectViewingBoxinfluence of objects on the ViewingBox of a sceneTRUE
Centercenter of objects, rotation center[0, 0, 0]
CenterXcenter of objects, rotation center, x-component0
CenterYcenter of objects, rotation center, y-component0
CenterZcenter of objects, rotation center, z-component0
Colorthe main colorRGB::SafetyOrange
Filledfilled or transparent areas and surfacesTRUE
FillColorcolor of areas and surfacesRGB::SafetyOrange
FillColor2second color of areas and surfaces for color blendsRGB::CornflowerBlue
FillColorTypesurface filling typesFlat
FillColorFunctionfunctional area/surface coloring 
FillColorDirectionthe direction of color transitions on surfaces[0, 0, 1]
FillColorDirectionXx-component of the direction of color transitions on surfaces0
FillColorDirectionYy-component of the direction of color transitions on surfaces0
FillColorDirectionZz-component of the direction of color transitions on surfaces1
Framesthe number of frames in an animation50
Legendmakes a legend entry 
LegendTextshort explanatory text for legend 
LegendEntryadd this object to the legend?FALSE
LineColorcolor of linesRGB::Grey40.[0.4]
LineWidthwidth of lines0.25
LineColor2color of linesRGB::DeepPink
LineStylesolid, dashed or dotted lines?Solid
LinesVisiblevisibility of linesTRUE
LineColorTypeline coloring typesFlat
LineColorFunctionfunctional line coloring 
LineColorDirectionthe direction of color transitions on lines[0, 1, 1]
LineColorDirectionXx-component of the direction of color transitions on lines0
LineColorDirectionYy-component of the direction of color transitions on lines1
LineColorDirectionZz-component of the direction of color transitions on lines1
Namethe name of a plot object (for browser and legend) 
ParameterEndend value of the animation parameter 
ParameterNamename of the animation parameter 
ParameterBegininitial value of the animation parameter 
ParameterRangerange of the animation parameter 
PointSizethe size of points1.5
PointStylethe presentation style of pointsFilledCircles
PointsVisiblevisibility of mesh pointsFALSE
Radiusradius of circles, spheres etc. 
Shadingsmooth color blend of surfacesSmooth
TimeEndend time of the animation10.0
TimeBeginstart time of the animation0.0
TimeRangethe real time span of an animation0.0 .. 10.0
Titleobject title 
TitleFontfont of object titles[" sans-serif ", 11]
TitlePositionposition of object titles 
TitleAlignmenthorizontal alignment of titles w.r.t. their coordinatesCenter
TitlePositionXposition of object titles, x component 
TitlePositionYposition of object titles, y component 
TitlePositionZposition of object titles, z component 
VisibleAfterobject visible after this time value 
VisibleBeforeobject visible until this time value 
VisibleFromToobject visible during this time range 
VisibleAfterEndobject visible after its animation time ended?TRUE
VisibleBeforeBeginobject visible before its animation time starts?TRUE


Example 1

With increasing radius, Waterman polyhedra get ever closer to spheres:

plot(plot::Waterman(r, r=0..10,
                    PointsVisible, PointSize=1,
     plot::Sphere(r, [0,0,0], r=0..10,

Example 2

Waterman polyhedra have a rather general definition and can be made from spheres centered anywhere:

plot(plot::Waterman(5, Center=[0,0,0]))

plot(plot::Waterman(5, Center=[0,0,1]))

To translate or scale a Waterman polyhedron, use plot::Translate3d and plot::Scale3d:

n := 3:
r := i -> 3/2+sqrt(i+1):
plot(plot::Translate3d([i mod n, i div n, 0],
               plot::Scale3d([1/(3*r(i)) $ 3],
                  plot::Waterman(r(i), Color=RGB::random())))
     $ i = 0..n^2-1, Axes=None)

Example 3

As usual, many attributes can be animated, although by the nature of Waterman polyhedra, the resulting animation will not be smooth:

plot(plot::Waterman(5, Center=[a/PI, cos(a), 0],
     AnimationStyle=BackAndForth, CameraDirection=[0,0.1,1])

Example 4

The LineColorFunction and FillColorFunction attributes can be set to functions which get indices of the currently painted surfacepolygon and its current vertex as fourth and fifth argument, respectively. This allows to color the polygons individually:

colors := [RGB::random() $ i = 1..42]:
plot(plot::Waterman(5, FillColorFunction=((x,y,z,i) -> colors[i])))

Another way of getting random colors which remain constant for each polygon is to use a procedure with option remember:

col := 
  option remember;
  RGB::fromHSV([360*frandom(), 1, 1]);
plot(plot::Waterman(7, FillColorFunction=((x,y,z,i) -> col(i))))



An arithmetical expression: the radius of the polyhedron (see below for details).

r is equivalent to the attribute Radius.


Animation parameter, specified as a = amin..amax, where amin is the initial parameter value, and amax is the final parameter value.


plot::Waterman uses plot::hull (and therefore, the Geometry Centre's qhull code) to compute the convex hull of the coordinates. Most of the remaining code has been contributed by Mirek Majewski.