imread — Read image data from an uploaded file into MATLAB-compatible arrays.

imread(filename) reads raster image data into dense column-major tensors using MATLAB-compatible shape conventions. Grayscale images return an MxN array, RGB images return an MxNx3 truecolor array, and alpha channels are available through the third output. Due to CORS and browser security restrictions, file:// and http:///https:// URLs are not currently supported — upload your image first and pass the resulting filename to imread.

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.

How RunMat runs 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.

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.

Related Image functions

Open-source implementation

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

• View imread.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing