Class: Niivue

Defined in: niivue/index.ts:140

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:607

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:153
`back`	`NVImage`	`null`	-	niivue/index.ts:293
`backgroundMasksOverlays`	`number`	`0`	-	niivue/index.ts:232
`blurShader`	`Shader`	`null`	-	niivue/index.ts:219
`bmpShader`	`Shader`	`null`	-	niivue/index.ts:206
`bmpTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:207
`bmpTextureWH`	`number`	`1.0`	-	niivue/index.ts:209
`canvas`	`HTMLCanvasElement`	`null`	-	niivue/index.ts:152
`circleShader?`	`Shader`	`undefined`	-	niivue/index.ts:204
`clickToSegmentGrowingBitmap`	`Uint8Array`	`null`	-	niivue/index.ts:170
`clickToSegmentIsGrowing`	`boolean`	`false`	-	niivue/index.ts:169
`clickToSegmentXY`	`number`[]	`undefined`	-	niivue/index.ts:171
`CLIP_PLANE_ID`	`number`	`1`	-	niivue/index.ts:322
`colorbarHeight`	`number`	`0`	-	niivue/index.ts:173
`colorbarShader?`	`Shader`	`undefined`	-	niivue/index.ts:199
`colormapLists`	`ColormapListEntry`[]	`[]`	-	niivue/index.ts:157
`colormapTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:156
`crosshairs3D`	`NiivueObject3D`	`null`	-	niivue/index.ts:225
`cuboidVertexBuffer?`	`WebGLBuffer`	`undefined`	-	niivue/index.ts:311
`currentClipPlaneIndex`	`number`	`0`	-	niivue/index.ts:318
`currentDrawUndoBitmap`	`number`	`undefined`	-	niivue/index.ts:602
`customLayout`	`object`[]	`[]`	-	niivue/index.ts:334
`customSliceShader`	`Shader`	`null`	-	niivue/index.ts:200
`deferredMeshes`	`LoadFromUrlParams`[]	`[]`	-	niivue/index.ts:296
`deferredVolumes`	`ImageFromUrlOptions`[]	`[]`	-	niivue/index.ts:295
`dicomLoader`	`DicomLoader`	`null`	-	niivue/index.ts:143
`DISTANCE_FROM_CAMERA`	`number`	`-0.54`	-	niivue/index.ts:324
`document`	`NVDocument`	`undefined`	-	niivue/index.ts:561
`dragModes`	`object`	`undefined`	-	niivue/index.ts:343
`dragModes.angle`	`DRAG_MODE`	`DRAG_MODE.angle`	-	niivue/index.ts:346
`dragModes.callbackOnly`	`DRAG_MODE`	`DRAG_MODE.callbackOnly`	-	niivue/index.ts:350
`dragModes.contrast`	`DRAG_MODE`	`DRAG_MODE.contrast`	-	niivue/index.ts:344
`dragModes.measurement`	`DRAG_MODE`	`DRAG_MODE.measurement`	-	niivue/index.ts:345
`dragModes.none`	`DRAG_MODE`	`DRAG_MODE.none`	-	niivue/index.ts:347
`dragModes.pan`	`DRAG_MODE`	`DRAG_MODE.pan`	-	niivue/index.ts:348
`dragModes.slicer3D`	`DRAG_MODE`	`DRAG_MODE.slicer3D`	-	niivue/index.ts:349
`drawFillOverwrites`	`boolean`	`true`	-	niivue/index.ts:176
`drawLut`	`LUT`	`undefined`	-	niivue/index.ts:166
`drawOpacity`	`number`	`0.8`	-	niivue/index.ts:167
`drawPenAxCorSag`	`number`	`-1`	-	niivue/index.ts:175
`drawPenFillPts`	`number`[][]	`[]`	-	niivue/index.ts:177
`drawPenLocation`	`number`[]	`undefined`	-	niivue/index.ts:174
`drawRimOpacity`	`number`	`-1.0`	-	niivue/index.ts:168
`drawShapePreviewBitmap`	`Uint8Array`	`null`	-	niivue/index.ts:179
`drawShapeStartLocation`	`number`[]	`undefined`	-	niivue/index.ts:178
`drawTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:163
`drawUndoBitmaps`	`Uint8Array`[]	`[]`	-	niivue/index.ts:165
`extentsMax?`	`vec3`	`undefined`	-	niivue/index.ts:237
`extentsMin?`	`vec3`	`undefined`	-	niivue/index.ts:236
`fiberShader?`	`Shader`	`undefined`	-	niivue/index.ts:202
`fontShader`	`Shader`	`null`	-	niivue/index.ts:201
`fontTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:203
`furthestFromPivot`	`number`	`10.0`	-	niivue/index.ts:316
`furthestVertexFromOrigin`	`number`	`100`	-	niivue/index.ts:297
`genericVAO`	`WebGLVertexArrayObject`	`null`	-	niivue/index.ts:223
`gradientTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:159
`gradientTextureAmount`	`number`	`0.0`	-	niivue/index.ts:160
`graph`	`Graph`	`undefined`	-	niivue/index.ts:325
`growCutShader?`	`Shader`	`undefined`	-	niivue/index.ts:210
`initialized`	`boolean`	`false`	-	niivue/index.ts:601
`isBusy`	`boolean`	`false`	-	niivue/index.ts:154
`lastCalled`	`number`	`undefined`	-	niivue/index.ts:319
`line3DShader?`	`Shader`	`undefined`	-	niivue/index.ts:191
`lineShader?`	`Shader`	`undefined`	-	niivue/index.ts:190
`loaders`	`LoaderRegistry`	`{}`	-	niivue/index.ts:141
`matCapTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:205
`mediaUrlMap`	`Map`< \| `NVMesh` \| `NVImage`, `string`>	`undefined`	-	niivue/index.ts:600
`meshShaders`	`object`[]	`undefined`	-	niivue/index.ts:340
`mousePos`	`number`[]	`undefined`	-	niivue/index.ts:300
`needsRefresh`	`boolean`	`false`	-	niivue/index.ts:155
`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:528
`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:409
`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:537
`onColormapChange`	() => `void`	`undefined`	-	niivue/index.ts:452
`onCustomMeshShaderAdded`	(`fragmentShaderText`: `string`, `name`: `string`) => `void`	`undefined`	-	niivue/index.ts:538
`onDebug`	() => `void`	`undefined`	callback function to run when niivue reports a debug message Example `niivue.onDebug = (debug) => { console.log('debug: ', debug) }`	niivue/index.ts:479
`onDicomLoaderFinishedWithImages`	(`files`: \| `NVImage`[] \| `NVMesh`[]) => `void`	`undefined`	-	niivue/index.ts:542
`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:551
`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:368
`onError`	() => `void`	`undefined`	callback function to run when niivue reports an error Example `niivue.onError = (error) => { console.log('error: ', error) }`	niivue/index.ts:449
`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:440
`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:419
`onInfo`	() => `void`	`undefined`	callback function to run when niivue reports detailed info Example `niivue.onInfo = (info) => { console.log('info: ', info) }`	niivue/index.ts:461
`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:398
`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:389
`onMeshAdded`	() => `void`	`undefined`	-	niivue/index.ts:514
`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:511
`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:429
`onMeshPropertyChanged`	(`meshIndex`: `number`, `key`: `string`, `val`: `unknown`) => `void`	`undefined`	-	niivue/index.ts:540
`onMeshShaderChanged`	(`meshIndex`: `number`, `shaderIndex`: `number`) => `void`	`undefined`	-	niivue/index.ts:539
`onMeshWithUrlRemoved`	(`url`: `string`) => `void`	`undefined`	-	niivue/index.ts:515
`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:377
`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:559
`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:490
`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:500
`onVolumeWithUrlRemoved`	(`url`: `string`) => `void`	`undefined`	-	niivue/index.ts:491
`onWarn`	() => `void`	`undefined`	callback function to run when niivue reports a warning Example `niivue.onWarn = (warn) => { console.log('warn: ', warn) }`	niivue/index.ts:470
`onZoom3DChange`	(`zoom`: `number`) => `void`	`undefined`	-	niivue/index.ts:518
`orientCubeShader?`	`Shader`	`undefined`	-	niivue/index.ts:185
`orientCubeShaderVAO`	`WebGLVertexArrayObject`	`null`	-	niivue/index.ts:186
`orientShaderAtlasI`	`Shader`	`null`	-	niivue/index.ts:212
`orientShaderAtlasU`	`Shader`	`null`	-	niivue/index.ts:211
`orientShaderF`	`Shader`	`null`	-	niivue/index.ts:215
`orientShaderI`	`Shader`	`null`	-	niivue/index.ts:214
`orientShaderPAQD`	`Shader`	`null`	-	niivue/index.ts:217
`orientShaderRGBU`	`Shader`	`null`	-	niivue/index.ts:216
`orientShaderU`	`Shader`	`null`	-	niivue/index.ts:213
`otherNV`	`Niivue`[]	`null`	-	niivue/index.ts:313
`overlayAlphaShader`	`number`	`1`	-	niivue/index.ts:234
`overlayOutlineWidth`	`number`	`0`	-	niivue/index.ts:233
`overlays`	`NVImage`[]	`[]`	-	niivue/index.ts:294
`overlayTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:180
`overlayTextureID`	`WebGLTexture`	`null`	-	niivue/index.ts:181
`paqdTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:164
`passThroughShader?`	`Shader`	`undefined`	-	niivue/index.ts:192
`pickingImageShader?`	`Shader`	`undefined`	-	niivue/index.ts:198
`pickingMeshShader?`	`Shader`	`undefined`	-	niivue/index.ts:197
`pivot3D`	`number`[]	`undefined`	-	niivue/index.ts:315
`position?`	`vec3`	`undefined`	-	niivue/index.ts:235
`readyForSync`	`boolean`	`false`	-	niivue/index.ts:255
`rectOutlineShader?`	`Shader`	`undefined`	-	niivue/index.ts:188
`rectShader?`	`Shader`	`undefined`	-	niivue/index.ts:187
`renderDrawAmbientOcclusion`	`number`	`0.4`	-	niivue/index.ts:172
`renderGradientShader?`	`Shader`	`undefined`	-	niivue/index.ts:193
`renderGradientValues`	`boolean`	`false`	-	niivue/index.ts:162
`renderGradientValuesShader?`	`Shader`	`undefined`	-	niivue/index.ts:194
`renderShader?`	`Shader`	`undefined`	-	niivue/index.ts:189
`renderSliceShader?`	`Shader`	`undefined`	-	niivue/index.ts:195
`renderVolumeShader?`	`Shader`	`undefined`	-	niivue/index.ts:196
`screenSlices`	`object`[]	`[]`	-	niivue/index.ts:301
`selectedObjectId`	`number`	`-1`	-	niivue/index.ts:321
`slice2DShader?`	`Shader`	`undefined`	-	niivue/index.ts:183
`sliceMMShader?`	`Shader`	`undefined`	-	niivue/index.ts:182
`sliceTypeAxial`	`SLICE_TYPE`	`SLICE_TYPE.AXIAL`	-	niivue/index.ts:354
`sliceTypeCoronal`	`SLICE_TYPE`	`SLICE_TYPE.CORONAL`	-	niivue/index.ts:355
`sliceTypeMultiplanar`	`SLICE_TYPE`	`SLICE_TYPE.MULTIPLANAR`	-	niivue/index.ts:357
`sliceTypeRender`	`SLICE_TYPE`	`SLICE_TYPE.RENDER`	-	niivue/index.ts:358
`sliceTypeSagittal`	`SLICE_TYPE`	`SLICE_TYPE.SAGITTAL`	-	niivue/index.ts:356
`sliceV1Shader?`	`Shader`	`undefined`	-	niivue/index.ts:184
`sobelBlurShader`	`Shader`	`null`	-	niivue/index.ts:220
`sobelFirstOrderShader`	`Shader`	`null`	-	niivue/index.ts:221
`sobelSecondOrderShader`	`Shader`	`null`	-	niivue/index.ts:222
`surfaceShader`	`Shader`	`null`	-	niivue/index.ts:218
`syncOpts`	`SyncOpts`	`undefined`	-	niivue/index.ts:243
`thumbnailVisible`	`boolean`	`false`	-	niivue/index.ts:208
`uiData`	`UIData`	`undefined`	-	niivue/index.ts:258
`unusedVAO`	`any`	`null`	-	niivue/index.ts:224
`useCustomGradientTexture`	`boolean`	`false`	-	niivue/index.ts:161
`volScale`	`number`[]	`[]`	-	niivue/index.ts:298
`VOLUME_ID`	`number`	`254`	-	niivue/index.ts:323
`volumeObject3D`	`NiivueObject3D`	`null`	-	niivue/index.ts:314
`volumeTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:158
`vox`	`number`[]	`[]`	-	niivue/index.ts:299

