Class: Niivue

Defined in: niivue/index.ts:366

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

Constructors

Constructor

new Niivue(options: Partial<NVConfigOptions>): Niivue;

Defined in: niivue/index.ts:898

Parameters

Parameter	Type	Default value	Description
`options`	`Partial`<`NVConfigOptions`>	`DEFAULT_OPTIONS`	options object to set modifiable Niivue properties

Returns

Niivue

Properties

Property	Type	Default value	Description	Defined in
`_gl`	`WebGL2RenderingContext`	`null`	-	niivue/index.ts:379
`back`	`NVImage`	`null`	-	niivue/index.ts:519
`backgroundMasksOverlays`	`number`	`0`	-	niivue/index.ts:458
`blurShader`	`Shader`	`null`	-	niivue/index.ts:445
`bmpShader`	`Shader`	`null`	-	niivue/index.ts:432
`bmpTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:433
`bmpTextureWH`	`number`	`1.0`	-	niivue/index.ts:435
`canvas`	`HTMLCanvasElement`	`null`	-	niivue/index.ts:378
`circleShader?`	`Shader`	`undefined`	-	niivue/index.ts:430
`clickToSegmentGrowingBitmap`	`Uint8Array`	`null`	-	niivue/index.ts:396
`clickToSegmentIsGrowing`	`boolean`	`false`	-	niivue/index.ts:395
`clickToSegmentXY`	`number`[]	`undefined`	-	niivue/index.ts:397
`CLIP_PLANE_ID`	`number`	`1`	-	niivue/index.ts:548
`colorbarHeight`	`number`	`0`	-	niivue/index.ts:399
`colorbarShader?`	`Shader`	`undefined`	-	niivue/index.ts:425
`colormapLists`	`ColormapListEntry`[]	`[]`	-	niivue/index.ts:383
`colormapTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:382
`crosshairs3D`	`NiivueObject3D`	`null`	-	niivue/index.ts:451
`cuboidVertexBuffer?`	`WebGLBuffer`	`undefined`	-	niivue/index.ts:537
`currentClipPlaneIndex`	`number`	`0`	-	niivue/index.ts:544
`currentDrawUndoBitmap`	`number`	`undefined`	-	niivue/index.ts:893
`customLayout`	`object`[]	`[]`	-	niivue/index.ts:560
`customSliceShader`	`Shader`	`null`	-	niivue/index.ts:426
`deferredMeshes`	`LoadFromUrlParams`[]	`[]`	-	niivue/index.ts:522
`deferredVolumes`	`ImageFromUrlOptions`[]	`[]`	-	niivue/index.ts:521
`dicomLoader`	`DicomLoader`	`null`	-	niivue/index.ts:369
`DISTANCE_FROM_CAMERA`	`number`	`-0.54`	-	niivue/index.ts:550
`document`	`NVDocument`	`undefined`	-	niivue/index.ts:852
`dragModes`	`object`	`undefined`	-	niivue/index.ts:630
`dragModes.angle`	`DRAG_MODE`	`DRAG_MODE.angle`	-	niivue/index.ts:633
`dragModes.callbackOnly`	`DRAG_MODE`	`DRAG_MODE.callbackOnly`	-	niivue/index.ts:637
`dragModes.contrast`	`DRAG_MODE`	`DRAG_MODE.contrast`	-	niivue/index.ts:631
`dragModes.measurement`	`DRAG_MODE`	`DRAG_MODE.measurement`	-	niivue/index.ts:632
`dragModes.none`	`DRAG_MODE`	`DRAG_MODE.none`	-	niivue/index.ts:634
`dragModes.pan`	`DRAG_MODE`	`DRAG_MODE.pan`	-	niivue/index.ts:635
`dragModes.slicer3D`	`DRAG_MODE`	`DRAG_MODE.slicer3D`	-	niivue/index.ts:636
`drawFillOverwrites`	`boolean`	`true`	-	niivue/index.ts:402
`drawLut`	`LUT`	`undefined`	-	niivue/index.ts:392
`drawOpacity`	`number`	`0.8`	-	niivue/index.ts:393
`drawPenAxCorSag`	`number`	`-1`	-	niivue/index.ts:401
`drawPenFillPts`	`number`[][]	`[]`	-	niivue/index.ts:403
`drawPenLocation`	`number`[]	`undefined`	-	niivue/index.ts:400
`drawRimOpacity`	`number`	`-1.0`	-	niivue/index.ts:394
`drawShapePreviewBitmap`	`Uint8Array`	`null`	-	niivue/index.ts:405
`drawShapeStartLocation`	`number`[]	`undefined`	-	niivue/index.ts:404
`drawTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:389
`drawUndoBitmaps`	`Uint8Array`[]	`[]`	-	niivue/index.ts:391
`extentsMax?`	`vec3`	`undefined`	-	niivue/index.ts:463
`extentsMin?`	`vec3`	`undefined`	-	niivue/index.ts:462
`fiberShader?`	`Shader`	`undefined`	-	niivue/index.ts:428
`fontShader`	`Shader`	`null`	-	niivue/index.ts:427
`fontTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:429
`furthestFromPivot`	`number`	`10.0`	-	niivue/index.ts:542
`furthestVertexFromOrigin`	`number`	`100`	-	niivue/index.ts:523
`genericVAO`	`WebGLVertexArrayObject`	`null`	-	niivue/index.ts:449
`gradientTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:385
`gradientTextureAmount`	`number`	`0.0`	-	niivue/index.ts:386
`graph`	`Graph`	`undefined`	-	niivue/index.ts:551
`growCutShader?`	`Shader`	`undefined`	-	niivue/index.ts:436
`initialized`	`boolean`	`false`	-	niivue/index.ts:892
`isBusy`	`boolean`	`false`	-	niivue/index.ts:380
`lastCalled`	`number`	`undefined`	-	niivue/index.ts:545
`line3DShader?`	`Shader`	`undefined`	-	niivue/index.ts:417
`lineShader?`	`Shader`	`undefined`	-	niivue/index.ts:416
`loaders`	`object`	`{}`	-	niivue/index.ts:367
`matCapTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:431
`mediaUrlMap`	`Map`< \| `NVMesh` \| `NVImage`, `string`>	`undefined`	-	niivue/index.ts:891
`meshShaders`	`object`[]	`undefined`	-	niivue/index.ts:566
`mousePos`	`number`[]	`undefined`	-	niivue/index.ts:526
`needsRefresh`	`boolean`	`false`	-	niivue/index.ts:381
`onAzimuthElevationChange`	(`azimuth`: `number`, `elevation`: `number`) => `void`	`undefined`	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) }`	niivue/index.ts:815
`onClickToSegment`	(`data`: `object`) => `void`	`undefined`	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) }`	niivue/index.ts:696
`onClipPlaneChange`	(`clipPlane`: `number`[]) => `void`	`undefined`	callback function to run when the user changes the clip plane Example `niivue.onClipPlaneChange = (clipPlane) => { console.log('clipPlane: ', clipPlane) }`	niivue/index.ts:824
`onColormapChange`	() => `void`	`undefined`	-	niivue/index.ts:739
`onCustomMeshShaderAdded`	(`fragmentShaderText`: `string`, `name`: `string`) => `void`	`undefined`	-	niivue/index.ts:825
`onDebug`	() => `void`	`undefined`	callback function to run when niivue reports a debug message Example `niivue.onDebug = (debug) => { console.log('debug: ', debug) }`	niivue/index.ts:766
`onDicomLoaderFinishedWithImages`	(`files`: \| `NVImage`[] \| `NVMesh`[]) => `void`	`undefined`	-	niivue/index.ts:829
`onDocumentLoaded`	(`document`: `NVDocument`) => `void`	`undefined`	callback function to run when the user loads a new NiiVue document Example `niivue.onDocumentLoaded = (document) => { console.log('document: ', document) }`	niivue/index.ts:838
`onDragRelease`	(`params`: `DragReleaseParams`) => `void`	`undefined`	callback function to run when the right mouse button is released after dragging Example `niivue.onDragRelease = () => { console.log('drag ended') }`	niivue/index.ts:655
`onError`	() => `void`	`undefined`	callback function to run when niivue reports an error Example `niivue.onError = (error) => { console.log('error: ', error) }`	niivue/index.ts:736
`onFrameChange`	(`volume`: `NVImage`, `index`: `number`) => `void`	`undefined`	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) }`	niivue/index.ts:727
`onImageLoaded`	(`volume`: `NVImage`) => `void`	`undefined`	callback function to run when a new volume is loaded Example `niivue.onImageLoaded = (volume) => { console.log('volume loaded') console.log('volume: ', volume) }`	niivue/index.ts:706
`onInfo`	() => `void`	`undefined`	callback function to run when niivue reports detailed info Example `niivue.onInfo = (info) => { console.log('info: ', info) }`	niivue/index.ts:748
`onIntensityChange`	(`volume`: `NVImage`) => `void`	`undefined`	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) }`	niivue/index.ts:685
`onLocationChange`	(`location`: `unknown`) => `void`	`undefined`	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) }`	niivue/index.ts:676
`onMeshAdded`	() => `void`	`undefined`	-	niivue/index.ts:801
`onMeshAddedFromUrl`	(`meshOptions`: `LoadFromUrlParams`, `mesh`: `NVMesh`) => `void`	`undefined`	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) }`	niivue/index.ts:798
`onMeshLoaded`	(`mesh`: `NVMesh`) => `void`	`undefined`	callback function to run when a new mesh is loaded Example `niivue.onMeshLoaded = (mesh) => { console.log('mesh loaded') console.log('mesh: ', mesh) }`	niivue/index.ts:716
`onMeshPropertyChanged`	(`meshIndex`: `number`, `key`: `string`, `val`: `unknown`) => `void`	`undefined`	-	niivue/index.ts:827
`onMeshShaderChanged`	(`meshIndex`: `number`, `shaderIndex`: `number`) => `void`	`undefined`	-	niivue/index.ts:826
`onMeshWithUrlRemoved`	(`url`: `string`) => `void`	`undefined`	-	niivue/index.ts:802
`onMouseUp`	(`data`: `Partial`<`UIData`>) => `void`	`undefined`	callback function to run when the left mouse button is released Example `niivue.onMouseUp = () => { console.log('mouse up') }`	niivue/index.ts:664
`onOptsChange`	(`propertyName`: keyof `NVConfigOptions`, `newValue`: \| `string` \| `number` \| `boolean` \| `number`[] \| `Float32Array` \| `MouseEventConfig` \| `TouchEventConfig` \| `number`[] \| [[`number`, `number`], [`number`, `number`]], `oldValue`: \| `string` \| `number` \| `boolean` \| `number`[] \| `Float32Array` \| `MouseEventConfig` \| `TouchEventConfig` \| `number`[] \| [[`number`, `number`], [`number`, `number`]]) => `void`	`undefined`	Callback for when any configuration option changes.	niivue/index.ts:846
`onVolumeAddedFromUrl`	(`imageOptions`: `ImageFromUrlOptions`, `volume`: `NVImage`) => `void`	`undefined`	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) }`	niivue/index.ts:777
`onVolumeUpdated`	() => `void`	`undefined`	callback function to run when updateGLVolume is called (most users will not need to use Example `niivue.onVolumeUpdated = () => { console.log('volume updated') }`	niivue/index.ts:787
`onVolumeWithUrlRemoved`	(`url`: `string`) => `void`	`undefined`	-	niivue/index.ts:778
`onWarn`	() => `void`	`undefined`	callback function to run when niivue reports a warning Example `niivue.onWarn = (warn) => { console.log('warn: ', warn) }`	niivue/index.ts:757
`onZoom3DChange`	(`zoom`: `number`) => `void`	`undefined`	-	niivue/index.ts:805
`orientCubeShader?`	`Shader`	`undefined`	-	niivue/index.ts:411
`orientCubeShaderVAO`	`WebGLVertexArrayObject`	`null`	-	niivue/index.ts:412
`orientShaderAtlasI`	`Shader`	`null`	-	niivue/index.ts:438
`orientShaderAtlasU`	`Shader`	`null`	-	niivue/index.ts:437
`orientShaderF`	`Shader`	`null`	-	niivue/index.ts:441
`orientShaderI`	`Shader`	`null`	-	niivue/index.ts:440
`orientShaderPAQD`	`Shader`	`null`	-	niivue/index.ts:443
`orientShaderRGBU`	`Shader`	`null`	-	niivue/index.ts:442
`orientShaderU`	`Shader`	`null`	-	niivue/index.ts:439
`otherNV`	`Niivue`[]	`null`	-	niivue/index.ts:539
`overlayAlphaShader`	`number`	`1`	-	niivue/index.ts:460
`overlayOutlineWidth`	`number`	`0`	-	niivue/index.ts:459
`overlays`	`NVImage`[]	`[]`	-	niivue/index.ts:520
`overlayTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:406
`overlayTextureID`	`WebGLTexture`	`null`	-	niivue/index.ts:407
`paqdTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:390
`passThroughShader?`	`Shader`	`undefined`	-	niivue/index.ts:418
`pickingImageShader?`	`Shader`	`undefined`	-	niivue/index.ts:424
`pickingMeshShader?`	`Shader`	`undefined`	-	niivue/index.ts:423
`pivot3D`	`number`[]	`undefined`	-	niivue/index.ts:541
`position?`	`vec3`	`undefined`	-	niivue/index.ts:461
`readyForSync`	`boolean`	`false`	-	niivue/index.ts:481
`rectOutlineShader?`	`Shader`	`undefined`	-	niivue/index.ts:414
`rectShader?`	`Shader`	`undefined`	-	niivue/index.ts:413
`renderDrawAmbientOcclusion`	`number`	`0.4`	-	niivue/index.ts:398
`renderGradientShader?`	`Shader`	`undefined`	-	niivue/index.ts:419
`renderGradientValues`	`boolean`	`false`	-	niivue/index.ts:388
`renderGradientValuesShader?`	`Shader`	`undefined`	-	niivue/index.ts:420
`renderShader?`	`Shader`	`undefined`	-	niivue/index.ts:415
`renderSliceShader?`	`Shader`	`undefined`	-	niivue/index.ts:421
`renderVolumeShader?`	`Shader`	`undefined`	-	niivue/index.ts:422
`screenSlices`	`object`[]	`[]`	-	niivue/index.ts:527
`selectedObjectId`	`number`	`-1`	-	niivue/index.ts:547
`slice2DShader?`	`Shader`	`undefined`	-	niivue/index.ts:409
`sliceMMShader?`	`Shader`	`undefined`	-	niivue/index.ts:408
`sliceTypeAxial`	`SLICE_TYPE`	`SLICE_TYPE.AXIAL`	-	niivue/index.ts:641
`sliceTypeCoronal`	`SLICE_TYPE`	`SLICE_TYPE.CORONAL`	-	niivue/index.ts:642
`sliceTypeMultiplanar`	`SLICE_TYPE`	`SLICE_TYPE.MULTIPLANAR`	-	niivue/index.ts:644
`sliceTypeRender`	`SLICE_TYPE`	`SLICE_TYPE.RENDER`	-	niivue/index.ts:645
`sliceTypeSagittal`	`SLICE_TYPE`	`SLICE_TYPE.SAGITTAL`	-	niivue/index.ts:643
`sliceV1Shader?`	`Shader`	`undefined`	-	niivue/index.ts:410
`sobelBlurShader`	`Shader`	`null`	-	niivue/index.ts:446
`sobelFirstOrderShader`	`Shader`	`null`	-	niivue/index.ts:447
`sobelSecondOrderShader`	`Shader`	`null`	-	niivue/index.ts:448
`surfaceShader`	`Shader`	`null`	-	niivue/index.ts:444
`syncOpts`	`SyncOpts`	`undefined`	-	niivue/index.ts:469
`thumbnailVisible`	`boolean`	`false`	-	niivue/index.ts:434
`uiData`	`UIData`	`undefined`	-	niivue/index.ts:484
`unusedVAO`	`any`	`null`	-	niivue/index.ts:450
`useCustomGradientTexture`	`boolean`	`false`	-	niivue/index.ts:387
`volScale`	`number`[]	`[]`	-	niivue/index.ts:524
`VOLUME_ID`	`number`	`254`	-	niivue/index.ts:549
`volumeObject3D`	`NiivueObject3D`	`null`	-	niivue/index.ts:540
`volumeTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:384
`vox`	`number`[]	`[]`	-	niivue/index.ts:525

