imshow — Display images in MATLAB and RunMat.
imshow displays grayscale, binary, and truecolor image data with MATLAB-style defaults. File-input handling and display scaling behavior follow MATLAB semantics.
Syntax
h = imshow(I)
h = imshow(I, [low high])
h = imshow(I, [])Inputs
I- Type
Any- Required
- Yes
- Description
- Image matrix/array or filename.
I- Type
Any- Required
- Yes
- Description
- Numeric grayscale image matrix/array.
DisplayRange- Type
NumericArray- Required
- Yes
- Default
[]- Description
- Display limits as [] or [low high].
Returns
h- Type
NumericScalar- Description
- Handle to the image object.
Errors
RunMat:imshow:InvalidArgument- When
- Image input, filename, or display range arguments are malformed or unsupported.
- Message
imshow: invalid argument
RunMat:imshow:Internal- When
- Internal image decoding or render preparation fails unexpectedly.
- Message
imshow: 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
imshow(I) displays 2-D numeric data with grayscale limits [0, 1], matching MATLAB double-image defaults.
imshow(BW) displays logical image data as black and white using [0, 1] limits.
imshow(RGB) displays MxNx3 truecolor data directly.
In runmat compatibility mode, imshow(RGBA) accepts supported numeric MxNx4 data as a RunMat extension and displays its fourth channel as alpha.
imshow(I, [low high]) displays grayscale image data using an explicit display range.
imshow(I, []) auto-scales grayscale image data from finite minimum to finite maximum.
imshow(filename) reads and decodes an image file, then displays it as truecolor data.
Rendering and residency
The compatibility target documents GPU Array input for imshow. RunMat treats imshow as a plotting sink rather than a precision-specialized compute kernel; grayscale gpuArray inputs may use the image/surface rendering path, while filename decoding and truecolor normalization run on the host.
Numeric provider precision frontier
imshow declares no direct numeric provider precision list; host generation/sampling or owner-aware gather and installed graphics rendering are separate boundaries.
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
Exactly one image/filename or image plus grayscale display range is accepted. Scalars/logical grayscale normalize to a two-dimensional host tensor; numeric grayscale uses class-derived limits (floating/logical 0..1, integer full class range), [] selects finite bounds, and an explicit two-element finite increasing vector supplies limits. Range controls reject truecolor and filename forms. Single/Double/uint8/uint16 truecolor requires nonempty M-by-N-by-3 data; supported M-by-N-by-4 is compatibility-gated. Logical truecolor and unsupported integer truecolor classes reject.
A filename is a string scalar, scalar string array or character row. Before the first suspension, the existing filesystem APIs capture its provider, provider-relative resolved path and resource lease. Every read and uploaded-name directory search stays on that same owner, checks revocation around awaits, and uses the supplied Runtime cancellation owner. Browser basename search retains its bounded unique-match rule. Decoding uses the actual installed image decoder and publishes RGBA doubles; no ambient provider re-selection or synthetic image is used.
Grayscale and truecolor rendering currently materialize host image/color grids and retain CData; old claims of a grayscale zero-copy numeric kernel are not made. The canonical union includes FilesystemRead/Filesystem for dynamic filenames and removes them for statically proven numeric/logical forms. Filename codec buffers and decoded-grid funding/cooperation are not a finite implementation. The real PNG example uses the existing Filesystem+Browser harness and property assertions, not a fabricated BrowserGraphics screenshot witness; physical Figure/presentation acceptance remains separate.
Examples
Display a simple grayscale image
row = 100;
col = 100;
rsm = ones(row, col);
imshow(rsm);Auto-scale a matrix for display
A = peaks(128);
imshow(A, []);Display truecolor RGB data
R = ones(64, 64);
G = zeros(64, 64);
B = zeros(64, 64);
RGB = cat(3, R, G, B);
imshow(RGB);Display an image file
imshow("photo.png");Rendered imshow example
[X, Y] = meshgrid(linspace(-3, 3, 220), linspace(-2, 2, 150));
field = exp(-0.8*((X-1).^2 + Y.^2)) - 0.7*exp(-((X+1).^2 + (Y-0.4).^2));
imshow(field, []);
title('Autoscaled Grayscale Field');
Compare this result with other chart types in the plot examples.
Using imshow with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how imshow changes the result.
Run a small imshow example, explain the result, then change one input and compare the output.
FAQ
What display range does imshow use for doubles?⌄
imshow(I) uses [0, 1] for floating-point grayscale data. Use imshow(I, []) when you want RunMat to scale the visible range from the data minimum to maximum.
Does imshow support uint8 and uint16 image defaults?⌄
Yes. Grayscale uint8 data uses [0, 255], grayscale uint16 data uses [0, 65535], and truecolor data of either class is normalized by the corresponding full-scale value.
How is imshow different from imagesc?⌄
imshow is for image display and uses grayscale or truecolor image defaults. imagesc is for scaled matrix visualization and maps data through the active colormap.
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
Source you can read
Every RunMat function's source is public. Read exactly how imshow is executed, line by line, in Rust.
- View the source for imshow 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.