Class: Niivue

Defined in: niivue/index.ts:364

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

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:377
`back`	`NVImage`	`null`	-	niivue/index.ts:516
`backgroundMasksOverlays`	`number`	`0`	-	niivue/index.ts:456
`blurShader`	`Shader`	`null`	-	niivue/index.ts:443
`bmpShader`	`Shader`	`null`	-	niivue/index.ts:430
`bmpTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:431
`bmpTextureWH`	`number`	`1.0`	-	niivue/index.ts:433
`canvas`	`HTMLCanvasElement`	`null`	-	niivue/index.ts:376
`circleShader?`	`Shader`	`undefined`	-	niivue/index.ts:428
`clickToSegmentGrowingBitmap`	`Uint8Array`	`null`	-	niivue/index.ts:394
`clickToSegmentIsGrowing`	`boolean`	`false`	-	niivue/index.ts:393
`clickToSegmentXY`	`number`[]	`undefined`	-	niivue/index.ts:395
`CLIP_PLANE_ID`	`number`	`1`	-	niivue/index.ts:545
`colorbarHeight`	`number`	`0`	-	niivue/index.ts:397
`colorbarShader?`	`Shader`	`undefined`	-	niivue/index.ts:423
`colormapLists`	`ColormapListEntry`[]	`[]`	-	niivue/index.ts:381
`colormapTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:380
`crosshairs3D`	`NiivueObject3D`	`null`	-	niivue/index.ts:449
`cuboidVertexBuffer?`	`WebGLBuffer`	`undefined`	-	niivue/index.ts:534
`currentClipPlaneIndex`	`number`	`0`	-	niivue/index.ts:541
`currentDrawUndoBitmap`	`number`	`undefined`	-	niivue/index.ts:886
`customLayout`	`object`[]	`[]`	-	niivue/index.ts:557
`customSliceShader`	`Shader`	`null`	-	niivue/index.ts:424
`deferredMeshes`	`LoadFromUrlParams`[]	`[]`	-	niivue/index.ts:519
`deferredVolumes`	`ImageFromUrlOptions`[]	`[]`	-	niivue/index.ts:518
`dicomLoader`	`DicomLoader`	`null`	-	niivue/index.ts:367
`DISTANCE_FROM_CAMERA`	`number`	`-0.54`	-	niivue/index.ts:547
`document`	`NVDocument`	`undefined`	-	niivue/index.ts:845
`dragModes`	`object`	`undefined`	-	niivue/index.ts:623
`dragModes.angle`	`DRAG_MODE`	`DRAG_MODE.angle`	-	niivue/index.ts:626
`dragModes.callbackOnly`	`DRAG_MODE`	`DRAG_MODE.callbackOnly`	-	niivue/index.ts:630
`dragModes.contrast`	`DRAG_MODE`	`DRAG_MODE.contrast`	-	niivue/index.ts:624
`dragModes.measurement`	`DRAG_MODE`	`DRAG_MODE.measurement`	-	niivue/index.ts:625
`dragModes.none`	`DRAG_MODE`	`DRAG_MODE.none`	-	niivue/index.ts:627
`dragModes.pan`	`DRAG_MODE`	`DRAG_MODE.pan`	-	niivue/index.ts:628
`dragModes.slicer3D`	`DRAG_MODE`	`DRAG_MODE.slicer3D`	-	niivue/index.ts:629
`drawFillOverwrites`	`boolean`	`true`	-	niivue/index.ts:400
`drawLut`	`LUT`	`undefined`	-	niivue/index.ts:390
`drawOpacity`	`number`	`0.8`	-	niivue/index.ts:391
`drawPenAxCorSag`	`number`	`-1`	-	niivue/index.ts:399
`drawPenFillPts`	`number`[][]	`[]`	-	niivue/index.ts:401
`drawPenLocation`	`number`[]	`undefined`	-	niivue/index.ts:398
`drawRimOpacity`	`number`	`-1.0`	-	niivue/index.ts:392
`drawShapePreviewBitmap`	`Uint8Array`	`null`	-	niivue/index.ts:403
`drawShapeStartLocation`	`number`[]	`undefined`	-	niivue/index.ts:402
`drawTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:387
`drawUndoBitmaps`	`Uint8Array`[]	`[]`	-	niivue/index.ts:389
`extentsMax?`	`vec3`	`undefined`	-	niivue/index.ts:461
`extentsMin?`	`vec3`	`undefined`	-	niivue/index.ts:460
`fiberShader?`	`Shader`	`undefined`	-	niivue/index.ts:426
`fontShader`	`Shader`	`null`	-	niivue/index.ts:425
`fontTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:427
`furthestFromPivot`	`number`	`10.0`	-	niivue/index.ts:539
`furthestVertexFromOrigin`	`number`	`100`	-	niivue/index.ts:520
`genericVAO`	`WebGLVertexArrayObject`	`null`	-	niivue/index.ts:447
`gradientTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:383
`gradientTextureAmount`	`number`	`0.0`	-	niivue/index.ts:384
`graph`	`Graph`	`undefined`	-	niivue/index.ts:548
`growCutShader?`	`Shader`	`undefined`	-	niivue/index.ts:434
`initialized`	`boolean`	`false`	-	niivue/index.ts:885
`isBusy`	`boolean`	`false`	-	niivue/index.ts:378
`lastCalled`	`number`	`undefined`	-	niivue/index.ts:542
`line3DShader?`	`Shader`	`undefined`	-	niivue/index.ts:415
`lineShader?`	`Shader`	`undefined`	-	niivue/index.ts:414
`loaders`	`object`	`{}`	-	niivue/index.ts:365
`matCapTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:429
`mediaUrlMap`	`Map`< \| `NVMesh` \| `NVImage`, `string`>	`undefined`	-	niivue/index.ts:884
`meshShaders`	`object`[]	`undefined`	-	niivue/index.ts:563
`mousePos`	`number`[]	`undefined`	-	niivue/index.ts:523
`needsRefresh`	`boolean`	`false`	-	niivue/index.ts:379
`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:808
`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:689
`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:817
`onColormapChange`	() => `void`	`undefined`	-	niivue/index.ts:732
`onCustomMeshShaderAdded`	(`fragmentShaderText`: `string`, `name`: `string`) => `void`	`undefined`	-	niivue/index.ts:818
`onDebug`	() => `void`	`undefined`	callback function to run when niivue reports a debug message Example `niivue.onDebug = (debug) => { console.log('debug: ', debug) }`	niivue/index.ts:759
`onDicomLoaderFinishedWithImages`	(`files`: \| `NVImage`[] \| `NVMesh`[]) => `void`	`undefined`	-	niivue/index.ts:822
`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:831
`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:648
`onError`	() => `void`	`undefined`	callback function to run when niivue reports an error Example `niivue.onError = (error) => { console.log('error: ', error) }`	niivue/index.ts:729
`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:720
`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:699
`onInfo`	() => `void`	`undefined`	callback function to run when niivue reports detailed info Example `niivue.onInfo = (info) => { console.log('info: ', info) }`	niivue/index.ts:741
`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:678
`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:669
`onMeshAdded`	() => `void`	`undefined`	-	niivue/index.ts:794
`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:791
`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:709
`onMeshPropertyChanged`	(`meshIndex`: `number`, `key`: `string`, `val`: `unknown`) => `void`	`undefined`	-	niivue/index.ts:820
`onMeshShaderChanged`	(`meshIndex`: `number`, `shaderIndex`: `number`) => `void`	`undefined`	-	niivue/index.ts:819
`onMeshWithUrlRemoved`	(`url`: `string`) => `void`	`undefined`	-	niivue/index.ts:795
`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:657
`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:839
`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:770
`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:780
`onVolumeWithUrlRemoved`	(`url`: `string`) => `void`	`undefined`	-	niivue/index.ts:771
`onWarn`	() => `void`	`undefined`	callback function to run when niivue reports a warning Example `niivue.onWarn = (warn) => { console.log('warn: ', warn) }`	niivue/index.ts:750
`onZoom3DChange`	(`zoom`: `number`) => `void`	`undefined`	-	niivue/index.ts:798
`orientCubeShader?`	`Shader`	`undefined`	-	niivue/index.ts:409
`orientCubeShaderVAO`	`WebGLVertexArrayObject`	`null`	-	niivue/index.ts:410
`orientShaderAtlasI`	`Shader`	`null`	-	niivue/index.ts:436
`orientShaderAtlasU`	`Shader`	`null`	-	niivue/index.ts:435
`orientShaderF`	`Shader`	`null`	-	niivue/index.ts:439
`orientShaderI`	`Shader`	`null`	-	niivue/index.ts:438
`orientShaderPAQD`	`Shader`	`null`	-	niivue/index.ts:441
`orientShaderRGBU`	`Shader`	`null`	-	niivue/index.ts:440
`orientShaderU`	`Shader`	`null`	-	niivue/index.ts:437
`otherNV`	`Niivue`[]	`null`	-	niivue/index.ts:536
`overlayAlphaShader`	`number`	`1`	-	niivue/index.ts:458
`overlayOutlineWidth`	`number`	`0`	-	niivue/index.ts:457
`overlays`	`NVImage`[]	`[]`	-	niivue/index.ts:517
`overlayTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:404
`overlayTextureID`	`WebGLTexture`	`null`	-	niivue/index.ts:405
`paqdTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:388
`passThroughShader?`	`Shader`	`undefined`	-	niivue/index.ts:416
`pickingImageShader?`	`Shader`	`undefined`	-	niivue/index.ts:422
`pickingMeshShader?`	`Shader`	`undefined`	-	niivue/index.ts:421
`pivot3D`	`number`[]	`undefined`	-	niivue/index.ts:538
`position?`	`vec3`	`undefined`	-	niivue/index.ts:459
`readyForSync`	`boolean`	`false`	-	niivue/index.ts:479
`rectOutlineShader?`	`Shader`	`undefined`	-	niivue/index.ts:412
`rectShader?`	`Shader`	`undefined`	-	niivue/index.ts:411
`renderDrawAmbientOcclusion`	`number`	`0.4`	-	niivue/index.ts:396
`renderGradientShader?`	`Shader`	`undefined`	-	niivue/index.ts:417
`renderGradientValues`	`boolean`	`false`	-	niivue/index.ts:386
`renderGradientValuesShader?`	`Shader`	`undefined`	-	niivue/index.ts:418
`renderShader?`	`Shader`	`undefined`	-	niivue/index.ts:413
`renderSliceShader?`	`Shader`	`undefined`	-	niivue/index.ts:419
`renderVolumeShader?`	`Shader`	`undefined`	-	niivue/index.ts:420
`screenSlices`	`object`[]	`[]`	-	niivue/index.ts:524
`selectedObjectId`	`number`	`-1`	-	niivue/index.ts:544
`slice2DShader?`	`Shader`	`undefined`	-	niivue/index.ts:407
`sliceMMShader?`	`Shader`	`undefined`	-	niivue/index.ts:406
`sliceTypeAxial`	`SLICE_TYPE`	`SLICE_TYPE.AXIAL`	-	niivue/index.ts:634
`sliceTypeCoronal`	`SLICE_TYPE`	`SLICE_TYPE.CORONAL`	-	niivue/index.ts:635
`sliceTypeMultiplanar`	`SLICE_TYPE`	`SLICE_TYPE.MULTIPLANAR`	-	niivue/index.ts:637
`sliceTypeRender`	`SLICE_TYPE`	`SLICE_TYPE.RENDER`	-	niivue/index.ts:638
`sliceTypeSagittal`	`SLICE_TYPE`	`SLICE_TYPE.SAGITTAL`	-	niivue/index.ts:636
`sliceV1Shader?`	`Shader`	`undefined`	-	niivue/index.ts:408
`sobelBlurShader`	`Shader`	`null`	-	niivue/index.ts:444
`sobelFirstOrderShader`	`Shader`	`null`	-	niivue/index.ts:445
`sobelSecondOrderShader`	`Shader`	`null`	-	niivue/index.ts:446
`surfaceShader`	`Shader`	`null`	-	niivue/index.ts:442
`syncOpts`	`SyncOpts`	`undefined`	-	niivue/index.ts:467
`thumbnailVisible`	`boolean`	`false`	-	niivue/index.ts:432
`uiData`	`UIData`	`undefined`	-	niivue/index.ts:482
`unusedVAO`	`any`	`null`	-	niivue/index.ts:448
`useCustomGradientTexture`	`boolean`	`false`	-	niivue/index.ts:385
`volScale`	`number`[]	`[]`	-	niivue/index.ts:521
`VOLUME_ID`	`number`	`254`	-	niivue/index.ts:546
`volumeObject3D`	`NiivueObject3D`	`null`	-	niivue/index.ts:537
`volumeTexture`	`WebGLTexture`	`null`	-	niivue/index.ts:382
`vox`	`number`[]	`[]`	-	niivue/index.ts:522

Accessors

drawBitmap

Get Signature

get drawBitmap(): Uint8Array;

Defined in: niivue/index.ts:981

Returns

Uint8Array

Set Signature

set drawBitmap(drawBitmap: Uint8Array): void;

Defined in: niivue/index.ts:985

Parameters

Parameter	Type
`drawBitmap`	`Uint8Array`

Returns

void

isAlphaClipDark

Get Signature

get isAlphaClipDark(): boolean;

Defined in: niivue/index.ts:871

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

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

Returns

NVMesh[]

Set Signature

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

Defined in: niivue/index.ts:977

Parameters

Parameter	Type
`meshes`	`NVMesh`[]

Returns

void

opts

Get Signature

get opts(): NVConfigOptions;

Defined in: niivue/index.ts:853

Get the current visualization options.

Returns

NVConfigOptions

scene

Get Signature

get scene(): Scene;

Defined in: niivue/index.ts:848

Get the current scene configuration.

Returns

Scene

sliceMosaicString

Get Signature

get sliceMosaicString(): string;

Defined in: niivue/index.ts:858

Get the slice mosaic layout string.

Returns

string

Set Signature

set sliceMosaicString(newSliceMosaicString: string): void;

Defined in: niivue/index.ts:863

Set the slice mosaic layout string.

Parameters

Parameter	Type
`newSliceMosaicString`	`string`

Returns

void

volScaleMultiplier

Get Signature

get volScaleMultiplier(): number;

Defined in: niivue/index.ts:989

Returns

number

Set Signature

set volScaleMultiplier(scale: number): void;

Defined in: niivue/index.ts:993

Parameters

Parameter	Type
`scale`	`number`

Returns

void

volumes

Get Signature

get volumes(): NVImage[];

Defined in: niivue/index.ts:965

Returns

NVImage[]

Set Signature

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

Defined in: niivue/index.ts:969

Parameters

Parameter	Type
`volumes`	`NVImage`[]

Returns

void

Methods

addColormap()

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

Defined in: niivue/index.ts:8849

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

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

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

Add mesh and notify subscribers

Parameters

Parameter	Type
`meshOptions`	`LoadFromUrlParams`[]

Returns

Promise<NVMesh[]>

addMeshFromUrl()

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

Defined in: niivue/index.ts:5412

Add mesh and notify subscribers

Parameters

Parameter	Type
`meshOptions`	`LoadFromUrlParams`

Returns

Promise<NVMesh>

addVolume()

addVolume(volume: NVImage): void;

Defined in: niivue/index.ts:3541

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

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

Parameters

Parameter	Type
`imageOptionsArray`	`ImageFromUrlOptions`[]

Returns

Promise<NVImage[]>

attachTo()

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

Defined in: niivue/index.ts:1041

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

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

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

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

calculateMvpMatrix()

calculateMvpMatrix(
   _unused: unknown,
   leftTopWidthHeight: number[],
   azimuth: number,
   elevation: number,
   flipX: boolean): mat4[];

Defined in: niivue/index.ts:12410

Build MVP, Model, and Normal matrices for rendering.

Parameters

Parameter	Type	Default value	Description
`_unused`	`unknown`	`undefined`	reserved
`leftTopWidthHeight`	`number`[]	`...`	viewport rectangle [x, y, w, h] in device pixels
`azimuth`	`number`	`undefined`	azimuth rotation in degrees
`elevation`	`number`	`undefined`	elevation rotation in degrees
`flipX`	`boolean`	`true`	whether to mirror the X axis (default true for radiological convention)

Returns

mat4[]

cleanup()

cleanup(): void;

Defined in: niivue/index.ts:934

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

Clear all persistent measurements and angles from the canvas.

Returns

void

Example

nv.clearAllMeasurements();

clearAngles()

clearAngles(): void;

Defined in: niivue/index.ts:10929

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

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

Clear custom layout and rely on built-in layouts

Returns

void

clearMeasurements()

clearMeasurements(): void;

Defined in: niivue/index.ts:10917

Clear all persistent measurement lines from the canvas.

Returns

void

Example

nv.clearMeasurements();

cloneVolume()

cloneVolume(index: number): NVImage;

Defined in: niivue/index.ts:4933

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

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

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

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

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

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

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

createEmptyDrawing()

createEmptyDrawing(): void;

Defined in: niivue/index.ts:5631

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

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

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

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

Parameters

Parameter	Type
`otherNV`	`Niivue`

Returns

void

drawGrowCut()

drawGrowCut(): void;

Defined in: niivue/index.ts:5697

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

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

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

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

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

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

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

frac2canvasPos()

frac2canvasPos(frac: vec3): number[];

Defined in: niivue/index.ts:14186

Parameters

Parameter	Type
`frac`	`vec3`

Returns

number[]

generateHTML()

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

Defined in: niivue/index.ts:5128

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

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

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

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

Get the currently assigned DICOM loader.

Returns

DicomLoader

getFrame4D()

getFrame4D(id: string): number;

Defined in: niivue/index.ts:9753

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

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

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

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

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

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

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

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

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

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

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

Converts NiiVue scene to JSON

Returns

ExportDocumentData

loadConnectome()

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

Defined in: niivue/index.ts:5614

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

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

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

Parameters

Parameter	Type
`dicomList`	`ImageFromUrlOptions`[]

Returns

Promise<Niivue>

loadDocument()

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

Defined in: niivue/index.ts:4950

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

set the color of the 3D clip plane

Parameters

Parameter	Type	Description
`color`	`number`[]	the new color. expects an array of RGBA values. values can range from 0 to 1

Returns

void

Example

niivue.setClipPlaneColor([1, 1, 1, 0.5]); // white, transparent

See

live demo usage

setClipPlaneThick()

setClipPlaneThick(thick: number): void;

Defined in: niivue/index.ts:4791

adjust thickness of the 3D clip plane

Parameters

Parameter	Type	Description
`thick`	`number`	thickness of slab. Value 0..1.73 (cube opposite corner length is sqrt(3)).

Returns

void

Example

niivue.setClipPlaneThick(0.3); // thin slab

See

live demo usage

setClipVolume()

setClipVolume(low: number[], high: number[]): void;

Defined in: niivue/index.ts:4808

set the clipping region for volume rendering

Parameters

Parameter	Type	Description
`low`	`number`[]	3-component array specifying the lower bound of the clipping region along the X, Y, and Z axes. Values range from 0 (start) to 1 (end of volume).
`high`	`number`[]	3-component array specifying the upper bound of the clipping region along the X, Y, and Z axes. Values range from 0 to 1.

Returns

void

Example

niivue.setClipPlaneColor([0.0, 0.0, 0.2], [1.0, 1.0, 0.7]); // remove inferior 20% and superior 30%

See

live demo usage

setColormap()

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

Defined in: niivue/index.ts:8861

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

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

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

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

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

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

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

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

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

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

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

Parameters

Parameter	Type
`name`	`string`

Returns

void

setDrawingEnabled()

setDrawingEnabled(trueOrFalse: boolean): void;

Defined in: niivue/index.ts:4596

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

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

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

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

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

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

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

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

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

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: number,
   layer: number,
   key: keyof NVMeshLayer,
val: number): Promise<void>;

Defined in: niivue/index.ts:4207

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

Parameters

Parameter	Type	Description
`mesh`	`number`	identity of mesh to change
`layer`	`number`	selects the mesh overlay (e.g. GIfTI or STC file)
`key`	keyof `NVMeshLayer`	attribute to change
`val`	`number`	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:4129

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: number, meshShaderNameOrNumber: number): void;

Defined in: niivue/index.ts:7302

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`	`number`	`undefined`	id of mesh to change
`meshShaderNameOrNumber`	`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:3441

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

sph2cartDeg()

sph2cartDeg(azimuth: number, elevation: number): number[];

Defined in: niivue/index.ts:4503

convert spherical AZIMUTH, ELEVATION to Cartesian

Parameters

Parameter	Type	Description
`azimuth`	`number`	azimuth number
`elevation`	`number`	elevation number

Returns

number[]

the converted [x, y, z] coordinates

Example

niivue = new Niivue();
xyz = niivue.sph2cartDeg(42, 42);

syncWith()

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

Defined in: niivue/index.ts:1128

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

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

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

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

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

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