textscatter3 — Create a 3-D text scatter chart from x/y/z coordinates and text labels.
textscatter3(x,y,z,str) creates a 3-D text scatter chart with labels from str at matching x/y/z coordinates. textscatter3(xyz,str) accepts an N-by-3 coordinate matrix. The returned handle is a textscatter chart object with data and display properties.
Syntax
ts = textscatter3(x, y, z, str)
ts = textscatter3(xyz, str)
ts = textscatter3(ax, ...)
ts = textscatter3(..., Name, Value)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
x | NumericArray | Yes | — | X coordinates. |
y | NumericArray | Yes | — | Y coordinates. |
z | NumericArray | Yes | — | Z coordinates. |
str | Any | Yes | — | String vector or cell array of character vectors. |
xyz | NumericArray | Yes | — | N-by-3 coordinate matrix. |
props | Any | Variadic | — | Name/value TextScatter properties. |
Returns
| Name | Type | Description |
|---|---|---|
ts | NumericScalar | Handle to the TextScatter chart object. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:textscatter:InvalidArgument | Coordinates, text labels, axes target, or TextScatter property values are invalid. | textscatter: invalid argument |
RunMat:textscatter:Internal | Internal plotting state update fails while creating or mutating TextScatter. | textscatter: internal operation failed |
How textscatter3 works
x,y,z, andstrmust have equal element counts.xyzmust be an N-by-3 matrix whose first, second, and third columns provide x, y, and z coordinates.- Coordinates can use single, double, or any of the eight integer classes.
XData,YData, andZDataretain their native class, shape, and exact values. strcan be a string scalar, string array, character row, character matrix, or cell array of text scalars.- The axes-target form
textscatter3(ax,...)renders into the supplied axes handle. ZDatais populated from the z coordinates and can be queried withget.TextDensityPercentage,MaxTextLength,MarkerColor,MarkerSize,ColorData,Colors, andVisiblefollow the same semantics astextscatter.getsupportsType,Parent,Children,TextData,XData,YData,ZData,TextDensityPercentage,MaxTextLength,MarkerColor,MarkerSize,ColorData,Colors,Visible,DisplayName, andTag.setsupportsTextData,XData,YData,ZData,TextDensityPercentage,MaxTextLength,MarkerColor,MarkerSize,ColorData,Colors,Visible,Color,FontSize,FontWeight,FontAngle, andInterpreter.- Categorical
ColorData, datasource properties, callbacks, app data, and interactive data-tip template objects are not implemented yet and raise explicit unsupported-property errors. - Typed-integer numeric axes aliases and explicit gpuArray inputs are RunMat-mode extensions.
Examples
Create a 3-D text scatter chart
x = [1 2 3];
y = [4 5 6];
z = [7 8 9];
words = ["one" "two" "three"];
ts = textscatter3(x, y, z, words);Use an N-by-3 coordinate matrix
xyz = [1 4 7; 2 5 8; 3 6 9];
textscatter3(xyz, ["one" "two" "three"]);Read z coordinates from the chart
ts = textscatter3([1 2], [3 4], [5 6], ["a" "b"]);
get(ts, 'ZData')Expected output:
ans =
5 6Using textscatter3 with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how textscatter3 changes the result.
Run a small textscatter3 example, explain the result, then change one input and compare the output.
FAQ
Does textscatter3 return a different object type than textscatter?⌄
The MATLAB chart type is textscatter for both 2-D and 3-D forms. RunMat follows that convention and distinguishes the 3-D form by storing nonempty ZData.
How are 3-D markers handled?⌄
When markers are enabled, RunMat creates an internal scatter3 marker plot using the same coordinates and resolved marker colors.
Can textscatter3 preserve gpuArray residency?⌄
The chart and its annotations are host graphics objects. Automatically resident inputs are gathered transparently through their owning provider. Explicit gpuArray inputs require RunMat mode.
Does get(ts,'ZData') preserve integer values?⌄
Yes. All three coordinate properties use authoritative native storage, including int64 and uint64 values outside the exact double range. Renderer geometry is a separate derived cache.
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 · triplot · waitbar · wordcloud · xlabel · xlim · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · ylabel · ylim · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zlim · zoom
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how textscatter3 is executed, line by line, in Rust.
- View the source for textscatter3 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.