Accessors

drawBitmap

Get Signature

get drawBitmap(): Uint8Array;

Defined in: niivue/index.ts:988

Returns

Uint8Array

Set Signature

set drawBitmap(drawBitmap: Uint8Array): void;

Defined in: niivue/index.ts:992

Parameters

Parameter	Type
`drawBitmap`	`Uint8Array`

Returns

void

isAlphaClipDark

Get Signature

get isAlphaClipDark(): boolean;

Defined in: niivue/index.ts:878

Get whether voxels below minimum intensity are drawn as dark or transparent.

Returns

boolean

True if dark voxels are opaque, false if transparent.

Set Signature

set isAlphaClipDark(newVal: boolean): void;

Defined in: niivue/index.ts:887

Set whether voxels below minimum intensity are drawn as dark or transparent.

See

live demo usage

Parameters

Parameter	Type	Description
`newVal`	`boolean`	True to make dark voxels opaque, false for transparent.

Returns

void

meshes

Get Signature

get meshes(): NVMesh[];

Defined in: niivue/index.ts:980

Returns

NVMesh[]

Set Signature

set meshes(meshes: NVMesh[]): void;

Defined in: niivue/index.ts:984

Parameters

Parameter	Type
`meshes`	`NVMesh`[]

Returns

void

opts

Get Signature

get opts(): NVConfigOptions;

Defined in: niivue/index.ts:860

Get the current visualization options.

Returns

NVConfigOptions

scene

Get Signature

get scene(): Scene;

Defined in: niivue/index.ts:855

Get the current scene configuration.

Returns

Scene

sliceMosaicString

Get Signature

get sliceMosaicString(): string;

Defined in: niivue/index.ts:865

Get the slice mosaic layout string.

Returns

string

Set Signature

set sliceMosaicString(newSliceMosaicString: string): void;

Defined in: niivue/index.ts:870

Set the slice mosaic layout string.

Parameters

Parameter	Type
`newSliceMosaicString`	`string`

Returns

void

volScaleMultiplier

Get Signature

get volScaleMultiplier(): number;

Defined in: niivue/index.ts:996

Returns

number

Set Signature

set volScaleMultiplier(scale: number): void;

Defined in: niivue/index.ts:1000

Parameters

Parameter	Type
`scale`	`number`

Returns

void

volumes

Get Signature

get volumes(): NVImage[];

Defined in: niivue/index.ts:972

Returns

NVImage[]

Set Signature

set volumes(volumes: NVImage[]): void;

Defined in: niivue/index.ts:976

Parameters

Parameter	Type
`volumes`	`NVImage`[]

Returns

void

Methods

addColormap()

addColormap(key: string, cmap: ColorMap): void;

Defined in: niivue/index.ts:8942

create a new colormap

Parameters

Parameter	Type	Description
`key`	`string`	name of new colormap
`cmap`	`ColorMap`	colormap properties (Red, Green, Blue, Alpha and Indices)

Returns

void

See

live demo usage

addLabel()

addLabel(
   text: string,
   style: NVLabel3DStyle,
   points?: number[] | number[][],
   anchor?: LabelAnchorPoint,
   onClick?: (label: NVLabel3D) => void): NVLabel3D;

Defined in: niivue/index.ts:13338

Add a 3D Label

Parameters

Parameter	Type	Description
`text`	`string`	the text content of the label
`style`	`NVLabel3DStyle`	visual styling options for the label (e.g., color, scale, line width)
`points?`	`number`[] \| `number`[][]	a 3D point `[x, y, z]` or array of points to anchor the label in space
`anchor?`	`LabelAnchorPoint`	optional label anchor position (e.g., top-left, center, etc.)
`onClick?`	(`label`: `NVLabel3D`) => `void`	optional callback function to invoke when the label is clicked

Returns

NVLabel3D

the created NVLabel3D instance

See

live demo usage

addMesh()

addMesh(mesh: NVMesh): void;

Defined in: niivue/index.ts:3617

add a new mesh to the canvas

Parameters

