surfc — Create composite surface-and-contour plots with MATLAB-compatible surfc behavior.
surfc combines a shaded surf-style surface with projected contour lines on the base plane. It supports MATLAB-compatible surface-family inputs and returns the primary surface handle.
Syntax
h = surfc(Z)
h = surfc(X, Y, Z)
h = surfc(Z, Name, Value, ...)
h = surfc(X, Y, Z, Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
Z | NumericArray | Yes | — | Surface height grid. |
X | NumericArray | Yes | — | X axis vector/meshgrid matrix matching Z columns. |
Y | NumericArray | Yes | — | Y axis vector/meshgrid matrix matching Z rows. |
props | Any | Variadic | — | Name/value surface style options. |
Returns
| Name | Type | Description |
|---|---|---|
h | NumericScalar | Handle to the rendered surface plot (with contour overlay). |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:surfc:InvalidArgument | Surface/grid/axis inputs or style name/value arguments are invalid. | surfc: invalid argument |
RunMat:surfc:Internal | Internal surface/contour construction or render preparation fails unexpectedly. | surfc: internal operation failed |
How surfc works
surfcshares the same surface semantics assurffor the primary surface object.- The primary surface's
XData,YData, andZDataretain native single, double, or integer class, exact values, and shape; surface rendering and projected-contour construction are explicit floating boundaries. - The returned handle is the surface handle for the composite result, while contour overlays are attached as the secondary composite plot content.
- The contour overlay uses the same modern contour-generation path as
contour, rather than a one-off composite implementation. - Colormap, colorbar, view, and subplot-local state all operate on the composite through the same shared axes metadata model.
- GPU-aware execution applies to both the surface side and the contour side where supported.
Examples
Create a shaded surface with projected contour lines
[X, Y] = meshgrid(linspace(-2, 2, 60), linspace(-2, 2, 60));
Z = X .* exp(-X.^2 - Y.^2);
surfc(X, Y, Z);Style the composite with colormap and camera controls
[X, Y] = meshgrid(linspace(-3, 3, 80), linspace(-3, 3, 80));
Z = cos(X) .* sin(Y);
h = surfc(X, Y, Z);
colormap('turbo');
colorbar;
view(45, 25);Inspect the returned primary surface handle
[X, Y] = meshgrid(1:20, 1:20);
Z = X + Y;
h = surfc(X, Y, Z);
get(h, 'Type')Expected output:
ans =
'surface'Rendered surfc example
[X, Y] = meshgrid(linspace(-4, 4, 120), linspace(-4, 4, 120));
R = sqrt(X.^2 + Y.^2) + 0.15;
Z = cos(2.5*R).*exp(-0.22*R);
surfc(X, Y, Z);
shading interp;
colormap('turbo');
colorbar;
title('Damped Radial Response');
xlabel('x');
ylabel('y');
zlabel('Amplitude');
view(38, 27);
Compare this result with other chart types in the MATLAB Plot Gallery.
Using surfc with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how surfc changes the result.
Run a small surfc example, explain the result, then change one input and compare the output.
FAQ
Where do the contour lines appear in a surfc plot?⌄
The contour lines are projected onto the base plane (the z-minimum of the axes). They sit below the surface as a 2-D footprint of the height field. The contour overlay uses the same colormap as the surface, so the colors stay consistent.
When should I use surfc vs calling surf and contour separately?⌄
surfc handles the composite in one call — the contour is automatically projected to the base plane and shares the surface's colormap and axes state. If you call surf and contour separately, the contour sits at z=0 by default and you'd need to manage hold state and z-placement yourself. Use surfc unless you need the contour at a custom z-level or with different level spacing than the default.
Can I control how many contour levels surfc draws?⌄
The contour overlay in surfc uses the default level-generation logic from the contour pipeline. If you need explicit control over level count or spacing, call surf and contour separately so you can pass a level vector to contour directly.
Related Plotting functions
2D Charts
area · bar · errorbar · heatmap · hist · histogram · loglog · pie · plot · scatter · semilogx · semilogy · stairs · stem
Other
addpoints · ancestor · animatedline · axes · barh · caxis · cla · clf · clim · colorcube · colororder · copyobj · daspect · datacursormode · dataTipTextRow · fcontour · figure · fill · fill3 · findobj · fsurf · gobjects · groot · hgload · hgsave · hidden · histogram2 · hold · line · linkaxes · openfig · opengl · pan · parula · patch · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · stackedplot · subtitle · suptitle · text · textscatter · textscatter3 · triplot · waitbar · wordcloud · xlabel · xlim · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · ylabel · ylim · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zlim · zoom
More plotting resources
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how surfc is executed, line by line, in Rust.
- View the source for surfc in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.