@niivue/niivue 0.61.0 → 0.62.0

package/build/index.d.ts

@@ -505,6 +505,11 @@ declare class NVImage {
      * Delegates to VolumeUtils.getValue.
      */
     getValue(x: number, y: number, z: number, frame4D?: number, isReadImaginary?: boolean): number;
+    /**
+     * Returns voxel intensities at specific native coordinates.
+     * Delegates to VolumeUtils.getValue.
+     */
+    getValues(x: number, y: number, z: number, frame4D?: number, isReadImaginary?: boolean): number[];
     /**
      * Update options for image
      */
@@ -561,6 +566,34 @@ declare class NVConnectome extends NVMesh {
     static loadConnectomeFromUrl(gl: WebGL2RenderingContext, url: string): Promise<NVConnectome>;
 }
 
+/**
+ * Represents a completed measurement between two points
+ */
+interface CompletedMeasurement {
+    startMM: vec3;
+    endMM: vec3;
+    distance: number;
+    sliceIndex: number;
+    sliceType: SLICE_TYPE;
+    slicePosition: number;
+}
+/**
+ * Represents a completed angle measurement between two lines
+ */
+interface CompletedAngle {
+    firstLineMM: {
+        start: vec3;
+        end: vec3;
+    };
+    secondLineMM: {
+        start: vec3;
+        end: vec3;
+    };
+    angle: number;
+    sliceIndex: number;
+    sliceType: SLICE_TYPE;
+    slicePosition: number;
+}
 /**
  * Slice Type
  * @ignore
@@ -572,6 +605,11 @@ declare enum SLICE_TYPE {
     MULTIPLANAR = 3,
     RENDER = 4
 }
+declare enum PEN_TYPE {
+    PEN = 0,
+    RECTANGLE = 1,
+    ELLIPSE = 2
+}
 declare enum SHOW_RENDER {
     NEVER = 0,
     ALWAYS = 1,
@@ -599,21 +637,22 @@ declare enum DRAG_MODE {
     slicer3D = 4,
     callbackOnly = 5,
     roiSelection = 6,
-    angle = 7
+    angle = 7,
+    crosshair = 8,
+    windowing = 9
 }
-declare enum DRAG_MODE_SECONDARY {
-    none = 0,
-    contrast = 1,
-    measurement = 2,
-    pan = 3,
-    slicer3D = 4,
-    callbackOnly = 5,
-    roiSelection = 6,
-    angle = 7
+interface MouseEventConfig {
+    leftButton: {
+        primary: DRAG_MODE;
+        withShift?: DRAG_MODE;
+        withCtrl?: DRAG_MODE;
+    };
+    rightButton: DRAG_MODE;
+    centerButton: DRAG_MODE;
 }
-declare enum DRAG_MODE_PRIMARY {
-    crosshair = 0,
-    windowing = 1
+interface TouchEventConfig {
+    singleTouch: DRAG_MODE;
+    doubleTouch: DRAG_MODE;
 }
 declare enum COLORMAP_TYPE {
     MIN_TO_MAX = 0,
@@ -640,6 +679,7 @@ type NVConfigOptions = {
     fontColor: Float32List;
     selectionBoxColor: number[];
     clipPlaneColor: number[];
+    paqdUniforms: number[];
     clipThick: number;
     clipVolumeLow: number[];
     clipVolumeHigh: number[];
@@ -664,12 +704,15 @@ type NVConfigOptions = {
     multiplanarShowRender: SHOW_RENDER;
     isRadiologicalConvention: boolean;
     meshThicknessOn2D: number | string;
-    dragMode: DRAG_MODE | DRAG_MODE_SECONDARY;
-    dragModePrimary: DRAG_MODE_PRIMARY;
+    dragMode: DRAG_MODE;
+    dragModePrimary: DRAG_MODE;
+    mouseEventConfig?: MouseEventConfig;
+    touchEventConfig?: TouchEventConfig;
     yoke3Dto2DZoom: boolean;
     isDepthPickMesh: boolean;
     isCornerOrientationText: boolean;
     isOrientationTextVisible: boolean;
+    showAllOrientationMarkers: boolean;
     heroImageFraction: number;
     heroSliceType: SLICE_TYPE;
     sagittalNoseLeft: boolean;
@@ -682,6 +725,7 @@ type NVConfigOptions = {
     dragAndDropEnabled: boolean;
     drawingEnabled: boolean;
     penValue: number;
+    penType: PEN_TYPE;
     floodFillNeighbors: number;
     isFilledPen: boolean;
     thumbnail: string;
@@ -781,6 +825,8 @@ type DocumentData = {
     sceneData?: Partial<SceneData>;
     connectomes?: string[];
     customData?: string;
+    completedMeasurements?: CompletedMeasurement[];
+    completedAngles?: CompletedAngle[];
 };
 type ExportDocumentData = {
     encodedImageBlobs: string[];
@@ -794,6 +840,8 @@ type ExportDocumentData = {
     labels: NVLabel3D[];
     connectomes: string[];
     customData: string;
+    completedMeasurements: CompletedMeasurement[];
+    completedAngles: CompletedAngle[];
 };
 /**
  * Creates and instance of NVDocument
@@ -808,6 +856,8 @@ declare class NVDocument {
     drawBitmap: Uint8Array | null;
     imageOptionsMap: Map<any, any>;
     meshOptionsMap: Map<any, any>;
+    completedMeasurements: CompletedMeasurement[];
+    completedAngles: CompletedAngle[];
     private _optsProxy;
     private _optsChangeCallback;
     constructor();
@@ -888,8 +938,9 @@ declare class NVDocument {
      *
      * @param embedImages  If false, encodedImageBlobs is left empty
      *                     (imageOptionsArray still records the URL / name).
+     * @param embedDrawing  If false, encodedDrawingBlob is left empty
      */
-    json(embedImages?: boolean): ExportDocumentData;
+    json(embedImages?: boolean, embedDrawing?: boolean): ExportDocumentData;
     download(fileName: string, compress: boolean, opts?: {
         embedImages: boolean;
     }): Promise<void>;
@@ -1571,6 +1622,8 @@ type UIData = {
     max3D?: number;
     windowX: number;
     windowY: number;
+    activeDragMode: DRAG_MODE | null;
+    activeDragButton: number | null;
     angleFirstLine: number[];
     angleState: 'none' | 'drawing_first_line' | 'drawing_second_line' | 'complete';
 };
@@ -1609,9 +1662,11 @@ declare class Niivue {
     useCustomGradientTexture: boolean;
     renderGradientValues: boolean;
     drawTexture: WebGLTexture | null;
+    paqdTexture: WebGLTexture | null;
     drawUndoBitmaps: Uint8Array[];
     drawLut: LUT;
     drawOpacity: number;
+    drawRimOpacity: number;
     clickToSegmentIsGrowing: boolean;
     clickToSegmentGrowingBitmap: Uint8Array | null;
     clickToSegmentXY: number[];
@@ -1621,6 +1676,8 @@ declare class Niivue {
     drawPenAxCorSag: number;
     drawFillOverwrites: boolean;
     drawPenFillPts: number[][];
+    drawShapeStartLocation: number[];
+    drawShapePreviewBitmap: Uint8Array | null;
     overlayTexture: WebGLTexture | null;
     overlayTextureID: WebGLTexture | null;
     sliceMMShader?: Shader;
@@ -1641,6 +1698,7 @@ declare class Niivue {
     pickingMeshShader?: Shader;
     pickingImageShader?: Shader;
     colorbarShader?: Shader;
+    customSliceShader: Shader | null;
     fontShader: Shader | null;
     fiberShader?: Shader;
     fontTexture: WebGLTexture | null;
@@ -1657,6 +1715,7 @@ declare class Niivue {
     orientShaderI: Shader | null;
     orientShaderF: Shader | null;
     orientShaderRGBU: Shader | null;
+    orientShaderPAQD: Shader | null;
     surfaceShader: Shader | null;
     blurShader: Shader | null;
     sobelBlurShader: Shader | null;
@@ -2113,20 +2172,38 @@ declare class Niivue {
      */
     mouseDownListener(e: MouseEvent): void;
     /**
-     * Handles left mouse button actions for crosshair or windowing mode.
+     * Gets the appropriate drag mode for a mouse button based on configuration.
+     * @internal
+     */
+    getMouseButtonDragMode(button: number, shiftKey: boolean, ctrlKey: boolean): DRAG_MODE;
+    /**
+     * Gets the appropriate drag mode for touch events based on configuration.
      * @internal
      */
-    mouseLeftButtonHandler(e: MouseEvent): void;
+    getTouchDragMode(isDoubleTouch: boolean): DRAG_MODE;
     /**
-     * Handles center mouse button drag to initiate 2D panning or clip plane adjustment.
+     * Sets the active drag mode for the current interaction.
      * @internal
      */
-    mouseCenterButtonHandler(e: MouseEvent): void;
+    setActiveDragMode(button: number, shiftKey: boolean, ctrlKey: boolean): void;
     /**
-     * Handles right mouse button drag to enable 2D panning or clip plane control.
+     * Gets the currently active drag mode, or falls back to configured defaults.
      * @internal
      */
-    mouseRightButtonHandler(e: MouseEvent): void;
+    getCurrentDragMode(): DRAG_MODE;
+    /**
+     * Clears the active drag mode.
+     * @internal
+     */
+    clearActiveDragMode(): void;
+    /**
+     * Unified handler for mouse actions based on drag mode.
+     * @internal
+     */
+    handleMouseAction(dragMode: DRAG_MODE, e: MouseEvent, pos: {
+        x: number;
+        y: number;
+    }): void;
     /**
      * calculate the the min and max voxel indices from an array of two values (used in selecting intensities with the selection box)
      * @internal
@@ -2362,6 +2439,12 @@ declare class Niivue {
      * @see {@link https://niivue.com/demos/features/basic.multiplanar.html | live demo usage}
      */
     setIsOrientationTextVisible(isOrientationTextVisible: boolean): void;
+    /**
+     * Show or hide all four orientation labels (e.g., L/R, A/P, S/I) in 2D slice views
+     * @param showAllOrientationMarkers - whether all four orientation markers should be displayed
+     * @example niivue.setShowAllOrientationMarkers(true)
+     */
+    setShowAllOrientationMarkers(showAllOrientationMarkers: boolean): void;
     /**
      * determine proportion of screen real estate devoted to rendering in multiplanar view.
      * @param fraction - proportion of screen devoted to primary (hero) image (0 to disable)
@@ -3097,6 +3180,16 @@ declare class Niivue {
      * @internal
      */
     drawPenLine(ptA: number[], ptB: number[], penValue: number): void;
+    /**
+     * Draw a rectangle from point A to point B
+     * @internal
+     */
+    drawRectangleMask(ptA: number[], ptB: number[], penValue: number): void;
+    /**
+     * Draw an ellipse from point A to point B (treating them as opposite corners of bounding box)
+     * @internal
+     */
+    drawEllipseMask(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.
      *
@@ -3139,6 +3232,12 @@ declare class Niivue {
      * @see {@link https://niivue.com/demos/features/cactus.html | live demo usage}
      */
     refreshDrawing(isForceRedraw?: boolean, useClickToSegmentBitmap?: boolean): void;
+    /**
+     * close probabilistic atlas texture
+     * @example niivue.closePAQD();
+     * @internal
+     */
+    closePAQD(): void;
     /**
      * Creates a 2D 1-component uint8 texture on the GPU with given dimensions.
      * @internal
@@ -3289,6 +3388,13 @@ declare class Niivue {
         Frag: string;
         shader: Shader;
     };
+    /**
+     * Install a special shader for 2D slice views
+     * @param fragmentShaderText - custom fragment shader.
+     * @if not text is provided, the default shader will be used
+     * @internal
+     */
+    setCustomSliceShader(fragmentShaderText?: string): void;
     /**
      * Define a new GLSL shader program to influence mesh coloration
      * @param fragmentShaderText - the GLSL source code for the custom fragment shader
@@ -3713,6 +3819,17 @@ declare class Niivue {
      * @internal
      */
     drawAngleText(): void;
+    /**
+     * Calculate and draw angle text for a completed angle.
+     * @internal
+     */
+    drawAngleTextForAngle(angle: {
+        firstLine: number[];
+        secondLine: number[];
+        sliceIndex: number;
+        sliceType: SLICE_TYPE;
+        slicePosition: number;
+    }): void;
     /**
      * Calculate angle between two lines in degrees.
      * @internal
@@ -3723,11 +3840,93 @@ declare class Niivue {
      * @internal
      */
     resetAngleMeasurement(): void;
+    /**
+     * Get slice information for the current measurement/angle.
+     * @internal
+     */
+    getCurrentSliceInfo(): {
+        sliceIndex: number;
+        sliceType: SLICE_TYPE;
+        slicePosition: number;
+    };
+    /**
+     * Get the current slice position based on slice type.
+     * @internal
+     */
+    getCurrentSlicePosition(sliceType: SLICE_TYPE): number;
+    /**
+     * Check if a measurement/angle should be drawn on the current slice.
+     * @internal
+     */
+    shouldDrawOnCurrentSlice(sliceIndex: number, sliceType: SLICE_TYPE, slicePosition: number): boolean;
+    /**
+     * Clear all persistent measurement lines from the canvas.
+     * @example
+     * ```js
+     * nv.clearMeasurements()
+     * ```
+     */
+    clearMeasurements(): void;
+    /**
+     * Clear all persistent angle measurements from the canvas.
+     * @example
+     * ```js
+     * nv.clearAngles()
+     * ```
+     */
+    clearAngles(): void;
+    /**
+     * Clear all persistent measurements and angles from the canvas.
+     * @example
+     * ```js
+     * nv.clearAllMeasurements()
+     * ```
+     */
+    clearAllMeasurements(): void;
     /**
      * Set the drag mode for mouse interactions.
      * @param mode - The drag mode to set ('none', 'contrast', 'measurement', 'angle', 'pan', 'slicer3D', 'callbackOnly', 'roiSelection')
      */
     setDragMode(mode: string | DRAG_MODE): void;
+    /**
+     * Set custom mouse event configuration for button mappings.
+     * @param config - Mouse event configuration object
+     * @example
+     * ```js
+     * nv.setMouseEventConfig({
+     *   leftButton: {
+     *     primary: DRAG_MODE.windowing,
+     *     withShift: DRAG_MODE.measurement,
+     *     withCtrl: DRAG_MODE.crosshair
+     *   },
+     *   rightButton: DRAG_MODE.crosshair,
+     *   centerButton: DRAG_MODE.pan
+     * })
+     * ```
+     */
+    setMouseEventConfig(config: MouseEventConfig): void;
+    /**
+     * Set custom touch event configuration for touch gesture mappings.
+     * @param config - Touch event configuration object
+     * @example
+     * ```js
+     * nv.setTouchEventConfig({
+     *   singleTouch: DRAG_MODE.windowing,
+     *   doubleTouch: DRAG_MODE.pan
+     * })
+     * ```
+     */
+    setTouchEventConfig(config: TouchEventConfig): void;
+    /**
+     * Get current mouse event configuration.
+     * @returns Current mouse event configuration or undefined if using defaults
+     */
+    getMouseEventConfig(): MouseEventConfig | undefined;
+    /**
+     * Get current touch event configuration.
+     * @returns Current touch event configuration or undefined if using defaults
+     */
+    getTouchEventConfig(): TouchEventConfig | undefined;
     /**
      * Draw a rectangle or outline at given position with specified color or default crosshair color.
      * @internal
@@ -3844,6 +4043,11 @@ declare class Niivue {
      * @internal
      */
     drawTextBelow(xy: number[], str: string, scale?: number, color?: number[] | null): void;
+    /**
+     * Draw text horizontally centered above the given coordinates.
+     * @internal
+     */
+    drawTextAbove(xy: number[], str: string, scale?: number, color?: number[] | null): void;
     /**
      * Update texture interpolation mode (nearest or linear) for background or overlay layer.
      * @internal
@@ -4075,6 +4279,21 @@ declare class Niivue {
      * @internal
      */
     canvasPos2frac(canvasPos: number[]): vec3;
+    /**
+     * Convert fractional volume coordinates to canvas pixel coordinates.
+     * Returns the first valid screen slice that contains the fractional coordinates.
+     * @internal
+     */
+    /**
+     * Convert fractional volume coordinates to canvas pixel coordinates with tile information.
+     * Returns both canvas position and the tile index for validation.
+     * @internal
+     */
+    frac2canvasPosWithTile(frac: vec3, preferredSliceType?: SLICE_TYPE): {
+        pos: number[];
+        tileIndex: number;
+    } | null;
+    frac2canvasPos(frac: vec3): number[] | null;
     /**
      * Calculates scaled slice dimensions and position within the canvas.
      * n.b. beware of similarly named `sliceScale` method.
@@ -4151,6 +4370,29 @@ declare class Niivue {
      * @internal
      */
     set gl(gl: WebGL2RenderingContext | null);
+    /**
+     * Find the first and last slices containing drawing data along a given axis
+     * @param sliceType - The slice orientation (AXIAL, CORONAL, or SAGITTAL)
+     * @returns Object containing first and last slice indices, or null if no data found
+     */
+    findDrawingBoundarySlices(sliceType: SLICE_TYPE): {
+        first: number;
+        last: number;
+    } | null;
+    /**
+     * Interpolate between mask slices using geometric or intensity-guided methods
+     * @param sliceIndexLow - Lower slice index (optional, will auto-detect if not provided)
+     * @param sliceIndexHigh - Higher slice index (optional, will auto-detect if not provided)
+     * @param options - Interpolation options
+     */
+    interpolateMaskSlices(sliceIndexLow?: number, sliceIndexHigh?: number, options?: {
+        intensityWeight?: number;
+        binaryThreshold?: number;
+        intensitySigma?: number;
+        applySmoothingToSlices?: boolean;
+        useIntensityGuided?: boolean;
+        sliceType?: SLICE_TYPE;
+    }): void;
 }
 
-export { COLORMAP_TYPE, type Connectome, type ConnectomeOptions, DEFAULT_OPTIONS, DRAG_MODE, DRAG_MODE_PRIMARY, DRAG_MODE_SECONDARY, type DicomLoader, type DicomLoaderInput, type DocumentData, type DragReleaseParams, type ExportDocumentData, INITIAL_SCENE_DATA, LabelAnchorPoint, LabelLineTerminator, LabelTextAlignment, type LegacyConnectome, type LegacyNodes, MULTIPLANAR_TYPE, type NVConfigOptions, type NVConnectomeEdge, type NVConnectomeNode, 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 };
+export { COLORMAP_TYPE, type CompletedAngle, type CompletedMeasurement, type Connectome, type ConnectomeOptions, DEFAULT_OPTIONS, DRAG_MODE, type DicomLoader, type DicomLoaderInput, type DocumentData, type DragReleaseParams, type ExportDocumentData, INITIAL_SCENE_DATA, LabelAnchorPoint, LabelLineTerminator, LabelTextAlignment, type LegacyConnectome, type LegacyNodes, MULTIPLANAR_TYPE, type MouseEventConfig, type NVConfigOptions, type NVConnectomeEdge, type NVConnectomeNode, NVDocument, NVImage, NVImageFromUrlOptions, NVLabel3D, NVLabel3DStyle, NVMesh, NVMeshFromUrlOptions, NVMeshLayerDefaults, NVMeshLoaders, NVMeshUtilities, NVUtilities, type NiftiHeader, type NiiVueLocation, type NiiVueLocationValue, Niivue, PEN_TYPE, type Point, SHOW_RENDER, SLICE_TYPE, type Scene, type SyncOpts, type TouchEventConfig, type Volume, cmapper, ColorTables as colortables };