Parameter	Type	Description
`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

addMeshesFromUrl()

addMeshesFromUrl(meshOptions: LoadFromUrlParams[]): Promise<NVMesh[]>;

Defined in: niivue/index.ts:5540

Add mesh and notify subscribers

Parameters

Parameter	Type
`meshOptions`	`LoadFromUrlParams`[]

Returns

Promise<NVMesh[]>

addMeshFromUrl()

addMeshFromUrl(meshOptions: LoadFromUrlParams): Promise<NVMesh>;

Defined in: niivue/index.ts:5519

Add mesh and notify subscribers

Parameters

Parameter	Type
`meshOptions`	`LoadFromUrlParams`

Returns

Promise<NVMesh>

addVolume()

addVolume(volume: NVImage): void;

Defined in: niivue/index.ts:3600

add a new volume to the canvas

Parameters

Parameter	Type	Description
`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

addVolumeFromUrl()

addVolumeFromUrl(imageOptions: ImageFromUrlOptions): Promise<NVImage>;

Defined in: niivue/index.ts:2788

Add an image and notify subscribers

Parameters

Parameter	Type
`imageOptions`	`ImageFromUrlOptions`

Returns

Promise<NVImage>

See

live demo usage

addVolumesFromUrl()

addVolumesFromUrl(imageOptionsArray: ImageFromUrlOptions[]): Promise<NVImage[]>;

Defined in: niivue/index.ts:2800

Parameters

Parameter	Type
`imageOptionsArray`	`ImageFromUrlOptions`[]

Returns

Promise<NVImage[]>

attachTo()

attachTo(id: string, isAntiAlias: any): Promise<Niivue>;

Defined in: niivue/index.ts:1048

attach the Niivue instance to the webgl2 canvas by element id

Parameters

Parameter	Type	Default value	Description
`id`	`string`	`undefined`	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>

Examples

niivue = new Niivue().attachTo("gl");

await niivue.attachTo("gl");

See

live demo usage

attachToCanvas()

attachToCanvas(canvas: HTMLCanvasElement, isAntiAlias: boolean): Promise<Niivue>;

Defined in: niivue/index.ts:1062

attach the Niivue instance to a canvas element directly

Parameters

Parameter	Type	Default value	Description
`canvas`	`HTMLCanvasElement`	`undefined`	the canvas element reference
`isAntiAlias`	`boolean`	`null`	-

Returns

Promise<Niivue>

Example

niivue = new Niivue();
await niivue.attachToCanvas(document.getElementById(id));

See

live demo usage

binarize()

binarize(volume: NVImage): void;

Defined in: niivue/index.ts:3810

Binarize a volume by converting all non-zero voxels to 1

Parameters

Parameter	Type	Description
`volume`	`NVImage`	the image volume to modify in place

Returns

void

See

live demo usage

broadcastTo()

broadcastTo(otherNV: Niivue | Niivue[], syncOpts: object): void;

Defined in: niivue/index.ts:1155

Sync the scene controls (orientation, crosshair location, etc.) from one Niivue instance to others. useful for using one canvas to drive another.

Parameters

Parameter	Type	Description
`otherNV`	`Niivue` \| `Niivue`[]	the other Niivue instance(s)
`syncOpts`	{ `2d`: `boolean`; `3d`: `boolean`; }	-
`syncOpts.2d`	`boolean`	-
`syncOpts.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

cleanup()

cleanup(): void;

Defined in: niivue/index.ts:941

Clean up event listeners and observers Call this when the Niivue instance is no longer needed. This will be called when the canvas is detached from the DOM

Returns

void

Example

niivue.cleanup();

clearAllMeasurements()

clearAllMeasurements(): void;

Defined in: niivue/index.ts:11038

Clear all persistent measurements and angles from the canvas.

Returns

void

Example

nv.clearAllMeasurements();

clearAngles()

clearAngles(): void;

Defined in: niivue/index.ts:11026

Clear all persistent angle measurements from the canvas.

Returns

void

Example

nv.clearAngles();

clearBounds()

clearBounds(mask: number, ltwh?: [number, number, number, number]): void;

Defined in: niivue/index.ts:15236

Clear a rectangular region of this instance's canvas.

Parameters

Parameter	Type	Description
`mask`	`number`	bitmask of buffers to clear (default: color+depth).
`ltwh?`	[`number`, `number`, `number`, `number`]	optional [x, y, w, h] region in device px (GL coords, bottom-left). If not provided, clears the full instance bounds (getBoundsRegion). For multiplanar panels, pass the panel’s own [x,y,w,h].

Returns

void

clearCustomLayout()

clearCustomLayout(): void;

Defined in: niivue/index.ts:3436

Clear custom layout and rely on built-in layouts

Returns

void

clearMeasurements()

clearMeasurements(): void;

Defined in: niivue/index.ts:11014

Clear all persistent measurement lines from the canvas.

Returns

void

Example

nv.clearMeasurements();

cloneVolume()

cloneVolume(index: number): NVImage;

Defined in: niivue/index.ts:5038

clone a volume and return a new volume

Parameters

Parameter	Type	Description
`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);

closeDrawing()

closeDrawing(): void;

Defined in: niivue/index.ts:6846

close drawing: make sure you have saved any changes before calling this!

Returns

void

Example

niivue.closeDrawing();

See

live demo usage

colormap()

colormap(lutName: string, isInvert: boolean): Uint8ClampedArray;

Defined in: niivue/index.ts:9866

Retrieve a colormap with optional inversion

Parameters

Parameter	Type	Default value	Description
`lutName`	`string`	`''`	name of the lookup table (LUT) colormap
`isInvert`	`boolean`	`false`	whether to invert the colormap

Returns

Uint8ClampedArray

the RGBA colormap as a Uint8ClampedArray

See

live demo usage

colormaps()

colormaps(): string[];

Defined in: niivue/index.ts:8932

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

conform()

conform(
   volume: NVImage,
   toRAS: boolean,
   isLinear: boolean,
   asFloat32: boolean,
isRobustMinMax: boolean): Promise<NVImage>;

Defined in: niivue/index.ts:9569

FreeSurfer-style conform reslices any image to a 256x256x256 volume with 1mm voxels

Parameters

Parameter	Type	Default value	Description
`volume`	`NVImage`	`undefined`	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

createConnectedLabelImage()

createConnectedLabelImage(
   id: string,
   conn: number,
   binarize: boolean,
onlyLargestClusterPerClass: boolean): Promise<NVImage>;

Defined in: niivue/index.ts:9281

Create a connected component label map from a volume

Parameters

Parameter	Type	Default value	Description
`id`	`string`	`undefined`	ID of the input volume
`conn`	`number`	`26`	connectivity for clustering (6 = faces, 18 = faces + edges, 26 = faces + edges + corners)
`binarize`	`boolean`	`false`	whether to binarize the volume before labeling
`onlyLargestClusterPerClass`	`boolean`	`false`	retain only the largest cluster for each label

Returns

Promise<NVImage>

a new NVImage with labeled clusters, using random colormap

See

live demo usage

createCustomMeshShader()

createCustomMeshShader(fragmentShaderText: string, name: string): object;

Defined in: niivue/index.ts:7424

Parameters

Parameter	Type	Default value	Description
`fragmentShaderText`	`string`	`undefined`	custom fragment shader.
`name`	`string`	`'Custom'`	title for new shader.

Returns

object

created custom mesh shader

Name	Type	Defined in
`Frag`	`string`	niivue/index.ts:7428
`Name`	`string`	niivue/index.ts:7428
`shader`	`Shader`	niivue/index.ts:7428

createEmptyDrawing()

createEmptyDrawing(): void;

Defined in: niivue/index.ts:5723

generate a blank canvas for the pen tool

Returns

void

Example

niivue.createEmptyDrawing();

See

live demo usage

createNiftiArray()

createNiftiArray(
   dims: number[],
   pixDims: number[],
   affine: number[],
   datatypeCode: NiiDataType,
img: Uint8Array): Promise<Uint8Array>;

Defined in: niivue/index.ts:9525

Create a binary NIfTI file as a Uint8Array, including header and image data

Parameters

Parameter	Type	Default value	Description
`dims`	`number`[]	`...`	image dimensions [x, y, z]
`pixDims`	`number`[]	`...`	voxel dimensions in mm [x, y, z]
`affine`	`number`[]	`...`	4×4 affine transformation matrix in row-major order
`datatypeCode`	`NiiDataType`	`NiiDataType.DT_UINT8`	NIfTI datatype code (e.g., DT_UINT8, DT_FLOAT32)
`img`	`Uint8Array`	`...`	image data buffer (optional)

Returns

Promise<Uint8Array>

a Uint8Array representing a complete NIfTI file

See

live demo usage

createOnLocationChange()

createOnLocationChange(axCorSag: number): void;

Defined in: niivue/index.ts:13215

Internal utility to generate human-readable location strings for the onLocationChange callback

Parameters

Parameter	Type	Default value	Description
`axCorSag`	`number`	`NaN`	optional axis index for coordinate interpretation (NaN by default)

Returns

void

Remarks

Computes string representation of current crosshair position in mm (and frame if 4D).

See

live demo usage

decimateHierarchicalMesh()

decimateHierarchicalMesh(mesh: number, order: number): boolean;

Defined in: niivue/index.ts:4235

reduce complexity of FreeSurfer mesh

Parameters

Parameter	Type	Default value	Description
`mesh`	`number`	`undefined`	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

doSyncGamma()

doSyncGamma(otherNV: Niivue): void;

Defined in: niivue/index.ts:1184

Parameters

Parameter	Type
`otherNV`	`Niivue`

Returns

void

drawGrowCut()

drawGrowCut(): void;

Defined in: niivue/index.ts:5789

dilate drawing so all voxels are colored. works on drawing with multiple colors

Returns

void

Example

niivue.drawGrowCut();

See

live demo usage

drawingBinaryDilationWithSeed()

drawingBinaryDilationWithSeed(seedXYZ: number[], neighbors: 6 | 18 | 26): void;

Defined in: niivue/index.ts:6121

Performs a 1-voxel binary dilation on a connected cluster within the drawing mask using the drawFloodFillCore function.

Parameters

Parameter	Type	Default value	Description
`seedXYZ`	`number`[]	`undefined`	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

drawMosaic()

drawMosaic(mosaicStr: string): void;

Defined in: niivue/index.ts:14856

display a lightbox or montage view

Parameters

Parameter	Type	Description
`mosaicStr`	`string`	specifies orientation (A,C,S) and location of slices.

Returns

void

Example

niivue.setSliceMosaicString("A -10 0 20");

See

live demo usage

drawOtsu()

drawOtsu(levels: number): void;

Defined in: niivue/index.ts:3969

remove dark voxels in air

Parameters

