`contourLines3d.Rd`

`contourLines3d`

draws contour lines on a surface;
`filledContour3d`

draws filled contours on it.

```
contourLines3d(obj, ...)
# S3 method for rglId
contourLines3d(obj, ...)
# S3 method for mesh3d
contourLines3d(obj, fn = "z",
nlevels = 10,
levels = NULL,
minVertices = 0,
plot = TRUE, ... )
filledContour3d(obj, ...)
# S3 method for rglId
filledContour3d(obj, plot = TRUE, replace = plot, ...)
# S3 method for 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 | Specified contour values. |

minVertices | See Details below. |

plot | Whether to draw the lines or return them in a dataframe. |

... | For the |

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 |

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.

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`

.

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).

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)
```