@niivue/niivue 0.44.0 → 0.44.1

package/build/index.d.ts

@@ -437,7 +437,7 @@ declare class NVImage {
      * read a 3D slab of voxels from a volume
      * @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'
+     * @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
      * @see {@link https://niivue.github.io/niivue/features/slab_selection.html | live demo usage}
      */
@@ -1191,6 +1191,9 @@ declare class NVMesh {
     unloadMesh(gl: WebGL2RenderingContext): void;
     updateMesh(gl: WebGL2RenderingContext): void;
     reverseFaces(gl: WebGL2RenderingContext): void;
+    hierarchicalOrder(): number;
+    decimateFaces(n: number, ntarget: number): void;
+    decimateHierarchicalMesh(gl: WebGL2RenderingContext, order?: number): boolean;
     setLayerProperty(id: number, key: keyof NVMeshLayer, val: number | string | boolean, gl: WebGL2RenderingContext): void;
     setProperty(key: keyof this, val: unknown, gl: WebGL2RenderingContext): void;
     generatePosNormClr(pts: Float32Array, tris: Uint32Array, rgba255: Uint8Array): Float32Array;
@@ -1520,6 +1523,7 @@ declare class NVMeshLoaders {
     static readSRF(buffer: ArrayBuffer): DefaultMeshType;
     static readTxtSTL(buffer: ArrayBuffer): DefaultMeshType;
     static readSTL(buffer: ArrayBuffer): DefaultMeshType;
+    static decimateLayerVertices(nVertLayer: number, nVertMesh: number): number;
     static readNII2(buffer: ArrayBuffer, n_vert?: number, anatomicalStructurePrimary?: string): Int32Array | Float32Array | Int16Array | Uint8Array;
     static readNII(buffer: ArrayBuffer, n_vert?: number, anatomicalStructurePrimary?: string): Float32Array | Uint8Array | Int32Array | Int16Array;
     static readMGH(buffer: ArrayBuffer, n_vert?: number, isReadColortables?: boolean): MGH;
@@ -1527,6 +1531,26 @@ declare class NVMeshLoaders {
     static readGII(buffer: ArrayBuffer, n_vert?: number): GII;
 }
 
+type Extents = {
+    mxDx: number;
+    extentsMin: number | number[];
+    extentsMax: number | number[];
+};
+/**
+ * Utilities class for common mesh functions
+ */
+declare class NVMeshUtilities {
+    static getClusterBoundaryU8(u8: Uint8Array, faces: number[] | Uint32Array): boolean[];
+    static createMZ3(vertices: Float32Array, indices: Uint32Array, compress?: boolean): ArrayBuffer;
+    static createOBJ(vertices: Float32Array, indices: Uint32Array): ArrayBuffer;
+    static createSTL(vertices: Float32Array, indices: Uint32Array): ArrayBuffer;
+    static downloadArrayBuffer(buffer: ArrayBuffer, filename: string): void;
+    static saveMesh(vertices: Float32Array, indices: Uint32Array, filename?: string, compress?: boolean): ArrayBuffer;
+    static getClusterBoundary(rgba8: Uint8Array, faces: number[] | Uint32Array): boolean[];
+    static getExtents(pts: number[] | Float32Array): Extents;
+    static generateNormals(pts: number[] | Float32Array, tris: number[] | Uint32Array): Float32Array;
+}
+
 type ColormapListEntry = {
     name: string;
     min: number;
@@ -2264,6 +2288,15 @@ declare class Niivue {
      * @see {@link https://niivue.github.io/niivue/features/clipplanes.html | live demo usage}
      */
     indexNearestXYZmm(mesh: number, Xmm: number, Ymm: number, Zmm: number): number[];
+    /**
+     * reduce complexity of FreeSurfer mesh
+     * @param mesh - identity of mesh to change
+     * @param order - decimation order 0..6
+     * @example niivue.decimateHierarchicalMesh(niivue.meshes[0].id, 4)
+     * @returns boolean false if mesh is not hierarchical or of lower order
+     * @see {@link https://niivue.github.io/niivue/features/meshes.html | live demo usage}
+     */
+    decimateHierarchicalMesh(mesh: number, order?: number): boolean;
     /**
      * reverse triangle winding of mesh (swap front and back faces)
      * @param id - identity of mesh to change
@@ -3009,4 +3042,4 @@ declare class Niivue {
     set gl(gl: WebGL2RenderingContext | null);
 }
 
-export { type Connectome, type ConnectomeOptions, DEFAULT_OPTIONS, DRAG_MODE, type DocumentData, type DragReleaseParams, type ExportDocumentData, INITIAL_SCENE_DATA, LabelLineTerminator, LabelTextAlignment, type LegacyConnectome, type LegacyNodes, MULTIPLANAR_TYPE, type NVConfigOptions, type NVConnectomeEdge, type NVConnectomeNode, NVController, NVDocument, NVImage, NVImageFromUrlOptions, NVLabel3D, NVLabel3DStyle, NVMesh, NVMeshFromUrlOptions, NVMeshLayerDefaults, NVMeshLoaders, NVUtilities, type NiftiHeader, type NiiVueLocation, type NiiVueLocationValue, Niivue, type Point, SHOW_RENDER, SLICE_TYPE, type Scene, type Volume, cmapper, ColorTables as colortables };
+export { type Connectome, type ConnectomeOptions, DEFAULT_OPTIONS, DRAG_MODE, type DocumentData, type DragReleaseParams, type ExportDocumentData, INITIAL_SCENE_DATA, LabelLineTerminator, LabelTextAlignment, type LegacyConnectome, type LegacyNodes, MULTIPLANAR_TYPE, type NVConfigOptions, type NVConnectomeEdge, type NVConnectomeNode, NVController, NVDocument, NVImage, NVImageFromUrlOptions, NVLabel3D, NVLabel3DStyle, NVMesh, NVMeshFromUrlOptions, NVMeshLayerDefaults, NVMeshLoaders, NVMeshUtilities, NVUtilities, type NiftiHeader, type NiiVueLocation, type NiiVueLocationValue, Niivue, type Point, SHOW_RENDER, SLICE_TYPE, type Scene, type Volume, cmapper, ColorTables as colortables };

package/build/index.js

@@ -13,7 +13,7 @@ var __publicField = (obj, key, value) => {
 import { mat4 as mat46, vec2, vec3 as vec311, vec4 as vec48 } from "gl-matrix";
 
 // package.json
-var version = "0.44.0";
+var version = "0.44.1";
 
 // src/logger.ts
 var _Log = class _Log {
@@ -11254,6 +11254,7 @@ var cmapper = new ColorTables();
 
 // src/nvmesh-utilities.ts
 import { vec3 as vec32 } from "gl-matrix";
+import { gzipSync } from "fflate/browser";
 var NVMeshUtilities = class {
   static getClusterBoundaryU8(u8, faces) {
     const border = new Array(u8.length).fill(false);
@@ -11279,6 +11280,112 @@ var NVMeshUtilities = class {
     }
     return border;
   }
+  static createMZ3(vertices, indices, compress2 = false) {
+    const magic = 23117;
+    const attr = 3;
+    const nface = indices.length / 3;
+    const nvert = vertices.length / 3;
+    const nskip = 0;
+    const headerSize = 16;
+    const indexSize = nface * 3 * 4;
+    const vertexSize = nvert * 3 * 4;
+    const totalSize = headerSize + indexSize + vertexSize;
+    const buffer = new ArrayBuffer(totalSize);
+    const writer = new DataView(buffer);
+    writer.setUint16(0, magic, true);
+    writer.setUint16(2, attr, true);
+    writer.setUint32(4, nface, true);
+    writer.setUint32(8, nvert, true);
+    writer.setUint32(12, nskip, true);
+    let offset = headerSize;
+    new Uint32Array(buffer, offset, indices.length).set(indices);
+    offset += indexSize;
+    new Float32Array(buffer, offset, vertices.length).set(vertices);
+    if (compress2) {
+      return gzipSync(new Uint8Array(buffer));
+    }
+    return buffer;
+  }
+  static createOBJ(vertices, indices) {
+    let objContent = "";
+    for (let i = 0; i < vertices.length; i += 3) {
+      objContent += `v ${vertices[i]} ${vertices[i + 1]} ${vertices[i + 2]}
+`;
+    }
+    for (let i = 0; i < indices.length; i += 3) {
+      objContent += `f ${indices[i] + 1} ${indices[i + 1] + 1} ${indices[i + 2] + 1}
+`;
+    }
+    const encoder = new TextEncoder();
+    const arrayBuffer = encoder.encode(objContent).buffer;
+    return arrayBuffer;
+  }
+  static createSTL(vertices, indices) {
+    const numTriangles = indices.length / 3;
+    const bufferLength = 84 + numTriangles * 50;
+    const arrayBuffer = new ArrayBuffer(bufferLength);
+    const dataView = new DataView(arrayBuffer);
+    for (let i = 0; i < 80; i++) {
+      dataView.setUint8(i, 0);
+    }
+    dataView.setUint32(80, numTriangles, true);
+    let offset = 84;
+    for (let i = 0; i < indices.length; i += 3) {
+      const i0 = indices[i] * 3;
+      const i1 = indices[i + 1] * 3;
+      const i2 = indices[i + 2] * 3;
+      dataView.setFloat32(offset, 0, true);
+      dataView.setFloat32(offset + 4, 0, true);
+      dataView.setFloat32(offset + 8, 0, true);
+      offset += 12;
+      dataView.setFloat32(offset, vertices[i0], true);
+      dataView.setFloat32(offset + 4, vertices[i0 + 1], true);
+      dataView.setFloat32(offset + 8, vertices[i0 + 2], true);
+      offset += 12;
+      dataView.setFloat32(offset, vertices[i1], true);
+      dataView.setFloat32(offset + 4, vertices[i1 + 1], true);
+      dataView.setFloat32(offset + 8, vertices[i1 + 2], true);
+      offset += 12;
+      dataView.setFloat32(offset, vertices[i2], true);
+      dataView.setFloat32(offset + 4, vertices[i2 + 1], true);
+      dataView.setFloat32(offset + 8, vertices[i2 + 2], true);
+      offset += 12;
+      dataView.setUint16(offset, 0, true);
+      offset += 2;
+    }
+    return arrayBuffer;
+  }
+  static downloadArrayBuffer(buffer, filename) {
+    const blob = new Blob([buffer], { type: "application/octet-stream" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.style.display = "none";
+    a.click();
+    setTimeout(() => {
+      document.body.removeChild(a);
+      URL.revokeObjectURL(url);
+    }, 0);
+  }
+  static saveMesh(vertices, indices, filename = ".mz3", compress2 = false) {
+    let buff = new ArrayBuffer(0);
+    if (/\.obj$/i.test(filename)) {
+      buff = this.createOBJ(vertices, indices);
+    } else if (/\.stl$/i.test(filename)) {
+      buff = this.createSTL(vertices, indices);
+    } else {
+      if (!/\.mz3$/i.test(filename)) {
+        filename += ".mz3";
+      }
+      buff = this.createMZ3(vertices, indices, compress2);
+    }
+    if (filename.length > 4) {
+      this.downloadArrayBuffer(buff, filename);
+    }
+    return buff;
+  }
   static getClusterBoundary(rgba8, faces) {
     const rgba32 = new Uint32Array(rgba8.buffer);
     const border = new Array(rgba32.length).fill(false);
@@ -12669,7 +12776,8 @@ var NVMeshLoaders = class _NVMeshLoaders {
   static readANNOT(buffer, n_vert, isReadColortables = false) {
     const view = new DataView(buffer);
     const n_vertex = view.getUint32(0, false);
-    if (n_vert !== n_vertex) {
+    const n_vertexDecimated = this.decimateLayerVertices(n_vertex, n_vert);
+    if (n_vert !== n_vertexDecimated) {
       throw new Error("ANNOT file has different number of vertices than mesh");
     }
     if (buffer.byteLength < 4 + 8 * n_vertex) {
@@ -13917,6 +14025,20 @@ var NVMeshLoaders = class _NVMeshLoaders {
     };
   }
   // readSTL()
+  static decimateLayerVertices(nVertLayer, nVertMesh) {
+    if (nVertLayer % nVertMesh === 0) {
+      return nVertLayer;
+    }
+    const V0 = 12;
+    const orderLayer = Math.round(Math.log((nVertLayer - 2) / (V0 - 2)) / Math.log(4));
+    const orderMesh = Math.round(Math.log((nVertMesh - 2) / (V0 - 2)) / Math.log(4));
+    const nVLayer = Math.pow(4, orderLayer) * (V0 - 2) + 2;
+    const nVMesh = Math.pow(4, orderMesh) * (V0 - 2) + 2;
+    if (nVLayer !== nVertLayer || nVMesh !== nVertMesh) {
+      return nVertLayer;
+    }
+    return nVertMesh;
+  }
   // read NIfTI2 format with embedded CIfTI
   // this variation very specific to connectome workbench
   // https://brainder.org/2015/04/03/the-nifti-2-file-format/
@@ -14077,8 +14199,9 @@ var NVMeshLoaders = class _NVMeshLoaders {
       );
       return scalars2;
     }
+    nvert = this.decimateLayerVertices(nvert, n_vert);
     if (nvert % n_vert !== 0) {
-      throw new Error("Vertices in NIfTI (" + nvert + ") is not a multiple of number of vertices (" + n_vert + ")");
+      throw new Error("Vertices in layer (" + nvert + ") is not a multiple of number of vertices (" + n_vert + ")");
     }
     if (isLittleEndian) {
       if (datatype === 16) {
@@ -14157,8 +14280,9 @@ var NVMeshLoaders = class _NVMeshLoaders {
       const dim = reader.getUint16(40 + i * 2, isLittleEndian);
       nvert *= Math.max(dim, 1);
     }
+    nvert = this.decimateLayerVertices(nvert, n_vert);
     if (nvert % n_vert !== 0) {
-      throw new Error("Vertices in NIfTI (" + nvert + ") is not a multiple of number of vertices (" + n_vert + ")");
+      throw new Error("Vertices in layer (" + nvert + ") is not a multiple of number of vertices (" + n_vert + ")");
     }
     if (isLittleEndian) {
       if (datatype === 16) {
@@ -14214,10 +14338,11 @@ var NVMeshLoaders = class _NVMeshLoaders {
     if (version2 !== 1 || mtype < 0 || mtype > 4) {
       log.warn("Not a valid MGH file");
     }
-    const nvert = width * height * depth * nframes;
+    let nvert = width * height * depth * nframes;
     let scalars = [];
+    nvert = this.decimateLayerVertices(nvert, n_vert);
     if (nvert % n_vert !== 0) {
-      log.warn("Vertices in NIfTI (" + nvert + ") is not a multiple of number of vertices (" + n_vert + ")");
+      log.warn("Vertices in layer (" + nvert + ") is not a multiple of number of vertices (" + n_vert + ")");
       return scalars;
     }
     if (mtype === 3) {
@@ -15961,6 +16086,91 @@ var NVMesh2 = class _NVMesh {
     }
     this.updateMesh(gl);
   }
+  hierarchicalOrder() {
+    const V0 = 12;
+    const F0 = 20;
+    const nF = this.tris.length / 3;
+    const order = Math.log(nF / F0) / Math.log(4);
+    if (nF !== Math.pow(4, order) * F0) {
+      return NaN;
+    }
+    const nV = this.pts.length / 3;
+    if (nV !== Math.pow(4, order) * (V0 - 2) + 2) {
+      return NaN;
+    }
+    for (let i = 0; i < 15; i += 3) {
+      if (this.tris[i] !== 0) {
+        return NaN;
+      }
+    }
+    for (let i = 15; i < 24; i += 3) {
+      if (this.tris[i] !== 3) {
+        return NaN;
+      }
+    }
+    for (let i = 24; i < 30; i += 3) {
+      if (this.tris[i] !== 4) {
+        return NaN;
+      }
+    }
+    return order;
+  }
+  decimateFaces(n, ntarget) {
+    let fac = this.tris;
+    const V0 = 12;
+    const F0 = 20;
+    for (let j = n - 1; j >= ntarget; j--) {
+      const nVjprev = Math.pow(4, j + 1) * (V0 - 2) + 2;
+      const nVj = Math.pow(4, j) * (V0 - 2) + 2;
+      const nFjprev = fac.length / 3;
+      const nFj = Math.pow(4, j) * F0;
+      console.log(`order ${j + 1} -> ${j} vertices ${nVjprev} -> ${nVj} faces ${nFjprev} -> ${nFj}`);
+      const remap = Array.from({ length: nVjprev }, (_, i) => i + 1);
+      for (let i = 0; i < nFjprev; i++) {
+        const v1 = fac[3 * i];
+        const v2 = fac[3 * i + 1];
+        const v3 = fac[3 * i + 2];
+        remap[v1 - 1] = Math.min(remap[v1 - 1], v2, v3);
+      }
+      const facJ = new Uint32Array(nFj * 3);
+      for (let i = 0; i < nFj; i++) {
+        facJ[3 * i] = remap[fac[3 * i] - 1];
+        facJ[3 * i + 1] = remap[fac[3 * i + 1] - 1];
+        facJ[3 * i + 2] = remap[fac[3 * i + 2] - 1];
+      }
+      fac = facJ;
+    }
+    this.tris = new Uint32Array(fac);
+  }
+  // internal function simplifies FreeSurfer triangulated mesh and overlays
+  decimateHierarchicalMesh(gl, order = 4) {
+    const inputOrder = this.hierarchicalOrder();
+    if (isNaN(inputOrder)) {
+      log.warn("Unable to decimate mesh: it does not have a hierarchical structure");
+      return false;
+    }
+    if (order >= inputOrder) {
+      log.warn(`Unable to decimate mesh: input order (${inputOrder}) must be larger than downsampled order (${order})`);
+      return false;
+    }
+    const inputVLength = this.pts.length / 3;
+    const V0 = 12;
+    const nV = Math.pow(4, order) * (V0 - 2) + 2;
+    this.pts = new Float32Array(this.pts.slice(0, nV * 3));
+    this.decimateFaces(inputOrder, order);
+    if (this.layers && this.layers.length > 0) {
+      for (let i = 0; i < this.layers.length; i++) {
+        const layer = this.layers[i];
+        if (layer.values instanceof Float32Array || layer.values.length !== inputVLength) {
+          layer.values = new Float32Array(layer.values.slice(0, nV));
+        } else {
+          log.warn(`decimation logic needs to be updated`);
+        }
+      }
+    }
+    this.updateMesh(gl);
+    return true;
+  }
   // adjust attributes of a mesh layer. invoked by niivue.setMeshLayerProperty()
   // TODO this method is a bit too generic
   setLayerProperty(id, key, val, gl) {
@@ -18016,7 +18226,7 @@ import { vec3 as vec38, vec4 as vec46 } from "gl-matrix";
 import * as nifti from "nifti-reader-js";
 import daikon from "daikon";
 import { mat3, mat4 as mat44, vec3 as vec37, vec4 as vec45 } from "gl-matrix";
-import { Decompress, decompressSync as decompressSync3, gzipSync } from "fflate/browser";
+import { Decompress, decompressSync as decompressSync3, gzipSync as gzipSync2 } from "fflate/browser";
 import { v4 as uuidv42 } from "@lukeed/uuid";
 
 // src/nvimage/utils.ts
@@ -20875,7 +21085,7 @@ var NVImage = class _NVImage {
     let saveData = null;
     const compress2 = fnm.endsWith(".gz");
     if (compress2) {
-      saveData = gzipSync(odata, {
+      saveData = gzipSync2(odata, {
         // GZIP-specific: the filename to use when decompressed
         filename: fnm,
         // GZIP-specific: the modification time. Can be a Date, date string,
@@ -21338,7 +21548,7 @@ var NVImage = class _NVImage {
    * read a 3D slab of voxels from a volume
    * @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'
+   * @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
    * @see {@link https://niivue.github.io/niivue/features/slab_selection.html | live demo usage}
    */
@@ -21362,7 +21572,7 @@ var NVImage = class _NVImage {
     let dt = this.hdr.datatypeCode;
     if (dataType === "uint8") {
       dt = 2 /* DT_UINT8 */;
-    } else if (dataType === "float32") {
+    } else if (dataType === "float32" || dataType === "scaled" || dataType === "normalized" || dataType === "windowed") {
       dt = 16 /* DT_FLOAT32 */;
     }
     if (dt === 2 /* DT_UINT8 */) {
@@ -21392,6 +21602,24 @@ var NVImage = class _NVImage {
         }
       }
     }
+    if (dataType === "scaled" || dataType === "normalized" || dataType === "windowed") {
+      for (let i2 = 0; i2 < img.length; i2++) {
+        img[i2] = img[i2] * this.hdr.scl_slope + this.hdr.scl_inter;
+      }
+    }
+    if (dataType === "normalized" || dataType === "windowed") {
+      let mn = this.cal_min;
+      let mx = this.cal_max;
+      if (dataType === "normalized") {
+        mn = this.global_min;
+        mx = this.global_max;
+      }
+      const scale = 1 / (mx - mn);
+      for (let i2 = 0; i2 < img.length; i2++) {
+        img[i2] = (img[i2] - mn) * scale;
+        img[i2] = Math.max(Math.min(img[i2], 1), 0);
+      }
+    }
     return [img, slabDims];
   }
   // getVolumeData()
@@ -25966,6 +26194,24 @@ var Niivue = class _Niivue {
     }
     return this.meshes[idx].indexNearestXYZmm(Xmm, Ymm, Zmm);
   }
+  /**
+   * reduce complexity of FreeSurfer mesh
+   * @param mesh - identity of mesh to change
+   * @param order - decimation order 0..6
+   * @example niivue.decimateHierarchicalMesh(niivue.meshes[0].id, 4)
+   * @returns boolean false if mesh is not hierarchical or of lower order
+   * @see {@link https://niivue.github.io/niivue/features/meshes.html | live demo usage}
+   */
+  decimateHierarchicalMesh(mesh, order = 3) {
+    const idx = this.getMeshIndexByID(mesh);
+    if (idx < 0) {
+      log.warn("reverseFaces() id not loaded", mesh);
+      return;
+    }
+    const ret = this.meshes[idx].decimateHierarchicalMesh(this.gl, order);
+    this.updateGLVolume();
+    return ret;
+  }
   /**
    * reverse triangle winding of mesh (swap front and back faces)
    * @param id - identity of mesh to change
@@ -26464,6 +26710,9 @@ var Niivue = class _Niivue {
     this.renderShader.use(this.gl);
     this.gl.uniform3fv(this.renderShader.uniforms.clipLo, this.opts.clipVolumeLow);
     this.gl.uniform3fv(this.renderShader.uniforms.clipHi, this.opts.clipVolumeHigh);
+    this.pickingImageShader.use(this.gl);
+    this.gl.uniform3fv(this.pickingImageShader.uniforms.clipLo, this.opts.clipVolumeLow);
+    this.gl.uniform3fv(this.pickingImageShader.uniforms.clipHi, this.opts.clipVolumeHigh);
     this.drawScene();
   }
   /**
@@ -28765,6 +29014,8 @@ var Niivue = class _Niivue {
     this.pickingImageShader.use(this.gl);
     this.gl.uniform1f(this.pickingImageShader.uniforms.overlays, this.overlays.length);
     this.gl.uniform3fv(this.pickingImageShader.uniforms.texVox, vox);
+    this.gl.uniform3fv(this.pickingImageShader.uniforms.clipLo, this.opts.clipVolumeLow);
+    this.gl.uniform3fv(this.pickingImageShader.uniforms.clipHi, this.opts.clipVolumeHigh);
     let shader = this.sliceMMShader;
     if (this.opts.isV1SliceShader) {
       shader = this.sliceV1Shader;
@@ -32679,6 +32930,7 @@ export {
   NVMeshFromUrlOptions,
   NVMeshLayerDefaults,
   NVMeshLoaders,
+  NVMeshUtilities,
   NVUtilities,
   Niivue,
   SHOW_RENDER,