Parameter	Type	Default value	Description
`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

drawUndo()

drawUndo(): void;

Defined in: niivue/index.ts:3690

Restore drawing to previous state

Returns

void

Example

niivue.drawUndo();

See

live demo usage

eventInBounds()

eventInBounds(evt: MouseEvent | Touch | TouchEvent): boolean;

Defined in: niivue/index.ts:15099

Returns true if a mouse/touch event happened inside this instance’s bounds.

Parameters

Parameter	Type
`evt`	`MouseEvent` \| `Touch` \| `TouchEvent`

Returns

boolean

findDrawingBoundarySlices()

findDrawingBoundarySlices(sliceType: SLICE_TYPE): object;

Defined in: niivue/index.ts:15906

Find the first and last slices containing drawing data along a given axis

Parameters

Parameter	Type	Description
`sliceType`	`SLICE_TYPE`	The slice orientation (AXIAL, CORONAL, or SAGITTAL)

Returns

object

Object containing first and last slice indices, or null if no data found

Name	Type	Defined in
`first`	`number`	niivue/index.ts:15906
`last`	`number`	niivue/index.ts:15906

frac2canvasPos()

frac2canvasPos(frac: vec3): number[];

Defined in: niivue/index.ts:14320

Parameters

Parameter	Type
`frac`	`vec3`

Returns

number[]

generateHTML()

generateHTML(canvasId: string, esm: string): Promise<string>;

Defined in: niivue/index.ts:5235

generates HTML of current scene

Parameters

Parameter	Type	Default value	Description
`canvasId`	`string`	`'gl1'`	id of canvas NiiVue will be attached to
`esm`	`string`	`undefined`	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);

generateLoadDocumentJavaScript()

generateLoadDocumentJavaScript(canvasId: string, esm: string): Promise<string>;

Defined in: niivue/index.ts:5194

generates JavaScript to load the current scene as a document

Parameters

Parameter	Type	Description
`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>`;

See

live demo usage

getCustomLayout()

getCustomLayout(): object[];

Defined in: niivue/index.ts:3445

Get the current custom layout if set

Returns

object[]

The current custom layout or null if using built-in layouts

getDescriptives()

getDescriptives(options: object): Descriptive;

Defined in: niivue/index.ts:8046

basic statistics for selected voxel-based image

Parameters

Parameter	Type	Description
`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
`options.drawingIsMask?`	`boolean`	-
`options.endVox?`	`number`[]	-
`options.layer?`	`number`	-
`options.masks?`	`number`[]	-
`options.roiIsMask?`	`boolean`	-
`options.startVox?`	`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

getDicomLoader()

getDicomLoader(): DicomLoader;

Defined in: niivue/index.ts:3070

Get the currently assigned DICOM loader.

Returns

DicomLoader

getFrame4D()

getFrame4D(id: string): number;

Defined in: niivue/index.ts:9846

determine active 3D volume from 4D time series

Parameters

Parameter	Type	Description
`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

getGradientTextureData()

getGradientTextureData(): Float32Array;

Defined in: niivue/index.ts:7827

Get the gradient texture produced by gradientGL as a TypedArray

Returns

Float32Array

Float32Array containing the gradient texture data, or null if no gradient texture exists

Example

niivue = new Niivue();
niivue.loadVolumes([{ url: "./someImage.nii" }]);
// ... after volume is loaded and gradient is computed
const gradientData = niivue.getGradientTextureData();
if (gradientData) {
  console.log("Gradient texture dimensions:", gradientData.length);
}

See

live demo usage

getMeshIndexByID()

getMeshIndexByID(id: string | number): number;

Defined in: niivue/index.ts:4168

Returns the index of a mesh given its ID or index.

Parameters

Parameter	Type	Description
`id`	`string` \| `number`	The mesh ID as a string, or an index number.

Returns

number

The mesh index, or -1 if not found or out of range.

getMouseEventConfig()

getMouseEventConfig(): MouseEventConfig;

Defined in: niivue/index.ts:11135

Get current mouse event configuration.

Returns

MouseEventConfig

Current mouse event configuration or undefined if using defaults

getOverlayIndexByID()

getOverlayIndexByID(id: string): number;

Defined in: niivue/index.ts:4314

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

Parameter	Type	Description
`id`	`string`	the id string to search for

Returns

number

See

NiiVue#getVolumeIndexByID

Example

niivue = new Niivue();
niivue.getOverlayIndexByID(someVolume.id);

getRadiologicalConvention()

getRadiologicalConvention(): boolean;

Defined in: niivue/index.ts:3543

Detect if display is using radiological or neurological convention.

Returns

boolean

radiological convention status

Example

let rc = niivue.getRadiologicalConvention();

getTouchEventConfig()

getTouchEventConfig(): TouchEventConfig;

Defined in: niivue/index.ts:11143

Get current touch event configuration.

Returns

TouchEventConfig

Current touch event configuration or undefined if using defaults

getVolumeIndexByID()

getVolumeIndexByID(id: string): number;

Defined in: niivue/index.ts:3631

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

Parameter	Type	Description
`id`	`string`	the id string to search for

Returns

number

Example

niivue = new Niivue();
niivue.getVolumeIndexByID(someVolume.id);

inBounds()

inBounds(x: number, y: number): boolean;

Defined in: niivue/index.ts:15189

Return true if the given canvas pixel coordinates are inside this Niivue instance's bounds.

Parameters

Parameter	Type
`x`	`number`
`y`	`number`

Returns

boolean

indexNearestXYZmm()

indexNearestXYZmm(
   mesh: number,
   Xmm: number,
   Ymm: number,
   Zmm: number): number[];

Defined in: niivue/index.ts:4218

returns the index of the mesh vertex that is closest to the provided coordinates

Parameters

Parameter	Type	Description
`mesh`	`number`	identity of mesh to change
`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

interpolateMaskSlices()

interpolateMaskSlices(
   sliceIndexLow?: number,
   sliceIndexHigh?: number,
   options?: object): void;

Defined in: niivue/index.ts:15921

Interpolate between mask slices using geometric or intensity-guided methods

Parameters

Parameter	Type	Description
`sliceIndexLow?`	`number`	Lower slice index (optional, will auto-detect if not provided)
`sliceIndexHigh?`	`number`	Higher slice index (optional, will auto-detect if not provided)
`options?`	{ `applySmoothingToSlices?`: `boolean`; `binaryThreshold?`: `number`; `intensitySigma?`: `number`; `intensityWeight?`: `number`; `sliceType?`: `SLICE_TYPE`; `useIntensityGuided?`: `boolean`; }	Interpolation options
`options.applySmoothingToSlices?`	`boolean`	-
`options.binaryThreshold?`	`number`	-
`options.intensitySigma?`	`number`	-
`options.intensityWeight?`	`number`	-
`options.sliceType?`	`SLICE_TYPE`	-
`options.useIntensityGuided?`	`boolean`	-

Returns

void

json()

json(): ExportDocumentData;

Defined in: niivue/index.ts:5325

Converts NiiVue scene to JSON

Returns

ExportDocumentData

loadConnectome()

loadConnectome(json:
  | Connectome
  | LegacyConnectome): this;

Defined in: niivue/index.ts:5709

load a connectome specified by json

Parameters

Parameter	Type	Description
`json`	\| `Connectome` \| `LegacyConnectome`	connectome model

Returns

this

Niivue instance

See

live demo usage

loadConnectomeFromUrl()

loadConnectomeFromUrl(url: string, headers: object): Promise<Niivue>;

Defined in: niivue/index.ts:5626

Load a connectome from a given URL and initialize it.

Parameters

Parameter	Type	Description
`url`	`string`	the URL to a JSON-formatted connectome definition
`headers`	{ }	optional HTTP headers to include with the request (e.g. for authorization)

Returns

Promise<Niivue>

the Niivue instance (for method chaining)

See

live demo usage

loadDeferred4DVolumes()

loadDeferred4DVolumes(id: string): Promise<void>;

Defined in: niivue/index.ts:9787

Load all volumes for image opened with limitFrames4D, the user can also click the ... on a 4D timeline to load deferred volumes

Parameters

Parameter	Type	Description
`id`	`string`	the ID of the 4D NVImage

Returns

Promise<void>

loadDicoms()

loadDicoms(dicomList: ImageFromUrlOptions[]): Promise<Niivue>;

Defined in: niivue/index.ts:5421

Parameters

Parameter	Type
`dicomList`	`ImageFromUrlOptions`[]

Returns

Promise<Niivue>

loadDocument()

loadDocument(document: NVDocument): Promise<Niivue>;

Defined in: niivue/index.ts:5055

Loads an NVDocument

Parameters

Parameter	Type
`document`	`NVDocument`

Returns

Promise<Niivue>

Niivue instance

See

live demo usage

loadDocumentFromUrl()

loadDocumentFromUrl(url: string): Promise<void>;

Defined in: niivue/index.ts:5045

Loads an NVDocument from a URL and integrates it into the scene.

Parameters

Parameter	Type
`url`	`string`

Returns

Promise<void>

loadDrawing()

loadDrawing(drawingBitmap: NVImage): boolean;

Defined in: niivue/index.ts:3709

Loads a drawing overlay and aligns it with the current background image. Converts the input image to match the background's orientation and stores it as a drawable bitmap. Initializes the undo history and prepares the drawing texture.

Parameters

Parameter	Type	Description
`drawingBitmap`	`NVImage`	A `NVImage` object representing the drawing to load. Must match the dimensions of the background image.

Returns

boolean

true if the drawing was successfully loaded and aligned; false if dimensions are incompatible.

loadDrawingFromUrl()

loadDrawingFromUrl(fnm: string, isBinarize: boolean): Promise<boolean>;

Defined in: niivue/index.ts:3832

Open drawing

Parameters

Parameter	Type	Default value	Description
`fnm`	`string`	`undefined`	filename of NIfTI format drawing
`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

loadFont()

loadFont(fontSheetUrl: any, metricsUrl: object): Promise<void>;

Defined in: niivue/index.ts:7323

Load typeface for colorbars, measurements and orientation text.

Parameters