Accessors

drawBitmap

Get Signature

get drawBitmap(): Uint8Array;

Defined in: niivue/index.ts:683

Returns

Uint8Array

Set Signature

set drawBitmap(drawBitmap: Uint8Array): void;

Defined in: niivue/index.ts:687

Parameters

Parameter	Type
`drawBitmap`	`Uint8Array`

Returns

void

isAlphaClipDark

Get Signature

get isAlphaClipDark(): boolean;

Defined in: niivue/index.ts:587

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:596

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:675

Returns

NVMesh[]

Set Signature

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

Defined in: niivue/index.ts:679

Parameters

Parameter	Type
`meshes`	`NVMesh`[]

Returns

void

opts

Get Signature

get opts(): NVConfigOptions;

Defined in: niivue/index.ts:569

Get the current visualization options.

Returns

NVConfigOptions

scene

Get Signature

get scene(): Scene;

Defined in: niivue/index.ts:564

Get the current scene configuration.

Returns

Scene

sliceMosaicString

Get Signature

get sliceMosaicString(): string;

Defined in: niivue/index.ts:574

Get the slice mosaic layout string.

Returns

string

Set Signature

set sliceMosaicString(newSliceMosaicString: string): void;

Defined in: niivue/index.ts:579

Set the slice mosaic layout string.

