Perspective plots, 3D ribbons and 3D histograms.
Description
persp3D
extends R's persp function.
ribbon3D
is similar to persp3D
but has ribbonlike colored surfaces.
hist3D
generates 3D histograms.
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30  persp3D (x = seq(0, 1, length.out = nrow(z)),
y = seq(0, 1, length.out = ncol(z)), z, ...,
colvar = z, phi = 40, theta = 40,
col = NULL, NAcol = "white", breaks = NULL,
border = NA, facets = TRUE, colkey = NULL, resfac = 1,
image = FALSE, contour = FALSE, panel.first = NULL,
clim = NULL, clab = NULL, bty = "b",
lighting = FALSE, shade = NA, ltheta = 135, lphi = 0,
inttype = 1, curtain = FALSE, add = FALSE, plot = TRUE)
ribbon3D (x = seq(0, 1, length.out = nrow(z)),
y = seq(0, 1, length.out = ncol(z)), z, ...,
colvar = z, phi = 40, theta = 40,
col = NULL, NAcol = "white", breaks = NULL,
border = NA, facets = TRUE, colkey = NULL, resfac = 1,
image = FALSE, contour = FALSE, panel.first = NULL,
clim = NULL, clab = NULL, bty = "b",
lighting = FALSE, shade = NA, ltheta = 135, lphi = 0,
space = 0.4, along = "x",
curtain = FALSE, add = FALSE, plot = TRUE)
hist3D (x = seq(0, 1, length.out = nrow(z)),
y = seq(0, 1, length.out = ncol(z)), z, ...,
colvar = z, phi = 40, theta = 40,
col = NULL, NAcol = "white", breaks = NULL,
border = NA, facets = TRUE, colkey = NULL,
image = FALSE, contour = FALSE,
panel.first = NULL, clim = NULL, clab = NULL, bty = "b",
lighting = FALSE, shade = NA, ltheta = 135, lphi = 0,
space = 0, opaque.top = FALSE, add = FALSE, plot = TRUE)

Arguments
z 
Matrix (2D) containing the values to be plotted as a persp plot. 
x, y 
Vectors or matrices with x and y values.
If a vector, 
colvar 
The variable used for coloring. If present, it should have the
same dimension as 
col 
Color palette to be used for the Finally, to mimic the behavior of persp, set 
NAcol 
Color to be used for 
breaks 
a set of finite numeric breakpoints for the colors; must have one more breakpoint than color and be in increasing order. Unsorted vectors will be sorted, with a warning. 
colkey 
A logical, The default is to draw the color key on side = 4, i.e. in the right margin.
If 
clab 
Only if 
clim 
Only if 
resfac 
Resolution factor, one value or a vector of two numbers, for
the x and y values respectively. A value > 1 will increase the
resolution. For instance, if 
theta, phi 
The angles defining the viewing direction.

