Class Niivue

Niivue can be attached to a canvas. An instance of Niivue contains methods for loading and rendering NIFTI image data in a WebGL 2.0 context.

Example

let niivue = new Niivue({crosshairColor: [0,1,0,0.5], textHeight: 0.5}) // a see-through green crosshair, and larger text labels

Index

Constructors

constructor

new Niivue(options?): Niivue
Parameters
- options: Partial<NVConfigOptions> = DEFAULT_OPTIONS
  options object to set modifiable Niivue properties
Returns Niivue
- Defined in niivue/index.ts:786

Properties

onAzimuthElevationChange

onAzimuthElevationChange: ((azimuth: number, elevation: number) => void) = ...

callback function to run when the user changes the rotation of the 3D rendering

Example

niivue.onAzimuthElevationChange = (azimuth, elevation) => {
console.log('azimuth: ', azimuth)
console.log('elevation: ', elevation)
}

onClickToSegment

onClickToSegment: ((data: {
mL: number;
mm3: number;
}) => void) = ...

callback function when clickToSegment is enabled and the user clicks on the image. data contains the volume of the segmented region in mm3 and mL

Example

niivue.onClickToSegment = (data) => {
console.log('clicked to segment')
console.log('volume mm3: ', data.mm3)
console.log('volume mL: ', data.mL)
}

onClipPlaneChange

onClipPlaneChange: ((clipPlane: number[]) => void) = ...

callback function to run when the user changes the clip plane

Example

niivue.onClipPlaneChange = (clipPlane) => {
console.log('clipPlane: ', clipPlane)
}

onDebug

onDebug: (() => void) = ...

callback function to run when niivue reports a debug message

Example

niivue.onDebug = (debug) => {
console.log('debug: ', debug)
}

onDocumentLoaded

onDocumentLoaded: ((document: NVDocument) => void) = ...

callback function to run when the user loads a new NiiVue document

Example

niivue.onDocumentLoaded = (document) => {
console.log('document: ', document)
}

onDragRelease

onDragRelease: ((params: DragReleaseParams) => void) = ...

callback function to run when the right mouse button is released after dragging

Example

niivue.onDragRelease = () => {
  console.log('drag ended')
}

onError

onError: (() => void) = ...

callback function to run when niivue reports an error

Example

niivue.onError = (error) => {
console.log('error: ', error)
}

onFrameChange

onFrameChange: ((volume: NVImage, index: number) => void) = ...

callback function to run when the user changes the volume when a 4D image is loaded

Example

niivue.onFrameChange = (volume, frameNumber) => {
console.log('frame changed')
console.log('volume: ', volume)
console.log('frameNumber: ', frameNumber)
}

onImageLoaded

onImageLoaded: ((volume: NVImage) => void) = ...

callback function to run when a new volume is loaded

Example

niivue.onImageLoaded = (volume) => {
console.log('volume loaded')
console.log('volume: ', volume)
}

onInfo

onInfo: (() => void) = ...

callback function to run when niivue reports detailed info

Example

niivue.onInfo = (info) => {
console.log('info: ', info)
}

onIntensityChange

onIntensityChange: ((volume: NVImage) => void) = ...

callback function to run when the user changes the intensity range with the selection box action (right click)

Example

niivue.onIntensityChange = (volume) => {
console.log('intensity changed')
console.log('volume: ', volume)
}

onLocationChange

onLocationChange: ((location: unknown) => void) = ...

callback function to run when the crosshair location changes

Example

niivue.onLocationChange = (data) => {
console.log('location changed')
console.log('mm: ', data.mm)
console.log('vox: ', data.vox)
console.log('frac: ', data.frac)
console.log('values: ', data.values)
}

onMeshAddedFromUrl

onMeshAddedFromUrl: ((meshOptions: LoadFromUrlParams, mesh: NVMesh) => void) = ...

callback function to run when a mesh is added from a url

Example

niivue.onMeshAddedFromUrl = (meshOptions, mesh) => {
console.log('mesh added from url')
console.log('meshOptions: ', meshOptions)
console.log('mesh: ', mesh)
}

onMeshLoaded

onMeshLoaded: ((mesh: NVMesh) => void) = ...

callback function to run when a new mesh is loaded

Example

niivue.onMeshLoaded = (mesh) => {
console.log('mesh loaded')
console.log('mesh: ', mesh)
}

onMouseUp

onMouseUp: ((data: Partial<UIData>) => void) = ...

callback function to run when the left mouse button is released

Example

niivue.onMouseUp = () => {
  console.log('mouse up')
}

onVolumeAddedFromUrl

onVolumeAddedFromUrl: ((imageOptions: ImageFromUrlOptions, volume: NVImage) => void) = ...

callback function to run when a volume is added from a url

Example

niivue.onVolumeAddedFromUrl = (imageOptions, volume) => {
console.log('volume added from url')
console.log('imageOptions: ', imageOptions)
console.log('volume: ', volume)
}

onVolumeUpdated

onVolumeUpdated: (() => void) = ...

