RunMat
  • Pricing
RunMat
GitHub
GitHub
Sign inTry in browser
DesktopRuntimePhysicsCADAdministrationAgent

Get RunMat updates

New releases, guides and examples.

Product+
  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download
Math+
  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting
Physics+
  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA
Industries+
  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance
Learn+
  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students
Compare+
  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons
Company+
  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms

Product

  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download

Math

  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting

Physics

  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA

Industries

  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance

Learn

  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students

Compare

  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons

Company

  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms
GitHubXLinkedIn

© Dystr, Inc. · RunMat v0.7.1, Nov 17, 2026

RunMat® is a registered trademark of Dystr, Inc. MATLAB® is a registered trademark of The MathWorks, Inc. RunMat is not affiliated with, endorsed by, or sponsored by The MathWorks, Inc.

/
See all docs
Builtin Reference
    • addpoints
    • ancestor
    • animatedline
    • area
    • autumn
    • axes
    • axis
    • bar
    • barh
    • bone
    • box
    • caxis
    • cla
    • clf
    • clim
    • colorbar
    • colorcube
    • colormap
    • colororder
    • contour
    • contour3
    • contourf
    • cool
    • copper
    • copyobj
    • cylinder
    • daspect
    • datacursormode
    • dataTipTextRow
    • drawnow
    • errorbar
    • fcontour
    • figure
    • fill
    • fill3
    • findobj
    • fsurf
    • gca
    • gcf
    • get
    • gobjects
    • gray
    • grid
    • groot
    • heatmap
    • hgload
    • hgsave
    • hidden
    • hist
    • histogram
    • histogram2
    • hold
    • hot
    • image
    • imagesc
    • imshow
    • inferno
    • isgraphics
    • ishandle
    • jet
    • legend
    • line
    • lines
    • linkaxes
    • loglog
    • magma
    • mesh
    • meshc
    • openfig
    • opengl
    • pan
    • parula
    • patch
    • pie
    • pink
    • plasma
    • plot
    • plot3
    • plotmatrix
    • plotyy
    • polarhistogram
    • polarplot
    • polarscatter
    • print
    • quiver
    • quiver3
    • ribbon
    • saveas
    • savefig
    • scatter
    • scatter3
    • semilogx
    • semilogy
    • set
    • sgtitle
    • shading
    • sphere
    • spring
    • stackedplot
    • stairs
    • stem
    • subplot
    • subtitle
    • summer
    • suptitle
    • surf
    • surfc
    • text
    • textscatter
    • textscatter3
    • title
    • triplot
    • turbo
    • view
    • viridis
    • waitbar
    • winter
    • wordcloud
    • xlabel
    • xlim
    • xline
    • xscale
    • xtickangle
    • xtickformat
    • xticklabels
    • xticks
    • ylabel
    • ylim
    • yline
    • yscale
    • ytickangle
    • ytickformat
    • yticklabels
    • yticks
    • zlabel
    • zlim
    • zoom

image — Display indexed or truecolor images in MATLAB and RunMat.

image displays indexed or truecolor data as a graphics object and returns an image handle. Axes placement, handle properties, and rendering semantics follow MATLAB behavior.

Syntax

h = image(C)
h = image(X, Y, C)
h = image(C, Name, Value, ...)
h = image(X, Y, C, Name, Value, ...)

Inputs

C
Type
Any
Required
Yes
Description
Image data array (indexed matrix or truecolor MxNx3/MxNx4).
X
Type
NumericArray
Required
Yes
Description
X coordinates or extent vector.
Y
Type
NumericArray
Required
Yes
Description
Y coordinates or extent vector.
props
Type
Any
Required
Variadic
Description
Name/value surface style options.
NameTypeRequiredDefaultDescription
CAnyYes—Image data array (indexed matrix or truecolor MxNx3/MxNx4).
XNumericArrayYes—X coordinates or extent vector.
YNumericArrayYes—Y coordinates or extent vector.
propsAnyVariadic—Name/value surface style options.

Returns

h
Type
NumericScalar
Description
Handle to the rendered image object.
NameTypeDescription
hNumericScalarHandle to the rendered image object.

Errors