Parameters

Parameter	Type
`newSliceMosaicString`	`string`

Returns

void

volScaleMultiplier

Get Signature

get volScaleMultiplier(): number;

Defined in: niivue/index.ts:691

Returns

number

Set Signature

set volScaleMultiplier(scale: number): void;

Defined in: niivue/index.ts:695

Parameters

Parameter	Type
`scale`	`number`

Returns

void

volumes

Get Signature

get volumes(): NVImage[];

Defined in: niivue/index.ts:667

Returns

NVImage[]

Set Signature

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

Defined in: niivue/index.ts:671

Parameters

Parameter	Type
`volumes`	`NVImage`[]

Returns

void

Methods

addColormap()

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

Defined in: niivue/index.ts:6747

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:9878

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:3148

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:4838

Add mesh and notify subscribers

Parameters

Parameter	Type
`meshOptions`	`LoadFromUrlParams`[]

Returns

Promise<NVMesh[]>

addMeshFromUrl()

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

Defined in: niivue/index.ts:4809

Add mesh and notify subscribers

Parameters

Parameter	Type
`meshOptions`	`LoadFromUrlParams`

Returns

Promise<NVMesh>

addVolume()

addVolume(volume: NVImage): void;

Defined in: niivue/index.ts:3131

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:2424

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:2436

