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
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
filename | StringScalar | Yes | — | File path or HTTP(S) URL to load. |
fmt | StringScalar | No | — | Explicit image format hint (e.g. 'png', 'jpg', 'tiff'). |
Returns
| Name | Type | Description |
|---|---|---|
I | NumericArray | Loaded image array (grayscale, truecolor, or multi-channel numeric tensor). |
I | NumericArray | Loaded image array. |
map | NumericArray | Colormap output placeholder (empty for direct-color image formats). |
alpha | NumericArray | Alpha channel output when present; otherwise empty. |
Returned values from imread depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:imread:InvalidArgument | Input argument types are invalid (for example non-string filename or format). | imread: invalid argument |
RunMat:imread:InvalidFilename | Filename input is empty. | imread: invalid filename |
RunMat:imread:InvalidFormat | Format hint input is empty. | imread: invalid format hint |
RunMat:imread:UnsupportedFormat | Requested format hint is not supported. | imread: unsupported image format |
RunMat:imread:TooManyInputs | More than two input arguments are supplied. | imread: too many input arguments |
RunMat:imread:TooManyOutputs | More than three outputs are requested. | imread: too many output arguments |
RunMat:imread:UnsupportedScheme | Source URL uses an unsupported non-file scheme. | imread: unsupported URL scheme |
RunMat:imread:FileReadError | Local file source cannot be read. | imread: file read error |
RunMat:imread:InvalidFileUrl | File URL path/host encoding is invalid. | imread: invalid file URL |
RunMat:imread:Timeout | HTTP request times out. | imread: request timed out |
RunMat:imread:NetworkError | HTTP request fails due to network/connectivity issues. | imread: network error |
RunMat:imread:HttpStatus | HTTP response returns non-success status. | imread: HTTP status error |
RunMat:imread:InvalidHeader | HTTP request contains invalid headers. | imread: invalid request header |
RunMat:imread:DecodeError | Image bytes cannot be decoded into a supported raster format. | imread: decode error |
RunMat:imread:ShapeError | Decoded image cannot be materialized into tensor shape. | imread: shape materialization error |
How imread works
- Accepts a character vector or string scalar for the image source.
- Due to CORS and browser security restrictions,
file://URLs andhttp:///https://URLs are not currently supported. Upload your image first and pass the resulting filename toimread. - Accepts an optional explicit format hint:
imread(filename, format). Common hints includepng,jpg,jpeg,tif,tiff,bmp,gif, andwebp. - 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
uint8tensors and 16-bit images returnuint16tensors. Floating-point images returnsingletensors when the decoder exposes floating-point pixel data. - For
[X, map] = imread(...), RunMat returnsXand 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 3Get Alpha Separately
[rgb, map, alpha] = imread("icon.png");
size(alpha)Expected output:
ans =
rows colsUse 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.
Related Image functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how imread is executed, line by line, in Rust.
- View the source for imread in Rust on GitHub
- Learn how the RunMat 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 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.