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.- 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. - GPU-resident coordinate buffers can feed the renderer directly on the happy path; otherwise RunMat gathers once 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 coordinate buffers directly. If a direct GPU path is not available for the active combination, RunMat gathers once and renders the same plot semantics on the host path.
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;
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. Each element controls the marker area for the corresponding point.
t = linspace(0, 4*pi, 200);
sizes = linspace(5, 50, 200);
scatter3(cos(t), sin(t), t, sizes);A scalar fourth argument sets all points 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. Each value maps through the active colormap. Add colorbar to show the mapping.
scatter3(x, y, z, 20, myValues);
colormap('turbo');
colorbar;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
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.