line — Create low-level 2-D or 3-D line graphics objects in MATLAB and RunMat.
line creates line graphics objects directly without clearing the current axes. It supports positional X,Y and X,Y,Z data, property constructors with XData, YData, and ZData, axes targeting, matrix column expansion, style strings, and common line name/value properties.
Syntax
h = line(X, Y)
h = line(X, Y, Z)
h = line(X, Y, Name, Value, ...)
h = line(Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | NumericArray | Yes | — | X data. |
Y | NumericArray | Yes | — | Y data. |
Z | NumericArray | Yes | — | Z data. |
props | Any | Variadic | — | Name/value pairs such as XData, YData, ZData, Color, LineWidth, and DisplayName. |
Returns
| Name | Type | Description |
|---|---|---|
h | NumericArray | Line graphics handle scalar or row vector when matrix data creates multiple lines. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:line:InvalidArgument | Line data, axes target, style arguments, or Name/Value pairs are invalid. | line: invalid argument |
RunMat:line:Internal | Internal plotting state update fails. | line: internal operation failed |
How line works
line(X,Y)creates a 2-D line object from vector data and returns its graphics handle.line(X,Y,Z)creates a 3-D line object and returns a line handle withXData,YData, andZDataproperties.- Matrix
XandYinputs with matching size create one line per column and return a row vector of handles. A vector paired with a matrix is reused for each matrix column when its length matches the matrix height. line('XData',x,'YData',y,...)supports low-level graphics construction, includingParentfor explicit axes targeting.lineappends to the target axes regardless of the currentholdmode, matching MATLAB's low-level graphics-object behavior.- Returned handles work with
getandsetfor line data, color, line style, line width, marker, display name, and visibility properties.
Options
XData,YData, andZDataprovide constructor data in name/value form.Parentaccepts an axes handle and routes construction to that axes.- Style strings such as
'r--o',':', and'k'are accepted after positional data. - Common line properties include
Color,LineWidth,LineStyle,Marker,MarkerSize,MarkerFaceColor,MarkerEdgeColor,DisplayName, andVisible.
Does RunMat run line on the GPU?
On the 2-D vector happy path, RunMat reuses exported plot input buffers and emits renderer-ready line geometry without a full host round-trip.
Reading data properties from a GPU-backed line can materialize source buffers; replacing XData or YData with set converts the object to host-backed line data while preserving handle semantics.
GPU memory and residency
line preserves GPU residency for simple 2-D vector inputs when the shared plotting context can consume exported GPU buffers directly. Matrix expansion, 3-D construction, and property-only forms gather to host data before registering the graphics object. GPU-backed handles still support get(h,'XData') and get(h,'YData') by reading back source buffers when those properties are requested.
Examples
Create a low-level 2-D line object
x = 0:0.1:1;
y = x.^2;
h = line(x, y, 'Color', 'r', 'LineWidth', 2);Expected output:
% h is a numeric line handleConstruct a line from graphics data properties
h = line('XData', [1 2 3], 'YData', [4 5 6], 'DisplayName', 'samples');
get(h, 'Type')Expected output:
ans =
'line'Create one line per matrix column
x = [1 1; 2 2; 3 3];
y = [1 3; 2 2; 3 1];
h = line(x, y);Expected output:
% h is a 1-by-2 row vector of line handlesCreate a 3-D line object
t = linspace(0, 2*pi, 100);
h = line(cos(t), sin(t), t, 'LineStyle', '--');Expected output:
% h is a line handle with XData, YData, and ZDataUsing line with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how line changes the result.
Run a small line example, explain the result, then change one input and compare the output.
FAQ
How is line different from plot?⌄
plot is a high-level charting command and clears the active axes unless hold on is enabled. line is a low-level graphics-object constructor, so it appends line objects to the target axes without requiring hold on.
Can I update line data after creating the object?⌄
Yes. Use set(h, 'XData', x, 'YData', y) for 2-D lines or also set ZData for 3-D lines. RunMat updates the stored geometry and invalidates cached render data.
What does line return for matrix inputs?⌄
Each matrix column becomes one line object. The return value is a row vector of graphics handles in column order.
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 · cla · clf · colorcube · colororder · copyobj · daspect · datacursormode · dataTipTextRow · fcontour · figure · fill3 · findobj · fsurf · gobjects · groot · hgload · hgsave · hidden · histogram2 · hold · linkaxes · openfig · opengl · pan · parula · patch · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · stackedplot · subtitle · suptitle · textscatter · textscatter3 · triplot · waitbar · wordcloud · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zoom
More plotting resources
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how line is executed, line by line, in Rust.
- View the source for line 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.