Parameter	Type	Default value	Description
`fontSheetUrl`	`any`	`defaultFontPNG`	URL to a bitmap font sheet image (e.g., a PNG atlas of glyphs)
`metricsUrl`	{ `atlas`: { `distanceRange`: `number`; `height`: `number`; `size`: `number`; `type`: `string`; `width`: `number`; `yOrigin`: `string`; }; `glyphs`: ( \| { `advance`: `number`; `atlasBounds?`: `undefined`; `planeBounds?`: `undefined`; `unicode`: `number`; } \| { `advance`: `number`; `atlasBounds`: { `bottom`: `number`; `left`: `number`; `right`: `number`; `top`: `number`; }; `planeBounds`: { `bottom`: `number`; `left`: `number`; `right`: `number`; `top`: `number`; }; `unicode`: `number`; })[]; `kerning`: `any`[]; `metrics`: { `ascender`: `number`; `descender`: `number`; `emSize`: `number`; `lineHeight`: `number`; `underlineThickness`: `number`; `underlineY`: `number`; }; }	`defaultFontMetrics`	URL to the corresponding font metrics JSON (defines character bounds and spacing)
`metricsUrl.atlas`	{ `distanceRange`: `number`; `height`: `number`; `size`: `number`; `type`: `string`; `width`: `number`; `yOrigin`: `string`; }	`...`	-
`metricsUrl.atlas.distanceRange`	`number`	`2`	-
`metricsUrl.atlas.height`	`number`	`256`	-
`metricsUrl.atlas.size`	`number`	`59.65625`	-
`metricsUrl.atlas.type`	`string`	`"msdf"`	-
`metricsUrl.atlas.width`	`number`	`512`	-
`metricsUrl.atlas.yOrigin`	`string`	`"bottom"`	-
`metricsUrl.glyphs`	( \| { `advance`: `number`; `atlasBounds?`: `undefined`; `planeBounds?`: `undefined`; `unicode`: `number`; } \| { `advance`: `number`; `atlasBounds`: { `bottom`: `number`; `left`: `number`; `right`: `number`; `top`: `number`; }; `planeBounds`: { `bottom`: `number`; `left`: `number`; `right`: `number`; `top`: `number`; }; `unicode`: `number`; })[]	`...`	-
`metricsUrl.kerning`	`any`[]	`[]`	-
`metricsUrl.metrics`	{ `ascender`: `number`; `descender`: `number`; `emSize`: `number`; `lineHeight`: `number`; `underlineThickness`: `number`; `underlineY`: `number`; }	`...`	-
`metricsUrl.metrics.ascender`	`number`	`0.927734375`	-
`metricsUrl.metrics.descender`	`number`	`-0.244140625`	-
`metricsUrl.metrics.emSize`	`number`	`1`	-
`metricsUrl.metrics.lineHeight`	`number`	`1.171875`	-
`metricsUrl.metrics.underlineThickness`	`number`	`0.048828125`	-
`metricsUrl.metrics.underlineY`	`number`	`-0.09765625`	-

Returns

Promise<void>

a Promise that resolves when the font is loaded

Example

niivue.loadFont("./Roboto.png", "./Roboto.json");

See

live demo usage

loadFreeSurferConnectome()

loadFreeSurferConnectome(json: FreeSurferConnectome): Promise<Niivue>;

Defined in: niivue/index.ts:5651

load a connectome specified by json

Parameters

Parameter	Type	Description
`json`	`FreeSurferConnectome`	freesurfer model

Returns

Promise<Niivue>

Niivue instance

See

live demo usage

loadFreeSurferConnectomeFromUrl()

loadFreeSurferConnectomeFromUrl(url: string, headers: object): Promise<Niivue>;

Defined in: niivue/index.ts:5639

Load a FreeSurfer-style connectome from a given URL and initialize it.

Parameters

Parameter	Type	Description
`url`	`string`	the URL of the JSON-formatted connectome file
`headers`	{ }	optional HTTP headers to include in the fetch request (e.g. for authorization)

Returns

Promise<Niivue>

the Niivue instance (for method chaining)

See

live demo usage

loadFromArrayBuffer()

loadFromArrayBuffer(buffer: ArrayBuffer, name: string): Promise<void>;

Defined in: niivue/index.ts:2988

Load an image or mesh from an array buffer

Parameters

Parameter	Type	Description
`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

loadFromFile()

loadFromFile(file: File): Promise<void>;

Defined in: niivue/index.ts:3006

Load a mesh or image volume from a File object

Parameters

Parameter	Type	Description
`file`	`File`	File object selected by the user (e.g. from an HTML input element)

Returns

Promise<void>

a Promise that resolves when the file has been loaded and added to the scene

See

live demo usage

loadFromUrl()

loadFromUrl(fnm: string): Promise<NVImage>;

Defined in: niivue/index.ts:9550

Load a NIfTI image from a URL and convert it to an NVImage object

Parameters

Parameter	Type	Description
`fnm`	`string`	URL of the NIfTI file to load

Returns

Promise<NVImage>

a Promise resolving to an NVImage (not yet added to GPU or scene)

See

live demo usage

loadImages()

loadImages(images: (
  | ImageFromUrlOptions
| LoadFromUrlParams)[]): Promise<Niivue>;

Defined in: niivue/index.ts:5382

Load an array of image or mesh URLs using appropriate handlers

Parameters

Parameter	Type	Description
`images`	( \| `ImageFromUrlOptions` \| `LoadFromUrlParams`)[]	array of image or mesh descriptors (with URL and optional name)

Returns

Promise<Niivue>

a Promise resolving to the current NiiVue instance after loading completes

Remarks

Automatically dispatches each item to either volume or mesh loader based on file extension or registered custom loader

See

live demo usage

loadMatCapTexture()

loadMatCapTexture(bmpUrl: string): Promise<WebGLTexture>;

Defined in: niivue/index.ts:7266

Load matcap for illumination model.

Parameters

Parameter	Type	Description
`bmpUrl`	`string`	name of matcap to load ("Shiny", "Cortex", "Cream")

Returns

Promise<WebGLTexture>

Example

niivue.loadMatCapTexture("Cortex");

See

live demo usage

loadMeshes()

loadMeshes(meshList: LoadFromUrlParams[]): Promise<Niivue>;

Defined in: niivue/index.ts:5600

load an array of meshes

Parameters

Parameter	Type	Description
`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

loadVolumes()

loadVolumes(volumeList: ImageFromUrlOptions[]): Promise<Niivue>;

Defined in: niivue/index.ts:5472

load an array of volume objects

Parameters

Parameter	Type	Description
`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

meshShaderNames()

meshShaderNames(sort: boolean): string[];

Defined in: niivue/index.ts:7507

retrieve all currently loaded meshes

Parameters

Parameter	Type	Default value	Description
`sort`	`boolean`	`true`	sort output alphabetically

Returns

string[]

list of available mesh shader names

Example

niivue.meshShaderNames();

See

live demo usage

moveCrosshairInVox()

moveCrosshairInVox(
   x: number,
   y: number,
   z: number): void;

Defined in: niivue/index.ts:14122

move crosshair a fixed number of voxels (not mm)

Parameters

Parameter	Type	Description
`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

moveVolumeDown()

moveVolumeDown(volume: NVImage): void;

Defined in: niivue/index.ts:4495

Move a volume down one index position in the stack of loaded volumes. This moves it down one layer

Parameters

Parameter	Type	Description
`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)

moveVolumeToBottom()

moveVolumeToBottom(volume: NVImage): void;

Defined in: niivue/index.ts:4472

Move a volume to the bottom of the stack of loaded volumes. The volume will become the background

Parameters

Parameter	Type	Description
`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

moveVolumeToTop()

moveVolumeToTop(volume: NVImage): void;

Defined in: niivue/index.ts:4507

Move a volume to the top position in the stack of loaded volumes. This will be the top layer

Parameters

Parameter	Type	Description
`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

moveVolumeUp()

moveVolumeUp(volume: NVImage): void;

Defined in: niivue/index.ts:4483

Move a volume up one index position in the stack of loaded volumes. This moves it up one layer

Parameters

Parameter	Type	Description
`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)

niftiArray2NVImage()

niftiArray2NVImage(bytes: Uint8Array): Promise<NVImage>;

Defined in: niivue/index.ts:9540

Convert a binary NIfTI file (as a Uint8Array) to an NVImage object

Parameters

Parameter	Type	Description
`bytes`	`Uint8Array`	binary contents of a NIfTI file

Returns

Promise<NVImage>

a Promise resolving to an NVImage object

See

live demo usage

refreshColormaps()

refreshColormaps(): Niivue;

Defined in: niivue/index.ts:9921

Rebuild and upload all colormap textures for volumes and meshes

Returns

Niivue

the current NiiVue instance, or undefined if no colormaps are used

See

live demo usage

refreshDrawing()

refreshDrawing(isForceRedraw: boolean, useClickToSegmentBitmap: boolean): void;

Defined in: niivue/index.ts:6860

copy drawing bitmap from CPU to GPU storage and redraw the screen

Parameters

Parameter	Type	Default value	Description
`isForceRedraw`	`boolean`	`true`	refreshes scene immediately (default true)
`useClickToSegmentBitmap`	`boolean`	`false`	-

Returns

void

Example

niivue.refreshDrawing();

See

live demo usage

removeHaze()

removeHaze(level: number, volIndex: number): void;

Defined in: niivue/index.ts:4009

remove dark voxels in air

Parameters

