@niivue/niivue 0.44.0 → 0.44.2-dev.1

package/dist/index.d.ts

@@ -107,6 +107,18 @@ declare enum LabelLineTerminator {
     CIRCLE = "circle",
     RING = "ring"
 }
+declare enum LabelAnchorPoint {
+    NONE = 0,
+    TOPLEFT = 9,
+    TOPCENTER = 10,
+    TOPRIGHT = 12,
+    MIDDLELEFT = 17,
+    MIDDLECENTER = 18,
+    MIDDLERIGHT = 20,
+    BOTTOMLEFT = 33,
+    BOTTOMCENTER = 34,
+    BOTTOMRIGHT = 36
+}
 /**
  * Class representing label style.
  * @ignore
@@ -140,12 +152,14 @@ declare class NVLabel3D {
     text: string;
     style: NVLabel3DStyle;
     points?: number[] | number[][];
+    anchor: LabelAnchorPoint;
+    onClick?: (label: NVLabel3D) => 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[][]);
+    constructor(text: string, style: NVLabel3DStyle, points?: number[] | number[][], anchor?: LabelAnchorPoint, onClick?: (label: NVLabel3D) => void);
 }
 
 /**
@@ -437,7 +451,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}
      */
@@ -584,7 +598,8 @@ declare enum DRAG_MODE {
     measurement = 2,
     pan = 3,
     slicer3D = 4,
-    callbackOnly = 5
+    callbackOnly = 5,
+    roiSelection = 6
 }
 /**
  * NVConfigOptions
@@ -619,6 +634,7 @@ type NVConfigOptions = {
     isOrientCube: boolean;
     multiplanarPadPixels: number;
     multiplanarForceRender: boolean;
+    multiplanarEqualSize: boolean;
     multiplanarShowRender: SHOW_RENDER;
     isRadiologicalConvention: boolean;
     meshThicknessOn2D: number | string;
@@ -653,13 +669,21 @@ type NVConfigOptions = {
     renderOverlayBlend: number;
     sliceMosaicString: string;
     centerMosaic: boolean;
+    penSize: number;
     clickToSegment: boolean;
     clickToSegmentRadius: number;
-    clickToSegmentSteps: number;
     clickToSegmentBright: boolean;
+    clickToSegmentAutoIntensity: boolean;
+    clickToSegmentIntensityMax: number;
+    clickToSegmentIntensityMin: number;
+    clickToSegmentPercent: number;
+    clickToSegmentMaxDistanceMM: number;
+    selectionBoxLineThickness: number;
+    selectionBoxIsOutline: boolean;
 };
 declare const DEFAULT_OPTIONS: NVConfigOptions;
 type SceneData = {
+    gamma: number;
     azimuth: number;
     elevation: number;
     crosshairPos: vec3;
@@ -672,6 +696,7 @@ type SceneData = {
     clipVolumeHigh: number[];
 };
 declare const INITIAL_SCENE_DATA: {
+    gamma: number;
     azimuth: number;
     elevation: number;
     crosshairPos: vec3;
@@ -696,6 +721,7 @@ type Scene = {
     pan2Dxyzmm: vec4;
     _elevation?: number;
     _azimuth?: number;
+    gamma?: number;
 };
 type DocumentData = {
     title: string;
@@ -958,6 +984,18 @@ type NiiVueLocation = {
     vox: vec3;
     xy: [number, number];
 };
+type SyncOpts = {
+    '3d'?: boolean;
+    '2d'?: boolean;
+    zoomPan?: boolean;
+    cal_min?: boolean;
+    cal_max?: boolean;
+    gamma?: boolean;
+    useSliceOffset?: boolean;
+    sliceType?: boolean;
+    crosshair?: boolean;
+    clipPlane?: boolean;
+};
 
 type ValuesArray = Array<{
     id: string;
@@ -1191,6 +1229,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;
@@ -1503,6 +1544,7 @@ declare class NVMeshLoaders {
     static readLayer(name: string, buffer: ArrayBuffer, nvmesh: NVMesh, opacity?: number, colormap?: string, colormapNegative?: string, useNegativeCmap?: boolean, cal_min?: number | null, cal_max?: number | null, outlineBorder?: number): NVMeshLayer | undefined;
     static readSMP(buffer: ArrayBuffer, n_vert: number): Float32Array;
     static readSTC(buffer: ArrayBuffer, n_vert: number): Float32Array;
+    static isCurv(buffer: ArrayBuffer): boolean;
     static readCURV(buffer: ArrayBuffer, n_vert: number): Float32Array;
     static readANNOT(buffer: ArrayBuffer, n_vert: number, isReadColortables?: boolean): ANNOT;
     static readNV(buffer: ArrayBuffer): DefaultMeshType;
@@ -1520,6 +1562,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 +1570,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;
@@ -1569,6 +1632,7 @@ type Descriptive = {
     cal_max: number;
     robust_min: number;
     robust_max: number;
+    area: number | null;
 };
 type SliceScale = {
     volScale: number[];
@@ -1653,6 +1717,7 @@ declare class Niivue {
     orientCubeShader?: Shader;
     orientCubeShaderVAO: WebGLVertexArrayObject | null;
     rectShader?: Shader;
+    rectOutlineShader?: Shader;
     renderShader?: Shader;
     lineShader?: Shader;
     line3DShader?: Shader;
@@ -1697,7 +1762,7 @@ declare class Niivue {
     extentsMin?: vec3;
     extentsMax?: vec3;
     private resizeObserver;
-    syncOpts: Record<string, unknown>;
+    syncOpts: SyncOpts;
     readyForSync: boolean;
     uiData: UIData;
     back: NVImage | null;
@@ -1718,7 +1783,7 @@ declare class Niivue {
         screen2frac?: number[];
     }>;
     cuboidVertexBuffer?: WebGLBuffer;
-    otherNV: Niivue | Niivue[] | null;
+    otherNV: Niivue[] | null;
     volumeObject3D: NiivueObject3D | null;
     pivot3D: number[];
     furthestFromPivot: number;
@@ -1973,7 +2038,7 @@ declare class Niivue {
      * @deprecated use broadcastTo instead
      * @see {@link https://niivue.github.io/niivue/features/sync.mesh.html | live demo usage}
      */
