{
"title": "scatter",
"category": "plotting",
"keywords": [
"scatter",
"scatter plot",
"2-D scatter",
"marker plot",
"matlab scatter",
"point cloud visualization"
],
"summary": "Create 2-D scatter plots for point clouds, size/color encoding, and MATLAB `scatter` workflows.",
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [
"single",
"double"
],
"broadcasting": "none",
"notes": "`scatter` is a rendering sink. GPU-resident inputs can stay on device when the shared plotting path can consume exported point buffers directly."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 2,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::plotting::scatter::tests",
"integration": "runmat-plot/tests/renderer_tests.rs"
},
"description": "`scatter` creates 2-D marker plots from paired x and y coordinates. In RunMat it returns a scatter handle, participates in the shared plotting property system, and supports the MATLAB `scatter(x, y, s, c, 'filled')` style of workflows for marker size, marker color, and display-name driven chart composition.",
"behaviors": [
"`scatter(x, y)` requires the same element count in both inputs.",
"The returned value is a scatter-handle object that can be inspected and updated through `get` and `set`.",
"Marker size, marker face color, marker edge color, and display name all flow through the shared plotting handle model.",
"Scatter plots integrate naturally with `subplot` and `legend`, so series labels and axes-local state stay scoped to the active axes.",
"GPU-resident point buffers can be rendered directly on the happy path; unsupported combinations fall back to host materialization while preserving the same visible result."
],
"examples": [
{
"description": "Create a basic 2-D scatter plot",
"input": "t = linspace(0, 2*pi, 100);\nscatter(cos(t), sin(t));"
},
{
"description": "Use marker sizing and color-style workflows",
"input": "x = linspace(0, 1, 25);\ny = x.^2;\nh = scatter(x, y);\nset(h, 'SizeData', 12, 'MarkerFaceColor', 'r', 'Marker', 'o');"
},
{
"description": "Drive the legend from scatter object display names",
"input": "x = 1:10;\nh1 = scatter(x, x);\nset(h1, 'DisplayName', 'linear');\nhold on;\nh2 = scatter(x, x.^2);\nset(h2, 'DisplayName', 'quadratic');\nlegend;"
}
],
"links": [
{ "label": "plot", "url": "./plot" },
{ "label": "scatter3", "url": "./scatter3" },
{ "label": "legend", "url": "./legend" },
{ "label": "get", "url": "./get" },
{ "label": "set", "url": "./set" }
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/plotting/ops/scatter.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/scatter.rs"
},
"gpu_residency": "`scatter` preserves GPU residency when the plotting path can consume exported point buffers directly. If the active marker/style combination cannot use the direct path, RunMat gathers once and renders the same plot semantics on the fallback path.",
"gpu_behavior": [
"The direct path keeps point buffers on the device and avoids an unnecessary host round-trip for supported scatter workflows.",
"Marker styling and legend/display-name behavior stay consistent across GPU and host fallback rendering."
]
}