# Atlases and labels

> Display label volumes (atlases) with label colormaps, read region names under the crosshair, and use outlines, probabilistic and mesh atlases.

A label volume (an atlas) stores an integer region code in each voxel
instead of an intensity. To display it, you give the volume a label
colormap: a color and a name for each code. NiiVue then draws each region
in its own color and reports the region name under the crosshair.

A volume has one colormap. It is a label colormap when its definition has a
`labels` array, and a continuous ramp otherwise; `setVolume(i, { colormap })`
selects either kind.

The demo loads the AAL atlas over the MNI152 template. Click anywhere to see
the region name:

## Label colormaps

`addColormapFromUrl` fetches a JSON file with `R`, `G` and `B` arrays plus
`labels` (and optionally `I`, the code of each entry) and registers it under
its file name. Select it like any colormap:

```js
await nv.addColormapFromUrl('/volumes/aal.json') // registered as 'aal'
await nv.loadVolumes([
  { url: '/volumes/mni152.nii.gz', calMin: 30, calMax: 80 },
  { url: '/volumes/aal.nii.gz', opacity: 0.5, colormap: 'aal' },
])
```

The URL can also be a `File`, and `addColormap(name, { R, G, B, labels })`
registers a table you build in code. `labels` may be empty: it still marks
the colormap as a label table. Built-in label colormaps include
`freesurfer`, `itksnap`, `slicer3d` and `Random` (generated per volume);
`nv.colormapNames('label')` lists them all:

```js
await nv.setVolume(1, { colormap: 'freesurfer' })
```

Picking a continuous colormap such as `'gray'` turns the labels off again.

A volume whose NIfTI header marks it as labels (`NIFTI_INTENT_LABEL`) and is
loaded without a colormap is drawn with `Random`, a generated palette that
gives every region code in the volume its own color. The same code gets the
same color in every volume, so a segmentation looks right with no setup;
pick an atlas table for its own colors and names. The palette covers at
least codes 0 to 255 and grows to every code the volume holds, in all of
its 4D frames and when `updateVolumeData` or an edit brings higher codes, so
a live segmentation keeps distinct colors.

Label volumes are sampled with nearest-neighbor interpolation on 2D slices,
so region borders stay sharp. A volume's `isNearestInterpolation` option
overrides that choice.

## Reading labels

With a label colormap set, the `locationChange` event includes the region
name for each volume in `detail.values[i].label`:

```js
nv.addEventListener('locationChange', (e) => {
  console.log(e.detail.values[1]?.label)
})
```

To measure the background image inside one region, pass that region's code
as a mask to `getDescriptives`:

```js
const stats = nv.getDescriptives({ volumeIndex: 0, masks: [{ index: 1, values: [17] }] })
```

## Outlines and dark voxels

`nv.setAtlasOutline(width, volumeIndex)` outlines the region borders. The
width is the distance, in the atlas's own voxels, that NiiVue probes for a
neighboring label, and 0 turns it off. You can also set `atlasOutline` in the load options. Outlines
are not drawn on streamed (chunked) volumes.

`nv.volumeIsAlphaClipDark = true` makes voxels below `calMin` transparent,
which hides the dark air around a template.

## Labels on a drawing

You can also show labels in the drawing layer. Register a colormap with
`labels`, make it the drawing colormap, and load the label image as a
drawing:

```js
nv.addColormap('torso', {
  R: [0, 0, 185],
  G: [0, 20, 102],
  B: [0, 152, 83],
  A: [0, 255, 255],
  I: [0, 1, 2],
  labels: ['background', 'spleen', 'kidneyR'],
})
nv.drawColormap = 'torso'
await nv.loadDrawing('/volumes/torsoLabel.nii.gz')
```

A drawing holds codes 0 to 255, so `drawColormap` accepts any label
colormap whose codes fit and refuses the rest. See
[Drawing and segmentation](https://niivue.com/docs/guide/drawing/) for editing the drawing.

## Probabilistic and mesh atlases

PAQD files store a probabilistic atlas (several labels and probabilities per
voxel). `hiddenLabels` hides PAQD labels as it does for a label volume.
`nv.volumePaqdUniforms` tunes how they render; see the
[PAQD atlas](https://niivue.com/docs/gallery/vox-paqd/) example.

Meshes can carry atlas labels too. MZ3 atlas meshes load with `loadMeshes`,
and list their labels in the legend, as a label volume does;
`setMesh(0, { isLegendVisible: false })` or `setVolume(i, { isLegendVisible: false })`
takes one out, and `nv.isLegendVisible = false` hides the legend. Readers for
FreeSurfer annot files and GIfTI label layers have not been ported yet, so
other mesh atlas formats do not load.

NiiVue 0.x had `addLabel()` for text labels in the 3D view. This version
does not. The `@niivue/uikit` package's `UIKitPointLabelOverlay` draws a text
label with a leader line to a point instead.

## In the gallery

- [Atlas with a statistical map](https://niivue.com/docs/gallery/vox-atlas-stat/)
- [Torso labels](https://niivue.com/docs/gallery/vox-torso/)
- [Mesh atlas](https://niivue.com/docs/gallery/mesh-atlas/)
- [PAQD atlas](https://niivue.com/docs/gallery/vox-paqd/)
- [BigBrain atlas](https://niivue.com/docs/gallery/vox-atlas-bigbrain/)