Parameter	Type	Default value	Description
`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

removeMesh()

removeMesh(mesh: NVMesh): void;

Defined in: niivue/index.ts:4440

Remove a triangulated mesh, connectome or tractogram

Parameters

Parameter	Type	Description
`mesh`	`NVMesh`	mesh to delete

Returns

void

Example

niivue = new Niivue();
niivue.removeMesh(this.meshes[3]);

See

live demo usage

removeMeshByUrl()

removeMeshByUrl(url: string): void;

Defined in: niivue/index.ts:4456

Remove a triangulated mesh, connectome or tractogram

Parameters

Parameter	Type	Description
`url`	`string`	URL of mesh to delete

Returns

void

Example

niivue.removeMeshByUrl("../images/cit168.mz3");

removeVolume()

removeVolume(volume: NVImage): void;

Defined in: niivue/index.ts:4405

Remove a volume

Parameters

Parameter	Type	Description
`volume`	`NVImage`	volume to delete

Returns

void

Example

niivue = new Niivue();
niivue.removeVolume(this.volumes[3]);

See

live demo usage

removeVolumeByIndex()

removeVolumeByIndex(index: number): void;

Defined in: niivue/index.ts:4425

Remove a volume from the scene by its index

Parameters

Parameter	Type	Description
`index`	`number`	index of the volume to remove

Returns

void

Throws

if the index is out of bounds

See

live demo usage

removeVolumeByUrl()

removeVolumeByUrl(url: string): void;

Defined in: niivue/index.ts:2883

Remove volume by url

Parameters

Parameter	Type	Description
`url`	`string`	Volume added by url to remove

Returns

void

See

live demo usage

reverseFaces()

reverseFaces(mesh: number): void;

Defined in: niivue/index.ts:4252

reverse triangle winding of mesh (swap front and back faces)

Parameters

Parameter	Type	Description
`mesh`	`number`	identity of mesh to change

Returns

void

Example

niivue.reverseFaces(niivue.meshes[0].id);

See

live demo usage

saveDocument()

saveDocument(
   fileName: string,
   compress: boolean,
options: object): Promise<void>;

Defined in: niivue/index.ts:5352

Save the current scene as an .nvd document.

Parameters

Parameter	Type	Default value	Description
`fileName`	`string`	`'untitled.nvd'`	Name of the file to create (default "untitled.nvd")
`compress`	`boolean`	`true`	If true, gzip-compress the JSON (default true)
`options`	{ `embedImages?`: `boolean`; `embedPreview?`: `boolean`; }	`{}`	Fine-grained switches: • embedImages – store encodedImageBlobs (default true) • embedPreview – store previewImageDataURL (default true)
`options.embedImages?`	`boolean`	`undefined`	-
`options.embedPreview?`	`boolean`	`undefined`	-

Returns

Promise<void>

Example

// smallest possible file – no preview, just metadata
await nv.saveDocument("scene.nvd", true, {
  embedImages: false,
  embedPreview: false,
});

See

live demo usage

saveHTML()

saveHTML(
   fileName: string,
   canvasId: string,
esm: string): Promise<void>;

Defined in: niivue/index.ts:5317

Save the current scene as a standalone HTML file

Parameters

Parameter	Type	Default value	Description
`fileName`	`string`	`'untitled.html'`	name of the HTML file to save (default: "untitled.html")
`canvasId`	`string`	`'gl1'`	ID of the canvas element NiiVue will attach to
`esm`	`string`	`undefined`	bundled ES module source for NiiVue

Returns

Promise<void>

a Promise that resolves when the file is downloaded

See

live demo usage

saveImage()

saveImage(options: SaveImageOptions): Promise<boolean | Uint8Array>;

Defined in: niivue/index.ts:4060

Save voxel-based image to disk.

Parameters

Parameter	Type	Default value	Description
`options`	`SaveImageOptions`	`defaultSaveImageOptions`	configuration object with the following fields: - `filename`: name of the NIfTI image to create - `isSaveDrawing`: whether to save the drawing layer or the background image - `volumeByIndex`: which image layer to save (0 for background)

Returns

Promise<boolean | Uint8Array>

true if successful when writing to disk, or a Uint8Array if exported as binary data

Example

niivue.saveImage({ filename: "myimage.nii.gz", isSaveDrawing: true });
niivue.saveImage({ filename: "myimage.nii.gz", isSaveDrawing: true });

See

live demo usage

saveScene()

saveScene(filename: string): Promise<void>;

Defined in: niivue/index.ts:1010

save webgl2 canvas as png format bitmap

Parameters

Parameter	Type	Default value	Description
`filename`	`string`	`'niivue.png'`	filename for screen capture

Returns

Promise<void>

Example

niivue.saveScene("test.png");

See

live demo usage

setAdditiveBlend()

setAdditiveBlend(isAdditiveBlend: boolean): void;

Defined in: niivue/index.ts:3533

control whether voxel overlays are combined using additive (emission) or traditional (transmission) blending.

Parameters

Parameter	Type	Description
`isAdditiveBlend`	`boolean`	emission (true) or transmission (false) mixing

Returns

void

Example

niivue.isAdditiveBlend(true);

See

live demo usage

setAtlasOutline()

setAtlasOutline(isOutline: number): void;

Defined in: niivue/index.ts:11884

Enable or disable atlas outline overlay

Parameters

Parameter	Type	Description
`isOutline`	`number`	number 0 to 1 for outline opacity

Returns

void

See

live demo usage

setBounds()

setBounds(bounds: [number, number, number, number]): void;

Defined in: niivue/index.ts:4785

Update the drawing bounds for this Niivue instance.

Parameters

Parameter	Type	Description
`bounds`	[`number`, `number`, `number`, `number`]	[x1, y1, x2, y2] in normalized (0–1) coordinates. Example: nv.setBounds([0,0,0.5,0.5]) // top-left quarter nv.setBounds([0.5,0.5,1,1]) // bottom-right quarter

Returns

void

setClipPlane()

setClipPlane(depthAzimuthElevation: number[]): void;

Defined in: niivue/index.ts:4626

Update the clip plane orientation in 3D view mode.

Parameters

Parameter	Type	Description
`depthAzimuthElevation`	`number`[]	a 3-component array: - `depth`: distance of clip plane from center of volume (0 to ~1.73, or >2.0 to disable clipping) - `azimuth`: camera angle around the object in degrees (0–360 or -180–180) - `elevation`: camera height in degrees (-90 to 90)

Returns

void

Example

niivue = new Niivue();
niivue.setClipPlane([42, 42]);

See

live demo usage

setClipPlaneColor()

setClipPlaneColor(color: number[]): void;

Defined in: niivue/index.ts:4900

Set the color of the 3D clip plane.

Parameters

Parameter	Type	Description
`color`	`number`[]	An array of RGBA values. - R, G, B components range from `0.0` to `1.0`. - A (alpha) component ranges from `-1.0` to `1.0`, where: - `0.0–1.0` → controls background translucency. - `-1.0–0.0` → applies translucent shading to the volume instead of the background.

Returns

void

Example

niivue.setClipPlaneColor([1, 1, 1, 0.5]); // white, translucent background
niivue.setClipPlaneColor([1, 1, 1, -0.5]); // white, translucent shading

See

Live demo usage

setClipPlanes()

setClipPlanes(depthAziElevs: number[][]): void;

Defined in: niivue/index.ts:4600

Set multiple clip planes from their depth/azimuth/elevation definitions.

depth: distance of clip plane from center of volume, range 0..~1.73 (e.g. 2.0 for no clip plane) azimuth: camera position in degrees around object, typically 0..360 (or -180..+180) elevation: camera height in degrees, range -90..90

This replaces the entire clipPlanes and clipPlaneDepthAziElevs arrays, ensuring they always have the same length.

Parameters

Parameter	Type	Description
`depthAziElevs`	`number`[][]	array of `[depth, azimuthDeg, elevationDeg]` values

Returns

void

See

live demo usage

setClipPlaneThick()

setClipPlaneThick(_thick: number): void;

Defined in: niivue/index.ts:4912

Parameters

Parameter	Type
`_thick`	`number`

Returns

void

Deprecated

This method has been removed. Use setClipPlanes instead, which generalizes clip plane configuration

See

Multiple clip plane demo

setClipVolume()

setClipVolume(_low: number[], _high: number[]): void;

Defined in: niivue/index.ts:4921

Parameters

Parameter	Type
`_low`	`number`[]
`_high`	`number`[]

Returns

void

Deprecated

This method has been removed. Use setClipPlanes instead, which generalizes clip plane configuration

See

Multiple clip plane demo

setColormap()

setColormap(id: string, colormap: string): void;

Defined in: niivue/index.ts:8954

update the colormap of an image given its ID

Parameters

Parameter	Type	Description
`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

setColorMap()

setColorMap(id: string, colormap: string): void;

Defined in: niivue/index.ts:9728

Parameters

Parameter	Type	Description
`id`	`string`	ID of the volume
`colormap`	`string`	name of the colormap to apply

Returns

void

Deprecated

Use setColormap instead. This alias is retained for compatibility with NiiVue < 0.35.

setColormapNegative()

setColormapNegative(id: string, colormapNegative: string): void;

Defined in: niivue/index.ts:9741

use given color map for negative voxels in image

Parameters

Parameter	Type	Description
`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

setCornerOrientationText()

setCornerOrientationText(isCornerOrientationText: boolean): void;

Defined in: niivue/index.ts:3338

determine if text appears at corner (true) or sides of 2D slice.

Parameters

Parameter	Type	Description
`isCornerOrientationText`	`boolean`	controls position of text

Returns

void

Example

niivue.setCornerOrientationText(true);

See

live demo usage

setCrosshairColor()

setCrosshairColor(color: number[]): void;

Defined in: niivue/index.ts:4670

set the crosshair and colorbar outline color

Parameters

Parameter	Type	Description
`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

setCrosshairWidth()

setCrosshairWidth(crosshairWidth: number): void;

Defined in: niivue/index.ts:4680

set thickness of crosshair

Parameters

Parameter	Type
`crosshairWidth`	`number`

Returns

void

Example

niivue.crosshairWidth(2);

See

live demo usage

setCustomGradientTexture()

setCustomGradientTexture(data: Float32Array | Uint8Array, dims?: number[]): void;

Defined in: niivue/index.ts:7916

Set a custom gradient texture to use instead of the one produced by gradientGL When a custom gradient texture is set, the useCustomGradientTexture flag is set to true to prevent gradientGL from overwriting the custom texture during volume updates.

Parameters

Parameter	Type	Description
`data`	`Float32Array` \| `Uint8Array`	Float32Array or Uint8Array containing RGBA gradient data, or null to revert to auto-generated gradient
`dims?`	`number`[]	Optional dimensions array [width, height, depth]. If not provided, uses current volume dimensions

Returns

void

Example

niivue = new Niivue();
niivue.loadVolumes([{ url: "./someImage.nii" }]);
// Create custom gradient data
const customGradient = new Float32Array(256 * 256 * 256 * 4); // example dimensions
// ... fill customGradient with desired values
niivue.setCustomGradientTexture(customGradient, [256, 256, 256]);

// To revert to auto-generated gradient:
niivue.setCustomGradientTexture(null);

See

live demo usage

setCustomLayout()

setCustomLayout(layout: object[]): void;

Defined in: niivue/index.ts:3401

Set a custom slice layout. This overrides the built-in layouts.

Parameters

Parameter	Type	Description
`layout`	`object`[]	Array of layout specifications for each slice view

Returns

void

Example

niivue.setCustomLayout([
    // Left 50% - Sag
    {sliceType: 2, position: [0, 0, 0.5, 1.0]},
    // Top right - Cor
    {sliceType: 1, position: [0.5, 0, 0.5, 0.5]},
    // Bottom right - Ax
    {sliceType: 0, position: [0.5, 0.5, 0.5, 0.5]}
  ])

