findobj — Find graphics objects by handle hierarchy and property predicates.
findobj walks the RunMat graphics handle tree and returns handles whose properties satisfy MATLAB-style search predicates. With no root handle it searches from the graphics root through figures, axes, plot children, numeric rulers, nonempty text labels, and legends represented by the RunMat plotting registry.
Syntax
h = findobj()
h = findobj(prop, value, ...)
h = findobj(objhandles, '-depth', d, filters...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
filters | Any | Variadic | — | Property/value predicates, -property, -regexp, -not, and logical operators. |
objhandles | Any | Yes | — | Graphics handle or handle array that restricts the search root. |
filters | Any | Variadic | — | Optional depth/flat options and property predicates. |
Returns
| Name | Type | Description |
|---|---|---|
h | NumericArray | Graphics handles that satisfy the requested hierarchy and property filters. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:findobj:InvalidArgument | Arguments, search roots, depth, operators, property names, or regexp patterns are malformed. | findobj: invalid argument |
How findobj works
findobj()returns the graphics root, figures, axes, and searchable descendants in traversal order.findobj(prop, value)returns objects whose property exactly matchesvalue.findobj(objhandles, ...)restricts the search to the supplied numeric graphics handle or numeric handle array. Duplicate roots can produce duplicate result handles, matching MATLAB traversal behavior.findobj(objhandles, 'flat', ...)searches only the supplied root handles.findobj(objhandles, '-depth', d, ...)limits descendant traversal to depthd;Infmeans unlimited depth.- Multiple property predicates are combined with implicit
-andwhen no logical operator is supplied. - An empty result is returned as a numeric
0x0tensor; nonempty results are returned as a numeric column vector of handles.
Options
'-not', predicatenegates a property, grouped,-property, or-regexppredicate.'-and','-or', and'-xor'combine adjacent predicates from left to right.'-property', propmatches objects that expose propertypropthrough RunMat's plottinggetsurface.'-regexp', prop, exprmatches text-renderable property values against a regular expression. A cell array or string array of patterns matches when any pattern matches.- Grouped predicates can be passed as cell arrays, for example
{ 'Type', 'line', '-and', 'DisplayName', 'series-a' }. - The
Typeproperty comparison is case-insensitive. Logical properties accept logical values and MATLAB-style'on'/'off'text. - Color properties normalize MATLAB short names, full names, hex colors, and RGB triples before comparison when both sides are recognized color specifications.
Does RunMat run findobj on the GPU?
findobj performs no provider dispatch because graphics-handle metadata is owned by the runtime plotting registry.
Plotting commands that created the graphics objects remain responsible for preserving or consuming GPU-resident data through the plotting pipeline.
GPU memory and residency
findobj returns host-side numeric graphics handles. It does not transfer, gather, or mutate GPU-resident arrays.
Examples
Find all line objects
plot(1:3, [1 4 9], 'DisplayName', 'series-a');
h = findobj('Type', 'line')Expected output:
% h is a column vector of matching line handlesSearch below the current axes
plot(1:3, [1 4 9], 'DisplayName', 'series-a');
h = findobj(gca(), 'DisplayName', 'series-a')Expected output:
% h contains the plotted line handleLimit search depth from a figure
f = gcf();
h = findobj(f, '-depth', 1)Expected output:
% h contains the figure and its axes, but not line descendantsUse a regular expression predicate
plot(1:3, [1 4 9], 'DisplayName', 'series-a');
h = findobj('-regexp', 'DisplayName', '^series-')Using findobj with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how findobj changes the result.
Run a small findobj example, explain the result, then change one input and compare the output.
FAQ
Does findobj include the graphics root?⌄
Yes. A root search starts at handle 0, and findobj() includes the root when no filter excludes it.
Can findobj search only a figure or axes?⌄
Yes. Pass a numeric figure, axes, or plot-object handle as the first argument to use that object as the search root.
Does findobj gather GPU arrays?⌄
No. findobj only searches host-side graphics metadata and never inspects provider-resident numeric buffers.
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 · 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 · textscatter · textscatter3 · triplot · waitbar · wordcloud · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zoom
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how findobj is executed, line by line, in Rust.
- View the source for findobj 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.