{
"title": "scatter3",
"category": "plotting",
"keywords": [
"scatter3",
"3-D scatter plot",
"point cloud",
"matlab scatter3",
"spatial data visualization",
"gpu plotting"
],
"summary": "Create 3-D scatter plots for spatial point clouds, encoded markers, and MATLAB `scatter3` workflows.",
"hero_image": "https://web.runmatstatic.com/builtin-image/runmat-matlab-plot-scatter3-3D-point-cloud.webp",
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [
"single",
"double"
],
"broadcasting": "none",
"notes": "`scatter3` is a rendering sink. GPU inputs can stay resident when the shared plotting device consumes exported buffers directly."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 3,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::plotting::scatter3::tests",
"integration": "runmat-plot/tests/renderer_tests.rs"
},
"description": "`scatter3` creates 3-D marker plots from matching x, y, and z coordinates. In RunMat it participates in the handle-returning plotting system, which means you can combine it with `subplot`, inspect the figure with `get`, adjust camera angles with `view`, and keep GPU-resident inputs on device when the shared rendering path is available.",
"behaviors": [
"`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 `view` and `zlabel`, 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."
],
"examples": [
{
"description": "Plot a 3-D helix as a point cloud",
"input": "t = linspace(0, 6*pi, 300);\nscatter3(cos(t), sin(t), t);"
},
{
"description": "Style a 3-D scatter plot and change the camera view",
"input": "t = linspace(0, 4*pi, 200);\nh = scatter3(cos(t), sin(t), t);\nset(h, 'DisplayName', 'helix', 'SizeData', 10);\nview(45, 25);"
},
{
"description": "Use subplot-local camera state with multiple 3-D plots",
"input": "subplot(1, 2, 1);\nscatter3(1:10, rand(1,10), rand(1,10));\nview(3);\nsubplot(1, 2, 2);\nscatter3(rand(1,10), rand(1,10), rand(1,10));\nview(2);",
"output": "% The two subplots keep independent 3-D view state"
},
{
"description": "3D point cloud with color-coded altitude",
"input": "n = 2000;\ntheta = 4*pi*rand(1, n);\nr = sqrt(rand(1, n));\nx = r .* cos(theta);\ny = r .* sin(theta);\nz = sin(3*r) ./ (1 + r);\n\nscatter3(x, y, z, 12, z, 'filled');\ncolormap('turbo');\ncolorbar;\ntitle('3-D Point Cloud — Altitude Encoded');\nxlabel('x');\nylabel('y');\nzlabel('z');\nview(35, 25);\ngrid on;",
"image_webp": "https://web.runmatstatic.com/builtin-image/runmat-matlab-plot-scatter3-3D-point-cloud.webp"
}
],
"faqs": [
{
"question": "How do I size scatter3 points by a data variable?",
"answer": "Pass a size vector as the fourth argument. Each element controls the marker area for the corresponding point.\n\n```matlab\nt = linspace(0, 4*pi, 200);\nsizes = linspace(5, 50, 200);\nscatter3(cos(t), sin(t), t, sizes);\n```\n\nA scalar fourth argument sets all points to the same size."
},
{
"question": "Can I color scatter3 points by a fourth variable?",
"answer": "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.\n\n```matlab\nscatter3(x, y, z, 20, myValues);\ncolormap('turbo');\ncolorbar;\n```"
},
{
"question": "How do I rotate or orbit a scatter3 plot?",
"answer": "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."
}
],
"links": [
{
"label": "plot3",
"url": "./plot3"
},
{
"label": "scatter",
"url": "./scatter"
},
{
"label": "view",
"url": "./view"
},
{
"label": "zlabel",
"url": "./zlabel"
},
{
"label": "subplot",
"url": "./subplot"
},
{
"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/scatter3.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/scatter3.rs"
},
"gpu_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.",
"gpu_behavior": [
"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."
]
}