RunMat:image:InvalidArgument
When
Image data, axis inputs, or name/value style arguments are invalid.
Message
image: invalid argument
RunMat:image:Internal
When
Internal image/surface construction or rendering fails unexpectedly.
Message
image: internal operation failed
RunMat:plotting:TooManyOutputs
When
More than one output is requested from a coordinate chart constructor.
Message
plotting: too many output arguments
IdentifierWhenMessage
RunMat:image:InvalidArgumentImage data, axis inputs, or name/value style arguments are invalid.image: invalid argument
RunMat:image:InternalInternal image/surface construction or rendering fails unexpectedly.image: internal operation failed
RunMat:plotting:TooManyOutputsMore than one output is requested from a coordinate chart constructor.plotting: too many output arguments

Behavior

image(C) displays image data using implicit axes; image(X, Y, C) places the image explicitly on the target axes.

Indexed images and truecolor images both use the shared surface/image rendering architecture.

The returned value is an image-handle object that works with get and set.

image is object-oriented and placement-oriented; use imagesc when you specifically want scaled matrix visualization with color mapping semantics.

Dedicated GPU-backed paths cover both indexed and truecolor image inputs when plotting-compatible buffers are available.

Rendering and residency

image uses the shared image/surface path and supports GPU-backed paths for indexed and truecolor image inputs.

image can render exported indexed or truecolor GPU buffers directly when a compatible shared plotting context is installed. Current handle publication still captures CData through owning-provider readback, and indexed host fallback can gather that source again. The renderer-buffer path is therefore not a zero-readback or exactly-one-gather guarantee. Export/readback/emission failures propagate through their owning completion protocol rather than authorizing replay.

Indexed images and truecolor images both have dedicated GPU-aware rendering paths in the image stack.

Image handle behavior, axes placement, and replay/export semantics remain aligned across GPU and fallback paths.

Declared source precision and class coverage

single

double

Coordinate broadcasting

none

Runtime contract and boundaries

Catalog default bindings retain the actual RuntimeContext and original rooted BuiltinArguments across parsing, provider readback, delegated calls and completion. Value-selected axes, properties and output counts remain Runtime decisions. Constructor results are host double graphics handles, not numerical GPU arrays; hist instead returns double counts/centres, plotyy up to three distinct handle outputs, and plotmatrix up to five.

Rendering is a fusion boundary and requires the installed graphics host/device. A direct compatible renderer route is not an elementwise or reduction provider kernel. Resident buffers retain their owning provider and existing export/error/completion protocol; an export, readback, allocation, cancellation or emission failure is an error, not permission to replay an attempted operation. Source data and renderer caches have distinct lifetimes. No new distributed chart implementation is declared.

The existing canonical CoordinateWork allocation policy refuses Managed calls before unowned chart scratch, metadata, readback or scene mutation. It checks captured cancellation generation and policy before publication and on completion; ingress failures are Never replay. This is an explicit missing finite owner, not an allocation estimate, algorithm completion or L25 closure. Provider-private allocations, renderer lifetime accounting, synchronous long geometry/copy cooperation, measured throughput and physical presentation remain independent qualification gates.

Native Single/Double/integer source ownership is distinguished from explicit binary64/f32 graphics conversion. The renderer does not promise exact wide-integer pixel positions. Logical, complex, sparse, scalar, vector, matrix, empty and higher-rank forms follow the identity-specific parser rather than a universal implicit cast. Sparse/complex rejection is not an integer not-applicable audit. Full MATLAB properties, browser/native parity and empty-shape conformance are not inferred from migration or historical test references.

Supported representations and remaining forms

Forms are C or X/Y/C plus shared surface-style pairs and CDataMapping=direct/scaled. C-only textual controls are separated by actual string/character-row kind; explicit numeric X/Y/C remains unchanged. This owner does not parse an independent leading-axes form. X/Y axis extents and source grid geometry are validated by the existing image/surface owner. Empty GPU extents now reject consistently rather than being silently changed to one.

Indexed CData uses direct mapping by default: floating indices are one-based, integer indices zero-based. Three-channel truecolor and separately gated four-channel data normalize native integer ranges or clamp finite floating values at the renderer boundary. Native CData is retained for get. Complex/sparse data and full MATLAB image/axes property parity remain outside this implementation; the generic surface-style grammar does not imply all image object setters exist.

Floating indexed and truecolor buffers can use compatible shared-device exporters. Retained CData currently requires an eager owning-provider property snapshot even on a direct renderer route. Indexed host fallback may read the numeric source again; neither zero-readback nor exactly-one-readback is promised. A prepared export/emission error propagates through its existing completion owner instead of host replay.

Examples

Display a simple indexed image

