RunMat
GitHub

imread — Read image files into arrays in MATLAB and RunMat.

imread(filename) reads raster image data into dense arrays. Grayscale images return M-by-N data, RGB images return M-by-N-by-3 truecolor data, and alpha channels are available via additional outputs, following MATLAB semantics.

Syntax

I = imread(filename)
I = imread(filename, fmt)
[I, map] = imread(filename)
[I, map] = imread(filename, fmt)
[I, map, alpha] = imread(filename)
[I, map, alpha] = imread(filename, fmt)

Inputs

NameTypeRequiredDefaultDescription
filenameStringScalarYes—File path or HTTP(S) URL to load.
fmtStringScalarNo—Explicit image format hint (e.g. 'png', 'jpg', 'tiff').

Returns

NameTypeDescription
INumericArrayLoaded image array (grayscale, truecolor, or multi-channel numeric tensor).
INumericArrayLoaded image array.
mapNumericArrayColormap output placeholder (empty for direct-color image formats).
alphaNumericArrayAlpha channel output when present; otherwise empty.

Returned values from imread depend on how many outputs the caller requests.

Errors

IdentifierWhenMessage
RunMat:imread:InvalidArgumentInput argument types are invalid (for example non-string filename or format).imread: invalid argument
RunMat:imread:InvalidFilenameFilename input is empty.imread: invalid filename
RunMat:imread:InvalidFormatFormat hint input is empty.imread: invalid format hint

How imread works

  • Accepts a character vector or string scalar for the image source.
  • Due to CORS and browser security restrictions, file:// URLs and http:///https:// URLs are not currently supported. Upload your image first and pass the resulting filename to imread.
  • Accepts an optional explicit format hint: imread(filename, format). Common hints include png, jpg, jpeg, tif, tiff, bmp, gif, and webp.
  • Without a format hint, RunMat detects the image format from the byte stream.
  • Grayscale images return MxN tensors. RGB and RGBA images return MxNx3 truecolor tensors using red, green, and blue planes along the third dimension.
  • 8-bit images return uint8 tensors and 16-bit images return uint16 tensors. Floating-point images return single tensors when the decoder exposes floating-point pixel data.
  • For [X, map] = imread(...), RunMat returns X and an empty colormap for direct-color formats.
  • For [X, map, alpha] = imread(...), RunMat returns alpha as an MxN tensor when the source image has an alpha channel; otherwise alpha is empty.
  • Animated image frame selection and indexed colormap extraction are not implemented yet; current decoding returns the first decoded image frame as direct pixel data.

Does RunMat run imread on the GPU?

imread does not dispatch provider kernels and is not fusion eligible. GPU-resident scalar string inputs are gathered before decoding, and decoded pixel tensors remain on the host.

GPU memory and residency

imread always returns host-resident tensors because file and network I/O plus image decoding occur on the CPU. Use gpuArray after reading if later operations should use device residency.

Examples

Read A Local PNG

img = imread("logo.png");
size(img)

Expected output:

ans =
    rows    cols     3

Get Alpha Separately

[rgb, map, alpha] = imread("icon.png");
size(alpha)

Expected output:

ans =
    rows    cols

Use An Explicit Format Hint

img = imread("raw-download", "jpg");

Expected output:

% Decodes the bytes as JPEG even when the file name has no extension.

Using imread with coding agents

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

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

FAQ

What shape does imread return for RGB images?⌄

RGB images return an MxNx3 tensor where the third dimension stores red, green, and blue planes. Data is stored in RunMat's column-major tensor layout while preserving MATLAB indexing semantics.

Where is the alpha channel returned?⌄

Use the three-output form: [X, map, alpha] = imread(filename). Direct-color images return an empty colormap in map; alpha is an MxN tensor when present.

Can imread load file:// or HTTP URLs?⌄

Not currently. Due to CORS and browser security restrictions, file:// and http:///https:// URLs are blocked. Upload your image first and pass the resulting filename to imread.

Does imread return GPU arrays?⌄

No. Image reading performs host I/O and CPU decoding, so outputs are host tensors. Call gpuArray(imread(...)) if subsequent processing should run on the GPU.

Are animated GIF frames supported?⌄

Not yet. The current decoder returns the first decoded image frame as direct pixel data.

Image

imhist

Open-source implementation

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

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

Download RunMat

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

Download RunMatTry in your browser