produces:
+----------------+----------------+
|                |                |
|                |     coronal    |
|                |                |
|                |                |
|   sagittal     +----------------+
|                |                |
|                |     axial      |
|                |                |
|                |                |
+----------------+----------------+

setCustomMeshShader()

setCustomMeshShader(fragmentShaderText: string, name: string): number;

Defined in: niivue/index.ts:7492

Define a new GLSL shader program to influence mesh coloration

Parameters

Parameter	Type	Default value	Description
`fragmentShaderText`	`string`	`''`	the GLSL source code for the custom fragment shader
`name`	`string`	`'Custom'`	a descriptive label for the shader (used in menus or debugging)

Returns

number

the index of the new shader (use with setMeshShader)

See

live demo usage

setDefaults()

setDefaults(options: Partial<NVConfigOptions>, resetBriCon: boolean): void;

Defined in: niivue/index.ts:3471

Reset scene to default settings.

Parameters

Parameter	Type	Default value	Description
`options`	`Partial`<`NVConfigOptions`>	`{}`
`resetBriCon`	`boolean`	`false`	also reset contrast (default false).

Returns

void

See

NiiVueOptions
live demo usage

Example

niivue.nv1.setDefaults(opts, true);

setDragMode()

setDragMode(mode: string | DRAG_MODE): void;

Defined in: niivue/index.ts:11048

Set the drag mode for mouse interactions.

Parameters

Parameter	Type	Description
`mode`	`string` \| `DRAG_MODE`	The drag mode to set ('none', 'contrast', 'measurement', 'angle', 'pan', 'slicer3D', 'callbackOnly', 'roiSelection')

Returns

void

setDrawColormap()

setDrawColormap(name: string): void;

Defined in: niivue/index.ts:4702

Parameters

Parameter	Type
`name`	`string`

Returns

void

setDrawingEnabled()

setDrawingEnabled(trueOrFalse: boolean): void;

Defined in: niivue/index.ts:4713

does dragging over a 2D slice create a drawing?

Parameters

Parameter	Type	Description
`trueOrFalse`	`boolean`	enabled (true) or not (false)

Returns

void

Example

niivue.setDrawingEnabled(true);

See

live demo usage

setDrawOpacity()

setDrawOpacity(opacity: number): void;

Defined in: niivue/index.ts:4759

control whether drawing is transparent (0), opaque (1) or translucent (between 0 and 1).

Parameters

Parameter	Type	Description
`opacity`	`number`	translucency of drawing

Returns

void

Example

niivue.setDrawOpacity(0.7);

See

live demo usage

setFrame4D()

setFrame4D(id: string, frame4D: number): void;

Defined in: niivue/index.ts:9819

show desired 3D volume from 4D time series

Parameters

Parameter	Type	Description
`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

setGamma()

setGamma(gamma: number): void;

Defined in: niivue/index.ts:9778

adjust screen gamma. Low values emphasize shadows but can appear flat, high gamma hides shadow details.

Parameters

Parameter	Type	Default value	Description
`gamma`	`number`	`1.0`	selects luminance, default is 1

Returns

void

Example

niivue.setGamma(1.0);

See

live demo usage

setGradientOpacity()

setGradientOpacity(gradientOpacity: number, renderSilhouette: number): Promise<void>;

Defined in: niivue/index.ts:4969

set volume rendering opacity influence of the gradient magnitude

Parameters

Parameter	Type	Default value	Description
`gradientOpacity`	`number`	`0.0`	amount of gradient magnitude influence on opacity (0..1), default 0 (no-influence)
`renderSilhouette`	`number`	`0.0`	make core transparent to enhance rims (0..1), default 0 (no-influence)

Returns

Promise<void>

Example

niivue.setGradientOpacity(0.6);

See

live demo usage

setHeroImage()

setHeroImage(fraction: number): void;

Defined in: niivue/index.ts:3370

determine proportion of screen real estate devoted to rendering in multiplanar view.

Parameters

Parameter	Type	Description
`fraction`	`number`	proportion of screen devoted to primary (hero) image (0 to disable)

Returns

void

Example

niivue.setHeroImage(0.5);

See

live demo usage

setHighResolutionCapable()

setHighResolutionCapable(forceDevicePixelRatio: number | boolean): void;

Defined in: niivue/index.ts:3553

Force WebGL canvas to use high resolution display, regardless of browser defaults.

Parameters

Parameter	Type	Description
`forceDevicePixelRatio`	`number` \| `boolean`	1: block high DPI; 0= allow high DPI: >0 use specified pixel ratio

Returns

void

Example

niivue.setHighResolutionCapable(true);

See

live demo usage

setInterpolation()

setInterpolation(isNearest: boolean): void;

Defined in: niivue/index.ts:11896

select between nearest and linear interpolation for voxel based images

Parameters

Parameter	Type	Description
`isNearest`	`boolean`	whether nearest neighbor interpolation is used, else linear interpolation

Returns

void

Example

niivue.setInterpolation(true);

See

live demo usage

setIsOrientationTextVisible()

setIsOrientationTextVisible(isOrientationTextVisible: boolean): void;

Defined in: niivue/index.ts:3349

Show or hide orientation labels (e.g., L/R, A/P) in 2D slice views

Parameters

Parameter	Type	Description
`isOrientationTextVisible`	`boolean`	whether orientation text should be displayed

Returns

void

Example

niivue.setIsOrientationTextVisible(false);

See

live demo usage

setMesh()

setMesh(mesh: NVMesh, toIndex: number): void;

Defined in: niivue/index.ts:4373

Reorders a mesh within the internal mesh list.

Parameters

Parameter	Type	Default value	Description
`mesh`	`NVMesh`	`undefined`	The `NVMesh` instance to reposition.
`toIndex`	`number`	`0`	Target index to move the mesh to. - If `0`, moves mesh to the front. - If `< 0`, removes the mesh. - If within bounds, inserts mesh at the specified index.

Returns

void

setMeshLayerProperty()

setMeshLayerProperty(
   mesh: string | number,
   layer: number,
   key: keyof NVMeshLayer,
val: number): Promise<void>;

Defined in: niivue/index.ts:4271

reverse triangle winding of mesh (swap front and back faces)

Parameters

Parameter	Type	Description
`mesh`	`string` \| `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`	value for attribute

Returns

Promise<void>

Example

niivue.setMeshLayerProperty(niivue.meshes[0].id, 0, "frame4D", 22);

See

live demo usage

setMeshProperty()

setMeshProperty(
   id: number,
   key: keyof NVMesh,
   val:
  | string
  | number
  | boolean
  | number[]
  | ColorMap
  | Float32Array
  | Uint8Array
  | LegacyConnectome): void;

Defined in: niivue/index.ts:4193

change property of mesh, tractogram or connectome

Parameters

Parameter	Type	Description
`id`	`number`	identity of mesh to change
`key`	keyof `NVMesh`	attribute to change
`val`	\| `string` \| `number` \| `boolean` \| `number`[] \| `ColorMap` \| `Float32Array` \| `Uint8Array` \| `LegacyConnectome`	for attribute

Returns

void

Example

niivue.setMeshProperty(niivue.meshes[0].id, "fiberLength", 42);

See

live demo usage

setMeshShader()

setMeshShader(id: string | number, meshShaderNameOrNumber: string | number): void;

Defined in: niivue/index.ts:7394

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

Parameter	Type	Default value	Description
`id`	`string` \| `number`	`undefined`	id of mesh to change
`meshShaderNameOrNumber`	`string` \| `number`	`2`	identify shader for usage

Returns

void

Example

niivue.setMeshShader("toon");

See

live demo usage

setMeshThicknessOn2D()

setMeshThicknessOn2D(meshThicknessOn2D: number): void;

Defined in: niivue/index.ts:3500

Limit visibility of mesh in front of a 2D image. Requires world-space mode.

Parameters

Parameter	Type	Description
`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

setModulationImage()

setModulationImage(
   idTarget: string,
   idModulation: string,
   modulateAlpha: number): void;

Defined in: niivue/index.ts:9756

modulate intensity of one image based on intensity of another

Parameters

Parameter	Type	Default value	Description
`idTarget`	`string`	`undefined`	the ID of the NVImage to be biased
`idModulation`	`string`	`undefined`	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

setMouseEventConfig()

setMouseEventConfig(config: MouseEventConfig): void;

Defined in: niivue/index.ts:11108

Set custom mouse event configuration for button mappings.

Parameters

Parameter	Type	Description
`config`	`MouseEventConfig`	Mouse event configuration object

Returns

void

Example

nv.setMouseEventConfig({
  leftButton: {
    primary: DRAG_MODE.windowing,
    withShift: DRAG_MODE.measurement,
    withCtrl: DRAG_MODE.crosshair,
  },
  rightButton: DRAG_MODE.crosshair,
  centerButton: DRAG_MODE.pan,
});

setMultiplanarLayout()

setMultiplanarLayout(layout: number): void;

Defined in: niivue/index.ts:3324

control placement of 2D slices.

Parameters

Parameter	Type	Description
`layout`	`number`	AUTO: 0, COLUMN: 1, GRID: 2, ROW: 3,

Returns

void

Example

niivue.setMultiplanarLayout(2);

See

live demo usage

setMultiplanarPadPixels()

setMultiplanarPadPixels(pixels: number): void;

Defined in: niivue/index.ts:3313

insert a gap between slices of a mutliplanar view.

Parameters

Parameter	Type	Description
`pixels`	`number`	spacing between tiles of multiplanar view

Returns

void

Example

niivue.setMultiplanarPadPixels(4);

See

live demo usage

setOpacity()

setOpacity(volIdx: number, newOpacity: number): void;

Defined in: niivue/index.ts:4870

set the opacity of a volume given by volume index

Parameters

