imagesc — Display scaled matrix images in MATLAB and RunMat.
imagesc displays matrix data using scaled colormap mapping and returns an image handle. Color-limit behavior and axes integration follow MATLAB semantics.
Syntax
h = imagesc(C)
h = imagesc(X, Y, C)
h = imagesc(C, clims)
h = imagesc(C, Name, Value, ...)
h = imagesc(X, Y, C, Name, Value, ...)Inputs
C- Type
NumericArray- Required
- Yes
- Description
- Indexed image matrix.
X- Type
NumericArray- Required
- Yes
- Description
- X coordinates or extent vector.
Y- Type
NumericArray- Required
- Yes
- Description
- Y coordinates or extent vector.
clims- Type
NumericArray- Required
- Yes
- Description
- Two-element color limits.
props- Type
Any- Required
- Variadic
- Description
- Name/value surface style options.
Returns
h- Type
NumericScalar- Description
- Handle to the rendered scaled image object.
Errors
RunMat:imagesc:InvalidArgument- When
- Image data, axis inputs, or name/value style arguments are invalid.
- Message
imagesc: invalid argument
RunMat:imagesc:Internal- When
- Internal image/surface construction or rendering fails unexpectedly.
- Message
imagesc: internal operation failed
RunMat:plotting:TooManyOutputs- When
- More than one output is requested from a coordinate chart constructor.
- Message
plotting: too many output arguments
Behavior
imagesc(C) displays a matrix using implicit axes and scaled color mapping.
imagesc(X, Y, C) places the scaled image explicitly on the axes using the provided coordinate extents.
Unlike image, imagesc is fundamentally about colormap-driven value visualization rather than direct indexed/truecolor graphics-object placement.
The returned value is still an image-handle object in the shared plotting handle system.
imagesc works naturally with colormap, colorbar, caxis, and subplot-local axes state.
Rendering and residency
imagesc uses the same modern image/surface path as image, but applies scaled color-mapped visualization semantics for matrix data.
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
C or X/Y/C uses the same retained image parser and native classification as image, with scaled mapping by default. CDataMapping may override that default. A sole remaining two-element numeric control is a finite strictly increasing explicit color range; otherwise shared surface-style pairs apply. Scalar-handle output and retained CData class/shape are independent of rendered color conversion.
Explicit limits update the active axes color limits. Without explicit limits the image builder uses the current axes snapshot when one exists; data-bound color scaling in rendering is not a guarantee that every MATLAB automatic caxis state transition is implemented. The same eager source snapshot, possible indexed fallback readback, exporter failure ownership, RGBA extension and finite metadata frontiers as image apply.
Examples
Display a matrix as a heatmap-style scaled image
[X, Y] = meshgrid(linspace(-3, 3, 60), linspace(-3, 3, 60));
A = sin(X) .* cos(Y);
imagesc(A);
colorbar;Place a scaled image on explicit axes
A = reshape(1:100, 10, 10);
imagesc([-5 5], [0 1], A);
colormap('parula');Use subplot-local color workflows
[X, Y] = meshgrid(linspace(-3, 3, 40), linspace(-3, 3, 40));
Z = sin(X) .* cos(Y);
subplot(1, 2, 1);
imagesc(Z);
colormap('jet');
colorbar;
subplot(1, 2, 2);
imagesc(magic(20));
colormap('gray');Dense matrix as a heatmap
[X, Y] = meshgrid(linspace(-pi, pi, 300), linspace(-pi, pi, 300));
Z = sin(3*X) .* cos(2*Y) + cos(X.*Y);
imagesc(Z);
colormap('turbo');
colorbar;
title('Scalar Field Heatmap');
xlabel('Column');
ylabel('Row');
axis equal;Rendered imagesc example
[X, Y] = meshgrid(linspace(-pi, pi, 300), linspace(-pi, pi, 300));
Z = sin(3*X) .* cos(2*Y) + cos(X.*Y);
imagesc(Z);
colormap('turbo');
colorbar;
title('Scalar Field Heatmap');
xlabel('Column');
ylabel('Row');
axis equal;
Compare this result with other chart types in the plot examples.
Using imagesc with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how imagesc changes the result.
Run a small imagesc example, explain the result, then change one input and compare the output.
FAQ
What's the difference between imagesc and image?⌄
imagesc maps a 2-D matrix through the colormap with automatic scaling — the min value maps to the bottom of the colormap and the max to the top. image treats input as direct indexed or truecolor data without automatic scaling. Use imagesc for heatmaps and value visualization; use image when you have actual image pixel data (RGB arrays or pre-indexed values).
How does colormap scaling work with imagesc?⌄
Scaled image rendering maps data through the active colormap. Explicit imagesc(C,[lo hi]) limits update the active axes color limits; caxis([lo hi]) also provides explicit axes limits for subsequent image workflows. Without explicit limits this owner snapshots any current axes limits and otherwise lets the surface renderer use data-bound scaling; it does not certify every MATLAB automatic caxis state transition.
imagesc(A);
caxis([-1 1]);
colorbar;How do I display a matrix as a heatmap?⌄
Pass the matrix directly to imagesc and add a colorbar for the legend. Pair with a colormap that suits your data — diverging maps like 'coolwarm' work well for data centered around zero, sequential maps like 'parula' for positive-only ranges.
imagesc(myMatrix);
colormap('parula');
colorbar;Related Plotting functions
2D Charts
area · bar · errorbar · heatmap · hist · histogram · loglog · pie · plot · scatter · semilogx · semilogy · stairs · stem
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
Source you can read
Every RunMat function's source is public. Read exactly how imagesc is executed, line by line, in Rust.
- View the source for imagesc 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.