# Overlays and thresholds

> Show statistical maps over anatomy: positive and negative thresholds, colormap types, opacity, outlines and several overlays.

An overlay is any volume after the first. A common case is a statistical map
drawn over an anatomical template, showing only the voxels that pass a
threshold.

The demo loads an SPM motor-task map over the MNI152 template. Positive
values use `redyell` and negative values use `winter`, each with its own
threshold:

## Positive and negative thresholds

For an overlay, `calMin` is the threshold: voxels below it are transparent.
`calMax` is where the colormap saturates. A signed map adds a second
colormap and window for the negative side:

```js
await nv.loadVolumes([
  { url: '/volumes/mni152.nii.gz', calMin: 30, calMax: 80, isColorbarVisible: false },
  { url: '/volumes/spmMotor.nii.gz', colormap: 'redyell', colormapNegative: 'winter' },
])
await nv.setVolume(1, { calMin: 3, calMax: 6, calMinNeg: -3, calMaxNeg: -6 })
```

The two sides do not have to match. `calMinNeg` and `calMaxNeg` default to
`NaN`, which mirrors the positive window.

## Colormap type

`colormapType` decides how the colorbar relates to the threshold:

| `COLORMAP_TYPE` | Colors span | Below `calMin` |
|---|---|---|
| `MIN_TO_MAX` (0, default) | `calMin` to `calMax` | transparent |
| `ZERO_TO_MAX_TRANSPARENT_BELOW_MIN` (1) | 0 to `calMax` | transparent |
| `ZERO_TO_MAX_TRANSLUCENT_BELOW_MIN` (2) | 0 to `calMax` | [fades in (translucent)](https://pubmed.ncbi.nlm.nih.gov/42675118/) |

Types 1 and 2 keep the color of a value the same as you move the threshold,
which makes maps thresholded at different levels easier to compare:

```js
import { COLORMAP_TYPE } from '@niivue/niivue'

await nv.setVolume(1, {
  colormapType: COLORMAP_TYPE.ZERO_TO_MAX_TRANSLUCENT_BELOW_MIN,
})
```

## Opacity and outlines

`opacity` fades an overlay (0 to 1), and `visible: false` hides it while
keeping its opacity:

```js
await nv.setVolume(1, { opacity: 0.6 })
```

`nv.volumeOutlineWidth` outlines the suprathreshold clusters on 2D
slices. The value is the outline width in overlay voxels; it applies to the
whole viewer, and 0 (the default) turns it off.

## Several overlays

With two or more overlays, two viewer settings decide how overlapping voxels
combine. `volumeOverlayAlphaBlend` combines their opacities and
`volumeOverlayColorBlend` combines their colors:

```js
import { OVERLAY_ALPHA_BLEND, OVERLAY_COLOR_BLEND } from '@niivue/niivue'

nv.volumeOverlayAlphaBlend = OVERLAY_ALPHA_BLEND.UNION
nv.volumeOverlayColorBlend = OVERLAY_COLOR_BLEND.OVER
```

| Setting | `0` (default) | `1` | `2` |
|---|---|---|---|
| `volumeOverlayAlphaBlend` | `MAX`: the most opaque wins | `ADDITIVE`: opacities add, capped at 1 | `UNION`: `1 - prod(1 - a)` |
| `volumeOverlayColorBlend` | `ADDITIVE`: opacity-weighted sum | `MEAN`: opacity-weighted average | `OVER`: later overlays on top |

Alpha `UNION` with colour `OVER` gives ordinary layered compositing, in
volume order. Colour `OVER` with another alpha mode changes only the opacity.
`UNION` was named `OVER` before 1.0.
`ADDITIVE` alpha suits fractions that sum to 1, such as tissue probability
maps. NiiVue 0.x had only the `MAX` and `ADDITIVE` defaults.

## In the gallery

- [Statistics](https://niivue.com/docs/gallery/vox-stats/): this demo plus clip planes and a 3D render
- [Multiple statistical maps](https://niivue.com/docs/gallery/vox-stats-multi/): three task maps
  with shared thresholds and the blend controls
- [Tissue maps](https://niivue.com/docs/gallery/vox-tissues/)
- [Modulation](https://niivue.com/docs/gallery/vox-modulate/): scale one overlay's brightness by
  another volume

Label volumes, where each value names a region, work differently; see
[Atlases and labels](https://niivue.com/docs/guide/atlases/).
