copyobj — Copy plot-child graphics objects to a compatible axes parent.

copyobj duplicates supported graphics objects and returns fresh graphics handles. MATLAB's public inputs are graphics objects rather than integer data. RunMat currently supports plot-child object copies, including line, scatter, bar, stairs, stem, area, quiver, image, heatmap, binscatter, surface, patch, line3, scatter3, contour, fcontour, fsurf, constant-line, pie, and histogram-backed plot children.

Syntax

hnew = copyobj(h, parent)

Inputs

Returns

Errors

How copyobj works

• copyobj(h, parent) copies each plot-child handle in h to a compatible axes parent. Plot children such as lines do not accept a figure or panel as their destination parent.
• Copied objects are inserted into the destination axes identified by parent.
• A scalar parent is applied to every source handle; same-sized source and parent arrays copy each source into the corresponding parent; a scalar source can be copied into each parent in a parent array.
• Handle arrays preserve the controlling input shape and receive fresh handle values. MATLAB forbids copying the same object more than once to the same parent in one call; enforcing that rule remains a compatibility gap.
• Because RunMat currently encodes graphics handles numerically, compatibility mode can separately enable exact host typed-integer handle aliases for all eight integer classes. Negative and nonexact values reject before lookup; exactly representable aligned wide integers proceed to ordinary handle lookup. Resident integer arrays always reject without provider gather.
• RunMat validates the whole source/parent copy plan before mutating graphics state, so invalid handle arrays do not leave partial copies behind.
• Copied plot children preserve their plotted geometry and readable/writable plot-child properties such as Type, Parent, data vectors, line styling, and display names.
• Figure, axes, text, legend, ruler, root-object, UI-container, and composite-chart deep copies are rejected with RunMat:copyobj:InvalidArgument rather than silently returning shallow placeholders.
• The optional copyobj(obj, parent, 'legacy') callback/application-data form is not implemented. Callback, application-data, context-menu, toolbar, axes-interaction, and data-tip-template copy rules remain general object-copy gaps.

Does RunMat run copyobj on the GPU?

copyobj performs no provider dispatch because graphics object copying is a host graphics-registry operation.

When copied plot elements were originally built from GPU-resident input data, the existing plot-state representation is cloned; no additional CPU/GPU transfer is initiated by copyobj itself.

GPU memory and residency

copyobj returns host-side numeric graphics handles. It does not gather, transform, or upload GPU arrays.

Examples

Copy a line to another axes

h = plot(1:3, [1 4 9], 'DisplayName', 'source');
ax2 = subplot(1,2,2);
h2 = copyobj(h, ax2);
get(h2, 'Parent') == ax2

Expected output:

ans = true

Copy a handle array to the same parent

h(1) = plot(1:3);
h(2) = plot(3:-1:1);
ax2 = subplot(1,2,2);
h2 = copyobj(h, ax2);
size(h2)

Expected output:

ans = [1 2]

Copy one object into two parent axes

h = plot(1:3);
ax1 = subplot(1,2,1);
ax2 = subplot(1,2,2);
h2 = copyobj(h, [ax1 ax2]);
size(h2)

Expected output:

ans = [1 2]

Using copyobj with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how copyobj changes the result.

FAQ

Related Plotting functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how copyobj is executed, line by line, in Rust.

• View the source for copyobj 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.

Getting started · Benchmarks · Pricing