{
"title": "image",
"category": "plotting",
"keywords": [
"image",
"image display",
"truecolor image",
"indexed image",
"matlab image",
"imshow style image"
],
"summary": "Display indexed or truecolor images as graphics objects with MATLAB `image` semantics and GPU-backed rendering paths.",
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [
"single",
"double"
],
"broadcasting": "none",
"notes": "`image` uses the shared image/surface path and supports GPU-backed paths for indexed and truecolor image inputs."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 3,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::plotting::image::tests",
"integration": "runmat-plot/tests/renderer_tests.rs"
},
"description": "`image` displays indexed or truecolor image data as a plotting object rather than as a detached bitmap. In RunMat it returns an image handle, uses the shared flattened surface/image-mode rendering path, and supports both host and GPU-backed truecolor or indexed-image workflows while preserving MATLAB `image` semantics around graphics-object behavior and axes placement.",
"behaviors": [
"`image(C)` displays image data using implicit axes; `image(X, Y, C)` places the image explicitly on the target axes.",
"Indexed images and truecolor images both use the shared surface/image rendering architecture.",
"The returned value is an image-handle object that works with `get` and `set`.",
"`image` is object-oriented and placement-oriented; use `imagesc` when you specifically want scaled matrix visualization with color mapping semantics.",
"Dedicated GPU-backed paths cover both indexed and truecolor image inputs when plotting-compatible buffers are available."
],
"examples": [
{
"description": "Display a simple indexed image",
"input": "C = [1 2 3; 3 2 1; 2 3 1];\nimage(C);\ncolormap('jet');"
},
{
"description": "Display a truecolor RGB image",
"input": "img = zeros(100, 100, 3);\nimg(:,:,1) = 1;\nimg(25:75,25:75,2) = 1;\nimage(img);",
"output": "% Displays a truecolor image object"
},
{
"description": "Position an image explicitly on axes and inspect the handle",
"input": "C = reshape(1:16, 4, 4);\nh = image([0 3], [10 40], C);\nget(h, 'Type')",
"output": "ans =\n 'image'"
}
],
"links": [
{ "label": "imagesc", "url": "./imagesc" },
{ "label": "colormap", "url": "./colormap" },
{ "label": "colorbar", "url": "./colorbar" },
{ "label": "get", "url": "./get" },
{ "label": "set", "url": "./set" }
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/plotting/ops/image.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/image.rs"
},
"gpu_residency": "`image` preserves GPU residency when the image pipeline can consume exported indexed or truecolor image buffers directly. If the active combination cannot stay on the direct path, RunMat gathers once and renders the same image-object semantics on the fallback path.",
"gpu_behavior": [
"Indexed images and truecolor images both have dedicated GPU-aware rendering paths in the image stack.",
"Image handle behavior, axes placement, and replay/export semantics remain aligned across GPU and fallback paths."
]
}