Parameter	Type	Description
`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

setPan2Dxyzmm()

setPan2Dxyzmm(xyzmmZoom: vec4): void;

Defined in: niivue/index.ts:4286

adjust offset position and scale of 2D sliceScale

Parameters

Parameter	Type	Description
`xyzmmZoom`	`vec4`	first three components are spatial, fourth is scaling

Returns

void

Example

niivue.setPan2Dxyzmm([5, -4, 2, 1.5]);

setPenValue()

setPenValue(penValue: number, isFilledPen: boolean): void;

Defined in: niivue/index.ts:4747

determine color and style of drawing

Parameters

Parameter	Type	Default value	Description
`penValue`	`number`	`undefined`	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

setRadiologicalConvention()

setRadiologicalConvention(isRadiologicalConvention: boolean): void;

Defined in: niivue/index.ts:3459

control whether 2D slices use radiological or neurological convention.

Parameters

Parameter	Type	Description
`isRadiologicalConvention`	`boolean`	new display convention

Returns

void

Example

niivue.setRadiologicalConvention(true);

See

live demo usage

setRenderAzimuthElevation()

setRenderAzimuthElevation(a: number, e: number): void;

Defined in: niivue/index.ts:4299

set rotation of 3D render view

Parameters

Parameter	Type
`a`	`number`
`e`	`number`

Returns

void

Example

niivue.setRenderAzimuthElevation(45, 15);

See

live demo usage

setRenderDrawAmbientOcclusion()

setRenderDrawAmbientOcclusion(ao: number): void;

Defined in: niivue/index.ts:9712

darken crevices and brighten corners when 3D rendering drawings.

Parameters

Parameter	Type	Description
`ao`	`number`	amount of ambient occlusion (default 0.4)

Returns

void

See

live demo usage

setScale()

setScale(scale: number): void;

Defined in: niivue/index.ts:4882

set the scale of the 3D rendering. Larger numbers effectively zoom.

Parameters

Parameter	Type	Description
`scale`	`number`	the new scale value

Returns

void

Example

niivue.setScale(2); // zoom some

See

live demo usage

setSelectionBoxColor()

setSelectionBoxColor(color: number[]): void;

Defined in: niivue/index.ts:4772

set the selection box color. A selection box is drawn when you right click and drag to change image contrast

Parameters

Parameter	Type	Description
`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

setShowAllOrientationMarkers()

setShowAllOrientationMarkers(showAllOrientationMarkers: boolean): void;

Defined in: niivue/index.ts:3359

Show or hide all four orientation labels (e.g., L/R, A/P, S/I) in 2D slice views

Parameters

Parameter	Type	Description
`showAllOrientationMarkers`	`boolean`	whether all four orientation markers should be displayed

Returns

void

Example

niivue.setShowAllOrientationMarkers(true);

setSliceMM()

setSliceMM(isSliceMM: boolean): void;

Defined in: niivue/index.ts:3522

control 2D slice view mode.

Parameters

Parameter	Type	Description
`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

setSliceMosaicString()

setSliceMosaicString(str: string): void;

Defined in: niivue/index.ts:3511

Create a custom multi-slice mosaic (aka lightbox, montage) view.

Parameters

Parameter	Type	Description
`str`	`string`	description of mosaic.

Returns

void

Example

niivue.setSliceMosaicString("A 0 20 C 30 S 42");

See

live demo usage

setSliceType()

setSliceType(st: SLICE_TYPE): this;

Defined in: niivue/index.ts:4855

set the slice type. This changes the view mode

Parameters

Parameter	Type	Description
`st`	`SLICE_TYPE`	sliceType is an enum of slice types to use

Returns

this

Example

niivue = new Niivue();
niivue.setSliceType(Niivue.sliceTypeMultiplanar);

See

live demo usage

setTouchEventConfig()

setTouchEventConfig(config: TouchEventConfig): void;

Defined in: niivue/index.ts:11125

Set custom touch event configuration for touch gesture mappings.

Parameters

Parameter	Type	Description
`config`	`TouchEventConfig`	Touch event configuration object

Returns

void

Example

nv.setTouchEventConfig({
  singleTouch: DRAG_MODE.windowing,
  doubleTouch: DRAG_MODE.pan,
});

setVolume()

setVolume(volume: NVImage, toIndex: number): void;

Defined in: niivue/index.ts:4333

set the index of a volume. This will change it's ordering and appearance if there are multiple volumes loaded.

Parameters

Parameter	Type	Default value	Description
`volume`	`NVImage`	`undefined`	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)

setVolumeRenderIllumination()

setVolumeRenderIllumination(gradientAmount: number): Promise<void>;

Defined in: niivue/index.ts:4933

set proportion of volume rendering influenced by selected matcap.

Parameters

Parameter	Type	Default value	Description
`gradientAmount`	`number`	`0.0`	amount of matcap (NaN or 0..1), default 0 (matte, surface normal does not influence color). NaN renders the gradients.

Returns

Promise<void>

Example

niivue.setVolumeRenderIllumination(0.6);

See

syncWith()

syncWith(otherNV: Niivue | Niivue[], syncOpts: object): void;

Defined in: niivue/index.ts:1135

Sync the scene controls (orientation, crosshair location, etc.) from one Niivue instance to another. useful for using one canvas to drive another.

Parameters

Parameter	Type	Description
`otherNV`	`Niivue` \| `Niivue`[]	the other Niivue instance that is the main controller
`syncOpts`	{ `2d`: `boolean`; `3d`: `boolean`; }	-
`syncOpts.2d`	`boolean`	-
`syncOpts.3d`	`boolean`	-

Returns

void

Example

niivue1 = new Niivue();
niivue2 = new Niivue();
niivue2.syncWith(niivue1);

Deprecated

use broadcastTo instead

See

live demo usage

unwatchOptsChanges()

unwatchOptsChanges(): void;

Defined in: niivue/index.ts:3588

Stop watching for changes to configuration options. This removes the current onOptsChange callback.

Returns

void

Example

niivue.unwatchOptsChanges();

See

live demo usage

updateGLVolume()

updateGLVolume(): void;

Defined in: niivue/index.ts:7993

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

useDicomLoader()

useDicomLoader(loader: DicomLoader): void;

Defined in: niivue/index.ts:3063

Set a custom loader for handling DICOM files.

Parameters

Parameter	Type
`loader`	`DicomLoader`

Returns

void

useLoader()

useLoader(
   loader: unknown,
   fileExt: string,
   toExt: string): void;

Defined in: niivue/index.ts:3050

Registers a custom external file loader for handling specific file types in Niivue.

This method allows you to define how certain file extensions are handled when loaded into Niivue. The provided loader function should return an object containing an ArrayBuffer of the file's contents and the file extension (used for inferring how Niivue should process the data).

Optionally, positions and indices can be returned to support loading mesh data (e.g. .mz3 format).

Parameters

Parameter	Type	Description
`loader`	`unknown`	A function that accepts a `File` or `ArrayBuffer` and returns an object with `arrayBuffer` and `fileExt` properties. May also return `positions` and `indices` for meshes.
`fileExt`	`string`	The original file extension (e.g. 'iwi.cbor') to associate with this loader.
`toExt`	`string`	The target file extension Niivue should treat the file as (e.g. 'nii' or 'mz3').

Returns

void

Example

const myCustomLoader = async (file) => {
  const arrayBuffer = await file.arrayBuffer()
  return {
    arrayBuffer,
    fileExt: 'iwi.cbor',
    positions: new Float32Array(...),
    indices: new Uint32Array(...)
  }
}

nv.useLoader(myCustomLoader, 'iwi.cbor', 'nii')

watchOptsChanges()

watchOptsChanges(callback: (propertyName: keyof NVConfigOptions, newValue:
  | string
  | number
  | boolean
  | number[]
  | Float32Array
  | MouseEventConfig
  | TouchEventConfig
  | number[]
  | [[number, number], [number, number]], oldValue:
  | string
  | number
  | boolean
  | number[]
  | Float32Array
  | MouseEventConfig
  | TouchEventConfig
  | number[]
  | [[number, number], [number, number]]) => void): void;

Defined in: niivue/index.ts:3572

Start watching for changes to configuration options. This is a convenience method that sets up the onOptsChange callback.

Parameters

Parameter	Type	Description
`callback`	(`propertyName`: keyof `NVConfigOptions`, `newValue`: \| `string` \| `number` \| `boolean` \| `number`[] \| `Float32Array` \| `MouseEventConfig` \| `TouchEventConfig` \| `number`[] \| [[`number`, `number`], [`number`, `number`]], `oldValue`: \| `string` \| `number` \| `boolean` \| `number`[] \| `Float32Array` \| `MouseEventConfig` \| `TouchEventConfig` \| `number`[] \| [[`number`, `number`], [`number`, `number`]]) => `void`	Function to call when any option changes

Returns

void

Example

niivue.watchOptsChanges((propertyName, newValue, oldValue) => {
  console.log(`Option ${propertyName} changed from ${oldValue} to ${newValue}`);
});

See

live demo usage

Example​

Constructors​

Constructor​

Parameters​

Returns​

Properties​

Accessors​

drawBitmap​

Get Signature​

Returns​

Set Signature​

Parameters​

Returns​

isAlphaClipDark​

Get Signature​

Returns​

Set Signature​

See​

Parameters​

Returns​

meshes​

Get Signature​

Returns​

Set Signature​

Parameters​

Returns​

opts​

Get Signature​

Returns​

scene​

Get Signature​

Returns​

sliceMosaicString​

Get Signature​

Returns​

Set Signature​

Parameters​

Returns​

volScaleMultiplier​

Get Signature​

Returns​

Set Signature​

Parameters​

Returns​

volumes​

Get Signature​

Returns​

Set Signature​

Parameters​

Returns​

Methods​

addColormap()​

Parameters​

Returns​

See​

addLabel()​

Parameters​

Returns​

See​

addMesh()​

Parameters​

Returns​

Example​

See​

addMeshesFromUrl()​

Parameters​

Returns​

addMeshFromUrl()​

Parameters​

Returns​

addVolume()​

Parameters​

Returns​

Example​

See​

addVolumeFromUrl()​

Parameters​

Returns​

See​

addVolumesFromUrl()​

Example

Constructors

Constructor

Parameters

Returns

Properties

Accessors

drawBitmap

Get Signature

Returns

Set Signature

Parameters

Returns

isAlphaClipDark

Get Signature

Returns

Set Signature

See

Parameters

Returns

meshes

Get Signature

Returns

Set Signature

Parameters

Returns

opts

Get Signature

Returns

scene

Get Signature

Returns

sliceMosaicString

Get Signature

Returns

Set Signature

Parameters

Returns

volScaleMultiplier

Get Signature

Returns

Set Signature

Parameters

Returns

volumes

Get Signature

Returns

Set Signature

Parameters

Returns

Methods

addColormap()

Parameters

Returns

See

addLabel()

Parameters

Returns

See

addMesh()

Parameters

Returns

Example

See

addMeshesFromUrl()

Parameters

Returns

addMeshFromUrl()

Parameters

Returns

addVolume()

Parameters

Returns

Example

See

addVolumeFromUrl()

Parameters

Returns

See

addVolumesFromUrl()