patch — Create a colored polygon patch from coordinates or faces and vertices.
patch publishes polygon geometry with constant, flat, or interpolated face coloring. Indexed and truecolor source data remain available through graphics properties and scene replay.
Syntax
h = patch(X, Y, C)
h = patch(X, Y, Z, C)
h = patch(S)
h = patch('Faces', F, 'Vertices', V, ...)
h = patch(ax, ...)Inputs
X- Type
NumericArray- Required
- Yes
- Description
- Patch X coordinates.
Y- Type
NumericArray- Required
- Yes
- Description
- Patch Y coordinates.
C- Type
Any- Required
- Yes
- Description
- Face color specification.
Z- Type
NumericArray- Required
- Yes
- Description
- Patch Z coordinates.
S- Type
Any- Required
- Yes
- Description
- Struct containing patch properties.
facevert- Type
Any- Required
- Variadic
- Description
- Faces/Vertices property/value pairs.
props- Type
Any- Required
- Variadic
- Description
- Additional patch property/value pairs.
ax- Type
NumericScalar- Required
- Yes
- Description
- Target axes handle.
data- Type
Any- Required
- Variadic
- Description
- Patch positional/property arguments.
Returns
h- Type
NumericScalar- Description
- Handle to the created patch object.
Errors
RunMat:patch:InvalidArgument- When
- Patch coordinates, faces/vertices, or property/value arguments are malformed.
- Message
patch: invalid argument
RunMat:patch:Internal- When
- Internal patch triangulation/render setup fails unexpectedly.
- Message
patch: internal operation failed
Geometry and properties
Vector coordinate inputs create one polygon; matrix coordinate inputs create one polygon per column. Polygon edges close automatically. Faces are MATLAB-style one-based vertex indices; Vertices accepts N-by-2 coordinates for 2-D geometry or N-by-3 for 3-D geometry.
XData, YData, ZData, CData, Faces, and Vertices retain native single, double, or integer class, shape, and exact values for properties and scene persistence. Host triangulation and renderer packing are explicit floating boundaries. The returned patch handle works with get, set, ishandle, and isgraphics.
A typed-integer numeric alias for a leading axes handle is a gated RunMat extension; ordinary axes objects remain the compatibility form.
FaceColor accepts named colors, RGB triples, flat, interp, or none. EdgeColor accepts named colors, RGB triples, or none. FaceAlpha and EdgeAlpha lie in [0,1]. LineWidth, DisplayName, and Visible use the shared plotting property model. Faces, Vertices, XData, YData, and ZData are supported properties; lighting, normals, texture coordinates, and callback properties remain deferred.
Patch is a plotting sink and fusion boundary. Host and gathered-GPU inputs produce the same object and handle behavior. GPU coordinate inputs gather for shape validation, one-based Faces handling, NaN padding, and polygon triangulation before submission to the shared GPU renderer; there is no direct resident triangulation/packing path.
Polygon colors
patch(X,Y,C) and patch(X,Y,Z,C) use a coordinate color grid: indexed C matches the X/Y grid, and RGB C adds a final three-component plane. For uncolored 3-D geometry, specify XData, YData, and ZData properties. patch('Faces',F,'Vertices',V,'FaceVertexCData',C) uses indexed scalar/per-face/per-vertex colors or n-by-3 RGB rows. Source colors remain separate from triangulated renderer vertices.
FaceColor='flat' uses one color per face (the first vertex for per-vertex data). FaceColor='interp' requires per-vertex colors, which are interpolated across each triangle. Floating truecolor components lie in [0,1], with NaN making the affected face/vertex transparent; integer components are normalized from their native class range at rendering.
Properties and replay
get and set accept FaceVertexCData, CData, and CDataMapping on patch handles. Color source class and shape survive scene replay; scaled indexed colors use axes color limits or the source extent. In direct mode, floating values are one-based colormap indices and integer values are zero-based indices.
Explicit GPU coordinate/color inputs use the existing plotting gather boundary where supported. Patch output is a host graphics handle, not a resident numeric GPU result. Finite whole-scene allocation and browser renderer execution remain separately qualified.
Examples
Create a triangle patch
x = [0 1 0];
y = [0 0 1];
h = patch(x, y, 'red');Create two rectangle patches from matrix columns
X = [0 2; 1 3; 1 3; 0 2];
Y = [0 0; 0 0; 1 1; 1 1];
h = patch(X, Y, 'cyan', 'EdgeColor', 'black');Create a patch from Faces and Vertices
V = [0 0; 1 0; 1 1; 0 1];
F = [1 2 3 4];
h = patch('Faces', F, 'Vertices', V, 'FaceColor', [0.2 0.6 0.9]);
get(h, 'Type')Expected output:
ans =
'patch'Create a 3-D patch
V = [0 0 0; 1 0 0; 0.5 1 0.5];
F = [1 2 3];
h = patch('Faces', F, 'Vertices', V, 'FaceAlpha', 0.6);
view(3);Interpolate colors across a triangular patch
F = [1 2 3]; V = [0 0; 1 0; 0 1]; C = [1 0 0; 0 1 0; 0 0 1]; h = patch('Faces',F,'Vertices',V,'FaceVertexCData',C,'FaceColor','interp'); assert(isequal(get(h,'FaceVertexCData'),C));Rendered patch example
vertices = [-1 -1 0; 1 -1 0; 1 1 0; -1 1 0; 0 0 1.8];
faces = [1 2 5; 2 3 5; 3 4 5; 4 1 5];
patch('Faces', faces, 'Vertices', vertices, 'FaceColor', [0.25 0.65 0.95], 'EdgeColor', [0.9 0.95 1.0], 'FaceAlpha', 0.72);
title('Triangulated Sensor Housing');
xlabel('x');
ylabel('y');
zlabel('z');
view(38, 24);
axis equal;
grid on;
Compare this result with other chart types in the plot examples.
Using patch with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how patch changes the result.
Run a small patch example, explain the result, then change one input and compare the output.
FAQ
Does patch close polygons automatically?⌄
Yes. You can provide open polygon coordinate lists; RunMat closes the edge loop when rendering the patch.
Are Faces indices zero-based or one-based?⌄
They are one-based to match MATLAB. Faces = [1 2 3] references the first, second, and third rows of Vertices.
Does patch have a direct GPU-resident geometry path?⌄
Not yet. RunMat gathers GPU-resident patch inputs for validation and triangulation, then submits the resulting geometry to the shared GPU renderer. A direct GPU triangulation/packing path can be added later for very large patch meshes.
When can FaceColor be interp?⌄
Provide color data for every vertex, then set FaceColor to interp.
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 · 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 patch is executed, line by line, in Rust.
- View the source for patch 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.