@niivue/niivue 0.52.0 → 0.53.1

package/build/index.d.ts

@@ -208,7 +208,10 @@ declare enum ImageType {
     DCM_FOLDER = 16,
     SRC = 17,
     FIB = 18,
-    BMP = 19
+    BMP = 19,
+    ZARR = 20,
+    NPY = 21,
+    NPZ = 22
 }
 type ImageFromUrlOptions = {
     url: string;
@@ -385,9 +388,9 @@ declare class NVImage {
      * @param colorbarVisible - TODO
      * @param colormapLabel - TODO
      */
-    constructor(dataBuffer?: ArrayBuffer | ArrayBuffer[] | 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[] | 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 | null): void;
-    static new(dataBuffer?: ArrayBuffer | ArrayBuffer[] | 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>;
+    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>;
     computeObliqueAngle(mtx44: mat4): number;
     float32V1asRGBA(inImg: Float32Array): Uint8Array;
     loadImgV1(isFlipX?: boolean, isFlipY?: boolean, isFlipZ?: boolean): boolean;
@@ -396,16 +399,16 @@ declare class NVImage {
     SetPixDimFromSForm(): void;
     readECAT(buffer: ArrayBuffer): ArrayBuffer;
     readV16(buffer: ArrayBuffer): ArrayBuffer;
+    readNPY(buffer: ArrayBuffer): Promise<ArrayBuffer>;
+    readNPZ(buffer: ArrayBuffer): Promise<ArrayBuffer>;
     imageDataFromArrayBuffer(buffer: ArrayBuffer): Promise<ImageData>;
     readBMP(buffer: ArrayBuffer): Promise<ArrayBuffer>;
     readVMR(buffer: ArrayBuffer): ArrayBuffer;
-    readMGH(buffer: ArrayBuffer): Promise<ArrayBuffer>;
     readFIB(buffer: ArrayBuffer): Promise<[ArrayBuffer, Float32Array]>;
     readSRC(buffer: ArrayBuffer): Promise<ArrayBuffer>;
     readHEAD(dataBuffer: ArrayBuffer, pairedImgData: ArrayBuffer | null): Promise<ArrayBuffer>;
     readMHA(buffer: ArrayBuffer, pairedImgData: ArrayBuffer | null): Promise<ArrayBuffer>;
     readMIF(buffer: ArrayBuffer, pairedImgData: ArrayBuffer | null): Promise<ArrayBuffer>;
-    readNRRD(dataBuffer: ArrayBuffer, pairedImgData: ArrayBuffer | null): Promise<ArrayBuffer>;
     calculateRAS(): void;
     hdr2RAS(nVolumes?: number): Promise<NIFTI1 | NIFTI2>;
     img2RAS(nVolume?: number): TypedVoxelArray;
@@ -431,7 +434,21 @@ declare class NVImage {
     calMinMax(vol?: number, isBorder?: boolean): number[];
     intensityRaw2Scaled(raw: number): number;
     intensityScaled2Raw(scaled: number): number;
+    /**
+     * Converts NVImage to NIfTI compliant byte array, potentially compressed.
+     * Delegates to ImageWriter.saveToUint8Array.
+     * @param fnm - Filename (determines if compression is needed via .gz suffix)
+     * @param drawing8 - Optional Uint8Array drawing overlay
+     * @returns Promise<Uint8Array>
+     */
     saveToUint8Array(fnm: string, drawing8?: Uint8Array | null): Promise<Uint8Array>;
+    /**
+     * save image as NIfTI volume and trigger download.
+     * Delegates to ImageWriter.saveToDisk.
+     * @param fnm - Filename for download. If empty, returns data without download.
+     * @param drawing8 - Optional Uint8Array drawing overlay
+     * @returns Promise<Uint8Array>
+     */
     saveToDisk(fnm?: string, drawing8?: Uint8Array | null): Promise<Uint8Array>;
     static fetchDicomData(url: string, headers?: Record<string, string>): Promise<Array<{
         name: string;
@@ -455,15 +472,15 @@ declare class NVImage {
     static loadFromFile({ file, // file can be an array of file objects or a single file object
     name, colormap, opacity, urlImgData, cal_min, cal_max, trustCalMinMax, percentileFrac, ignoreZeroVoxels, useQFormNotSForm, colormapNegative, frame4D, limitFrames4D, imageType }: ImageFromFileOptions): Promise<NVImage>;
     /**
-     * factory function to load and return a new NVImage instance from a base64 encoded string
-     *
-     * @returns NVImage instance
-     * @example
-     * myImage = NVImage.loadFromBase64('SomeBase64String')
+     * Creates a Uint8Array representing a NIFTI file (header + optional image data).
+     * Delegates to ImageWriter.createNiftiArray.
+     */
+    static createNiftiArray(dims?: number[], pixDims?: number[], affine?: number[], datatypeCode?: NiiDataType, img?: TypedVoxelArray | Uint8Array): Uint8Array;
+    /**
+     * Creates a NIFTI1 header object with basic properties.
+     * Delegates to ImageWriter.createNiftiHeader.
      */
-    static createNiftiArray(dims?: number[], pixDims?: number[], affine?: number[], datatypeCode?: number, // DT_UINT8
-    img?: Uint8Array): Uint8Array;
-    static createNiftiHeader(dims?: number[], pixDims?: number[], affine?: number[], datatypeCode?: number): NIFTI1;
+    static createNiftiHeader(dims?: number[], pixDims?: number[], affine?: number[], datatypeCode?: NiiDataType): NIFTI1;
     /**
      * read a 3D slab of voxels from a volume
      * @param voxStart - first row, column and slice (RAS order) for selection
@@ -472,6 +489,14 @@ declare class NVImage {
      * @returns the an array where ret[0] is the voxel values and ret[1] is dimension of selection
      * @see {@link https://niivue.github.io/niivue/features/slab_selection.html | live demo usage}
      */
+    /**
+     * read a 3D slab of voxels from a volume, specified in RAS coordinates.
+     * Delegates to VolumeUtils.getVolumeData.
+     * @param voxStart - first row, column and slice (RAS order) for selection
+     * @param voxEnd - final row, column and slice (RAS order) for selection
+     * @param dataType - array data type. Options: 'same' (default), 'uint8', 'float32', 'scaled', 'normalized', 'windowed'
+     * @returns the an array where ret[0] is the voxel values and ret[1] is dimension of selection
+     */
     getVolumeData(voxStart?: number[], voxEnd?: number[], dataType?: string): [TypedVoxelArray, number[]];
     /**
      * write a 3D slab of voxels from a volume
@@ -480,6 +505,14 @@ declare class NVImage {
      * @param img - array of voxel values to insert (RAS order)
      * @see {@link https://niivue.github.io/niivue/features/slab_selection.html | live demo usage}
      */
+    /**
+     * write a 3D slab of voxels from a volume, specified in RAS coordinates.
+     * Delegates to VolumeUtils.setVolumeData.
+     * Input slabData is assumed to be in the correct raw data type for the target image.
+     * @param voxStart - first row, column and slice (RAS order) for selection
+     * @param voxEnd - final row, column and slice (RAS order) for selection
+     * @param img - array of voxel values to insert (RAS order, raw data type)
+     */
     setVolumeData(voxStart?: number[], voxEnd?: number[], img?: TypedVoxelArray): void;
     /**
      * factory function to load and return a new NVImage instance from a base64 encoded string
@@ -518,20 +551,28 @@ declare class NVImage {
      * newZeroImage = NVImage.zerosLike(myImage)
      */
     static zerosLike(nvImage: NVImage, dataType?: string): NVImage;
-    getValue(x: number, y: number, z: number, frame4D?: number, isReadImaginary?: boolean): number;
     /**
-     * @param id - id of 3D Object (is this the base volume or an overlay?)
-     * @param gl - WebGL rendering context
-     * @returns new 3D object in model space
+     * Returns voxel intensity at specific native coordinates.
+     * Delegates to VolumeUtils.getValue.
+     * @param x - Native X coordinate (0-indexed)
+     * @param y - Native Y coordinate (0-indexed)
+     * @param z - Native Z coordinate (0-indexed)
+     * @param frame4D - 4D frame index (0-indexed)
+     * @param isReadImaginary - Flag to read from imaginary data array
+     * @returns Scaled voxel intensity
      */
-    toNiivueObject3D(id: number, gl: WebGL2RenderingContext): NiivueObject3D;
+    getValue(x: number, y: number, z: number, frame4D?: number, isReadImaginary?: boolean): number;
     /**
      * Update options for image
      */
     applyOptionsUpdate(options: ImageFromUrlOptions): void;
     getImageOptions(): ImageFromUrlOptions;
     /**
-     * Converts NVImage to NIfTI compliant byte array
+     * Converts NVImage to NIfTI compliant byte array.
+     * Handles potential re-orientation of drawing data.
+     * Delegates to ImageWriter.toUint8Array.
+     * @param drawingBytes - Optional Uint8Array drawing overlay
+     * @returns Uint8Array
      */
     toUint8Array(drawingBytes?: Uint8Array | null): Uint8Array;
     convertVox2Frac(vox: vec3): vec3;
@@ -731,6 +772,7 @@ type NVConfigOptions = {
     isAlphaClipDark: boolean;
     gradientOrder: number;
     gradientOpacity: number;
+    invertScrollDirection: boolean;
 };
 declare const DEFAULT_OPTIONS: NVConfigOptions;
 type SceneData = {
@@ -956,7 +998,7 @@ type Point = {
     };
 };
 /**
- * Representes the vertices of a connectome
+ * Represents the vertices of a connectome
  * @ignore
  */
 type NVConnectomeNode = {
@@ -1291,7 +1333,7 @@ declare class NVMesh {
     decimateFaces(n: number, ntarget: number): void;
     decimateHierarchicalMesh(gl: WebGL2RenderingContext, order?: number): boolean;
     setLayerProperty(id: number, key: keyof NVMeshLayer, val: number | string | boolean, gl: WebGL2RenderingContext): Promise<void>;
-    setProperty(key: keyof this, val: unknown, gl: WebGL2RenderingContext): void;
+    setProperty(key: keyof this, val: number | string | boolean | Uint8Array | number[] | ColorMap | LegacyConnectome | Float32Array, gl: WebGL2RenderingContext): void;
     generatePosNormClr(pts: Float32Array, tris: Uint32Array, rgba255: Uint8Array): Float32Array;
     static readMesh(buffer: ArrayBuffer, name: string, gl: WebGL2RenderingContext, opacity?: number, rgba255?: Uint8Array, visible?: boolean): Promise<NVMesh>;
     static loadLayer(layer: NVMeshLayer, nvmesh: NVMesh): Promise<void>;
@@ -1317,7 +1359,7 @@ declare class NVUtilities {
     static arrayBufferToBase64(arrayBuffer: ArrayBuffer): string;
     static decompress(data: Uint8Array): Promise<Uint8Array>;
     static decompressToBuffer(data: Uint8Array): Promise<ArrayBuffer>;
-    static readMatV4(buffer: ArrayBuffer): Promise<Record<string, TypedNumberArray>>;
+    static readMatV4(buffer: ArrayBuffer, isReplaceDots?: boolean): Promise<Record<string, TypedNumberArray>>;
     static b64toUint8(base64: string): Uint8Array;
     static uint8tob64(bytes: Uint8Array): string;
     static download(content: string | ArrayBuffer, fileName: string, contentType: string): void;
@@ -1622,6 +1664,8 @@ declare class Niivue {
     extentsMin?: vec3;
     extentsMax?: vec3;
     private resizeObserver;
+    private resizeEventListener;
+    private canvasObserver;
     syncOpts: SyncOpts;
     readyForSync: boolean;
     uiData: UIData;
@@ -1858,6 +1902,13 @@ declare class Niivue {
      * @param options  - options object to set modifiable Niivue properties
      */
     constructor(options?: Partial<NVConfigOptions>);
+    /**
+     * 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
+     * @example niivue.cleanup();
+     */
+    cleanup(): void;
     get volumes(): NVImage[];
     set volumes(volumes: NVImage[]);
     get meshes(): NVMesh[];
@@ -1878,7 +1929,7 @@ declare class Niivue {
      * @param id - the id of an html canvas element
      * @param isAntiAlias - determines if anti-aliasing is requested (if not specified, AA usage depends on hardware)
      * @example niivue = new Niivue().attachTo('gl')
-     * @example niivue.attachTo('gl')
+     * @example await niivue.attachTo('gl')
      * @see {@link https://niivue.github.io/niivue/features/basic.multiplanar.html | live demo usage}
      */
     attachTo(id: string, isAntiAlias?: any): Promise<this>;
@@ -1887,7 +1938,7 @@ declare class Niivue {
      * @param canvas - the canvas element reference
      * @example
      * niivue = new Niivue()
-     * niivue.attachToCanvas(document.getElementById(id))
+     * await niivue.attachToCanvas(document.getElementById(id))
      */
     attachToCanvas(canvas: HTMLCanvasElement, isAntiAlias?: boolean | null): Promise<this>;
     /**
@@ -1985,6 +2036,7 @@ declare class Niivue {
     touchStartListener(e: TouchEvent): void;
     touchEndListener(e: TouchEvent): void;
     windowingHandler(x: number, y: number, volIdx?: number): void;
+    mouseLeaveListener(): void;
     mouseMoveListener(e: MouseEvent): void;
     resetBriCon(msg?: TouchEvent | MouseEvent | null): void;
     setDragStart(x: number, y: number): void;
@@ -2200,7 +2252,7 @@ declare class Niivue {
      * @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): void;
+    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
@@ -2607,7 +2659,7 @@ declare class Niivue {
      * @see {@link https://niivue.github.io/niivue/features/draw2.html | live demo usage}
      */
     drawGrowCut(): void;
-    drawPt(x: number, y: number, z: number, penValue: number): void;
+    drawPt(x: number, y: number, z: number, penValue: number, drawBitmap?: Uint8Array | null): void;
     drawPenLine(ptA: number[], ptB: number[], penValue: number): void;
     /**
      * Performs a 1-voxel binary dilation on a connected cluster within the drawing mask using the drawFloodFillCore function.
@@ -2618,8 +2670,7 @@ declare class Niivue {
     drawingBinaryDilationWithSeed(seedXYZ: number[], // seed voxel x,y,z
     neighbors?: 6 | 18 | 26): void;
     drawFloodFillCore(img: Uint8Array, seedVx: number, neighbors?: number): void;
-    drawFloodFill(seedXYZ: number[], newColor?: number, growSelectedCluster?: number, // if non-zero, growth based on background intensity POSITIVE_INFINITY for selected or bright, NEGATIVE_INFINITY for selected or darker
-    forceMin?: number, forceMax?: number, neighbors?: number, maxDistanceMM?: number, is2D?: boolean): void;
+    drawFloodFill(seedXYZ: number[], newColor?: number, growSelectedCluster?: number, forceMin?: number, forceMax?: number, neighbors?: number, maxDistanceMM?: number, is2D?: boolean, targetBitmap?: Uint8Array | null, isGrowClusterTool?: boolean): void;
     drawPenFilled(): void;
     /**
      * close drawing: make sure you have saved any changes before calling this!
@@ -2895,6 +2946,11 @@ declare class Niivue {
     inGraphTile(x: number, y: number): boolean;
     updateBitmapFromClickToSegment(): void;
     sumBitmap(img: Uint8Array): number;
+    doClickToSegment(options: {
+        x: number;
+        y: number;
+        tileIndex: number;
+    }): void;
     mouseClick(x: number, y: number, posChange?: number, isDelta?: boolean): void;
     drawRuler(): void;
     drawRuler10cm(startXYendXY: number[], rulerColor: number[], rulerWidth?: number): void;