-    syncWith(otherNV: Niivue, syncOpts?: {
+    syncWith(otherNV: Niivue | Niivue[], syncOpts?: {
         '2d': boolean;
         '3d': boolean;
     }): void;
@@ -1992,6 +2057,15 @@ declare class Niivue {
         '2d': boolean;
         '3d': boolean;
     }): void;
+    doSync3d(otherNV: Niivue): void;
+    doSync2d(otherNV: Niivue): void;
+    doSyncGamma(otherNV: Niivue): void;
+    doSyncZoomPan(otherNV: Niivue): void;
+    doSyncCrosshair(otherNV: Niivue): void;
+    doSyncCalMin(otherNV: Niivue): void;
+    doSyncCalMax(otherNV: Niivue): void;
+    doSyncSliceType(otherNV: Niivue): void;
+    doSyncClipPlane(otherNV: Niivue): void;
     /**
      * Sync the scene controls (orientation, crosshair location, etc.) from one Niivue instance to another. useful for using one canvas to drive another.
      * @internal
@@ -2264,6 +2338,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
@@ -2643,9 +2726,17 @@ declare class Niivue {
     drawGrowCut(): void;
     drawPt(x: number, y: number, z: number, penValue: number): 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.
+     *
+     * @param seedXYZ -  voxel index of the seed voxel in the mask array.
+     * @param neighbors - Number of neighbors to consider for connectivity and dilation (6, 18, or 26).
+     */
+    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): void;
+    forceMin?: number, forceMax?: number, neighbors?: number, maxDistanceMM?: number): void;
     drawPenFilled(): void;
     /**
      * close drawing: make sure you have saved any changes before calling this!
@@ -2774,13 +2865,33 @@ declare class Niivue {
     updateGLVolume(): void;
     /**
      * basic statistics for selected voxel-based image
-     * @param layer - selects image to describe
-     * @param masks - are optional binary images to filter voxles
-     * @returns numeric values to describe image
-     * @example niivue.getDescriptives(0);
+     * @param options - 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
+     * @returns 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 {@link https://niivue.github.io/niivue/features/draw2.html | live demo usage}
      */
