Matlab Display VolumeSAFE

The MATLAB Agentic Toolkit brings proven MATLAB capabilities to AI agents, making engineering and scientific workflows agent-ready.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: matlab-display-volume
description: Display 3-D image volumes, medical image volumes, surface meshes, and annotations for 3-D image processing. Use when displaying 3-D images or isosurfaces with volshow, creating volume viewers with viewer3d, adding Regions of Interest (ROI) or annotations, overlaying masks or segmentations, streaming volumetric data, or building apps with volume display.
license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md
metadata:
  author: MathWorks
  version: "1.1"
---

# Volume Display

Display volumes with `volshow` for performant, high quality volume display. Display isosurface meshes, triangulations, and surfaces using `images.ui.graphics.Surface` rather than `isosurface` for more performant, higher quality mesh display with more responsive interactions for meshes of all sizes.

## When to Use

- User asks to create a GUI, app, dashboard, or interactive tool for volume, isosurface, or surface mesh display
- User wants ROIs, annotations, or other lines and shapes plotted on top of the volume or surface mesh
- User wants to display labeled data or other overlay volumes on top of a volume

## When NOT to Use

- User does not have the Image Processing Toolbox — fall back to `isosurface` + `patch`, but recommend `volshow` for better performance.

## Medical Image Volumes

When the user has the Medical Imaging Toolbox, use `medicalVolume` to load DICOM/NIfTI/NRRD files, then call the `volshow` method on that object. This automatically sets the spatial `Transformation` and `SpatialUnits` from the file metadata. All other patterns in this skill (Viewer, overlays, annotations, streaming, app building) still apply — only the entry point differs.

```matlab
medVol = medicalVolume("brain.nii");
obj = volshow(medVol);
```

## Key Objects

| Object | Constructor | Key callback |
|--------|------------|-------------|
| `Viewer` | `viewer3d(parent)` | `CameraMovedFcn`, `ObjectClickedFcn` |
| `Volume` | `volshow(data, Parent=viewer)` | |
| `Surface` | `images.ui.graphics.Surface(viewer, Data=tri)` | |
| Interactive Annotations | `uidraw(parent, "shape")` | `AnnotationMovedFcn` (on Viewer) |

**Utilities:** `linkviewers(viewers)` synchronizes camera motion across multiple Viewers. `title(viewer, "text")` sets the Viewer title.

## Workflow

1. **Create Viewer** — call `viewer3d()` or `viewer3d(parent)` for app contexts
2. **Add Volume** — call `volshow(V, Parent=viewer)` to display volumetric data
3. *(Optional)* **Add surfaces** — call `images.ui.graphics.Surface(viewer, Data=tri)` for mesh display
4. *(Optional)* **Add annotations** — call `uidraw(volObj, "line")` for interactive ROIs
5. *(Optional)* **Configure callbacks** — set `CameraMovedFcn`, `AnnotationMovedFcn`, or `ObjectClickedFcn` on the Viewer
6. **Update data** — set `obj.Data = newV` to stream; use `waitfor(viewer,"Busy",false)` for synchronization

## Legacy Patterns to Avoid

| Do NOT use | Use instead | Why |
|------------|-------------|-----|
| `isosurface` + `patch` | `images.ui.graphics.Surface(viewer, Data=tri)` | Better rendering, interactive performance, depth peeling |
| `clear(viewer)` then re-add objects | Reuse objects, update `Data` property | Avoids reconstruction overhead |
| `drawnow` for volume streaming sync | `waitfor(viewer,"Busy",false)` | Volume data loads asynchronously; `drawnow` is still appropriate for Surface animation |
| Creating new `volshow` each frame | Keep reference, set `obj.Data = V` | Reuse avoids GPU reallocation |

## Patterns

### Standard Volume Display

Simple cases of volume display can call `volshow` without specifying a parent. All name-value arguments can be set as properties on the Volume object, and the volume data can be updated by setting the `Data` property.

```matlab
obj = volshow(V);
```

Choose `DisplayRangeMode` based on the data type and value range:

| Data characteristics | Recommended mode |
|---------------------|-----------------|
| Normalized `single`/`double` in [0, 1] | `"data-range"` (default) |
| `uint8` or `int8` | `"data-range"` (default) |
| `uint16` with values up to 1023 (e.g., 10-bit CT) | `"10-bit"` |
| `uint16` with values up to 4095 (e.g., 12-bit CT/MR) | `"12-bit"` |
| `uint16` full range or `int16` | `"16-bit"` |
| Custom window/level needed | `"manual"` with `DisplayRange=[low high]` |

```matlab
% 12-bit medical volume
obj = volshow(V, DisplayRangeMode="12-bit");

% Manual window/level
obj = volshow(V, DisplayRangeMode="manual", DisplayRange=[200 1200]);
```

Set `RenderingStyle` to control how voxel data is visualized. See the dedicated **Rendering Styles** section below for detailed guidance.

**Choosing a Colormap** — Select based on data content:

| Data content | Recommended colormap | Rationale |
|-------------|---------------------|-----------|
| CT / MR (anatomical) | `gray(256)` | Clinical convention; preserves radiologist familiarity |
| CT with window/level | `gray(256)` + `DisplayRange` | Narrow range highlights target tissue |
| Fluorescence / emission | `hot(256)` or `green(256)` | Hot emphasizes intensity peaks; green matches fluorophore |
| General scientific | `parula(256)` (default) | Perceptually uniform, accessible |
| Multi-structure / labeled | `turbo(256)` | Full-spectrum rainbow, perceptually ordered |
| Signed data (e.g., flow, strain) | Custom diverging (blue-white-red) | Distinguishes positive/negative around midpoint |

```matlab
obj = volshow(V, Colormap=gray(256));
```

**Choosing an Alphamap** — The alphamap is a 256×1 vector mapping normalized intensity [0, 1] to opacity [0, 1]. It controls which structures are visible vs. transparent. The default is a cubic ramp (`x.^3`), which suppresses low-intensity background while revealing bright structures.

| Goal | Alphamap shape | Construction |
|------|---------------|--------------|
| Show bright structures, hide background | Cubic ramp (default) | `linspace(0,1,256)'.^3` |
| Show all intensities equally | Linear ramp | `

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.