C = [1 2 3; 3 2 1; 2 3 1];
image(C);
colormap('jet');

Display a truecolor RGB image

img = zeros(100, 100, 3);
img(:,:,1) = 1;
img(25:75,25:75,2) = 1;
image(img);

Expected output:

% Displays a truecolor image object

Position an image explicitly on axes and inspect the handle

C = reshape(1:16, 4, 4);
h = image([0 3], [10 40], C);
get(h, 'Type')

Expected output:

ans =
    'image'

Rendered image example

[X, Y] = meshgrid(linspace(0, 1, 180), linspace(0, 1, 180));
pattern = 0.5 + 0.5*sin(4*pi*X).*cos(3*pi*Y);
color_index = round(1 + 63*pattern);

image(color_index);
colormap('turbo');
colorbar;
title('Indexed Color Field');
xlabel('Column');
ylabel('Row');
axis equal;
Expected output:
Synthetic indexed color field displayed with the MATLAB image function in RunMat

Compare this result with other chart types in the plot examples.

Using image with coding agents

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

Run a small image example, explain the result, then change one input and compare the output.

FAQ

How do I display RGB data with image?⌄

Pass an MxNx3 array where the third dimension holds red, green, and blue channels. Values should be in [0, 1] for doubles or [0, 255] for uint8.

img = zeros(100, 100, 3);
img(:,:,1) = 1;           % full red
img(30:70, 30:70, 2) = 1; % green square
image(img);
When should I use image vs imagesc?⌄

image displays pixel data as-is — either indexed colors through a colormap or direct RGB truecolor. imagesc automatically scales a 2-D matrix so its min and max span the full colormap range. If you're showing actual image pixels or pre-indexed data, use image. If you're visualizing a matrix of computed values as a heatmap, use imagesc.

Why does my image appear upside down?⌄

By default, image sets the y-axis to go from top to bottom (row 1 at the top), which matches matrix indexing. If your coordinate system expects y to increase upward, call axis xy after image to flip the axis direction. Use axis ij to restore the default matrix-style orientation.

Related Plotting functions

2D Charts

area · bar · errorbar · heatmap · hist · histogram · loglog · pie · plot · scatter · semilogx · semilogy · stairs · stem

3D & Surface

contour · contour3 · contourf · mesh · meshc · plot3 · quiver · scatter3 · surf · surfc

Images

imagesc · imshow

Axes & Layout

axis · box · grid · sgtitle · subplot · title · view · zlabel

Appearance

colorbar · colormap · legend · shading

Handle Access

gca · gcf · get · set

Other

addpoints · ancestor · animatedline · autumn · axes · barh · bone · caxis · cla · clf · clim · colorcube · colororder · cool · copper · copyobj · cylinder · daspect · datacursormode · dataTipTextRow · drawnow · fcontour · figure · fill · fill3 · findobj · fsurf · gobjects · gray · groot · hgload · hgsave · hidden · histogram2 · hold · hot · inferno · isgraphics · ishandle · jet · line · lines · linkaxes · magma · openfig · opengl · pan · parula · patch · pink · plasma · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · spring · stackedplot · subtitle · summer · suptitle · text · textscatter · textscatter3 · triplot · turbo · viridis · waitbar · winter · wordcloud · xlabel · xlim · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · ylabel · ylim · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zlim · zoom

More plotting resources

  • Choosing the right plot type
  • Styling plots and axes
  • Plot replay and export
  • Complete plotting guide

Source you can read

Every RunMat function's source is public. Read exactly how image is executed, line by line, in Rust.

  • View the source for image in Rust on GitHub
  • Learn how the RunMat runtime works
  • Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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

Download RunMat

Download RunMat for full performance, or use RunMat in your browser for zero setup.

Download RunMatOpen Sandbox
On this page
  • Syntax
  • Inputs
  • Returns
  • Errors
  • Behavior
  • Rendering and residency
  • Declared source precision and class coverage
  • Coordinate broadcasting
  • Runtime contract and boundaries
  • Supported representations and remaining forms
  • Examples
  • Display a simple indexed image
  • Display a truecolor RGB image
  • Position an image explicitly on axes and inspect the handle
  • Rendered image example
  • Using image with coding agents
  • FAQ
  • Related Plotting functions
  • 2D Charts
  • 3D & Surface
  • Images
  • Axes & Layout
  • Appearance
  • Handle Access
  • Other
  • More plotting resources
  • Source you can read
  • About RunMat