Contours of a 3D surface

Renders a surface as stacked horizontal contour bands. Each contour band is a polygon placed at its corresponding z-level.

Usage

geom_contour_3d(
  mapping = NULL,
  data = NULL,
  stat = "surface_3d",
  position = "identity",
  ...,
  bins = 20,
  binwidth = NULL,
  breaks = NULL,
  cull_backfaces = FALSE,
  sort_method = "pairwise",
  scale_depth = TRUE,
  force_convex = FALSE,
  light = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_contour_3d(
  mapping = NULL,
  data = NULL,
  geom = "contour_3d",
  position = "identity",
  ...,
  bins = 20,
  binwidth = NULL,
  breaks = NULL,
  cull_backfaces = FALSE,
  sort_method = "pairwise",
  scale_depth = TRUE,
  force_convex = FALSE,
  light = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by aes().

data

Point grid data with x, y, z coordinates.

stat

Statistical transformation. Defaults to "surface_3d".

position

Position adjustment, defaults to "identity".

...

Other arguments passed to the layer.

bins

Number of contour levels. Default is 20. Ignored if breaks or binwidth is provided.

binwidth

Width of each contour band. Overrides bins if provided.

breaks

Numeric vector specifying exact contour break points. Overrides both bins and binwidth if provided.

cull_backfaces

Logical indicating whether to remove back-facing polygons from rendering. This is primarily for performance optimization but may be useful for aesthetic reasons in some situations. Backfaces are determined using screen-space winding order after 3D transformation. Defaults vary by geometry type: FALSE for open surface-type geometries, TRUE for solid objects (hulls, voxels, etc. where backfaces are generally hidden unless frontfaces are transparent or explicitly disabled).

sort_method

Depth sorting algorithm. See sorting_methods for details.

scale_depth

Logical indicating whether polygon linewidths should be scaled to make closer lines wider and farther lines narrower. Default is TRUE. Scaling is based on the mean depth of a polygon.

force_convex

Logical indicating whether to remove polygon vertices that are not part of the convex hull. Default value varies by geom. Specifying TRUE can help reduce artifacts in surfaces that have polygon tiles that wrap over a visible horizon. For prism-type geoms like columns and voxels, FALSE is safe because polygons fill always be convex.

light

A lighting specification object created by light(),"none" to disable lighting, or NULL to inherit plot-level lighting specs from the coord. Specify plot-level lighting in coord_3d() and layer-specific lighting in geom_*3d() functions.

na.rm

If FALSE, missing values are removed.

show.legend

Logical indicating whether this layer should be included in legends.

inherit.aes

If FALSE, overrides the default aesthetics.

geom

Geometry function used to display the data. Defaults to "surface_3d".

Value

A Layer object that can be added to a ggplot.

Details

This geom takes point grid data (like that produced by stat_surface_3d(), stat_function_3d(), stat_smooth_3d(), or stat_density_3d()) and converts it to filled contour polygons using the isoband package.

Aesthetics

geom_contour_3d() requires:

x, y, z

Point coordinates forming a regular grid

And understands these additional aesthetics:

fill

Band fill color. For automatic coloring by elevation, use aes(fill = after_stat(z)). Default is "grey60".

colour

Band border color (default: "grey30")

alpha

Transparency

linewidth

Border width (default: 0.1)

linetype

Border line type

Computed variables

Each contour band is placed at its corresponding z-level (the upper boundary of the band). To color by elevation, use aes(fill = after_stat(z)).

See also

geom_surface_3d() for continuous surface rendering, geom_ridgeline_3d() for cross-sectional ridgeline rendering, stat_function_3d() for mathematical function surfaces, stat_smooth_3d() for fitted model surfaces, coord_3d() for 3D coordinate systems, ggplot2::geom_contour_filled() for the 2D equivalent.

Examples

# Basic usage with volcano data
ggplot(mountain, aes(x, y, z)) +
      geom_contour_3d(color = "white", fill = "black") +
      coord_3d(light = "none", ratio = c(1.5, 2, 1))


# Map fill to elevation and customize number of levels
ggplot(mountain, aes(x, y, z, fill = after_stat(z))) +
      geom_contour_3d(bins = 12, color = "white") +
      scale_fill_viridis_c() +
      coord_3d(light = "none", ratio = c(1.5, 2, 1))


# Specify exact breaks
ggplot(mountain, aes(x, y, z, fill = after_stat(z))) +
  geom_contour_3d(breaks = seq(0, 200, by = 5)) +
  scale_fill_viridis_c() +
  coord_3d(light = "none")


# With stat_density_3d
ggplot(faithful, aes(eruptions, waiting)) +
  stat_density_3d(geom = "contour_3d",
    sort_method = "pairwise") +
  coord_3d()


# With stat_function_3d
ggplot() +
  stat_function_3d(
    fun = function(x, y) sin(x) * cos(y),
    xlim = c(-pi, pi), ylim = c(-pi, pi),
    geom = "contour_3d",
    bins = 50, color = "black"
  ) +
  scale_fill_viridis_c(option = "B") +
  coord_3d(light = "none")