Parameters

Parameter	Type
`imageOptionsArray`	`ImageFromUrlOptions`[]

Returns

Promise<NVImage[]>

attachTo()

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

Defined in: niivue/index.ts:743

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:757

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:3279

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:834

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:650

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:8104

Clear all persistent measurements and angles from the canvas.

Returns

void

Example

nv.clearAllMeasurements();

clearAngles()

clearAngles(): void;

Defined in: niivue/index.ts:8092

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:11172

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:2973

Clear custom layout and rely on built-in layouts

Returns

void

clearMeasurements()

clearMeasurements(): void;

Defined in: niivue/index.ts:8080

Clear all persistent measurement lines from the canvas.

Returns

void

Example

nv.clearMeasurements();

cloneVolume()

cloneVolume(index: number): NVImage;

Defined in: niivue/index.ts:4335

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:5658

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:7136

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:6737

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:6916

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:6842

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:5934

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:5938
`Name`	`string`	niivue/index.ts:5938
`shader?`	`Shader`	niivue/index.ts:5938

createEmptyDrawing()

createEmptyDrawing(): void;

Defined in: niivue/index.ts:4995

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:6872

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:9762

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:3569

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:863

Parameters

Parameter	Type
`otherNV`	`Niivue`

Returns

void

drawGrowCut()

