matlab-display-volume

# 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 | `linspace(0,1,256)'` |
| Reveal only a specific intensity band | Gaussian peak | `exp(-((x-center).^2)/(2*width^2))` |
| Hard threshold (binary visibility) | Step function | `double((1:256)' > threshold)` |
| Hide bright, show dim (e.g., cavities) | Inverted ramp | `linspace(1,0,256)'` |
| Custom: show bone, hide soft tissue (CT) | Step at bone HU | `double(linspace(0,1,256)' > 0.3)` |

```matlab
% Gaussian alphamap centered at 60% intensity (width 10%)
x = linspace(0, 1, 256)';
alpha = exp(-((x - 0.6).^2) / (2*0.1^2));
obj = vo