contour — Create contour line plots in MATLAB and RunMat.
contour creates contour line plots from scalar fields using implicit or explicit coordinates, explicit levels, and a supported subset of contour appearance properties. RunMat returns an opaque contour handle; MATLAB's contour-matrix first output and two-output [M, c] form remain graphics-representation gaps.
Syntax
h = contour(Z)
h = contour(Z, N)
h = contour(Z, V)
h = contour(Z, Name, Value, ...)
h = contour(Z, V, Name, Value, ...)
h = contour(X, Y, Z)All supported contour forms
h = contour(Z)
h = contour(Z, N)
h = contour(Z, V)
h = contour(Z, Name, Value, ...)
h = contour(Z, V, Name, Value, ...)
h = contour(X, Y, Z)
h = contour(X, Y, Z, N)
h = contour(X, Y, Z, V)
h = contour(X, Y, Z, V, Name, Value, ...)
h = contour(X, Y, Z, N, Name, Value, ...)
h = contour(ax, ...)Inputs
Z- Type
NumericArray- Required
- Yes
- Description
- Contour height grid.
N- Type
NumericScalar- Required
- Yes
- Description
- Requested contour level count.
V- Type
NumericArray- Required
- Yes
- Description
- Explicit contour level values.
props- Type
Any- Required
- Variadic
- Description
- Name/value contour options.
V- Type
Any- Required
- Yes
- Description
- Contour level count/value vector.
X- Type
NumericArray- Required
- Yes
- Description
- X coordinate vector matching Z columns or meshgrid matrix matching Z.
Y- Type
NumericArray- Required
- Yes
- Description
- Y coordinate vector matching Z rows or meshgrid matrix matching Z.
ax- Type
Any- Required
- Yes
- Description
- Target axes object.
args- Type
Any- Required
- Variadic
- Description
- Any supported contour data, level, line-specification, and property arguments.
Returns
h- Type
NumericScalar- Description
- Handle to contour line plot.
Errors
RunMat:contour:InvalidArgument- When
- Contour input arrays, level arguments, or name/value options are invalid.
- Message
contour: invalid argument
RunMat:contour:Internal- When
- Internal contour render preparation fails unexpectedly.
- Message
contour: internal operation failed
RunMat:plotting:TooManyOutputs- When
- More than one output is requested from a coordinate chart constructor.
- Message
plotting: too many output arguments
Behavior
contour(Z) uses implicit axes, while contour(X, Y, Z) accepts strictly monotonic coordinate vectors or meshgrid-style matrices and contour(ax, ...) selects an existing axes target.
All eight built-in integer classes are accepted for X, Y, Z, positional level counts/vectors, LevelList, LevelStep, and LineWidth; integer shape, distinctness, meshgrid identity, ordering, count, and scalar constraints are validated from authoritative storage before floating graphics conversion.
A scalar level argument is a positive requested level count bounded by RunMat's one-million-level materialization guard; a vector is an explicit monotonically increasing level list, and [k k] requests one level at k.
Contour state is subplot-local and composes naturally with colormap, colorbar, and surface/composite builtins.
The public compatibility surface accepts GPU arrays but performs contour plotting on the client. RunMat preserves that behavior for resident integers through exact owning-provider gather and additionally accelerates eligible floating Z grids through the shared WGPU plotting context.
Options
'LevelList' accepts an explicit monotonically increasing vector of contour values; RunMat also accepts 'Levels' as an alias.
'LevelStep' accepts a positive finite scalar spacing, and 'LineWidth' accepts a positive finite scalar width.
'LineColor' accepts color strings, RGB triples, and 'auto', 'flat', or 'none'. Typed-integer RGB triples containing only exact 0/1 channels are a separately gated RunMat extension because the public RGB contract does not explicitly advertise integer classes.
The broader Contour property surface, including label-generation properties, EdgeColor, FaceColor, alpha controls, and post-construction typed XData/YData/ZData mutation, remains a general graphics-property coverage gap.
Rendering and residency
Floating gpuArray Z can use RunMat's shared WGPU contour path. Integer gpuArray coordinates, heights, levels, and scalar properties gather exactly through the owning provider before the client graphics boundary because the contour shaders consume floating buffers.
Declared source precision and class coverage
single
double
int8
int16
int32
int64
uint8
uint16
uint32
uint64
Coordinate broadcasting
none
Runtime contract and boundaries
Graphics results are host double handles; fill/fill3 may return a row of handles for independently created polygon columns/groups. Sphere instead supports zero through three requested outputs: statement form plots, while output forms return host double coordinate grids. Handle aliases, value-selected options and exact graphics receiver roles are resolved by Runtime, not guessed from scalar facts.
The existing numerical and geometry owners validate coordinates, integer controls, shapes and properties. Single/double and all eight integer source classes retain their native storage wherever the object has authoritative source properties; client geometry and renderer buffers are deliberate floating boundaries, not a promise of exact wide-integer pixel positions. There is no sparse/complex plotting implementation or numeric broadcasting promise here. Logical, scalar, vector, matrix, rank and empty admission follows each documented owner below rather than a universal coercion.
RuntimeOwned preparation retains the original BuiltinArguments through suspension and completion. Eligible direct GPU routes require the live owning provider, admitted precision/storage/shape, compatible exports and installed plotting device. NoAttempt means pre-effect inapplicability, not permission to swallow export, allocation, cancellation or emission errors. Existing provider errors are propagated and ingress errors are terminal Never replay. Source-property queries and figure persistence may require explicit owner-aware readback; surface property snapshots and quiver3/patch construction are not zero-copy routes.
Canonical UserInterface capability and host-callback effects reflect scene creation/presentation; function-sampling entries additionally declare Unknown effects for arbitrary user callbacks and require the Process execution stack. NativeAndWasm means the Runtime entry is portable, not that an absent graphics host is emulated. Portable Runtime linkage introduces no separate native numerical library artifact. Rendering is a fusion boundary and distributed execution is unsupported; no numeric provider kernel or fusion primitive is invented.
Chart scratch, metadata, retained render state and the sphere coordinate builder do not yet have complete finite host allocation ownership. The shared canonical HostAllocationReceipt policy guard refuses Managed work before extraction/gather/callbacks or scene mutation, preserves ordinary Unbounded routes, and checks captured cancellation generation and policy before publication. This is an explicit L25 gap, not allocation completion. Long synchronous geometry/copy loops, renderer/provider-private allocation accounting, full MATLAB property parity, physical performance and actual example execution remain independently required.
Supported representations and remaining forms
Core forms are Z; Z plus level count/vector; X,Y,Z plus optional levels; leading axes; optional LineSpec followed by name/value pairs. Z must be at least 2-by-2 and nonconstant after the existing contour validation. Coordinate vectors are strictly monotonic; meshgrid-style coordinate matrices must have the correct identity and varying dimensions. Empty, mismatched or degenerate grids fail rather than becoming an invented 1-by-1 field.
Level counts are positive finite whole scalars subject to the existing one-million-level materialization ceiling. Explicit levels are strictly increasing, with [k k] representing a single level. LevelStep is positive finite; LineWidth is positive finite. Levels/LevelList, LevelStep, LineColor/Color, LineWidth and the existing LevelListMode controls use one shared parser. Integer order/count/meshgrid checks precede floating conversion; integer RGB 0/1 channels use the existing separately gated contour extension.
The returned value is the RunMat graphics handle, not MATLAB contour-matrix M or [M,c] output. Full contour labels, broad properties and post-construction coordinate mutation remain gaps. Eligible floating Z can use prepared GPU contours; axes/control reads and integer grids gather through their actual owner. A prepared composite publishes its requested parts only after their construction succeeds; errors are not fallback signals.
Contour draws level lines on the base plane. LineColor none intentionally creates no visible contour object and can return NaN; it does not manufacture a valid handle.
Examples
Create a contour line plot from a scalar field
[X, Y] = meshgrid(-2:0.25:2, -2:0.25:2);
Z = X .* exp(-X.^2 - Y.^2);
contour(X, Y, Z);Use explicit contour levels
[X, Y] = meshgrid(-2:0.25:2, -2:0.25:2);
Z = X .* exp(-X.^2 - Y.^2);
contour(X, Y, Z, [0 0.25 0.5]);Inspect the returned contour handle
[X, Y] = meshgrid(1:20, 1:20);
Z = X + Y;
h = contour(X, Y, Z);
get(h, 'Type')Expected output:
ans =
'contour'Temperature-style level sets
[X, Y] = meshgrid(linspace(-3, 3, 120), linspace(-3, 3, 120));
Z = 2*exp(-((X-1).^2 + Y.^2)) + 1.5*exp(-((X+1.5).^2 + (Y-1).^2)) - exp(-(X.^2 + (Y+1.5).^2));
contour(X, Y, Z, 20);
colormap('turbo');
colorbar;
title('Thermal Field — Level Sets');
xlabel('x (m)');
ylabel('y (m)');
axis equal;Rendered contour example
[X, Y] = meshgrid(linspace(-3, 3, 120), linspace(-3, 3, 120));
Z = 2*exp(-((X-1).^2 + Y.^2)) + 1.5*exp(-((X+1.5).^2 + (Y-1).^2)) - exp(-(X.^2 + (Y+1.5).^2));
contour(X, Y, Z, 20);
colormap('turbo');
colorbar;
title('Thermal Field - Level Sets');
xlabel('x (m)');
ylabel('y (m)');
axis equal;
Compare this result with other chart types in the plot examples.
Using contour with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how contour changes the result.
Run a small contour example, explain the result, then change one input and compare the output.
FAQ
How do I set specific contour levels?⌄
Pass a vector of values as the fourth argument. Each value becomes one contour line.
contour(X, Y, Z, [0.1 0.3 0.5 0.7 0.9]);If you pass a scalar instead, it's interpreted as the number of levels (e.g., contour(X, Y, Z, 20) draws 20 automatically spaced levels).
Can I add labels to the contour lines?⌄
MATLAB supports contour labels through clabel and contour label properties. RunMat's current contour object does not yet implement that broader label-generation surface.
What's the difference between contour and contourf?⌄
contour draws line-only iso-curves — the regions between lines are transparent. contourf fills those regions with colors from the active colormap. Use contour when you want to overlay on other plots or keep the background visible, and contourf when the filled color bands are the primary visualization.
Related Plotting functions
2D Charts
area · bar · errorbar · heatmap · hist · histogram · loglog · pie · plot · scatter · semilogx · semilogy · stairs · stem
Other
addpoints · ancestor · animatedline · autumn · axes · barh · bone · caxis · cla · clf · clim · colorcube · colororder · cool · copper · copyobj · cylinder · daspect · datacursormode · dataTipTextRow · drawnow · fcontour · figure · fill · fill3 · findobj · fsurf · gobjects · gray · groot · hgload · hgsave · hidden · histogram2 · hold · hot · inferno · isgraphics · ishandle · jet · line · lines · linkaxes · magma · openfig · opengl · pan · parula · patch · pink · plasma · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · spring · stackedplot · subtitle · summer · suptitle · text · textscatter · textscatter3 · triplot · turbo · viridis · waitbar · winter · wordcloud · xlabel · xlim · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · ylabel · ylim · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zlim · zoom
More plotting resources
Source you can read
Every RunMat function's source is public. Read exactly how contour is executed, line by line, in Rust.
- View the source for contour in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.