@niivue/niivue 0.56.0 → 0.58.0

package/README.md

@@ -1,10 +1,6 @@
 # NiiVue
 
-NiiVue is web-based visualization tool for neuroimaging that can run on any operating system and any web device (phone, tablet, computer). This repository contains only the **core NiiVue package** that can be embedded into other projects. We have additional [repositories](https://github.com/niivue) that wrap NiiVue for use in jupyter notebooks, vscode, and electron applications. 
-
-### [Click here to see NiiVue live demos](https://niivue.github.io/niivue/)
-
-What makes NiiVue unique is its ability to simultaneously display all the datatypes popular with neuroimaging: voxels, meshes, tractography streamlines, statistical maps and connectomes. Alternative voxel-based web tools include [ami](https://fnndsc.github.io/ami/), [BioImage Suite Web](https://bioimagesuiteweb.github.io/webapp/viewer.html), [BrainBrowser](https://brainbrowser.cbrain.mcgill.ca/volume-viewer), [nifti-drop](http://vsoch.github.io/nifti-drop), [OHIF DICOM Viewer](https://viewer.ohif.org/), [Papaya](https://www.fmrib.ox.ac.uk/ukbiobank/group_means/index.html), and [VTK.js](https://kitware.github.io/paraview-glance/app/).
+NiiVue is web-based visualization tool for neuroimaging that can run on any operating system and any web device (phone, tablet, computer). This repository contains only the **core NiiVue package** that can be embedded into other projects. See [niivue.com](https://niivue.com/) for examples and documentation. 
 
 ## Local Development
 
@@ -16,55 +12,3 @@ cd niivue
 npm install
 npm run dev
 ```
-
-The command `npm run demo` will minify the project and locally host all of the [live demos](https://niivue.github.io/niivue/). The [DEVELOP.md file provides more details for developers](./packages/niivue/DEVELOP.md).
-
-# Developer Documentation
-
-[Click here for the docs web page](https://niivue.github.io/niivue/devdocs/)
-
-# Projects and People using NiiVue
-
-- Analysis of Functional NeuroImages (AFNI) [Scientific and Statistical Computing Core](https://afni.nimh.nih.gov/) (National Institutes of Health)
-- [BOOSTLET.js](https://boostlet.org/) image processing plugins work with NiiVue.
-- [brainchop](https://github.com/neuroneural/brainchop) uses NiiVue for their [drag-and-drop segmentation, brain extraction and parcellation tool](https://neuroneural.github.io/brainchop/)
-- [BrainLife.io](https://brainlife.io/about/) integrates NiiVue into [ezbids](https://brainlife.io/ezbids/)
-- [CACTAS](https://github.com/mpsych/CACTAS) from [Daniel Haehn's team](https://danielhaehn.com/) is extending NiiVue drawing and segmentation capabilities
-- [ChRIS Research Integration System (ChRIS) from Boston Children's Hospital](https://chrisproject.org/) uses [NiiVue](https://app.chrisproject.org/niivue)
-- [Center for the Study of Aphasia Recovery (C-STAR)](https://cstar.sc.edu/) (University of South Carolina)
-- [Digital Brain Bank](https://elifesciences.org/articles/73153) for navigating MRI datasets
-- FMRIB's Software Library (FSL) [Wellcome Centre for Integrative Neuroimaging](https://www.win.ox.ac.uk/) (University of Oxford)
-- FreeSurfer [Laboratories for Computational Neuroimaging](https://lcn.martinos.org/) (Massachusetts General Hospital) uses NiiVue for [FreeBrowse](https://github.com/freesurfer/freebrowse)
-- [OpenNeuro.org](https://openneuro.org) uses NiiVue to visualize datasets
-- [neurodesk](https://www.neurodesk.org/) uses NiiVue for their [QSMxT Quantitative Susceptibility Mapping toolbox](https://github.com/QSMxT/QSMxT-UI)
-- [Neuroinformatics Research and Development Group](http://neuroinformatics.uw.edu/) embeds NiiVue in [tractoscope](https://github.com/nrdg/tractoscope)
-- [nilearn](https://nilearn.github.io/stable/index.html) is extending [ipyniivue](https://github.com/niivue/ipyniivue)
-- [niivue-vscode](https://github.com/niivue/niivue-vscode) is a VSCode extension for displaying images
-- [QuantCo](https://www.quantco.com/) is using NiiVue in medical imaging workflows
-- [FSL Clinical](https://fslclinical.com/) is using NiiVue in brain imaging reports
-- [brain2print](https://brain2print.org/) (from the NiiVue team) uses NiiVue for showing both volume data and converted meshes
-- [ct2print](https://ct2print.org/) (from the NiiVue team) uses NiiVue for showing volume and mesh data
-- [ipyniivue](https://github.com/niivue/ipyniivue) allows NiiVue to be used in Jupyter Notebooks
-- [T2Lesion](https://niivue.github.io/T2lesion/) (from the NiiVue team) uses NiiVue to show input data and segmented lesion masks
-- [NiiVue Desktop](https://github.com/niivue/desktop) (from the NiiVue team) uses NiiVue in a crossplatform Electron app
-- [NiiVue iOS](https://github.com/niivue/ios) (from the NiiVue team) uses NiiVue in a hybrid Swift + webView mobile app
-- [NiiVue Neglect](https://niivue.github.io/niivue-neglect/) uses NiiVue to visualise stroke lesion data in the spatial neglect severity prediction tool
-- [Plurimedia](https://www.plurimedia.it/) uses NiiVue in client work for medical image visualization
-- [Slice:Drop Reloaded](https://gaiborjosue.github.io/slicedrop.github.com/reload/) uses WebGL2-based NiiVue to extend the pioneering WebGL1-based [slicedrop](https://slicedrop.com/) that used the seminal XTK library.
-- [VoxLogicA-UI](https://voxlogica-project.github.io/VoxLogicA-UI/) makes advanced medical
-imaging analysis intuitive
-
-# Funding
-
-- 2021-2022 [P50 DC014664](https://reporter.nih.gov/search/D3sOjJtXwkSRKLpYf1ctBg/project-details/10094384) NIH NIDCD [NOT-OD-21-091](https://grants.nih.gov/grants/guide/notice-files/NOT-OD-21-091.html#:~:text=NOT%2DOD%2D21%2D091,Software%20Tools%20for%20Open%20Science)
-- 2023-2026 [RF1 MH133701](https://reporter.nih.gov/search/D3sOjJtXwkSRKLpYf1ctBg/project-details/10724895) NIH NIMH
-
-# Supported Formats
-
-NiiVue supports many popular brain imaging formats:
-
-- Voxel-based formats: [NIfTI](https://brainder.org/2012/09/23/the-nifti-file-format/), [NRRD](http://teem.sourceforge.net/nrrd/format.html), [MRtrix MIF](https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#mrtrix-image-formats), [AFNI HEAD/BRIK](https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.attributes.html), [MGH/MGZ](https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat), [ITK MHD](https://itk.org/Wiki/ITK/MetaIO/Documentation#Reading_a_Brick-of-Bytes_.28an_N-Dimensional_volume_in_a_single_file.29), [ECAT7](https://github.com/openneuropet/PET2BIDS/tree/28aae3fab22309047d36d867c624cd629c921ca6/ecat_validation/ecat_info), [DSI-Studio SRC](https://dsi-studio.labsolver.org/doc/cli_data.html).
-- Mesh-based formats: [GIfTI](https://www.nitrc.org/projects/gifti/), [ASC](http://www.grahamwideman.com/gw/brain/fs/surfacefileformats.htm), [BYU/GEO/G](http://www.grahamwideman.com/gw/brain/fs/surfacefileformats.htm), [BrainSuite DFS](http://brainsuite.org/formats/dfs/), [ICO/TRI](http://www.grahamwideman.com/gw/brain/fs/surfacefileformats.htm), [PLY](<https://en.wikipedia.org/wiki/PLY_(file_format)>), [BrainNet NV](https://www.nitrc.org/projects/bnv/), [BrainVoyager SRF](https://support.brainvoyager.com/brainvoyager/automation-development/84-file-formats/344-users-guide-2-3-the-format-of-srf-files), [FreeSurfer](http://www.grahamwideman.com/gw/brain/fs/surfacefileformats.htm), [MZ3](https://github.com/neurolabusc/surf-ice/tree/master/mz3), [OFF](<https://en.wikipedia.org/wiki/OFF_(file_format)>), [Wavefront OBJ](https://brainder.org/tag/obj/), [STL](https://medium.com/3d-printing-stories/why-stl-format-is-bad-fea9ecf5e45), [Legacy VTK](https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf), [WRL](https://en.wikipedia.org/wiki/VRML), [X3D](https://3dprint.nih.gov/).
-- Mesh overlay formats: [GIfTI](https://www.nitrc.org/projects/gifti/), [CIfTI-2](https://balsa.wustl.edu/about/fileTypes), [MZ3](https://github.com/neurolabusc/surf-ice/tree/master/mz3), [SMP](https://support.brainvoyager.com/brainvoyager/automation-development/84-file-formats/40-the-format-of-smp-files), STC, FreeSurfer (CURV/ANNOT)
-- Tractography formats: [TCK](https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#tracks-file-format-tck), [TRK](http://trackvis.org/docs/?subsect=fileformat), [TRX](https://github.com/frheault/tractography_file_format), [TSF](https://mrtrix.readthedocs.io/en/dev/getting_started/image_data.html#track-scalar-file-format-tsf), [TT](https://dsi-studio.labsolver.org/doc/cli_data.html), VTK, AFNI .niml.tract
-- DICOM: [DICOM](https://dicom.nema.org/medical/dicom/current/output/chtml/part10/chapter_7.html) and [DICOM Manifests](docs/development-notes/dicom-manifests.md)

package/build/index.d.ts

@@ -152,13 +152,13 @@ declare class NVLabel3D {
     style: NVLabel3DStyle;
     points?: number[] | number[][];
     anchor: LabelAnchorPoint;
-    onClick?: (label: NVLabel3D) => void;
+    onClick?: (label: NVLabel3D, e?: MouseEvent) => void;
     /**
      * @param text - The text of the label
      * @param style - The style of the label
      * @param points - An array of points label for label lines
      */
-    constructor(text: string, style: NVLabel3DStyle, points?: number[] | number[][], anchor?: LabelAnchorPoint, onClick?: (label: NVLabel3D) => void);
+    constructor(text: string, style: NVLabel3DStyle, points?: number[] | number[][], anchor?: LabelAnchorPoint, onClick?: (label: NVLabel3D, e?: MouseEvent) => void);
 }
 
 /**
@@ -390,7 +390,7 @@ declare class NVImage {
      */
     constructor(dataBuffer?: ArrayBuffer | ArrayBuffer[] | ArrayBufferLike | null, name?: string, colormap?: string, opacity?: number, pairedImgData?: ArrayBuffer | null, cal_min?: number, cal_max?: number, trustCalMinMax?: boolean, percentileFrac?: number, ignoreZeroVoxels?: boolean, useQFormNotSForm?: boolean, colormapNegative?: string, frame4D?: number, imageType?: ImageType, cal_minNeg?: number, cal_maxNeg?: number, colorbarVisible?: boolean, colormapLabel?: LUT | null, colormapType?: number);
     init(dataBuffer?: ArrayBuffer | ArrayBuffer[] | ArrayBufferLike | null, name?: string, colormap?: string, opacity?: number, _pairedImgData?: ArrayBuffer | null, cal_min?: number, cal_max?: number, trustCalMinMax?: boolean, percentileFrac?: number, ignoreZeroVoxels?: boolean, useQFormNotSForm?: boolean, colormapNegative?: string, frame4D?: number, imageType?: ImageType, cal_minNeg?: number, cal_maxNeg?: number, colorbarVisible?: boolean, colormapLabel?: LUT | null, colormapType?: number, imgRaw?: ArrayBuffer | ArrayBufferLike | null): void;
-    static new(dataBuffer?: ArrayBuffer | ArrayBuffer[] | ArrayBufferLike | null, name?: string, colormap?: string, opacity?: number, pairedImgData?: ArrayBuffer | null, cal_min?: number, cal_max?: number, trustCalMinMax?: boolean, percentileFrac?: number, ignoreZeroVoxels?: boolean, useQFormNotSForm?: boolean, colormapNegative?: string, frame4D?: number, imageType?: ImageType, cal_minNeg?: number, cal_maxNeg?: number, colorbarVisible?: boolean, colormapLabel?: LUT | null, colormapType?: number): Promise<NVImage>;
+    static new(dataBuffer: ArrayBuffer | ArrayBuffer[] | ArrayBufferLike | null, name: string, colormap: string, opacity: number, pairedImgData: ArrayBuffer | null, cal_min: number, cal_max: number, trustCalMinMax: boolean, percentileFrac: number, ignoreZeroVoxels: boolean, useQFormNotSForm: boolean, colormapNegative: string, frame4D: number, imageType: ImageType, cal_minNeg: number, cal_maxNeg: number, colorbarVisible: boolean, colormapLabel: LUT | null, colormapType: number, zarrData: null | unknown): Promise<NVImage>;
     computeObliqueAngle(mtx44: mat4): number;
     float32V1asRGBA(inImg: Float32Array): Uint8Array;
     loadImgV1(isFlipX?: boolean, isFlipY?: boolean, isFlipZ?: boolean): boolean;
@@ -403,6 +403,7 @@ declare class NVImage {
     readNPZ(buffer: ArrayBuffer): Promise<ArrayBuffer>;
     imageDataFromArrayBuffer(buffer: ArrayBuffer): Promise<ImageData>;
     readBMP(buffer: ArrayBuffer): Promise<ArrayBuffer>;
+    readZARR(buffer: ArrayBuffer, zarrData: unknown): Promise<ArrayBufferLike>;
     readVMR(buffer: ArrayBuffer): ArrayBuffer;
     readFIB(buffer: ArrayBuffer): Promise<[ArrayBuffer, Float32Array]>;
     readSRC(buffer: ArrayBuffer): Promise<ArrayBuffer>;
@@ -428,7 +429,7 @@ declare class NVImage {
      * set contrast/brightness to robust range (2%..98%)
      * @param vol - volume for estimate (use -1 to use estimate on all loaded volumes; use INFINITY for current volume)
      * @param isBorder - if true (default) only center of volume used for estimate
-     * @sets volume brightness and returns array [pct2, pct98, mnScale, mxScale]
+     * @returns volume brightness and returns array [pct2, pct98, mnScale, mxScale]
      * @see {@link https://niivue.github.io/niivue/features/timeseries2.html | live demo usage}
      */
     calMinMax(vol?: number, isBorder?: boolean): number[];
@@ -775,8 +776,10 @@ type NVConfigOptions = {
     isAlphaClipDark: boolean;
     gradientOrder: number;
     gradientOpacity: number;
+    renderSilhouette: number;
     gradientAmount: number;
     invertScrollDirection: boolean;
+    is2DSliceShader: boolean;
 };
 declare const DEFAULT_OPTIONS: NVConfigOptions;
 type SceneData = {
@@ -821,16 +824,16 @@ type Scene = {
     gamma?: number;
 };
 type DocumentData = {
-    title: string;
-    imageOptionsArray: ImageFromUrlOptions[];
-    meshOptionsArray: unknown[];
-    opts: NVConfigOptions;
-    previewImageDataURL: string;
-    labels: NVLabel3D[];
-    encodedImageBlobs: string[];
-    encodedDrawingBlob: string;
+    title?: string;
+    imageOptionsArray?: ImageFromUrlOptions[];
+    meshOptionsArray?: unknown[];
+    opts?: Partial<NVConfigOptions>;
+    previewImageDataURL?: string;
+    labels?: NVLabel3D[];
+    encodedImageBlobs?: string[];
+    encodedDrawingBlob?: string;
     meshesString?: string;
-    sceneData?: SceneData;
+    sceneData?: Partial<SceneData>;
     connectomes?: string[];
     customData?: string;
 };
@@ -924,17 +927,25 @@ declare class NVDocument {
      */
     removeImage(image: NVImage): void;
     /**
-     * Returns the options for the image if it was added by url
+     * Fetch any image data that is missing from this document.
+     * This includes loading image blobs for `ImageFromUrlOptions` with valid `url` fields.
+     * After calling this, `volumes` and `imageOptionsMap` will be populated.
      */
-    getImageOptions(image: NVImage): ImageFromUrlOptions | null;
+    fetchLinkedData(): Promise<void>;
     /**
-     * Converts NVDocument to JSON
+     * Returns the options for the image if it was added by url
      */
-    json(): ExportDocumentData;
+    getImageOptions(image: NVImage): ImageFromUrlOptions | null;
     /**
-     * Downloads a JSON file with options, scene, images, meshes and drawing of {@link Niivue} instance
+     * Serialise the document.
+     *
+     * @param embedImages  If false, encodedImageBlobs is left empty
+     *                     (imageOptionsArray still records the URL / name).
      */
-    download(fileName: string, compress: boolean): Promise<void>;
+    json(embedImages?: boolean): ExportDocumentData;
+    download(fileName: string, compress: boolean, opts?: {
+        embedImages: boolean;
+    }): Promise<void>;
     /**
      * Deserialize mesh data objects
      */
@@ -948,9 +959,20 @@ declare class NVDocument {
      */
     static loadFromFile(file: Blob): Promise<NVDocument>;
     /**
-     * Factory method to return an instance of NVDocument from JSON
+     * Factory method to return an instance of NVDocument from JSON.
+     *
+     * This will merge any saved configuration options (`opts`) with the DEFAULT_OPTIONS,
+     * ensuring any missing values are filled with defaults. It also restores special-case
+     * fields like `meshThicknessOn2D` when serialized as the string "infinity".
+     *
+     * @param data - A serialized DocumentData object
+     * @returns A reconstructed NVDocument instance
      */
     static loadFromJSON(data: DocumentData): NVDocument;
+    /**
+     * Factory method to return an instance of NVDocument from JSON
+     */
+    static oldloadFromJSON(data: DocumentData): NVDocument;
 }
 
 type NiftiHeader = {
@@ -1036,6 +1058,7 @@ type ConnectomeOptions = {
     edgeMax: number;
     edgeScale: number;
     legendLineThickness?: number;
+    showLegend?: boolean;
 };
 type Connectome = ConnectomeOptions & {
     nodes: NVConnectomeNode[];
@@ -1204,6 +1227,9 @@ type NVMeshLayer = {
     colormapType?: number;
     base64?: string;
     colorbarVisible?: boolean;
+    showLegend?: boolean;
+    labels?: NVLabel3D[];
+    atlasValues?: AnyNumberArray;
 };
 declare const NVMeshLayerDefaults: {
     colormap: string;
@@ -1217,6 +1243,8 @@ declare const NVMeshLayerDefaults: {
     cal_maxNeg: number;
     colormapType: COLORMAP_TYPE;
     values: number[];
+    useNegativeCmap: boolean;
+    showLegend: boolean;
 };
 declare class NVMeshFromUrlOptions {
     url: string;
@@ -1297,6 +1325,7 @@ declare class NVMesh {
     nodeScale: number;
     edgeScale: number;
     legendLineThickness: number;
+    showLegend: boolean;
     nodeColormap: string;
     edgeColormap: string;
     nodeColormapNegative?: string;
@@ -1330,6 +1359,7 @@ declare class NVMesh {
     updateFibers(gl: WebGL2RenderingContext): void;
     indexNearestXYZmm(Xmm: number, Ymm: number, Zmm: number): number[];
     unloadMesh(gl: WebGL2RenderingContext): void;
+    scalars2RGBA(rgba: Uint8ClampedArray, layer: NVMeshLayer, scalars: AnyNumberArray, isNegativeCmap?: boolean): Uint8ClampedArray;
     blendColormap(u8: Uint8Array, additiveRGBA: Uint8Array, layer: NVMeshLayer, mn: number, mx: number, lut: Uint8ClampedArray, invert?: boolean): void;
     updateMesh(gl: WebGL2RenderingContext): void;
     reverseFaces(gl: WebGL2RenderingContext): void;
@@ -1498,6 +1528,7 @@ type Graph = {
     lineColor?: number[];
     textColor?: number[];
     lineThickness?: number;
+    gridLineThickness?: number;
     lineAlpha?: number;
     lines?: number[][];
     selectedColumn?: number;
@@ -1565,6 +1596,8 @@ type UIData = {
     lastTwoTouchDistance: number;
     multiTouchGesture: boolean;
     dpr?: number;
+    max2D?: number;
+    max3D?: number;
     windowX: number;
     windowY: number;
 };
@@ -1617,6 +1650,7 @@ declare class Niivue {
     overlayTexture: WebGLTexture | null;
     overlayTextureID: WebGLTexture | null;
     sliceMMShader?: Shader;
+    slice2DShader?: Shader;
     sliceV1Shader?: Shader;
     orientCubeShader?: Shader;
     orientCubeShaderVAO: WebGLVertexArrayObject | null;
@@ -2270,7 +2304,7 @@ declare class Niivue {
     binarize(volume: NVImage): void;
     /**
      * Open drawing
-     * @param filename - of NIfTI format drawing
+     * @param fnm - filename of NIfTI format drawing
      * @param isBinarize - if true will force drawing voxels to be either 0 or 1.
      * @example niivue.loadDrawingFromUrl("../images/lesion.nii.gz");
      * @see {@link https://niivue.github.io/niivue/features/draw.ui.html | live demo usage}
@@ -2293,12 +2327,17 @@ declare class Niivue {
      */
     removeHaze(level?: number, volIndex?: number): void;
     /**
-     * save voxel-based image to disk
-     * @param fnm - filename of NIfTI image to create
-     * @param isSaveDrawing - determines whether drawing or background image is saved
-     * @param volumeByIndex - determines layer to save (0 for background)
-     * @param volumeByIndex - determines layer to save (0 for background)
-     * @example niivue.saveImage({ filename: "myimage.nii.gz", isSaveDrawing: true });
+     * Save voxel-based image to disk.
+     *
+     * @param options - 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 `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 {@link https://niivue.github.io/niivue/features/draw.ui.html | live demo usage}
      */
     saveImage(options?: SaveImageOptions): Promise<boolean | Uint8Array>;
@@ -2307,14 +2346,14 @@ declare class Niivue {
      * change property of mesh, tractogram or connectome
      * @param id - identity of mesh to change
      * @param key - attribute to change
-     * @param value - for attribute
+     * @param val - for attribute
      * @example niivue.setMeshProperty(niivue.meshes[0].id, 'fiberLength', 42)
      * @see {@link https://niivue.github.io/niivue/features/meshes.html | live demo usage}
      */
     setMeshProperty(id: number, key: keyof NVMesh, val: number | string | boolean | Uint8Array | number[] | ColorMap | LegacyConnectome | Float32Array): void;
     /**
      * returns the index of the mesh vertex that is closest to the provided coordinates
-     * @param id - identity of mesh to change
+     * @param mesh - identity of mesh to change
      * @param Xmm - location in left/right dimension
      * @param Ymm - location in posterior/anterior dimension
      * @param Zmm - location in foot/head dimension
@@ -2334,7 +2373,7 @@ declare class Niivue {
     decimateHierarchicalMesh(mesh: number, order?: number): boolean;
     /**
      * reverse triangle winding of mesh (swap front and back faces)
-     * @param id - identity of mesh to change
+     * @param mesh - identity of mesh to change
      * @example niivue.reverseFaces(niivue.meshes[0].id)
      * @see {@link https://niivue.github.io/niivue/features/meshes.html | live demo usage}
      */
@@ -2344,7 +2383,7 @@ declare class Niivue {
      * @param mesh - identity of mesh to change
      * @param layer - selects the mesh overlay (e.g. GIfTI or STC file)
      * @param key - attribute to change
-     * @param value - for attribute
+     * @param val - value for attribute
      * @example niivue.setMeshLayerProperty(niivue.meshes[0].id, 0, 'frame4D', 22)
      * @see {@link https://niivue.github.io/niivue/features/mesh.4D.html | live demo usage}
      */
@@ -2455,8 +2494,11 @@ declare class Niivue {
      */
     sph2cartDeg(azimuth: number, elevation: number): number[];
     /**
-     * update the clip plane orientation in 3D view mode
-     * @param azimuthElevationDepth - a two component vector. azimuth: camera position in degrees around object, typically 0..360 (or -180..+180). elevation: camera height in degrees, range -90..90
+     * Update the clip plane orientation in 3D view mode.
+     * @param depthAzimuthElevation - 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)
      * @example
      * niivue = new Niivue()
      * niivue.setClipPlane([42, 42])
@@ -2513,7 +2555,7 @@ declare class Niivue {
     sliceScroll2D(posChange: number, x: number, y: number, isDelta?: boolean): void;
     /**
      * set the slice type. This changes the view mode
-     * @param sliceType - an enum of slice types to use
+     * @param st - sliceType is an enum of slice types to use
      * @example
      * niivue = new Niivue()
      * niivue.setSliceType(Niivue.sliceTypeMultiplanar)
@@ -2556,7 +2598,8 @@ declare class Niivue {
     setClipPlaneThick(thick: number): void;
     /**
      * set the clipping region for volume rendering
-     * @param color - the new color. expects an array of RGBA values. values can range from 0 to 1
+     * @param low - 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).
+     * @param high - 3-component array specifying the upper bound of the clipping region along the X, Y, and Z axes. Values range from 0 to 1.
      * @example
      * niivue.setClipPlaneColor([0.0, 0.0, 0.2], [1.0, 1.0, 0.7]) // remove inferior 20% and superior 30%
      * @see {@link https://niivue.github.io/niivue/features/clipplanes.html | live demo usage}
@@ -2574,11 +2617,12 @@ declare class Niivue {
     /**
      * set volume rendering opacity influence of the gradient magnitude
      * @param gradientOpacity - amount of gradient magnitude influence on opacity (0..1), default 0 (no-influence)
+     * @param renderSilhouette - make core transparent to enhance rims (0..1), default 0 (no-influence)
      * @example
      * niivue.setGradientOpacity(0.6);
      * @see {@link https://niivue.github.io/niivue/features/gradient.opacity.html | live demo usage}
      */
-    setGradientOpacity(gradientOpacity?: number): Promise<void>;
+    setGradientOpacity(gradientOpacity?: number, renderSilhouette?: number): Promise<void>;
     overlayRGBA(volume: NVImage): Uint8ClampedArray;
     vox2mm(XYZ: number[], mtx: mat4): vec3;
     /**
@@ -2634,14 +2678,22 @@ declare class Niivue {
      */
     json(): ExportDocumentData;
     /**
-     * save the entire scene (objects and settings) as a document
-     * @param fileName - the name of the document storing the scene
-     * @param compress - whether the file should be compressed
+     * Save the current scene as an .nvd document.
+     *
+     * @param fileName  Name of the file to create (default "untitled.nvd")
+     * @param compress  If true, gzip-compress the JSON (default true)
+     * @param options   Fine-grained switches:
+     *                  • embedImages  – store encodedImageBlobs  (default true)
+     *                  • embedPreview – store previewImageDataURL (default true)
+     *
      * @example
-     * niivue.saveDocument("niivue.basic.nvd")
-     * @see {@link https://niivue.github.io/niivue/features/document.3d.html | live demo usage}
+     * // smallest possible file – no preview, just metadata
+     * await nv.saveDocument('scene.nvd', true, { embedImages:false, embedPreview:false });
      */
-    saveDocument(fileName?: string, compress?: boolean): Promise<void>;
+    saveDocument(fileName?: string, compress?: boolean, options?: {
+        embedImages?: boolean;
+        embedPreview?: boolean;
+    }): Promise<void>;
     loadImages(images: Array<ImageFromUrlOptions | LoadFromUrlParams>): Promise<this>;
     loadDicoms(dicomList: ImageFromUrlOptions[]): Promise<this>;
     /**
@@ -2673,20 +2725,25 @@ declare class Niivue {
      */
     loadMeshes(meshList: LoadFromUrlParams[]): Promise<this>;
     /**
-     * load a connectome specified by url
-     * @returns Niivue instance
+     * Load a connectome from a given URL and initialize it.
+     *
+     * @param url - the URL to a JSON-formatted connectome definition
+     * @param headers - optional HTTP headers to include with the request (e.g. for authorization)
+     * @returns the `Niivue` instance (for method chaining)
      * @see {@link https://niivue.github.io/niivue/features/connectome.html | live demo usage}
      */
     loadConnectomeFromUrl(url: string, headers?: {}): Promise<this>;
     /**
-     * load a connectome specified by url
-     * @returns Niivue instance
+     * Load a FreeSurfer-style connectome from a given URL and initialize it.
+     * @param url - the URL of the JSON-formatted connectome file
+     * @param headers - optional HTTP headers to include in the fetch request (e.g. for authorization)
+     * @returns the `Niivue` instance (for method chaining)
      * @see {@link https://niivue.github.io/niivue/features/connectome.html | live demo usage}
      */
     loadFreeSurferConnectomeFromUrl(url: string, headers?: {}): Promise<this>;
     /**
      * load a connectome specified by json
-     * @param connectome - freesurfer model
+     * @param json - freesurfer model
      * @returns Niivue instance
      * @see {@link https://niivue.github.io/niivue/features/connectome.html | live demo usage}
      */
@@ -2699,7 +2756,7 @@ declare class Niivue {
     loadConnectomeAsMesh(json: Connectome | LegacyConnectome | FreeSurferConnectome): NVMesh;
     /**
      * load a connectome specified by json
-     * @param connectome - model
+     * @param json - connectome model
      * @returns Niivue instance
      * @see {@link https://niivue.github.io/niivue/features/connectome.html | live demo usage}
      */
@@ -2744,7 +2801,9 @@ declare class Niivue {
      * @see {@link https://niivue.github.io/niivue/features/cactus.html | live demo usage}
      */
     refreshDrawing(isForceRedraw?: boolean, useClickToSegmentBitmap?: boolean): void;
+    r8Tex2D(texID: WebGLTexture | null, activeID: number, dims: number[], isInit?: boolean): WebGLTexture | null;
     r8Tex(texID: WebGLTexture | null, activeID: number, dims: number[], isInit?: boolean): WebGLTexture | null;
+    rgbaTex2D(texID: WebGLTexture | null, activeID: number, dims: number[], data?: Uint8Array | null, isFlipVertical?: boolean): WebGLTexture | null;
     rgbaTex(texID: WebGLTexture | null, activeID: number, dims: number[], isInit?: boolean): WebGLTexture | null;
     rgba16Tex(texID: WebGLTexture | null, activeID: number, dims: number[], isInit?: boolean): WebGLTexture | null;
     requestCORSIfNotSameOrigin(img: HTMLImageElement, url: string): void;
@@ -2753,7 +2812,7 @@ declare class Niivue {
     loadBmpTexture(bmpUrl: string): Promise<WebGLTexture | null>;
     /**
      * Load matcap for illumination model.
-     * @param name - name of matcap to load ("Shiny", "Cortex", "Cream")
+     * @param bmpUrl - name of matcap to load ("Shiny", "Cortex", "Cream")
      * @example
      * niivue.loadMatCapTexture("Cortex");
      * @see {@link https://niivue.github.io/niivue/features/shiny.volumes.html | live demo usage}
@@ -2762,7 +2821,9 @@ declare class Niivue {
     initFontMets(): void;
     /**
      * Load typeface for colorbars, measurements and orientation text.
-     * @param name - name of matcap to load ("Roboto", "Garamond", "Ubuntu")
+     * @param fontSheetUrl - URL to a bitmap font sheet image (e.g., a PNG atlas of glyphs)
+     * @param metricsUrl - URL to the corresponding font metrics JSON (defines character bounds and spacing)
+     * @returns a Promise that resolves when the font is loaded
      * @example
      * niivue.loadMatCapTexture("Cortex");
      * @see {@link https://niivue.github.io/niivue/features/selectfont.html | live demo usage}
@@ -2832,9 +2893,9 @@ declare class Niivue {
     };
     /**
      * Define a new GLSL shader program to influence mesh coloration
-     * @param fragmentShaderText - custom fragment shader.
-     * @param ame - title for new shader.
-     * @returns index of the new shader (for setMeshShader)
+     * @param fragmentShaderText - the GLSL source code for the custom fragment shader
+     * @param name - a descriptive label for the shader (used in menus or debugging)
+     * @returns the index of the new shader (use with {@link setMeshShader})
      * @see {@link https://niivue.github.io/niivue/features/mesh.atlas.html | live demo usage}
      */
     setCustomMeshShader(fragmentShaderText?: string, name?: string): number;
@@ -2889,7 +2950,6 @@ declare class Niivue {
     refreshLayers(overlayItem: NVImage, layer: number): void;
     /**
      * query all available color maps that can be applied to volumes
-     * @param sort - whether or not to sort the returned array
      * @returns an array of colormap strings
      * @example
      * niivue = new Niivue()
@@ -2900,7 +2960,7 @@ declare class Niivue {
     /**
      * create a new colormap
      * @param key - name of new colormap
-     * @param colormap - properties (Red, Green, Blue, Alpha and Indices)
+     * @param cmap - colormap properties (Red, Green, Blue, Alpha and Indices)
      * @see {@link https://niivue.github.io/niivue/features/colormaps.html | live demo usage}
      */
     addColormap(key: string, cmap: ColorMap): void;
@@ -2940,7 +3000,7 @@ declare class Niivue {
     conform(volume: NVImage, toRAS?: boolean, isLinear?: boolean, asFloat32?: boolean, isRobustMinMax?: boolean): Promise<NVImage>;
     /**
      * darken crevices and brighten corners when 3D rendering drawings.
-     * @param amount - amount of ambient occlusion (default 0.4)
+     * @param ao - amount of ambient occlusion (default 0.4)
      * @see {@link https://niivue.github.io/niivue/features/torso.html | live demo usage}
      */
     setRenderDrawAmbientOcclusion(ao: number): void;
@@ -3074,9 +3134,13 @@ declare class Niivue {
     createOnLocationChange(axCorSag?: number): void;
     /**
      * Add a 3D Label
-     * @param text - text of the label
-     * @param style - label style
-     * @param point - 3D point on the model
+     * @param text - the text content of the label
+     * @param style - visual styling options for the label (e.g., color, scale, line width)
+     * @param points - a 3D point `[x, y, z]` or array of points to anchor the label in space
+     * @param anchor - optional label anchor position (e.g., top-left, center, etc.)
+     * @param onClick - optional callback function to invoke when the label is clicked
+     * @returns the created `NVLabel3D` instance
+     * @see {@link https://niivue.github.io/niivue/features/labels.html | live demo usage}
      */
     addLabel(text: string, style: NVLabel3DStyle, points?: number[] | number[][], anchor?: LabelAnchorPoint, onClick?: (label: NVLabel3D) => void): NVLabel3D;
     calculateScreenPoint(point: [number, number, number], mvpMatrix: mat4, leftTopWidthHeight: number[]): vec4;