-    getDescriptives(layer?: number, masks?: any[], drawingIsMask?: boolean): Descriptive;
+    getDescriptives(options: {
+        layer?: number;
+        masks?: number[];
+        drawingIsMask?: boolean;
+        roiIsMask?: boolean;
+        startVox?: number[];
+        endVox?: number[];
+    }): Descriptive;
     refreshLayers(overlayItem: NVImage, layer: number): void;
     /**
      * query all available color maps that can be applied to volumes
@@ -2912,6 +3023,7 @@ declare class Niivue {
     effectiveCanvasHeight(): number;
     effectiveCanvasWidth(): number;
     getAllLabels(): NVLabel3D[];
+    getConnectomeLabels(): NVLabel3D[];
     getBulletMarginWidth(): number;
     getLegendPanelWidth(): number;
     getLegendPanelHeight(): number;
@@ -2943,9 +3055,10 @@ declare class Niivue {
     screenFieldOfViewMM(axCorSag?: number, forceSliceMM?: boolean): vec3;
     screenFieldOfViewExtendedVox(axCorSag?: number): MM;
     screenFieldOfViewExtendedMM(axCorSag?: number): MM;
-    drawSliceOrientationText(leftTopWidthHeight: number[], axCorSag: SLICE_TYPE): void;
+    drawSliceOrientationText(leftTopWidthHeight: number[], axCorSag: SLICE_TYPE, padLeftTop?: number[]): void;
     xyMM2xyzMM(axCorSag: SLICE_TYPE, sliceFrac: number): number[];
-    draw2D(leftTopWidthHeight: number[], axCorSag: SLICE_TYPE, customMM?: number): void;
+    draw2DMain(leftTopWidthHeight: number[], axCorSag: SLICE_TYPE, customMM?: number): void;
+    draw2D(leftTopWidthHeight: number[], axCorSag: SLICE_TYPE, customMM?: number, imageWidthHeight?: number[]): void;
     calculateMvpMatrix(_unused: unknown, leftTopWidthHeight: number[], azimuth: number, elevation: number): mat4[];
     calculateModelMatrix(azimuth: number, elevation: number): mat4;
     calculateRayDirection(azimuth: number, elevation: number): vec3;
@@ -2964,12 +3077,13 @@ declare class Niivue {
      * @param style - label style
      * @param point - 3D point on the model
      */
-    addLabel(text: string, style: NVLabel3DStyle, points?: number[] | number[][]): NVLabel3D;
+    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;
     getLabelAtPoint(screenPoint: [number, number]): NVLabel3D | null;
     drawLabelLine(label: NVLabel3D, pos: vec2, mvpMatrix: mat4, leftTopWidthHeight: number[], secondPass?: boolean): void;
-    draw3DLabel(label: NVLabel3D, pos: vec2, mvpMatrix: mat4, leftTopWidthHeight: number[], bulletMargin: number, legendWidth: number, secondPass?: boolean): void;
+    draw3DLabel(label: NVLabel3D, pos: vec2, mvpMatrix?: mat4, leftTopWidthHeight?: number[], bulletMargin?: number, legendWidth?: number, secondPass?: boolean): void;
     draw3DLabels(mvpMatrix: mat4, leftTopWidthHeight: number[], secondPass?: boolean): void;
+    drawAnchoredLabels(): void;
     draw3D(leftTopWidthHeight?: number[], mvpMatrix?: mat4 | null, modelMatrix?: mat4 | null, normalMatrix?: mat4 | null, azimuth?: number | null, elevation?: number): string | undefined;
     drawMesh3D(isDepthTest?: boolean, alpha?: number, m?: mat4, modelMtx?: mat4, normMtx?: mat4): void;
     drawCrosshairs3D(isDepthTest?: boolean, alpha?: number, mvpMtx?: mat4 | null, is2DView?: boolean, isSliceMM?: boolean): void;
@@ -3009,4 +3123,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, LabelAnchorPoint, 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 SyncOpts, type Volume, cmapper, ColorTables as colortables };