# Clip planes and cutaways

> Cut into the 3D render with up to six clip planes: describing and setting planes, cutaways and the cut surface.

Clip planes slice away part of the 3D render so you can see inside a
volume. A viewer has up to six of them.

## Describing a plane

Each plane is three numbers, `[depth, azimuth, elevation]`:

- `depth` is the plane's distance from the center of the volume, from -1 to
  1. A depth of 0 cuts through the middle. A depth of 2, which
  `setClipPlanes` uses for the slots you leave out, turns the plane off.
- `azimuth` and `elevation` are the direction the plane faces, in degrees,
  using the same angles as the render camera. For example `[0, 90, 0]` cuts
  at the midline from the right, and `[0.1, 0, -90]` trims from below.

## Setting planes

`setClipPlanes` replaces every plane at once. Planes you leave out are turned
off, so an empty list removes all clipping:

```js
nv.setClipPlanes([
  [0.1, 180, 20],
  [0.1, 0, -20],
])
nv.setClipPlanes([]) // no clipping
```

Six axis-aligned planes make a box that keeps only the middle of the volume.
On a multi-channel image, set `clipPlaneOverlay` to `true` so the planes cut
every channel, not only the first:

```js
nv.clipPlaneOverlay = true
nv.setClipPlanes([
  [0.1, 270, 0], // left
  [0.1, 90, 0], // right
  [0.1, 180, 0], // anterior
  [0.1, 0, 0], // posterior
  [0.1, 0, -90], // inferior
  [0.1, 0, 90], // superior
])
```

To change one plane, use `setClipPlaneDepthAziElev(depth, azimuth,
elevation, index)`, or `setClipPlane([depth, azimuth, elevation])`, which
sets the active plane (`activeClipPlaneIndex`, 0 by default).
`getClipPlaneDepthAziElev(index)` reads a plane back.

```js
nv.setClipPlaneDepthAziElev(0.3, 90, 0, 1) // plane 1
nv.setClipPlane([0, 270, 0])               // the active plane
```

`setClipPlane` and `setClipPlaneDepthAziElev` fire a `clipPlaneChange` event
with the new `[depth, azimuth, elevation]`. `setClipPlanes` does not.

## Cutaways

By default each plane removes everything on its side, so adding planes trims
the volume further. Set `isClipPlaneCutaway` to `true` to remove only the
region that lies behind all the planes at once. With two or three planes this
cuts a notch out of the volume and leaves the rest intact, which is the
classic anatomical cutaway.

```js
nv.isClipPlaneCutaway = true
```

## The cut surface

`clipPlaneColor` is an RGBA color for the surface where a plane cuts the
volume. Its alpha picks one of three looks:

| Alpha | Result |
|-------|--------|
| `0` | the cut is invisible; you see straight into the volume |
| greater than 0 | the plane is drawn as a translucent sheet of that color |
| less than 0 | the cut surface of the volume is tinted by the color, with strength `abs(alpha)` |

```js
nv.clipPlaneColor = [0.7, 0, 0.7, 0.4] // the default
```

Always assign the property. Editing the array the getter returns changes the
color but does not redraw the view.

## Keyboard and mouse

With the pointer over the viewer, the `C` key cycles the active plane through
a few preset directions (posterior, right, left, anterior, inferior,
superior, then off), and `A` chooses which of the six planes is active.
Scrolling over the render moves the active plane's depth while it is inside
the volume, and a right drag turns it. FEATURE_PARITY.md marks full parity with the old package's clip
plane mouse and keyboard handling as not yet verified.

Clip planes affect the 3D render. Mesh clipping on 2D slices is a separate
setting, `meshThicknessOn2D`; see [Meshes and layers](https://niivue.com/docs/guide/meshes/).

## See also

- [Clip planes](https://niivue.com/docs/gallery/vox-clip/): one to six planes, cutaway and cut
  surface options.
- [FreeSurfer clip](https://niivue.com/docs/gallery/freesurfer-clip/): a clip plane over a
  FreeSurfer volume and pial surface.
- [Allen IMSC](https://niivue.com/docs/gallery/allen-imsc/): a clip box and cutaway over a
  four-channel microscopy cell.