callback function to run when updateGLVolume is called (most users will not need to use

Example

niivue.onVolumeUpdated = () => {
console.log('volume updated')
}

onWarn

onWarn: (() => void) = ...

callback function to run when niivue reports a warning

Example

niivue.onWarn = (warn) => {
console.log('warn: ', warn)
}

Methods

addColormap

addColormap(key, cmap): void
create a new colormap
Parameters
- key: string
  name of new colormap
- cmap: ColorMap
Returns void
See
live demo usage
- Defined in niivue/index.ts:6653

addLabel

addLabel(text, style, points?, anchor?, onClick?): NVLabel3D
Add a 3D Label
Parameters
- text: string
  text of the label
- style: NVLabel3DStyle
  label style
- Optionalpoints: number[] | number[][]
- Optionalanchor: LabelAnchorPoint
- OptionalonClick: ((label: NVLabel3D) => void)
  - - (label): void
    - Parameters
      label: NVLabel3D
      Returns void
Returns NVLabel3D
- Defined in niivue/index.ts:9937

addMesh

addMesh(mesh): void
add a new mesh to the canvas
Parameters
- mesh: NVMesh
  the new mesh to add to the canvas
Returns void
Example
```
niivue = new Niivue()
niivue.addMesh(NVMesh.loadFromUrl({url:'../someURL.gii'}))
```
See
live demo usage
- Defined in niivue/index.ts:2537

addMeshesFromUrl

addMeshesFromUrl(meshOptions): Promise<NVMesh[]>
Add mesh and notify subscribers
Parameters
- meshOptions: LoadFromUrlParams[]
Returns Promise<NVMesh[]>
See
live demo usage
- Defined in niivue/index.ts:4179

addMeshFromUrl

addMeshFromUrl(meshOptions): Promise<NVMesh>
Add mesh and notify subscribers
Parameters
- meshOptions: LoadFromUrlParams
Returns Promise<NVMesh>
See
live demo usage
- Defined in niivue/index.ts:4157

addVolume

addVolume(volume): void
add a new volume to the canvas
Parameters
- volume: NVImage
  the new volume to add to the canvas
Returns void
Example
```
niivue = new Niivue()
niivue.addVolume(NVImage.loadFromUrl({url:'../someURL.nii.gz'}))
```
See
live demo usage
- Defined in niivue/index.ts:2520

addVolumeFromUrl

addVolumeFromUrl(imageOptions): Promise<NVImage>
Add an image and notify subscribers
Parameters
- imageOptions: ImageFromUrlOptions
Returns Promise<NVImage>
See
live demo usage
- Defined in niivue/index.ts:1964

arrayEquals

arrayEquals(a, b): boolean
Not documented publicly for now test if two arrays have equal values for each element
Parameters
- a: unknown[]
  the first array
- b: unknown[]
  the second array
Returns boolean
Example
```
Niivue.arrayEquals(a, b)

TODO this should maybe just use array-equal from NPM
```
- Defined in niivue/index.ts:1115

attachTo

attachTo(id, isAntiAlias?): Promise<Niivue>
attach the Niivue instance to the webgl2 canvas by element id
Parameters
- id: string
  the id of an html canvas element
- isAntiAlias: any = null
  determines if anti-aliasing is requested (if not specified, AA usage depends on hardware)
Returns Promise<Niivue>
Example
```
niivue = new Niivue().attachTo('gl')
```
Example
```
niivue.attachTo('gl')
```
See
live demo usage
- Defined in niivue/index.ts:894

attachToCanvas

attachToCanvas(canvas, isAntiAlias?): Promise<Niivue>
attach the Niivue instance to a canvas element directly
Parameters
- canvas: HTMLCanvasElement
  the canvas element reference
- isAntiAlias: boolean = null
Returns Promise<Niivue>
Example
```
niivue = new Niivue()
niivue.attachToCanvas(document.getElementById(id))
```
- Defined in niivue/index.ts:907

broadcastTo

broadcastTo(otherNV, syncOpts?): void
Sync the scene controls (orientation, crosshair location, etc.) from one Niivue instance to others. useful for using one canvas to drive another.
Parameters
- otherNV: Niivue | Niivue[]
  the other Niivue instance(s)
- syncOpts: {
  2d: boolean;
  3d: boolean;
  } = ...
  - 2d: boolean
  - 3d: boolean
Returns void
Example
```
niivue1 = new Niivue()
niivue2 = new Niivue()
niivue3 = new Niivue()
niivue1.broadcastTo(niivue2)
niivue1.broadcastTo([niivue2, niivue3])
```
See
live demo usage
- Defined in niivue/index.ts:979

calculateMinMaxVoxIdx

calculateMinMaxVoxIdx(array): number[]
calculate the the min and max voxel indices from an array of two values (used in selecting intensities with the selection box)
Parameters
- array: number[]
  an array of two values
Returns number[]
an array of two values representing the min and max voxel indices
- Defined in niivue/index.ts:1316

cloneVolume

cloneVolume(index): NVImage
clone a volume and return a new volume
Parameters
- index: number
  the index of the volume to clone
Returns NVImage
new volume to work with, but that volume is not added to the canvas
Example
```
niivue = new Niivue()
niivue.cloneVolume(0)
```
- Defined in niivue/index.ts:3761

closeDrawing

closeDrawing(): void
close drawing: make sure you have saved any changes before calling this!

Returns void
Example
```
niivue.closeDrawing();
```
See
live demo usage
- Defined in niivue/index.ts:5246

colormaps

colormaps(): string[]
query all available color maps that can be applied to volumes

Returns string[]
an array of colormap strings
Example
```
niivue = new Niivue()
colormaps = niivue.colormaps()
```
See
live demo usage
- Defined in niivue/index.ts:6643

conform

conform(volume, toRAS?, isLinear?, asFloat32?, isRobustMinMax?): Promise<NVImage>
FreeSurfer-style conform reslices any image to a 256x256x256 volume with 1mm voxels
Parameters
- volume: NVImage
  input volume to be re-oriented, intensity-scaled and resliced
- toRAS: boolean = false
  reslice to row, column slices to right-anterior-superior not left-inferior-anterior (default false).
- isLinear: boolean = true
  reslice with linear rather than nearest-neighbor interpolation (default true).
- asFloat32: boolean = false
  use Float32 datatype rather than Uint8 (default false).
- isRobustMinMax: boolean = false
  clamp intensity with robust min max (~2%..98%) instead of FreeSurfer (0%..99.99%) (default false).
Returns Promise<NVImage>
See
live demo usage
- Defined in niivue/index.ts:7225

createCustomMeshShader

createCustomMeshShader(fragmentShaderText, name?): {
    Frag: string;
    Name: string;
    shader: Shader;
}
Parameters
- fragmentShaderText: string
  custom fragment shader.
- name: string = 'Custom'
  title for new shader.
Returns {
    Frag: string;
    Name: string;
    shader: Shader;
}
created custom mesh shader
- Frag: string
- Name: string
- shader: Shader
- Defined in niivue/index.ts:5501

createEmptyDrawing

createEmptyDrawing(): void
generate a blank canvas for the pen tool

Returns void
Example
```
niivue.createEmptyDrawing()
```
See
live demo usage
- Defined in niivue/index.ts:4364

decimateHierarchicalMesh

decimateHierarchicalMesh(mesh, order?): boolean
reduce complexity of FreeSurfer mesh
Parameters
- mesh: number
  identity of mesh to change
- order: number = 3
  decimation order 0..6
Returns boolean
boolean false if mesh is not hierarchical or of lower order
Example
```
niivue.decimateHierarchicalMesh(niivue.meshes[0].id, 4)
```
See
live demo usage
- Defined in niivue/index.ts:3111

drawGrowCut

drawGrowCut(): void
dilate drawing so all voxels are colored. works on drawing with multiple colors

Returns void
Example
```
niivue.drawGrowCut();
```
See
live demo usage
- Defined in niivue/index.ts:4424

drawingBinaryDilationWithSeed

drawingBinaryDilationWithSeed(seedXYZ, neighbors?): void
Performs a 1-voxel binary dilation on a connected cluster within the drawing mask using the drawFloodFillCore function.
Parameters
- seedXYZ: number[]
  voxel index of the seed voxel in the mask array.
- neighbors: 6 | 18 | 26 = 6
  Number of neighbors to consider for connectivity and dilation (6, 18, or 26).
Returns void
- Defined in niivue/index.ts:4678

drawMosaic

drawMosaic(mosaicStr): void
display a lightbox or montage view
Parameters
- mosaicStr: string
  specifies orientation (A,C,S) and location of slices.
Returns void
Example
```
niivue.setSliceMosaicString("A -10 0 20");
```
See
live demo usage
- Defined in niivue/index.ts:11158

drawOtsu

drawOtsu(levels?): void
remove dark voxels in air
Parameters
- levels: number = 2
  (2-4) segment brain into this many types. For example drawOtsu(2) will create a binary drawing where bright voxels are colored and dark voxels are clear.
Returns void
Example
```
niivue.drawOtsu(3);
```
See
live demo usage
- Defined in niivue/index.ts:2864

drawUndo

drawUndo(): void
Restore drawing to previous state

Returns void
Example
```
niivue.drawUndo();
```
See
live demo usage
- Defined in niivue/index.ts:2595

generateHTML

generateHTML(canvasId?, esm): Promise<string>
generates HTML of current scene
Parameters
- canvasId: string = 'gl1'
  id of canvas NiiVue will be attached to
- esm: string
  bundled version of NiiVue
Returns Promise<string>
HTML with javascript of the current scene
Example
```
const template = `<html><body><canvas id="gl1"></canvas><script type="module" async>
      %%javascript%%</script></body></html>`;
nv1.generateHTML("page.html", esm);
```
- Defined in niivue/index.ts:3941

generateLoadDocumentJavaScript

generateLoadDocumentJavaScript(canvasId, esm): Promise<string>
generates JavaScript to load the current scene as a document
Parameters
- canvasId: string
  id of canvas NiiVue will be attached to
- esm: string
  bundled version of NiiVue
Returns Promise<string>
Example
```
const javascript = this.generateLoadDocumentJavaScript("gl1");
const html = `<html><body><canvas id="gl1"></canvas><script type="module" async>
       ${javascript}</script></body></html>`;
```
- Defined in niivue/index.ts:3900

getDescriptives

getDescriptives(options): Descriptive
basic statistics for selected voxel-based image
Parameters
- options: {
      drawingIsMask?: boolean;
      endVox?: number[];
      layer?: number;
      masks?: number[];
      roiIsMask?: boolean;
      startVox?: number[];
  }
  an object containing the following properties:
  - layer: selects image to describe
  - masks: optional binary images to filter voxels
  - drawingIsMask: a boolean indicating if the drawing is used as a mask
  - roiIsMask: a boolean indicating if the ROI is used as a mask
  - startVox: the starting voxel coordinates
  - endVox: the ending voxel coordinates
  - OptionaldrawingIsMask?: boolean
  - OptionalendVox?: number[]
  - Optionallayer?: number
  - Optionalmasks?: number[]
  - OptionalroiIsMask?: boolean
  - OptionalstartVox?: number[]
Returns Descriptive
numeric values to describe image or regions of images
Example
```
niivue.getDescriptives({
  layer: 0,
  masks: [],
  drawingIsMask: true, // drawingIsMask and roiIsMask are mutually exclusive
  roiIsMask: false,
  startVox: [10, 20, 30], // ignored if roiIsMask is false
  endVox: [40, 50, 60] // ignored if roiIsMask is false
});
```
See
live demo usage
- Defined in niivue/index.ts:5861

getFrame4D

getFrame4D(id): number
determine active 3D volume from 4D time series
Parameters
- id: string
  the ID of the 4D NVImage
Returns number
currently selected volume (indexed from 0)
Example
```
nv1.getFrame4D(nv1.volumes[0].id);
```
See
live demo usage
- Defined in niivue/index.ts:7497

getMediaByUrl

getMediaByUrl(url): NVMesh | NVImage
Find media by url
Parameters
- url: string
Returns NVMesh | NVImage
- Defined in niivue/index.ts:2042

getOverlayIndexByID

getOverlayIndexByID(id): number
get the index of an overlay by its unique id. unique ids are assigned to the NVImage.id property when a new NVImage is created.
Parameters
- id: string
  the id string to search for
Returns number
See
NiiVue#getVolumeIndexByID
Example
```
niivue = new Niivue()
niivue.getOverlayIndexByID(someVolume.id)
```
- Defined in niivue/index.ts:3190

getRadiologicalConvention

getRadiologicalConvention(): boolean
Detect if display is using radiological or neurological convention.

Returns boolean
radiological convention status
Example
```
let rc = niivue.getRadiologicalConvention()
```
- Defined in niivue/index.ts:2489

getVolumeIndexByID

getVolumeIndexByID(id): number
get the index of a volume by its unique id. unique ids are assigned to the NVImage.id property when a new NVImage is created.
Parameters
- id: string
  the id string to search for
Returns number
Example
```
niivue = new Niivue()
niivue.getVolumeIndexByID(someVolume.id)
```
- Defined in niivue/index.ts:2551

indexNearestXYZmm

indexNearestXYZmm(mesh, Xmm, Ymm, Zmm): number[]
returns the index of the mesh vertex that is closest to the provided coordinates
Parameters
- mesh: number
- Xmm: number
  location in left/right dimension
- Ymm: number
  location in posterior/anterior dimension
- Zmm: number
  location in foot/head dimension
Returns number[]
the an array where ret[0] is the mesh index and ret[1] is distance from vertex to coordinates
Example
```
niivue.indexNearestXYZmm(niivue.meshes[0].id, -22, 42, 13)
```
See
live demo usage
- Defined in niivue/index.ts:3094

isMeshExt

isMeshExt(url): boolean
Returns boolean: true if filename ends with mesh extension (TRK, pial, etc)
Parameters
- url: string
  filename
Returns boolean
- Defined in niivue/index.ts:2113

json

json(): ExportDocumentData
Converts NiiVue scene to JSON

Returns ExportDocumentData
- Defined in niivue/index.ts:4029

loadConnectome

loadConnectome(json): this
load a connectome specified by json
Parameters
- json: Connectome | LegacyConnectome
Returns this
Niivue instance

See
live demo usage
- Defined in niivue/index.ts:4346

loadConnectomeFromUrl

loadConnectomeFromUrl(url, headers?): Promise<Niivue>
load a connectome specified by url
Parameters
- url: string
- headers: {} = {}
Returns Promise<Niivue>
Niivue instance

See
live demo usage
- Defined in niivue/index.ts:4275

loadDeferred4DVolumes

loadDeferred4DVolumes(id): Promise<void>
Load all volumes for image opened with limitFrames4D, the user can also click the ... on a 4D timeline to load deferred volumes
Parameters
- id: string
  the ID of the 4D NVImage
Returns Promise<void>
- Defined in niivue/index.ts:7439

loadDocument

loadDocument(document): this
Loads an NVDocument
Parameters
- document: NVDocument
Returns this
Niivue instance

See
live demo usage
- Defined in niivue/index.ts:3779

loadDocumentFromUrl

loadDocumentFromUrl(url): Promise<void>
Parameters
- url: string
  URL of NVDocument
Returns Promise<void>
- Defined in niivue/index.ts:3769

loadDrawingFromUrl

loadDrawingFromUrl(fnm, isBinarize?): Promise<boolean>
Open drawing
Parameters
- fnm: string
- isBinarize: boolean = false
  if true will force drawing voxels to be either 0 or 1.
Returns Promise<boolean>
Example
```
niivue.loadDrawingFromUrl("../images/lesion.nii.gz");
```
See
live demo usage
- Defined in niivue/index.ts:2731

loadFreeSurferConnectome

loadFreeSurferConnectome(json): Promise<Niivue>
load a connectome specified by json
Parameters
- json: FreeSurferConnectome
Returns Promise<Niivue>
Niivue instance

See
live demo usage
- Defined in niivue/index.ts:4298

loadFreeSurferConnectomeFromUrl

loadFreeSurferConnectomeFromUrl(url, headers?): Promise<Niivue>
load a connectome specified by url
Parameters
- url: string
- headers: {} = {}
Returns Promise<Niivue>
Niivue instance

See
live demo usage
- Defined in niivue/index.ts:4286

loadFromArrayBuffer

loadFromArrayBuffer(buffer, name): Promise<void>
Load an image or mesh from an array buffer
Parameters
- buffer: ArrayBuffer
  ArrayBuffer with the entire contents of a mesh or volume
- name: string
  string of filename, extension used to infer type (NIfTI, MGH, MZ3, etc)
Returns Promise<void>
See
live demo usage
- Defined in niivue/index.ts:2126

loadFromFile

loadFromFile(file): Promise<void>
Load a mesh or image from a file object
Parameters
- file: File
  File object
Returns Promise<void>
- Defined in niivue/index.ts:2142

loadMatCapTexture

loadMatCapTexture(bmpUrl): Promise<WebGLTexture>
Load matcap for illumination model.
Parameters
- bmpUrl: string
Returns Promise<WebGLTexture>
Example
```
niivue.loadMatCapTexture("Cortex");
```
See
live demo usage
- Defined in niivue/index.ts:5435

loadMeshes

loadMeshes(meshList): Promise<Niivue>
load an array of meshes
Parameters
- meshList: LoadFromUrlParams[]
  the array of objects to load. each object must have a resolvable "url" property at a minimum
Returns Promise<Niivue>
Niivue instance
Example
```
niivue = new Niivue()
niivue.loadMeshes([{url: 'someMesh.gii'}])
```
See
live demo usage
- Defined in niivue/index.ts:4239

loadVolumes

loadVolumes(volumeList): Promise<Niivue>
load an array of volume objects
Parameters
- volumeList: ImageFromUrlOptions[]
  the array of objects to load. each object must have a resolvable "url" property at a minimum
Returns Promise<Niivue>
returns the Niivue instance
Example
```
niivue = new Niivue()
niivue.loadVolumes([{url: 'someImage.nii.gz}, {url: 'anotherImage.nii.gz'}])
```
See
live demo usage
- Defined in niivue/index.ts:4109

meshShaderNames

meshShaderNames(sort?): string[]
retrieve all currently loaded meshes
Parameters
- sort: boolean = true
  sort output alphabetically
Returns string[]
list of available mesh shader names
Example
```
niivue.meshShaderNames();
```
See
live demo usage
- Defined in niivue/index.ts:5549

moveCrosshairInVox

moveCrosshairInVox(x, y, z): void
move crosshair a fixed number of voxels (not mm)
Parameters
- x: number
  translate left (-) or right (+)
- y: number
  translate posterior (-) or +anterior (+)
- z: number
  translate inferior (-) or superior (+)
Returns void
Example
```
niivue.moveCrosshairInVox(1, 0, 0)
```
See
live demo usage
- Defined in niivue/index.ts:10712

moveVolumeDown

moveVolumeDown(volume): void
Move a volume down one index position in the stack of loaded volumes. This moves it down one layer
Parameters
- volume: NVImage
  the volume to move
Returns void
Example
```
niivue = new Niivue()
niivue.moveVolumeDown(this.volumes[1]) // move the second image to the background position (it was 1 index, now will be 0)
```
- Defined in niivue/index.ts:3361

moveVolumeToBottom

moveVolumeToBottom(volume): void
Move a volume to the bottom of the stack of loaded volumes. The volume will become the background
Parameters
- volume: NVImage
  the volume to move
Returns void
Example
```
niivue = new Niivue()
niivue.moveVolumeToBottom(this.volumes[3]) // move the 4th volume to the 0 position. It will be the new background
```
- Defined in niivue/index.ts:3338

moveVolumeToTop

moveVolumeToTop(volume): void
Move a volume to the top position in the stack of loaded volumes. This will be the top layer
Parameters
- volume: NVImage
  the volume to move
Returns void
Example
```
niivue = new Niivue()
niivue.moveVolumeToTop(this.volumes[0]) // move the background image to the top layer position
```
- Defined in niivue/index.ts:3373

moveVolumeUp

moveVolumeUp(volume): void
Move a volume up one index position in the stack of loaded volumes. This moves it up one layer
Parameters
- volume: NVImage
  the volume to move
Returns void
Example
```
niivue = new Niivue()
niivue.moveVolumeUp(this.volumes[0]) // move the background image to the second index position (it was 0 index, now will be 1)
```
- Defined in niivue/index.ts:3349

refreshDrawing

refreshDrawing(isForceRedraw?, useClickToSegmentBitmap?): void
copy drawing bitmap from CPU to GPU storage and redraw the screen
Parameters
- isForceRedraw: boolean = true
  refreshes scene immediately (default true)
- useClickToSegmentBitmap: boolean = false
Returns void
Example
```
niivue.refreshDrawing();
```
See
live demo usage
- Defined in niivue/index.ts:5260

removeHaze

removeHaze(level?, volIndex?): void
remove dark voxels in air
Parameters
- level: number = 5
  (1-5) larger values for more preserved voxels
- volIndex: number = 0
  volume to dehaze
Returns void
Example
```
niivue.removeHaze(3, 0);
```
See
live demo usage
- Defined in niivue/index.ts:2904

removeMesh

removeMesh(mesh): void
Remove a triangulated mesh, connectome or tractogram
Parameters
- mesh: NVMesh
  mesh to delete
Returns void
Example
```
niivue = new Niivue()
niivue.removeMesh(this.meshes[3])
```
See
live demo usage
- Defined in niivue/index.ts:3306

removeMeshByUrl

removeMeshByUrl(url): void
Remove a triangulated mesh, connectome or tractogram
Parameters
- url: string
  URL of mesh to delete
Returns void
Example
```
niivue.removeMeshByUrl('../images/cit168.mz3')
```
- Defined in niivue/index.ts:3322

removeVolume

removeVolume(volume): void
Remove a volume
Parameters
- volume: NVImage
  volume to delete
Returns void
Example
```
niivue = new Niivue()
niivue.removeVolume(this.volumes[3])
```
See
live demo usage
- Defined in niivue/index.ts:3273

removeVolumeByIndex

removeVolumeByIndex(index): void
Remove a volume by index
Parameters
- index: number
  of volume to remove
Returns void
- Defined in niivue/index.ts:3291

removeVolumeByUrl

removeVolumeByUrl(url): void
Remove volume by url
Parameters
- url: string
  Volume added by url to remove
Returns void
See
live demo usage
- Defined in niivue/index.ts:2054

reverseFaces

reverseFaces(mesh): void
reverse triangle winding of mesh (swap front and back faces)
Parameters
- mesh: number
Returns void
Example
```
niivue.reverseFaces(niivue.meshes[0].id)
```
See
live demo usage
- Defined in niivue/index.ts:3128

saveDocument

saveDocument(fileName?, compress?): Promise<void>
save the entire scene (objects and settings) as a document
Parameters
- fileName: string = 'untitled.nvd'
  the name of the document storing the scene
- compress: boolean = true
  whether the file should be compressed
Returns Promise<void>
Example
```
niivue.saveDocument("niivue.basic.nvd")
```
See
live demo usage
- Defined in niivue/index.ts:4050

saveHTML

saveHTML(fileName?, canvasId?, esm): Promise<void>
save current scene as HTML
Parameters
- fileName: string = 'untitled.html'
  the name of the HTML file
- canvasId: string = 'gl1'
  id of canvas NiiVue will be attached to
- esm: string
  bundled version of NiiVue
Returns Promise<void>
- Defined in niivue/index.ts:4021

saveImage

saveImage(options?): boolean | Uint8Array
save voxel-based image to disk
Parameters
- options: SaveImageOptions = defaultSaveImageOptions
Returns boolean | Uint8Array
Example
```
niivue.saveImage({ filename: "myimage.nii.gz", isSaveDrawing: true });
```
See
live demo usage
- Defined in niivue/index.ts:2950

saveScene

saveScene(filename?): Promise<void>
save webgl2 canvas as png format bitmap
Parameters
- filename: string = 'niivue.png'
  filename for screen capture
Returns Promise<void>
Example
```
niivue.saveScene('test.png');
```
See
live demo usage
- Defined in niivue/index.ts:856

setAdditiveBlend

setAdditiveBlend(isAdditiveBlend): void
control whether voxel overlays are combined using additive (emission) or traditional (transmission) blending.
Parameters
- isAdditiveBlend: boolean
  emission (true) or transmission (false) mixing
Returns void
Example
```
niivue.isAdditiveBlend(true)
```
See
live demo usage
- Defined in niivue/index.ts:2479

setClipPlane

setClipPlane(depthAzimuthElevation): void
update the clip plane orientation in 3D view mode
Parameters
- depthAzimuthElevation: number[]
Returns void
Example
```
niivue = new Niivue()
niivue.setClipPlane([42, 42])
```
See
live demo usage
- Defined in niivue/index.ts:3443

setClipPlaneColor

setClipPlaneColor(color): void
set the color of the 3D clip plane
Parameters
- color: number[]
  the new color. expects an array of RGBA values. values can range from 0 to 1
Returns void
Example
```
niivue.setClipPlaneColor([1, 1, 1, 0.5]) // white, transparent
```
See
live demo usage
- Defined in niivue/index.ts:3651

setClipPlaneThick

setClipPlaneThick(thick): void
adjust thickness of the 3D clip plane
Parameters
- thick: number
  thickness of slab. Value 0..1.73 (cube opposite corner length is sqrt(3)).
Returns void
Example
```
niivue.setClipPlaneThick(0.3) // thin slab
```
See
live demo usage
- Defined in niivue/index.ts:3665

setClipVolume

setClipVolume(low, high): void
set the clipping region for volume rendering
Parameters
- low: number[]
- high: number[]
Returns void
Example
```
niivue.setClipPlaneColor([0.0, 0.0, 0.2], [1.0, 1.0, 0.7]) // remove inferior 20% and superior 30%
```
See
live demo usage
- Defined in niivue/index.ts:3681

setColormap

setColormap(id, colormap): void
update the colormap of an image given its ID
Parameters
- id: string
  the ID of the NVImage
- colormap: string
  the name of the colormap to use
Returns void
Example
```
niivue.setColormap(niivue.volumes[0].id,, 'red')
```
See
live demo usage
- Defined in niivue/index.ts:6665

setColormapNegative

setColormapNegative(id, colormapNegative): void
use given color map for negative voxels in image
Parameters
- id: string
  the ID of the NVImage
- colormapNegative: string
  the name of the colormap to use
Returns void
Example
```
niivue = new Niivue()
niivue.setColormapNegative(niivue.volumes[1].id,"winter");
```
See
live demo usage
- Defined in niivue/index.ts:7393

setCornerOrientationText

setCornerOrientationText(isCornerOrientationText): void
determine if text appears at corner (true) or sides of 2D slice.
Parameters
- isCornerOrientationText: boolean
  controls position of text
Returns void
Example
```
niivue.setCornerOrientationText(true)
```
See
live demo usage
- Defined in niivue/index.ts:2383

setCrosshairColor

setCrosshairColor(color): void
set the crosshair and colorbar outline color
Parameters
- color: number[]
  an RGBA array. values range from 0 to 1
Returns void
Example
```
niivue = new Niivue()
niivue.setCrosshairColor([0, 1, 0, 0.5]) // set crosshair to transparent green
```
See
live demo usage
- Defined in niivue/index.ts:3465

setCrosshairWidth

setCrosshairWidth(crosshairWidth): void
set thickness of crosshair
Parameters
- crosshairWidth: number
Returns void
Example
```
niivue.crosshairWidth(2)
```
See
live demo usage
- Defined in niivue/index.ts:3475

setCustomMeshShader

setCustomMeshShader(fragmentShaderText?, name?): number
Define a new GLSL shader program to influence mesh coloration
Parameters
- fragmentShaderText: string = ''
  custom fragment shader.
- name: string = 'Custom'
Returns number
index of the new shader (for setMeshShader)

See
live demo usage
- Defined in niivue/index.ts:5534

setDefaults

setDefaults(options?, resetBriCon?): void
Reset scene to default settings.
Parameters
- options: Partial<NVConfigOptions> = {}
- resetBriCon: boolean = false
  also reset contrast (default false).
Returns void
See
- NiiVueOptions
- live demo usage
Example
```
niivue.nv1.setDefaults(opts, true);
```
- Defined in niivue/index.ts:2417

setDrawingEnabled

setDrawingEnabled(trueOrFalse): void
does dragging over a 2D slice create a drawing?
Parameters
- trueOrFalse: boolean
  enabled (true) or not (false)
Returns void
Example
```
niivue.setDrawingEnabled(true)
```
See
live demo usage
- Defined in niivue/index.ts:3508

setDrawOpacity

setDrawOpacity(opacity): void
control whether drawing is transparent (0), opaque (1) or translucent (between 0 and 1).
Parameters
- opacity: number
  translucency of drawing
Returns void
Example
```
niivue.setDrawOpacity(0.7)
```
See
live demo usage
- Defined in niivue/index.ts:3537

setFrame4D

setFrame4D(id, frame4D): void
show desired 3D volume from 4D time series
Parameters
- id: string
  the ID of the 4D NVImage
- frame4D: number
  frame to display (indexed from zero)
Returns void
Example
```
nv1.setFrame4D(nv1.volumes[0].id, 42);
```
See
live demo usage
- Defined in niivue/index.ts:7470

setGamma

setGamma(gamma?): void
adjust screen gamma. Low values emphasize shadows but can appear flat, high gamma hides shadow details.
Parameters
- gamma: number = 1.0
  selects luminance, default is 1
Returns void
Example
```
niivue.setGamma(1.0);
```
See
live demo usage
- Defined in niivue/index.ts:7430

setHeroImage

setHeroImage(fraction): void
determine proportion of screen real estate devoted to rendering in multiplanar view.
Parameters
- fraction: number
  proportion of screen devoted to primary (hero) image (0 to disable)
Returns void
Example
```
niivue.setHeroImage(0.5)
```
See
live demo usage
- Defined in niivue/index.ts:2394

setHighResolutionCapable

setHighResolutionCapable(isHighResolutionCapable): void
Force WebGL canvas to use high resolution display, regardless of browser defaults.
Parameters
- isHighResolutionCapable: boolean
  allow high-DPI display
Returns void
Example
```
niivue.setHighResolutionCapable(true);
```
See
live demo usage
- Defined in niivue/index.ts:2499

setInterpolation

setInterpolation(isNearest): void
select between nearest and linear interpolation for voxel based images
Parameters
- isNearest: boolean
  whether nearest neighbor interpolation is used, else linear interpolation
Returns void
Example
```
niivue.setInterpolation(true);
```
See
live demo usage
- Defined in niivue/index.ts:8711

setMeshLayerProperty

setMeshLayerProperty(mesh, layer, key, val): void
reverse triangle winding of mesh (swap front and back faces)
Parameters
- mesh: number
  identity of mesh to change
- layer: number
  selects the mesh overlay (e.g. GIfTI or STC file)
- key: keyof NVMeshLayer
  attribute to change
- val: number
Returns void
Example
```
niivue.setMeshLayerProperty(niivue.meshes[0].id, 0, 'frame4D', 22)
```
See
live demo usage
- Defined in niivue/index.ts:3147

setMeshProperty

setMeshProperty(id, key, val): void
change property of mesh, tractogram or connectome
Parameters
- id: number
  identity of mesh to change
- key: keyof NVMesh
  attribute to change
- val: number
Returns void
Example
```
niivue.setMeshProperty(niivue.meshes[0].id, 'fiberLength', 42)
```
See
live demo usage
- Defined in niivue/index.ts:3073

setMeshShader

setMeshShader(id, meshShaderNameOrNumber?): void
select new shader for triangulated meshes and connectomes. Note that this function requires the mesh is fully loaded: you may want use await with loadMeshes (as seen in live demo).
Parameters
- id: number
  id of mesh to change
- meshShaderNameOrNumber: number = 2
  identify shader for usage
Returns void
Example
```
niivue.setMeshShader('toon');
```
See
live demo usage
- Defined in niivue/index.ts:5471

setMeshThicknessOn2D

setMeshThicknessOn2D(meshThicknessOn2D): void
Limit visibility of mesh in front of a 2D image. Requires world-space mode.
Parameters
- meshThicknessOn2D: number
  distance from voxels for clipping mesh. Use Infinity to show entire mesh or 0.0 to hide mesh.
Returns void
Example
```
niivue.setMeshThicknessOn2D(42)
```
See
live demo usage
- Defined in niivue/index.ts:2446

setModulationImage

setModulationImage(idTarget, idModulation, modulateAlpha?): void
modulate intensity of one image based on intensity of another
Parameters
- idTarget: string
  the ID of the NVImage to be biased
- idModulation: string
  the ID of the NVImage that controls bias (empty string to disable modulation)
- modulateAlpha: number = 0
  does the modulation influence alpha transparency (values greater than 1).
Returns void
Example
```
niivue.setModulationImage(niivue.volumes[0].id, niivue.volumes[1].id);
```
See
- live demo scalar usage
- live demo usage
- Defined in niivue/index.ts:7408

setMultiplanarLayout

setMultiplanarLayout(layout): void
control placement of 2D slices.
Parameters
- layout: number
  AUTO: 0, COLUMN: 1, GRID: 2, ROW: 3,
Returns void
Example
```
niivue.setMultiplanarLayout(2)
```
See
live demo usage
- Defined in niivue/index.ts:2369

setMultiplanarPadPixels

setMultiplanarPadPixels(pixels): void
insert a gap between slices of a mutliplanar view.
Parameters
- pixels: number
  spacing between tiles of multiplanar view
Returns void
Example
```
niivue.setMultiplanarPadPixels(4)
```
See
live demo usage
- Defined in niivue/index.ts:2358

setOpacity

setOpacity(volIdx, newOpacity): void
set the opacity of a volume given by volume index
Parameters
- volIdx: number
  the volume index of the volume to change
- newOpacity: number
  the opacity value. valid values range from 0 to 1. 0 will effectively remove a volume from the scene
Returns void
Example
```
niivue = new Niivue()
niivue.setOpacity(0, 0.5) // make the first volume transparent
```
See
live demo usage
- Defined in niivue/index.ts:3620

setPan2Dxyzmm

setPan2Dxyzmm(xyzmmZoom): void
adjust offset position and scale of 2D sliceScale
Parameters
- xyzmmZoom: vec4
  first three components are spatial, fourth is scaling
Returns void
Example
```
niivue.setPan2Dxyzmm([5,-4, 2, 1.5])
```
- Defined in niivue/index.ts:3162

setPenValue

setPenValue(penValue, isFilledPen?): void
determine color and style of drawing
Parameters
- penValue: number
  sets the color of the pen
- isFilledPen: boolean = false
  determines if dragging creates flood-filled shape
Returns void
Example
```
niivue.setPenValue(1, true)
```
See
live demo usage
- Defined in niivue/index.ts:3525

setRadiologicalConvention

setRadiologicalConvention(isRadiologicalConvention): void
control whether 2D slices use radiological or neurological convention.
Parameters
- isRadiologicalConvention: boolean
  new display convention
Returns void
Example
```
niivue.setRadiologicalConvention(true)
```
See
live demo usage
- Defined in niivue/index.ts:2405

setRenderAzimuthElevation

setRenderAzimuthElevation(a, e): void
set rotation of 3D render view
Parameters
- a: number
- e: number
Returns void
Example
```
niivue.setRenderAzimuthElevation(45, 15)
```
See
live demo usage
- Defined in niivue/index.ts:3175

setRenderDrawAmbientOcclusion

setRenderDrawAmbientOcclusion(ao): void
darken crevices and brighten corners when 3D rendering drawings.
Parameters
- ao: number
Returns void
See
live demo usage
- Defined in niivue/index.ts:7368

setScale

setScale(scale): void
set the scale of the 3D rendering. Larger numbers effectively zoom.
Parameters
- scale: number
  the new scale value
Returns void
Example
```
niivue.setScale(2) // zoom some
```
See
live demo usage
- Defined in niivue/index.ts:3639

setSelectionBoxColor

setSelectionBoxColor(color): void
set the selection box color. A selection box is drawn when you right click and drag to change image contrast
Parameters
- color: number[]
  an RGBA array. values range from 0 to 1
Returns void
Example
```
niivue = new Niivue()
niivue.setSelectionBoxColor([0, 1, 0, 0.5]) // set to transparent green
```
See
live demo usage
- Defined in niivue/index.ts:3550

setSliceMM

setSliceMM(isSliceMM): void
control 2D slice view mode.
Parameters
- isSliceMM: boolean
  control whether 2D slices use world space (true) or voxel space (false). Beware that voxel space mode limits properties like panning, zooming and mesh visibility.
Returns void
Example
```
niivue.setSliceMM(true)
```
See
live demo usage
- Defined in niivue/index.ts:2468

setSliceMosaicString

setSliceMosaicString(str): void
Create a custom multi-slice mosaic (aka lightbox, montage) view.
Parameters
- str: string
  description of mosaic.
Returns void
Example
```
niivue.setSliceMosaicString("A 0 20 C 30 S 42")
```
See
live demo usage
- Defined in niivue/index.ts:2457

setSliceType

setSliceType(st): this
set the slice type. This changes the view mode
Parameters
- st: SLICE_TYPE
Returns this
Example
```
niivue = new Niivue()
niivue.setSliceType(Niivue.sliceTypeMultiplanar)
```
See
live demo usage
- Defined in niivue/index.ts:3605

setVolume

setVolume(volume, toIndex?): void
set the index of a volume. This will change it's ordering and appearance if there are multiple volumes loaded.
Parameters
- volume: NVImage
  the volume to update
- toIndex: number = 0
  the index to move the volume to. The default is the background (0 index)
Returns void
Example
```
niivue = new Niivue()
niivue.setVolume(someVolume, 1) // move it to the second position in the array of loaded volumes (0 is the first position)
```
- Defined in niivue/index.ts:3209

setVolumeRenderIllumination

setVolumeRenderIllumination(gradientAmount?): Promise<void>
set proportion of volume rendering influenced by selected matcap.
Parameters
- gradientAmount: number = 0.0
  amount of matcap (0..1), default 0 (matte, surface normal does not influence color)
Returns Promise<void>
Example
```
niivue.setVolumeRenderIllumination(0.6);
```
See
live demo usage
- Defined in niivue/index.ts:3700

sph2cartDeg

sph2cartDeg(azimuth, elevation): number[]
convert spherical AZIMUTH, ELEVATION to Cartesian
Parameters
- azimuth: number
  azimuth number
- elevation: number
  elevation number
Returns number[]
the converted [x, y, z] coordinates
Example
```
niivue = new Niivue()
xyz = niivue.sph2cartDeg(42, 42)
```
- Defined in niivue/index.ts:3418

syncWith

syncWith(otherNV, syncOpts?): void
Sync the scene controls (orientation, crosshair location, etc.) from one Niivue instance to another. useful for using one canvas to drive another.
Parameters
- otherNV: Niivue | Niivue[]
  the other Niivue instance that is the main controller
- syncOpts: {
  2d: boolean;
  3d: boolean;
  } = ...
  - 2d: boolean
  - 3d: boolean
Returns void
Example
```
niivue1 = new Niivue()
niivue2 = new Niivue()
niivue2.syncWith(niivue1)
```
Deprecated
use broadcastTo instead

See
live demo usage
- Defined in niivue/index.ts:959

updateGLVolume

updateGLVolume(): void
update the webGL 2.0 scene after making changes to the array of volumes. It's always good to call this method after altering one or more volumes manually (outside of Niivue setter methods)

Returns void
Example
```
niivue = new Niivue()
niivue.updateGLVolume()
```
See
live demo usage
- Defined in niivue/index.ts:5810

Class Niivue

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Niivue

Properties

onAzimuthElevationChange

Example

onClickToSegment

Example

onClipPlaneChange

Example

onDebug

Example

onDocumentLoaded

Example

onDragRelease

Example

onError

Example

onFrameChange

Example

onImageLoaded

Example

onInfo

Example

onIntensityChange

Example

onLocationChange

Example

onMeshAddedFromUrl

Example

onMeshLoaded

Example

onMouseUp

Example

onVolumeAddedFromUrl

Example

onVolumeUpdated

Example

onWarn

Example

Methods

addColormap

Parameters

Returns void

See

addLabel

Parameters

Parameters

Returns void

Returns NVLabel3D

addMesh

Parameters

Returns void

Example

See

addMeshesFromUrl

Parameters

Returns Promise<NVMesh[]>

See

addMeshFromUrl

Parameters

Returns Promise<NVMesh>

See

addVolume

Parameters

Returns void

Example

See

addVolumeFromUrl

Parameters

Returns Promise<NVImage>

See

arrayEquals

Returns {
Frag: string;
Name: string;
shader: Shader;
}