scatter3 — Create 3-D scatter plots with marker size/color encodings using MATLAB-compatible scatter3 forms.
scatter3 creates 3-D marker plots from matching x/y/z coordinates and returns a graphics handle. It supports MATLAB-compatible forms for marker sizing, coloring, fill options, axes targeting, and plot property updates.
Syntax
h = scatter3(X, Y, Z)
h = scatter3(X, Y, Z, S)
h = scatter3(X, Y, Z, S, C)
h = scatter3(X, Y, Z, LineSpec)
h = scatter3(X, Y, Z, Name, Value, ...)
h = scatter3(ax, X, Y, Z)All supported scatter3 forms
h = scatter3(X, Y, Z)
h = scatter3(X, Y, Z, S)
h = scatter3(X, Y, Z, S, C)
h = scatter3(X, Y, Z, LineSpec)
h = scatter3(X, Y, Z, Name, Value, ...)
h = scatter3(ax, X, Y, Z)
h = scatter3(ax, X, Y, Z, S)
h = scatter3(ax, X, Y, Z, S, C)
h = scatter3(ax, X, Y, Z, LineSpec)
h = scatter3(ax, X, Y, Z, Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | NumericArray | Yes | — | X coordinates. |
Y | NumericArray | Yes | — | Y coordinates. |
Z | NumericArray | Yes | — | Z coordinates. |
S | NumericArray | Yes | — | Marker area specification. |
C | Any | Yes | — | Color specification (uniform, per-point scalar, or RGB matrix). |
lineSpec | StyleSpec | Yes | — | Marker/line style shorthand. |
props | Any | Variadic | — | Name/value marker style properties. |
ax | AxesHandle | Yes | — | Target axes handle. |
Returns
| Name | Type | Description |
|---|---|---|
h | NumericScalar | Handle to the rendered 3-D scatter plot. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:scatter3:InvalidArgument | Input data, axes targeting, or marker style arguments are invalid. | scatter3: invalid argument |
RunMat:scatter3:Internal | Internal 3-D scatter construction or rendering fails unexpectedly. | scatter3: internal operation failed |
How scatter3 works
scatter3(x, y, z)requires matching element counts across all three inputs; MATLAB documents all eight integer classes for each coordinate and for marker sizeS.- The builtin returns a scatter handle for the created plot object.
- 3-D scatter plots work naturally with
viewandzlabel, and all camera state remains subplot-local. - Host X/Y/Z graphics properties and FIG scene payloads retain authoritative f64, f32, or native integer class, shape, and exact values. A derived f32 vertex cache is used only for rendering and never becomes property or serialization authority.
- GPU-resident coordinate buffers can feed the renderer directly on the supported single/double path; otherwise RunMat gathers exactly through the handle's owning provider before plotting.
- Marker size and display-name style workflows are handled through the shared plotting object/property system.
Does RunMat run scatter3 on the GPU?
The preferred path keeps point buffers on the device and emits renderer-ready geometry without a full host round-trip.
Subplot, view, and object-handle behavior is the same on both the GPU and fallback host paths.
GPU memory and residency
scatter3 preserves GPU residency when the plotting path can consume exported single/double coordinate buffers directly. If a direct path is unavailable, RunMat gathers through the input handle's owning provider and renders the same plot semantics on the host path; host integer source data remains exact and authoritative independently of renderer materialization.
Examples
Plot a 3-D helix as a point cloud
t = linspace(0, 6*pi, 300);
scatter3(cos(t), sin(t), t);Style a 3-D scatter plot and change the camera view
t = linspace(0, 4*pi, 200);
h = scatter3(cos(t), sin(t), t);
set(h, 'DisplayName', 'helix', 'SizeData', 10);
view(45, 25);Use subplot-local camera state with multiple 3-D plots
subplot(1, 2, 1);
scatter3(1:10, rand(1,10), rand(1,10));
view(3);
subplot(1, 2, 2);
scatter3(rand(1,10), rand(1,10), rand(1,10));
view(2);Expected output:
% The two subplots keep independent 3-D view state3D point cloud with color-coded altitude
n = 2000;
theta = 4*pi*rand(1, n);
r = sqrt(rand(1, n));
x = r .* cos(theta);
y = r .* sin(theta);
z = sin(3*r) ./ (1 + r);
scatter3(x, y, z, 12, z, 'filled');
colormap('turbo');
colorbar;
title('3-D Point Cloud — Altitude Encoded');
xlabel('x');
ylabel('y');
zlabel('z');
view(35, 25);
grid on;
Compare this result with other chart types in the MATLAB Plot Gallery.
Using scatter3 with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how scatter3 changes the result.
Run a small scatter3 example, explain the result, then change one input and compare the output.
FAQ
How do I size scatter3 points by a data variable?⌄
Pass a size vector as the fourth argument, for example scatter3(cos(t), sin(t), t, sizes). Each element controls the corresponding marker area; a scalar fourth argument sets every point to the same size.
Can I color scatter3 points by a fourth variable?⌄
Pass a color vector as the fifth argument after the size vector, for example scatter3(x, y, z, 20, myValues). Each value maps through the active colormap; add colorbar to show the mapping.
How do I rotate or orbit a scatter3 plot?⌄
Use view(az, el) to set the camera angle programmatically. az is the horizontal orbit in degrees, el is the vertical tilt. view(3) gives the standard 3-D default. Each subplot keeps its own independent camera state, so you can show the same data from multiple angles in a subplot grid.
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 scatter3 is executed, line by line, in Rust.
- View the source for scatter3 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.