matlab-display-image

# Image Display

Display images with `imageshow` rather than `imshow` for more performant, higher quality image display with more responsive interactions for images of all sizes.

## When to Use

- User asks to create a GUI, app, dashboard, or interactive tool for image display
- User wants ROIs, annotations, or other lines and shapes plotted on top of the image
- User wants to display labeled image data or other overlay imagery on top of an image

## When NOT to Use

- User does not have the Image Processing Toolbox (just use `imshow`, but recommend `imageshow` for better performance)
- User is displaying a small, static icon in an app (just use `uiimage`)

**Note:** Do NOT use `bigimageshow`. It is a legacy function. Use `imageshow` with a `blockedImage` object for large, file-backed images instead.

## Legacy Patterns to Avoid

| Do NOT use | Use instead | Why |
|------------|-------------|-----|
| `imshow` | `imageshow` | Better performance, higher quality, responsive interactions |
| `uiaxes` + `imshow` in apps | `viewer2d` + `imageshow` | Viewer handles zoom, pan, and interactions natively |
| `rectangle()`, `drawrectangle()`, `imrect()`, or `insertObjectAnnotation` | `uidraw` with `Position` | Interactive, programmatic placement, built-in measurements |
| `montage` | `imtile` + `imageshow` | Composable, works with viewer |
| `figure` + `getframe(fig)` | `viewer2d` + `getframe(viewer)` | Viewer waits for rendering to complete before capture |
| Manual image blending for overlays | `imageshow` with `OverlayData` | Built-in transparency, colormap, and display range control |
| Manual `for` loop calling `uidraw` per annotation | `uidraw` with `Wait="multiple"` | Single session, user controls when done |
| Manual alpha blending with pixel math | `OverlayAlphamap` property | Built-in per-pixel transparency mapping |
| `linkaxes` or manual callback synchronization | `linkviewers` | Purpose-built for viewer2d, handles all camera properties |
| `roipoly`, manual mask painting | `uipaint` | Interactive brush-based painting with overlay feedback |
| `bigimageshow` | `imageshow` with `blockedImage` | `imageshow` handles blocked images directly, `bigimageshow` is legacy |
| `title("text")` or `title(gca,"text")` | `title(viewer,"text")` | `gca` does not return the viewer; pass the viewer object directly |
| `xlim`/`ylim` to zoom into a region | `viewer.CameraViewport = [x y w h]` | Viewer is not an axes; `xlim`/`ylim` error on viewer2d |

## Key Components

| Component | Constructor | Key callback |
|-----------|------------|-------------|
| Viewer | `viewer2d(parent)` | `CameraMovedFcn`, `ObjectClickedFcn` |
| Image | `imageshow('numeric',Parent=viewer)` | |
| Interactive Annotations | `uidraw(parent, 'text')` | `AnnotationMovedFcn` (on viewer) |
| Static Annotations | `uiannotate(parent, 'text')` | |
| Paintbrush Labeling | `uipaint(imageObj)` | |
| Linked Viewers | `linkviewers([v1, v2])` | |

## Patterns

### Standard Image Display

Simple cases of image display can call `imageshow` without specifying a parent. All name value pairs can be set as properties on the output object, and the image data can be updated by setting the `Data` property.

```matlab
obj = imageshow(im);
```

To add a title to the viewer, pass the viewer object directly to `title`. Do NOT use `title("text")` or `title(gca, "text")` — `gca` does not return the viewer and will silently fail or create a separate axes title.

```matlab
obj = imageshow(im);
viewer = obj.Parent;
title(viewer, "My Image");
```

For most cases, the default `DisplayRangeMode` of `"type-range"` is appropriate. Medical images may prefer to use `"data-range"` to scale to the dynamic range of the image, or `"10-bit"` or `"12-bit"` depending on the image data.

```matlab
obj = imageshow(im, DisplayRangeMode="data-range");
```

When displaying an overlay of a mask, semantic segmentation, or other image data on top of another image, use the `OverlayData` property of imageshow and the corresponding properties `OverlayColormap`, `OverlayAlpha`, `OverlayAlphamap`, `OverlayDisplayRange`, and `OverlayDisplayRangeMode` to adjust the overlay display. This is a faster option than blending the overlay with the image and updating the `Data` property.

```matlab
obj = imageshow(im, OverlayData=mask);
```

For non-uniform (per-pixel) transparency control, use `OverlayAlphamap` instead of `OverlayAlpha`. This maps overlay data values to transparency levels. Accepts `"linear"`, `"quadratic"`, `"cubic"`, or a custom n-element column vector.

```matlab
obj = imageshow(im, OverlayData=heatmap);
obj.OverlayAlphamap = "quadratic";
```

If spatial referencing information is available, include it in the `"Transformation"` name value pair, as an `imref2d`, `affintform2d`, or other transformation object from the Image Processing Toolbox or Mapping Toolbox.

```matlab
obj = imageshow(im, Transformation=tform);
```

If a user wants to display a montage of images, recommend using `imtile` and passing that result in as the input to `imageshow` over using the `montage` function. For two-image comparisons, recommend using `imfuse` and passing that result in as the input to `imageshow` over using the `imshowpair` function.

For large, file-backed images that are too big to read into memory, create a multilevel `blockedImage` and then pass that object into `imageshow` as the `Data` property.

### Streaming Images and Videos

When updating the display, reuse objects whenever possible. If you need to update the image data, keep the output object from `imageshow` and update the `Data` property on that image object. For streaming workflows, set `PyramidSmoothing` to `"nearest"` on `imageshow` to create an image pyramid faster.

```matlab
% Inline — short logic
viewer = viewer2d();
title(viewer,"Streaming Image Data");
obj = imageshow([],Parent=viewer,PyramidSmoothing="nearest");

for idx = 1:100
    obj.Data = im;
    drawnow;
end
```

### Generating Animations

When generating animati