border 
The color of the lines drawn around the surface facets.
The default, 
facets 
If 
image 
If 
contour 
If 
panel.first 
A 
along 
The direction along which the ribbons are drawn, one of "x", "y" or "xy", for ribbons parallel to the x y or both axes. In the latter case, the figure looks like a net. 
curtain 
If 
space 
The amount of space (as a fraction of the average bar/ribbon width)
left between bars/ribbons. A value inbetween [0, 0.9] ( 
bty 
The type of the box, the default only drawing background panels.
Only effective if the persp
argument ( 
lighting 
If not Will overrule See examples in jet.col. 
shade 
the degree of shading of the surface facets. Values of shade close to one yield shading similar to a point light source model and values close to zero produce no shading. Values in the range 0.5 to 0.75 provide an approximation to daylight illumination. See persp. 
ltheta, lphi 
if finite values are specified for 
inttype 
The interpolation type to create the polygons, either
averaging the 
opaque.top 
Only used when 
add 
Logical. If 
plot 
Logical. If 
... 
additional arguments passed to the plotting methods.
The following persp arguments can be specified:
In addition, the perspbox arguments
For all functions, the arguments The arguments after ... must be matched exactly. 
Details
persp3D
is an extension to the default persp plot that has
the possibility to add a color key, to increase the
resolution in order to make smoother images,
to toggle on or off facet coloration, ...
The perspective plots are drawn as filled polygons. Each polygon is defined by
4 corners and a color, defined in its centre.
When facets are colored, there are three interpolation schemes as set by inttype
.
The default (inttype = 1
) is similar to R's function persp
,
and assumes that the z
values define the points on the corners of
each polygon. In case a colvar
is defined, its values are to be recalculated
to the middle of each polygon, i.e. the color values need to be of size
(nx1)(ny1), and averages are taken from the original data
(nx and ny are number of x and y points).
This will make the colors (and/or shading) smoother.
When inttype = 1
then NA
values in colvar
will be used as
such during the averaging. This will tend to make the NA
region larger.
An alternative is to set inttype = 3
, which is similar to inttype = 1
except for the NA
values, which will be removed during the averaging.
This will tend to make the NA
region smaller.
By setting inttype = 2
, a second interpolation scheme
is selected. This is mainly of use in case a colvar
is defined, and it
is not desirable that the colors are smoothened.
In this scheme, it is assumed that the z
values and colvar
values are both defined in the centre of the polygons.
To color the facets the x, y, z grid is extended (to a (nx+1)(ny+1) grid),
while colvar
is used as such.
This will make the zvalues (topography) smoother than the original data.
This type of interpolation may be preferable for color variables that have NA
values,
as taking averages tends to increase the NA
region.
Value
Returns, as invisible, the viewing transformation matrix.
See trans3D.
Note
To make a contour
to appear on top of an image,
i.e. when side = "z"
, the viewing depth
of the contour segments is artificially decreased. In some cases this
may produce slight artifacts. The viewing depth can be adjusted with argument dDepth
,
e.g. persp3D(z = volcano, contour = list(side = "z", dDepth = 0.))
Parts of this help page come from the help pages of the Rcore function persp.
Author(s)
Karline Soetaert <karline.soetaert@nioz.nl>
References
The persp function on which this implementation is based:
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
See Also
persp for the function on which this is based.
Hypsometry for an example where axispanels are colored.
scatter3D for a combination of a persp surface and data points.
text3D for annotating axes (hist3D).
plotdev for zooming, rescaling, rotating a plot.
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226  # save plotting parameters
pm < par("mfrow")
## =======================================================================
## Ribbon, persp, color keys, facets
## =======================================================================
par(mfrow = c(2, 2))
# simple, no scaling, use breaks to set colors
persp3D(z = volcano, main = "volcano", clab = c("height", "m"),
breaks = seq(80,200, by = 10))
# keep ratios between x and y (scale = FALSE)
# change ratio between x and z (expand)
persp3D(z = volcano, x = 1: nrow(volcano), y = 1:ncol(volcano),
expand = 0.3, main = "volcano", facets = FALSE, scale = FALSE,
clab = "height, m", colkey = list(side = 1, length = 0.5))
# ribbon, in xdirection
V < volcano[, seq(1, ncol(volcano), by = 3)] # lower resolution
ribbon3D(z = V, colkey = list(width = 0.5, length = 0.5,
cex.axis = 0.8, side = 2), clab = "m")
# ribbon, in ydirection
Vy < volcano[seq(1, nrow(volcano), by = 3), ]
ribbon3D(z = Vy, expand = 0.3, space = 0.3, along = "y",
colkey = list(width = 0.5, length = 0.5, cex.axis = 0.8))
## =======================================================================
## Several ways to visualise 3D data
## =======================================================================
x < seq(pi, pi, by = 0.2)
y < seq(pi, pi, by = 0.3)
grid < mesh(x, y)
z < with(grid, cos(x) * sin(y))
par(mfrow = c(2,2))
persp3D(z = z, x = x, y = y)
persp3D(z = z, x = x, y = y, facets = FALSE, curtain = TRUE)
# ribbons in two directions and larger spaces
ribbon3D(z = z, x = x, y = y, along = "xy", space = 0.3)
hist3D(z = z, x = x, y = y, border = "black")
## =======================================================================
## Contours and images added
## =======================================================================
par(mfrow = c(2, 2))
x < seq(1, nrow(volcano), by = 3)
y < seq(1, ncol(volcano), by = 3)
Volcano < volcano [x, y]
ribbon3D(z = Volcano, contour = TRUE, zlim= c(100, 200),
image = TRUE)
persp3D(z = Volcano, contour = TRUE, zlim= c(200, 200), image = FALSE)
persp3D(z = Volcano, x = x, y = y, scale = FALSE,
contour = list(nlevels = 20, col = "red"),
zlim = c(200, 200), expand = 0.2,
image = list(col = grey (seq(0, 1, length.out = 100))))
persp3D(z = Volcano, contour = list(side = c("zmin", "z", "350")),
zlim = c(100, 400), phi = 20, image = list(side = 350))
## =======================================================================
## Use of inttype
## =======================================================================
par(mfrow = c(2, 2))
persp3D(z = Volcano, shade = 0.5, colkey = FALSE)
persp3D(z = Volcano, inttype = 2, shade = 0.5, colkey = FALSE)
x < y < seq(0, 2*pi, length.out = 10)
z < with (mesh(x, y), cos(x) *sin(y)) + runif(100)
cv < matrix(nrow = 10, 0.5*runif(100))
persp3D(x, y, z, colvar = cv) # takes averages of z
persp3D(x, y, z, colvar = cv, inttype = 2) # takes averages of colvar
## =======================================================================
## Use of inttype with NAs
## =======================================================================
par(mfrow = c(2, 2))
VV < V2 < volcano[10:15, 10:15]
V2[3:4, 3:4] < NA
V2[4, 5] < NA
image2D(V2, border = "black") # shows true NA region
# averages of V2, including NAs, NA region larger
persp3D(z = VV, colvar = V2, inttype = 1, theta = 0,
phi = 20, border = "black", main = "inttype = 1")
# extension of VV; NAs unaffected
persp3D(z = VV, colvar = V2, inttype = 2, theta = 0,
phi = 20, border = "black", main = "inttype = 2")
# average of V2, ignoring NA; NA region smaller
persp3D(z = VV, colvar = V2, inttype = 3, theta = 0,
phi = 20, border = "black", main = "inttype = 3")
## =======================================================================
## Use of panel.first
## =======================================================================
par(mfrow = c(1, 1))
# A function that is called after the axes were drawn
panelfirst < function(trans) {
zticks < seq(100, 180, by = 20)
len < length(zticks)
XY0 < trans3D(x = rep(1, len), y = rep(1, len), z = zticks,
pmat = trans)
XY1 < trans3D(x = rep(1, len), y = rep(61, len), z = zticks,
pmat = trans)
segments(XY0$x, XY0$y, XY1$x, XY1$y, lty = 2)
rm < rowMeans(volcano)
XY < trans3D(x = 1:87, y = rep(ncol(volcano), 87),
z = rm, pmat = trans)
lines(XY, col = "blue", lwd = 2)
}
persp3D(z = volcano, x = 1:87, y = 1: 61, scale = FALSE, theta = 10,
expand = 0.2, panel.first = panelfirst, colkey = FALSE)
## =======================================================================
## with / without colvar / facets
## =======================================================================
par(mfrow = c(2, 2))
persp3D(z = volcano, shade = 0.3, col = gg.col(100))
# shiny colors  set lphi for more brightness
persp3D(z = volcano, lighting = TRUE, lphi = 90)
persp3D(z = volcano, col = "lightblue", colvar = NULL,
shade = 0.3, bty = "b2")
# this also works:
# persp3D(z = volcano, col = "grey", shade = 0.3)
# tilted x and ycoordinates of 'volcano'
volcx < matrix(nrow = 87, ncol = 61, data = 1:87)
volcx < volcx + matrix(nrow = 87, ncol = 61,
byrow = TRUE, data = seq(0., 15, length.out = 61))
volcy < matrix(ncol = 87, nrow = 61, data = 1:61)
volcy < t(volcy + matrix(ncol = 87, nrow = 61,
byrow = TRUE, data = seq(0., 15, length.out = 87)))
persp3D(volcano, x = volcx, y = volcy, phi = 80)
## =======================================================================
## Several persps on one plot
## =======================================================================
par(mfrow = c(1, 1))
clim < range(volcano)
persp3D(z = volcano, zlim = c(100, 600), clim = clim,
box = FALSE, plot = FALSE)
persp3D(z = volcano + 200, clim = clim, colvar = volcano,
add = TRUE, colkey = FALSE, plot = FALSE)
persp3D(z = volcano + 400, clim = clim, colvar = volcano,
add = TRUE, colkey = FALSE) # plot = TRUE by default
## =======================================================================
## hist3D
## =======================================================================
par(mfrow = c(2, 2))
VV < volcano[seq(1, 87, 15), seq(1, 61, 15)]
hist3D(z = VV, scale = FALSE, expand = 0.01, border = "black")
# transparent colors
hist3D(z = VV, scale = FALSE, expand = 0.01,
alpha = 0.5, opaque.top = TRUE, border = "black")
hist3D(z = VV, scale = FALSE, expand = 0.01, facets = FALSE, lwd = 2)
hist3D(z = VV, scale = FALSE, expand = 0.01, facets = NA)
## =======================================================================
## hist3D and ribbon3D with greyish background, rotated, rescaled,...
## =======================================================================
par(mfrow = c(2, 2))
hist3D(z = VV, scale = FALSE, expand = 0.01, bty = "g", phi = 20,
col = "#0072B2", border = "black", shade = 0.2, ltheta = 90,
space = 0.3, ticktype = "detailed", d = 2)
# extending the ranges
plotdev(xlim = c(0.2, 1.2), ylim = c(0.2, 1.2), theta = 45)
ribbon3D(z = VV, scale = FALSE, expand = 0.01, bty = "g", phi = 20,
col = "lightblue", border = "black", shade = 0.2, ltheta = 90,
space = 0.3, ticktype = "detailed", d = 2, curtain = TRUE)
ribbon3D(z = VV, scale = FALSE, expand = 0.01, bty = "g", phi = 20, zlim = c(95,183),
col = "lightblue", lighting = TRUE, ltheta = 50, along = "y",
space = 0.7, ticktype = "detailed", d = 2, curtain = TRUE)
## =======================================================================
## hist3D for a 1D data set
## =======================================================================
par(mfrow = c(2, 1))
x < rchisq(1000, df = 4)
hs < hist(x, breaks = 15)
hist3D(x = hs$mids, y = 1, z = matrix(ncol = 1, data = hs$density),
bty = "g", ylim = c(0., 2.0), scale = FALSE, expand = 20,
border = "black", col = "white", shade = 0.3, space = 0.1,
theta = 20, phi = 20, main = "3D perspective")
# reset plotting parameters
par(mfrow = pm)
