Height-field visualization
Visualize elevation, terrain, or another scalar field defined over a rectangular x/y grid.
Plotly · Class
go.Surface
go.Surface creates an interactive 3D surface trace from gridded z values, with optional x/y coordinates and configurable coloring. Add it to a go.Figure to display the surface.
How it works
Create a go.Surface trace with a two-dimensional z grid and optionally provide x and y coordinates, color settings, and display controls. Add the trace to a go.Figure to render an interactive 3D surface.
Syntax
go.Surface(arg=None, **kwargs)Parameters
| Name | Type | Description |
|---|---|---|
z | array-like | Two-dimensional array containing the surface height values. |
x | array-like | Optional x-axis coordinates for the surface grid. |
y | array-like | Optional y-axis coordinates for the surface grid. |
surfacecolor | array-like | Optional values used to determine surface coloring. |
colorscale | list or string | Color mapping used for surface values. |
Returns
A Plotly Surface trace object.
Key points
- Pass x and y to place the surface on explicit coordinate axes rather than relying on index positions.
- Use surfacecolor when color should represent a separate data array instead of the surface height.
- Construct the trace with a two-dimensional z dataset and place it directly in a Figure.
- Regularly spaced coordinate vectors can be generated for the two horizontal axes.
- A Figure can contain a Surface trace initialized with z, x, and y together.
Common mistakes
- Omitting x or y does not leave the axes undefined; Plotly uses integer indices instead.
Example: Interactive 3D surface
import numpy as np
import plotly.graph_objects as go
x = np.linspace(-2, 2, 40)
y = np.linspace(-2, 2, 40)
X, Y = np.meshgrid(x, y)
Z = np.sin(X**2 + Y**2)
fig = go.Figure(go.Surface(x=x, y=y, z=Z, colorscale="Viridis"))
fig.show()Creates an interactive surface from one-dimensional x and y coordinates plus a two-dimensional z grid.
When to use it
Function exploration
Display a computed mathematical function such as z = f(x, y) in an interactive 3D scene.
Multivariate surface display
Encode a second measurement on the surface using a separate color array.
Interview questions
QWhat data does go.Surface need?
go.Surface represents a surface in a 3D Cartesian scene. Its primary input is a two-dimensional z array; x and y can be supplied to define the coordinate axes, otherwise integer indices are used.
Follow-up: How would you color the surface by values other than z? Supply a surfacecolor array and configure a colorscale.
QHow do x, y, and z work together?
Use one-dimensional x and y coordinate arrays with a two-dimensional z grid when the surface lies on a rectangular coordinate grid. The example documentation constructs x and y with linspace, then uses meshgrid to calculate z.
Follow-up: What should be checked if the plot is malformed? Verify that the z dimensions correspond to the intended x and y grid.
QHow can surface coloring be customized?
A surface can be visually encoded with surfacecolor, while colorscale controls the mapping of values to colors. This separates the geometry represented by z from the quantity used for coloring.
Follow-up: How can you hide the color scale? Set the trace's showscale property to false.
Related
plotly.graph_objects.Figurego.Isosurfacego.Volumesurfacecolorcolorscale