{
"title": "surfc",
"category": "plotting",
"keywords": [
"surfc",
"surface with contour",
"composite surface plot",
"projected contour overlay",
"matlab surfc"
],
"summary": "Create composite surface-and-contour plots for scalar fields with MATLAB `surfc` semantics and projected contour overlays.",
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [
"single",
"double"
],
"broadcasting": "none",
"notes": "`surfc` combines the shared surface path with the modern contour path instead of relying on a separate legacy composite implementation."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 3,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::plotting::surfc::tests"
},
"description": "`surfc` is the composite member of the surface family: it combines a shaded `surf`-style surface with contour lines projected onto the base plane. In RunMat the returned handle is the primary surface handle, while the contour overlay is added as the secondary composite child. That keeps the composite behavior explicit without reintroducing a separate legacy plotting stack.",
"behaviors": [
"`surfc` shares the same surface semantics as `surf` for the primary surface object.",
"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": [
{
"description": "Create a shaded surface with projected contour lines",
"input": "[X, Y] = meshgrid(linspace(-2, 2, 60), linspace(-2, 2, 60));\nZ = X .* exp(-X.^2 - Y.^2);\nsurfc(X, Y, Z);"
},
{
"description": "Style the composite with colormap and camera controls",
"input": "[X, Y] = meshgrid(linspace(-3, 3, 80), linspace(-3, 3, 80));\nZ = cos(X) .* sin(Y);\nh = surfc(X, Y, Z);\ncolormap('turbo');\ncolorbar;\nview(45, 25);"
},
{
"description": "Inspect the returned primary surface handle",
"input": "[X, Y] = meshgrid(1:20, 1:20);\nZ = X + Y;\nh = surfc(X, Y, Z);\nget(h, 'Type')",
"output": "ans =\n 'surface'"
}
],
"faqs": [
{
"question": "Where do the contour lines appear in a surfc plot?",
"answer": "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."
},
{
"question": "When should I use surfc vs calling surf and contour separately?",
"answer": "`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."
},
{
"question": "Can I control how many contour levels surfc draws?",
"answer": "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."
}
],
"links": [
{
"label": "surf",
"url": "./surf"
},
{
"label": "meshc",
"url": "./meshc"
},
{
"label": "contour",
"url": "./contour"
},
{
"label": "contourf",
"url": "./contourf"
},
{
"label": "view",
"url": "./view"
},
{
"label": "Choosing the right plot type",
"url": "/docs/plotting/choosing-the-right-plot-type"
},
{
"label": "Styling plots and axes",
"url": "/docs/plotting/styling-plots-and-axes"
},
{
"label": "Plot replay and export",
"url": "/docs/plotting/plot-replay-and-export"
},
{
"label": "Complete plotting guide",
"url": "/blog/matlab-plotting-guide"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/plotting/ops/surfc.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/surfc.rs"
}
}