contourLines3d: Draw contours on a surface.
In rgl: 3D Visualization Using OpenGL

Description Usage Arguments Details Value Note Author(s) See Also Examples

contourLines3d draws contour lines on a surface; filledContour3d draws filled contours on it.

contourLines3d(obj, ...)
## S3 method for class 'rglId'
contourLines3d(obj, ...)
## S3 method for class 'mesh3d'
contourLines3d(obj, fn = "z", 
    nlevels = 10, 
    levels = NULL, 
    minVertices = 0,
    plot = TRUE, ... )
filledContour3d(obj, ...)
## S3 method for class 'rglId'
filledContour3d(obj, plot = TRUE, replace = plot, ...)
## S3 method for class 'mesh3d'
filledContour3d(obj, fn = "z", 
    nlevels = 20, 
    levels = pretty(range(values), nlevels), 
    color.palette = function(n) hcl.colors(n, "YlOrRd", rev = TRUE),
    col = color.palette(length(levels) - 1),
    minVertices = 0,
    plot = TRUE, 
    keepValues = FALSE, ... )

`obj`	The object(s) on which to draw contour lines.
`fn`	The function(s) to be contoured. See Details.
`nlevels`	Suggested number of contour levels if `levels` is not given.
`levels`	Specified contour values.
`minVertices`	See Details below.
`plot`	Whether to draw the lines or return them in a dataframe.
`...`	For the `"mesh3d"` methods, additional parameters to pass to `segments3d` when drawing the contour lines or to `shade3d` when drawing the filled contours. For the `"rglId"` methods, additional parameters to pass to the `"mesh3d"` methods.
`replace`	Whether to delete the objects that are being contoured.
`color.palette`	a color palette function to assign colors in the plot
`col`	the actual colors to use in the plot.
`keepValues`	whether to save the function values at each vertex when `plot = FALSE`

For contourLines3d, the fn argument can be any of the following:

a character vector naming one or more functions
a function
a numeric vector with one value per vertex
NULL, indicating that the numeric values are saved in obj$values
a list containing any of the above.

For filledContour3d, only one function can be specified.

The special names "x", "y", "z" may be used in fn to specify functions returning one of those coordinates. (If you have existing functions x(), y() or z() they will be masked by this choice; specify such functions by value rather than name, e.g. fn = x instead of fn = "x".)

Functions in fn with formal arguments x, y and z will receive the coordinates of vertices in those arguments, otherwise they will receive the coordinates in a single n x 3 matrix. They should be vectorized and return one value per vertex.

Each of the functions will be evaluated at each vertex of the surface specified by obj, and contours will be drawn assuming the function is linear between vertices. If contours of a nonlinear function are needed, you may want to increase minVertices as described below.

If levels is not specified, values will be set separately for each entry in fn, using pretty(range(values, na.rm = TRUE), nlevels) where values are the values on the vertices.

The minVertices argument is used to improve the approximation to the contour when the function is non-linear. In that case, the interpolation between vertices can be inaccurate. If minVertices is set to a positive number (e.g. 10000), then the mesh is modified by subdivision to have at least that number of vertices, so that pieces are smaller and the linear interpolation is more accurate.

For both contourLines3d and filledContour3d the "rglId" method converts the given id values to a mesh, and calls the "mesh3d" method.

The "mesh3d" method returns an object of class "rglId" corresponding to what was drawn if plot is TRUE,

If plot is FALSE, contourLines3d returns a dataframe containing columns c("x", "y", "z", "fn", "level") giving the coordinates of the endpoints of each line segment, the name (or index) of the function for this contour, and the level of the contour.

If plot is FALSE, filledContour3d returns a "mesh3d" object holding the result. If keepValues is TRUE, the mesh will contain the values corresponding to each vertex (with linear approximations at the boundaries).

To draw contours on a surface, the surface should be drawn with material property polygon_offset = 1 (or perhaps some larger positive value) so that the lines of the contour are not obscured by the surface.

In R versions prior to 3.6.0, the default color.palette is grDevices::cm.colors.

Duncan Murdoch

The misc3d package contains the function contour3d to draw contour surfaces in space instead of contour lines on surfaces.

# Add contourlines in "z" to a persp plot

z <- 2 * volcano        # Exaggerate the relief
x <- 10 * (1:nrow(z))   # 10 meter spacing (S to N)
y <- 10 * (1:ncol(z))   # 10 meter spacing (E to W)

open3d()
id <- persp3d(x, y, z, aspect = "iso",
      axes = FALSE, box = FALSE, polygon_offset = 1)
contourLines3d(id)     # "z" is the default function
filledContour3d(id, polygon_offset = 1, nlevels = 10, replace = TRUE)

# Draw longitude and latitude lines on a globe

lat <- matrix(seq(90, -90, len = 50)*pi/180, 50, 50, byrow = TRUE)
long <- matrix(seq(-180, 180, len = 50)*pi/180, 50, 50)

r <- 6378.1 # radius of Earth in km
x <- r*cos(lat)*cos(long)
y <- r*cos(lat)*sin(long)
z <- r*sin(lat)

open3d()
ids <- persp3d(x, y, z, col = "white", 
        texture = system.file("textures/worldsmall.png", package = "rgl"), 
        specular = "black", axes = FALSE, box = FALSE, xlab = "", ylab = "", zlab = "",
        normal_x = x, normal_y = y, normal_z = z, polygon_offset = 1)
        
contourLines3d(ids, list(latitude = function(x, y, z) asin(z/sqrt(x^2+y^2+z^2))*180/pi,
                         longitude = function(x, y, z) atan2(y, x)*180/pi))