drawGrowCut(): void;

Defined in: niivue/index.ts:5022

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:5248

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:10859

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:3341

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:3204

Restore drawing to previous state

Returns

void

Example

niivue.drawUndo();

See

live demo usage

eventInBounds()

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

Defined in: niivue/index.ts:11051

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

Parameters

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

Returns

boolean

findDrawingBoundarySlices()

findDrawingBoundarySlices(sliceType: SLICE_TYPE): object;

Defined in: niivue/index.ts:11831

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:11831
`last`	`number`	niivue/index.ts:11831

generateHTML()

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

Defined in: niivue/index.ts:4529

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:4488

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:2982

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:6308

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:2640

Get the currently assigned DICOM loader.

Returns

DicomLoader

getFrame4D()

getFrame4D(id: string): number;

Defined in: niivue/index.ts:7117

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:6201

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:3514

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:8173

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:3655

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:3080

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:8181

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:3162

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:11123

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:3551

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:11846

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:4619

Converts NiiVue scene to JSON

Returns

ExportDocumentData

loadConnectome()

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

Defined in: niivue/index.ts:4981

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:4924

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:7061

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:4711

Parameters

Parameter	Type
`dicomList`	`ImageFromUrlOptions`[]

Returns

Promise<Niivue>

loadDocument()

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

Defined in: niivue/index.ts:4352

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:4342

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:3223

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:3297

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:5847

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:4949

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:4937

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:2558

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:2576

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:6897

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:4672

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:11803

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:4898

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:4762

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:6015

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:10446

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:3806

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:3776

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:3821

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:3791

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:6887

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:7191

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:5672

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:3370

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:3744

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:3760

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:3704

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:3729

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:2516

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:3588

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:4646

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:4611

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:3406

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:705

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:3070

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:8730

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:4092

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:3942

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:4223

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:3924

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:4235

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:4244

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:6759

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:7002

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:7015

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:2890

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:3971

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:3981

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:6227

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:2953

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:5970

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

setCustomMeshShaderFromUrl()

setCustomMeshShaderFromUrl(url: string, name: string): Promise<number>;

Defined in: niivue/index.ts:5986

Fetch GLSL fragment shader source from a URL and register it as a custom mesh shader.

Parameters

Parameter	Type	Default value	Description
`url`	`string`	`undefined`	URL pointing to a plain-text GLSL fragment shader file
`name`	`string`	`''`	a descriptive label for the shader (used in menus or debugging)

Returns

Promise<number>

the index of the new shader (use with setMeshShader)

Async

Throws

when the fetch fails or the response is not OK

See

live demo usage

setDefaults()

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

Defined in: niivue/index.ts:3008

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:8114

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:4003

Parameters

Parameter	Type
`name`	`string`

Returns

void

setDrawingEnabled()

setDrawingEnabled(trueOrFalse: boolean): void;

Defined in: niivue/index.ts:4014

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:4066

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:7093

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:7052

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:4292

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:2922

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:3090

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:8742

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:2901

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:3684

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:3608

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:3526

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:5913

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(niivue.meshes[0].id, "toon");

See

live demo usage

setMeshThicknessOn2D()

setMeshThicknessOn2D(meshThicknessOn2D: number): void;

Defined in: niivue/index.ts:3037

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:7030

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:8146

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:2876

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:2865

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:4193

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:3627

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:4054

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:2996

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:3640

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:6986

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:4205

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:4079

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:2911

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:3059

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:3048

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:4178

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:8163

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:3667

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:4256

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:814

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:3119

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:6255

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:2633

Set a custom loader for handling DICOM files.

Parameters

Parameter	Type
`loader`	`DicomLoader`

Returns

void

useLoader()

useLoader(
   loader: (data: string | ArrayBuffer | Uint8Array) => Promise<any>,
   fileExt: string,
   toExt: string): void;

Defined in: niivue/index.ts:2621

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`	(`data`: `string` \| `ArrayBuffer` \| `Uint8Array`) => `Promise`<`any`>	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:3109

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()