copper3d 3.0.1 → 3.0.2

package/dist/index.d.ts

@@ -17,10 +17,13 @@ import { Copper3dTrackballControls } from "./Controls/Copper3dTrackballControls"
 import { MeshNodeTool } from "./Utils/MeshNodeTool";
 import { removeGuiFolderChilden } from "./Utils/segmentation/coreTools/gui";
 import { nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, exportPaintImageType, IOptVTKLoader } from "./types/types";
-import { IPaintImage, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates } from "./Utils/segmentation/coreTools/coreType";
+import { IPaintImage, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, IGuiMeta } from "./Utils/segmentation/coreTools/coreType";
+import { NrrdState } from "./Utils/segmentation/coreTools/NrrdState";
+import { GuiState } from "./Utils/segmentation/coreTools/GuiState";
+import type { ToolMode, IAnnotationCallbacks } from "./Utils/segmentation/coreTools/coreType";
 import { CHANNEL_COLORS, CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss } from "./Utils/segmentation/core/index";
 import type { LayerId, ChannelValue } from "./Utils/segmentation/core/index";
 import "./css/style.css";
-export declare const REVISION = "v3.0.1-beta";
+export declare const REVISION = "v3.0.2-beta";
 export { copperRenderer, copperRendererOnDemond, copperMSceneRenderer, setHDRFilePath, addLabelToScene, convert3DPostoScreenPos, convertScreenPosto3DPos, addBoxHelper, fullScreenListenner, configKiwriousHeart, copperScene, copperSceneOnDemond, copperMScene, CameraViewPoint, kiwrious, NrrdTools, loading, Copper3dTrackballControls, createTexture2D_NRRD, MeshNodeTool, throttle, removeGuiFolderChilden, CHANNEL_COLORS, CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, };
-export type { positionType, screenPosType, optsType, nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, IPaintImage, exportPaintImageType, IOptVTKLoader, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, LayerId, ChannelValue, };
+export type { positionType, screenPosType, optsType, nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, IPaintImage, exportPaintImageType, IOptVTKLoader, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, NrrdState, GuiState, IGuiMeta, ToolMode, IAnnotationCallbacks, LayerId, ChannelValue, };

package/dist/index.js

@@ -20,7 +20,7 @@ import { MeshNodeTool } from "./Utils/MeshNodeTool";
 import { removeGuiFolderChilden } from "./Utils/segmentation/coreTools/gui";
 import { CHANNEL_COLORS, CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss } from "./Utils/segmentation/core/index";
 import "./css/style.css";
-export const REVISION = "v3.0.1-beta";
+export const REVISION = "v3.0.2-beta";
 console.log(`%cCopper3D Visualisation %cBeta:${REVISION}`, "padding: 3px;color:white; background:#023047", "padding: 3px;color:white; background:#f50a25");
 export { copperRenderer, copperRendererOnDemond, copperMSceneRenderer, setHDRFilePath, addLabelToScene, convert3DPostoScreenPos, convertScreenPosto3DPos, addBoxHelper, fullScreenListenner, configKiwriousHeart, copperScene, copperSceneOnDemond, copperMScene, CameraViewPoint, kiwrious, NrrdTools, loading, Copper3dTrackballControls, createTexture2D_NRRD, MeshNodeTool, throttle, removeGuiFolderChilden, CHANNEL_COLORS, CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EACL,eAAe,EAGf,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAY,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,QAAQ,MAAM,iCAAiC,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,iDAAiD;AAEjD,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAc5E,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAG3G,OAAO,iBAAiB,CAAC;AAEzB,MAAM,CAAC,MAAM,QAAQ,GAAG,aAAa,CAAC;AAEtC,OAAO,CAAC,GAAG,CACT,mCAAmC,QAAQ,EAAE,EAC7C,8CAA8C,EAC9C,8CAA8C,CAC/C,CAAC;AAEF,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,SAAS,EACT,OAAO,EACP,yBAAyB,EACzB,oBAAoB,EACpB,YAAY,EACZ,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,kBAAkB,EAClB,SAAS,EACT,SAAS,GACV,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EACL,eAAe,EAGf,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAY,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,QAAQ,MAAM,iCAAiC,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,iDAAiD;AAEjD,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAiB5E,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAG3G,OAAO,iBAAiB,CAAC;AAEzB,MAAM,CAAC,MAAM,QAAQ,GAAG,aAAa,CAAC;AAEtC,OAAO,CAAC,GAAG,CACT,mCAAmC,QAAQ,EAAE,EAC7C,8CAA8C,EAC9C,8CAA8C,CAC/C,CAAC;AAEF,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,SAAS,EACT,OAAO,EACP,yBAAyB,EACzB,oBAAoB,EACpB,YAAY,EACZ,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,kBAAkB,EAClB,SAAS,EACT,SAAS,GACV,CAAC"}

package/dist/types/Utils/segmentation/CommToolsData.d.ts

@@ -1,18 +1,22 @@
-import { IProtected, IGUIStates, INrrdStates, ICursorPage, IConvertObjType, INewMaskData, IKeyBoardSettings } from "./coreTools/coreType";
+import { IProtected, ICursorPage, IConvertObjType, INewMaskData, IKeyBoardSettings, IAnnotationCallbacks } from "./coreTools/coreType";
+import { NrrdState } from "./coreTools/NrrdState";
+import { GuiState } from "./coreTools/GuiState";
 import { MaskVolume } from "./core/index";
 export declare class CommToolsData {
     baseCanvasesSize: number;
     private _reusableSliceBuffer;
     private _reusableBufferWidth;
     private _reusableBufferHeight;
+    /** External annotation callbacks — set via draw() options */
+    protected annotationCallbacks: IAnnotationCallbacks;
     /** Whether the keyboard-config dialog is open (suppresses all shortcuts). */
     protected _configKeyBoard: boolean;
     /** Active keyboard shortcut bindings. */
     protected _keyboardSettings: IKeyBoardSettings;
-    nrrd_states: INrrdStates;
-    cursorPage: ICursorPage;
-    gui_states: IGUIStates;
-    protectedData: IProtected;
+    protected nrrd_states: NrrdState;
+    protected cursorPage: ICursorPage;
+    protected gui_states: GuiState;
+    protected protectedData: IProtected;
     constructor(container: HTMLElement, mainAreaContainer: HTMLElement, options?: {
         layers?: string[];
     });
@@ -56,9 +60,9 @@ export declare class CommToolsData {
     private generateSystemCanvases;
     private generateLayerTargets;
     /**
-     * Rewrite this {clearPaint} function under DrawToolCore
+     * Rewrite this {clearActiveSlice} function under DrawToolCore
      */
-    clearPaint(): void;
+    clearActiveSlice(): void;
     /**
      * Rewrite this {undoLastPainting} function under DrawToolCore
      */
@@ -68,9 +72,9 @@ export declare class CommToolsData {
      */
     redoLastPainting(): void;
     /**
-     * Rewrite this {clearStoreImages} function under NrrdTools
+     * Rewrite this {clearActiveLayer} function under NrrdTools
      */
-    clearStoreImages(): void;
+    clearActiveLayer(): void;
     /**
      * Rewrite this {resizePaintArea} function under NrrdTools
      */
@@ -103,6 +107,17 @@ export declare class CommToolsData {
      * Rewrite this {resetLayerCanvas} function under NrrdTools
      */
     resetLayerCanvas(): void;
+    /**
+     * Enter sphere mode: clear all layer canvases (not MaskVolume),
+     * hide all mask data so sphere overlay is the only visible annotation.
+     * Rewrite this under NrrdTools.
+     */
+    enterSphereMode(): void;
+    /**
+     * Exit sphere mode: clear sphere canvas overlay, reload all layer
+     * MaskVolume data back onto canvases. Rewrite this under NrrdTools.
+     */
+    exitSphereMode(): void;
     /**
      * Rewrite this {setSyncsliceNum} function under NrrdTools
      */

package/dist/types/Utils/segmentation/DragOperator.d.ts

@@ -1,4 +1,6 @@
-import { IDragOpts, IDrawingEvents, IProtected, IGUIStates, INrrdStates } from "./coreTools/coreType";
+import { IDragOpts, IDrawingEvents, IProtected } from "./coreTools/coreType";
+import { NrrdState } from "./coreTools/NrrdState";
+import { GuiState } from "./coreTools/GuiState";
 import type { EventRouter } from "./eventRouter";
 export declare class DragOperator {
     container: HTMLElement;
@@ -16,10 +18,16 @@ export declare class DragOperator {
     private setEmptyCanvasSize;
     private getOrCreateSliceBuffer;
     private renderSliceToCanvas;
+    private refreshSphereOverlayCb;
     private eventRouter;
-    constructor(container: HTMLElement, nrrd_sates: INrrdStates, gui_states: IGUIStates, protectedData: IProtected, drawingPrameters: IDrawingEvents, setSyncsliceNum: () => void, setIsDrawFalse: (target: number) => void, flipDisplayImageByAxis: () => void, setEmptyCanvasSize: (axis?: "x" | "y" | "z") => void, getOrCreateSliceBuffer: (axis: "x" | "y" | "z") => ImageData | null, renderSliceToCanvas: (layer: string, axis: "x" | "y" | "z", sliceIndex: number, buffer: ImageData, targetCtx: CanvasRenderingContext2D, scaledWidth: number, scaledHeight: number) => void);
+    constructor(container: HTMLElement, nrrd_sates: NrrdState, gui_states: GuiState, protectedData: IProtected, drawingPrameters: IDrawingEvents, setSyncsliceNum: () => void, setIsDrawFalse: (target: number) => void, flipDisplayImageByAxis: () => void, setEmptyCanvasSize: (axis?: "x" | "y" | "z") => void, getOrCreateSliceBuffer: (axis: "x" | "y" | "z") => ImageData | null, renderSliceToCanvas: (layer: string, axis: "x" | "y" | "z", sliceIndex: number, buffer: ImageData, targetCtx: CanvasRenderingContext2D, scaledWidth: number, scaledHeight: number) => void);
     private init;
     setShowDragNumberDiv(sliceIndexContainer: HTMLDivElement): void;
+    /**
+     * Set the sphere overlay refresh callback.
+     * Called by NrrdTools after DrawToolCore is initialized.
+     */
+    setRefreshSphereOverlay(cb: () => void): void;
     /**
      * Set the EventRouter reference for centralized event handling.
      * Called by NrrdTools/DrawToolCore after EventRouter is initialized.

package/dist/types/Utils/segmentation/DrawToolCore.d.ts

@@ -6,6 +6,8 @@ import { CrosshairTool } from "./tools/CrosshairTool";
 import { ContrastTool } from "./tools/ContrastTool";
 import { ZoomTool } from "./tools/ZoomTool";
 import { EraserTool } from "./tools/EraserTool";
+import { PanTool } from "./tools/PanTool";
+import { DrawingTool } from "./tools/DrawingTool";
 import { ImageStoreHelper } from "./tools/ImageStoreHelper";
 import { UndoManager } from "./core";
 export declare class DrawToolCore extends CommToolsData {
@@ -16,17 +18,17 @@ export declare class DrawToolCore extends CommToolsData {
     eraserUrls: string[];
     pencilUrls: string[];
     undoManager: UndoManager;
-    /** Snapshot of the active layer's slice captured on mouse-down (before drawing). */
-    private preDrawSlice;
-    private preDrawAxis;
-    private preDrawSliceIndex;
     protected eventRouter: EventRouter | null;
     protected sphereTool: SphereTool;
     protected crosshairTool: CrosshairTool;
     protected contrastTool: ContrastTool;
     protected zoomTool: ZoomTool;
     protected eraserTool: EraserTool;
+    protected panTool: PanTool;
+    protected drawingTool: DrawingTool;
     protected imageStoreHelper: ImageStoreHelper;
+    /** Slice index recorded when paintOnCanvas() starts, guards stale-click */
+    private paintSliceIndex;
     start: () => void;
     constructor(container: HTMLElement, options?: {
         layers?: string[];
@@ -37,15 +39,13 @@ export declare class DrawToolCore extends CommToolsData {
     setPencilIconUrls(urls: string[]): void;
     private setCurrentLayer;
     draw(opts?: IDrawOpts): void;
-    drawCalSphereDown(x: number, y: number, sliceIndex: number, cal_position: "tumour" | "skin" | "nipple" | "ribcage"): void;
-    drawCalSphereUp(): void;
     private zoomActionAfterDrawSphere;
     private clearSpherePrintStoreImages;
     private paintOnCanvas;
+    /** Extracted from paintOnCanvas() — handles sphere placement on left-click */
+    private handleSphereClick;
     /*************************************May consider to move outside *******************************************/
     private drawLine;
-    private drawLinesOnLayer;
-    private paintOnCanvasLayer;
     private initAllCanvas;
     private useEraser;
     configMouseZoomWheel(): (e: WheelEvent) => void;
@@ -58,6 +58,11 @@ export declare class DrawToolCore extends CommToolsData {
     private configMouseSphereWheel;
     drawCalculatorSphere(radius: number): void;
     drawSphere(mouseX: number, mouseY: number, radius: number): void;
+    /**
+     * Refresh sphere canvas from sphereMaskVolume for the current slice/axis.
+     * Called after view changes (slice switch, zoom, contrast, axis switch).
+     */
+    refreshSphereOverlay(): void;
     /**
      * Convert cursor point between axis views.
      * Delegated to CrosshairTool.
@@ -68,13 +73,17 @@ export declare class DrawToolCore extends CommToolsData {
     getRestLayer(): string[];
     /**************************** Undo/Redo functions (Phase 6 — Delta-based) ****************************/
     /**
-     * Clear mask on current slice canvas.
+     * Clear the mask on the current slice canvas for the active layer ONLY.
+     *
+     * This method only clears the active layer's MaskVolume slice data for the
+     * currently viewed slice index. Other slices in the same layer remain intact.
+     * Other background layers are also left untouched.
+     * After clearing, all layer canvases are re-rendered from the `MaskVolume`
+     * to keep the visuals in sync.
      *
-     * Only clears the active layer's MaskVolume slice data.
-     * Other layers are left untouched. After clearing, all layer canvases
-     * are re-rendered from MaskVolume to keep visuals in sync.
+     * The operation is recorded to the UndoManager to allow for user rollback.
      */
-    clearPaint(): void;
+    clearActiveSlice(): void;
     /**
      * Undo the last drawing operation on the active layer.
      * Restores the MaskVolume slice to its pre-draw state, re-renders
@@ -93,9 +102,7 @@ export declare class DrawToolCore extends CommToolsData {
      */
     private applyUndoRedoToCanvas;
     /****************************Store images (delegated to ImageStoreHelper)****************************************************/
-    storeAllImages(index: number, layer: string): void;
-    storeImageToLayer(index: number, canvas: HTMLCanvasElement): ImageData;
-    storeEachLayerImage(index: number, layer: string): void;
+    syncLayerSliceData(index: number, layer: string): void;
     /******************************** Utils gui related functions (delegated to ContrastTool) ***************************************/
     setupConrastEvents(callback: (step: number, towards: "horizental" | "vertical") => void): void;
     configContrastDragMode: () => void;

package/dist/types/Utils/segmentation/NrrdTools.d.ts

@@ -1,9 +1,10 @@
 import { nrrdSliceType, storeExportPaintImageType, loadingBarType } from "../../types/types";
 import { GUI } from "dat.gui";
-import { IMaskData, IDragOpts, IGuiParameterSettings, IKeyBoardSettings } from "./coreTools/coreType";
+import { IMaskData, IDragOpts, IKeyBoardSettings, ToolMode, IGuiMeta } from "./coreTools/coreType";
 import { DragOperator } from "./DragOperator";
 import { DrawToolCore } from "./DrawToolCore";
 import type { ChannelValue, RGBAColor, ChannelColorMap } from "./core";
+import type { SphereType } from "./tools/SphereTool";
 /**
  * Core NRRD annotation tool for medical image segmentation.
  *
@@ -25,6 +26,10 @@ export declare class NrrdTools extends DrawToolCore {
     private guiParameterSettings;
     private _sliceRAFId;
     private _pendingSliceStep;
+    /** Whether calculator mode is active (not part of gui_states interface) */
+    private _calculatorActive;
+    /** Stored closure callbacks from gui.ts setupGui() */
+    private guiCallbacks;
     constructor(container: HTMLDivElement, options?: {
         layers?: string[];
     });
@@ -49,10 +54,11 @@ export declare class NrrdTools extends DrawToolCore {
      * @param gui GUI
      */
     setupGUI(gui: GUI): void;
-    getGuiSettings(): {
-        guiState: import("./coreTools/coreType").IGUIStates;
-        guiSetting: IGuiParameterSettings | undefined;
-    };
+    /**
+     * Sync guiParameterSettings with current volume metadata.
+     * Called internally when slices are loaded or switched.
+     */
+    private syncGuiParameterSettings;
     /**
      * Set the active layer and update fillColor/brushColor to match the active channel.
      */
@@ -61,6 +67,97 @@ export declare class NrrdTools extends DrawToolCore {
      * Set the active channel (1-8) and update fillColor/brushColor.
      */
     setActiveChannel(channel: ChannelValue): void;
+    /**
+     * Set the active sphere type for the SphereTool.
+     * Replaces direct mutation of `gui_states.activeSphereType`.
+     *
+     * @example
+     * ```ts
+     * nrrdTools.setActiveSphereType('nipple');
+     * ```
+     */
+    setActiveSphereType(type: SphereType): void;
+    /**
+     * Get the currently active sphere type.
+     */
+    getActiveSphereType(): SphereType;
+    /**
+     * Set the current tool mode. Handles deactivation of the previous mode
+     * and activation of the new mode, including all gui.ts side-effects.
+     *
+     * Replaces direct mutation of `guiSettings.value.guiState["pencil"]` etc.
+     * from Vue components.
+     */
+    setMode(mode: ToolMode): void;
+    /**
+     * Get the current tool mode based on gui_states flags.
+     */
+    getMode(): ToolMode;
+    /**
+     * Check if calculator mode is active.
+     */
+    isCalculatorActive(): boolean;
+    /**
+     * Set mask overlay opacity.
+     * @param value Opacity value [0.1, 1]
+     */
+    setOpacity(value: number): void;
+    /**
+     * Get the current mask overlay opacity.
+     */
+    getOpacity(): number;
+    /**
+     * Set brush and eraser size, and trigger cursor update.
+     * @param size Brush size [5, 50]
+     */
+    setBrushSize(size: number): void;
+    /**
+     * Get the current brush/eraser size.
+     */
+    getBrushSize(): number;
+    /**
+     * Set window high (image contrast) value.
+     * Call finishWindowAdjustment() when the user finishes dragging.
+     */
+    setWindowHigh(value: number): void;
+    /**
+     * Set window low (image center) value.
+     * Call finishWindowAdjustment() when the user finishes dragging.
+     */
+    setWindowLow(value: number): void;
+    /**
+     * Finish a window/contrast adjustment (repaint all contrast slices).
+     */
+    finishWindowAdjustment(): void;
+    /**
+     * Adjust contrast by delta, used for drag-based contrast adjustment.
+     * @param type "windowHigh" or "windowLow"
+     * @param delta Delta amount to adjust
+     */
+    adjustContrast(type: "windowHigh" | "windowLow", delta: number): void;
+    /**
+     * Get slider metadata for UI configuration.
+     * @param key Slider key: "globalAlpha", "brushAndEraserSize", "windowHigh", "windowLow"
+     * @returns IGuiMeta with min, max, step, and current value
+     */
+    getSliderMeta(key: string): IGuiMeta | null;
+    /**
+     * Set the pencil stroke color.
+     */
+    setPencilColor(hex: string): void;
+    /**
+     * Get the current pencil stroke color.
+     */
+    getPencilColor(): string;
+    /**
+     * Execute a named UI action.
+     * @param action Action name
+     *
+     * Renamed from original gui_states methods:
+     * - "clearActiveSliceMask" (was "clear") — clear annotations on current slice
+     * - "clearActiveLayerMask" (was "clearAll") — clear annotations on all slices for active layer
+     */
+    executeAction(action: "undo" | "redo" | "clearActiveSliceMask" | "clearActiveLayerMask" | "resetZoom" | "downloadCurrentMask"): void;
     /**
      * Sync brush/fill color from the active layer's volume color map.
      * Falls back to global CHANNEL_HEX_COLORS if volume not available.
@@ -331,6 +428,17 @@ export declare class NrrdTools extends DrawToolCore {
     getVoxelSpacing(): number[];
     getSpaceOrigin(): number[];
     getMaskData(): IMaskData;
+    /**
+     * Programmatically place a calculator sphere at the given position.
+     *
+     * Replicates the full mouse-down → mouse-up flow (handleSphereClick + pointerup)
+     * so that backend-supplied sphere data is stored identically to a manual click.
+     *
+     * @param x - X coordinate in unscaled (original) image space
+     * @param y - Y coordinate in unscaled (original) image space
+     * @param sliceIndex - Target slice index (z-axis)
+     * @param cal_position - Sphere type to place
+     */
     setCalculateDistanceSphere(x: number, y: number, sliceIndex: number, cal_position: "tumour" | "skin" | "nipple" | "ribcage"): void;
     /**
      * Switch all contrast slices' orientation
@@ -339,15 +447,22 @@ export declare class NrrdTools extends DrawToolCore {
     setSliceOrientation(axisTo: "x" | "y" | "z"): void;
     addSkip(index: number): void;
     removeSkip(index: number): void;
-    clear(): void;
+    /**
+     * Reset the entire NrrdTools instance comprehensively.
+     * This clears ALL data across ALL layers globally, resets the Canvas visuals,
+     * undo/redo history, volume models, index parameters, and sphere overlays.
+     * Primarily used when switching cases/datasets or when a completely fresh state is needed.
+     * It is heavier than `clearActiveLayer` or `clearActiveSlice`.
+     */
+    reset(): void;
     setSliceMoving(step: number): void;
     setMainAreaSize(factor: number): void;
     getContainer(): HTMLElement;
     getDrawingCanvas(): HTMLCanvasElement;
-    getNrrdToolsSettings(): import("./coreTools/coreType").INrrdStates;
+    getNrrdToolsSettings(): import("./coreTools/NrrdState").NrrdState;
     getMaxSliceNum(): number[];
     getCurrentSlicesNumAndContrastNum(): {
-        currentIndex: number;
+        currentSliceIndex: number;
         contrastIndex: number;
     };
     getCurrentSliceIndex(): number;
@@ -370,7 +485,7 @@ export declare class NrrdTools extends DrawToolCore {
     private updateMaxIndex;
     /**
      * Update the original canvas size, allow set to threejs load one (pixel distance not the mm).
-     * Then update the changedWidth and changedHeight based on the sizeFoctor.
+     * Then update the changedWidth and changedHeight based on the sizeFactor.
      */
     updateOriginAndChangedWH(): void;
     /**
@@ -379,7 +494,14 @@ export declare class NrrdTools extends DrawToolCore {
      */
     setSyncsliceNum(): void;
     appendLoadingbar(loadingbar: HTMLDivElement): void;
-    clearStoreImages(): void;
+    /**
+     * Clear all annotations on the currently active layer across its entire 3D volume.
+     * This resets all voxels globally for the active layer's `MaskVolume` (depth, width, height)
+     * and triggers the `onClearLayerVolume` event to sync the wiped volume to the backend.
+     * It also clears the undo/redo stack for the active layer ONLY.
+     * Other background layers are not impacted by this operation.
+     */
+    clearActiveLayer(): void;
     /**
      * Reset the draw and display canvases layout after mouse pan.
      * If no params in, then center the draw and display canvases.
@@ -391,6 +513,26 @@ export declare class NrrdTools extends DrawToolCore {
      * Clear masks on drawingCanvas layers.
      */
     resetLayerCanvas(): void;
+    /**
+     * Enter sphere mode.
+     *
+     * Clears all layer canvases and the master composite canvas so that
+     * only the sphere overlay is visible. Does NOT touch MaskVolume data.
+     * Also disables drag mode to prevent slice dragging conflicts.
+     *
+     * Called when sphere mode is toggled on (keyboard shortcut or GUI).
+     */
+    enterSphereMode(): void;
+    /**
+     * Exit sphere mode.
+     *
+     * Clears sphere overlay, restores all layer MaskVolume data onto
+     * their canvases by temporarily lifting the sphere guard in
+     * reloadMasksFromVolume and calling it.
+     *
+     * Called when sphere mode is toggled off (keyboard shortcut or GUI).
+     */
+    exitSphereMode(): void;
     redrawMianPreOnDisplayCanvas(): void;
     /**
      * Resize the draw and display canvas size based on the input size factor number.

package/dist/types/Utils/segmentation/core/MaskVolume.d.ts

@@ -317,7 +317,7 @@ export declare class MaskVolume {
      *
      * @example
      * ```ts
-     * vol.clear();
+     * vol.reset();
      * vol.getVoxel(256, 256, 50); // 0
      * ```
      */

package/dist/types/Utils/segmentation/core/UndoManager.d.ts

@@ -40,7 +40,7 @@ export declare class UndoManager {
     redo(): MaskDelta | undefined;
     canUndo(): boolean;
     canRedo(): boolean;
-    /** Clear undo and redo stacks for a specific layer (called on clearStoreImages). */
+    /** Clear undo and redo stacks for a specific layer (called on clearActiveLayer). */
     clearLayer(layer: string): void;
     /** Clear all stacks for all layers (called on full dataset reload). */
     clearAll(): void;

package/dist/types/Utils/segmentation/core/index.d.ts

@@ -70,7 +70,5 @@
 export type { Dimensions, RGBAColor, ChannelColorMap, SliceRenderOptions, LayerId, ChannelValue, } from './types';
 export { RenderMode, MASK_CHANNEL_COLORS, MASK_CHANNEL_CSS_COLORS, CHANNEL_COLORS, CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, } from './types';
 export { MaskVolume } from './MaskVolume';
-export type { IPaintImage, IPaintImages } from './MigrationUtils';
-export { convertIPaintImagesToVolume, convertVolumeToIPaintImages, } from './MigrationUtils';
 export type { MaskDelta } from './UndoManager';
 export { UndoManager } from './UndoManager';

package/dist/types/Utils/segmentation/coreTools/GuiState.d.ts

@@ -0,0 +1,22 @@
+/**
+ * GuiState — Grouped state management for GUI configuration.
+ *
+ * Replaces the flat IGUIStates object with 4 semantic sub-groups:
+ * - mode:         Tool mode flags (pencil/eraser/sphere)
+ * - drawing:      Brush/pencil appearance and behavior
+ * - viewConfig:   UI layout and interaction parameters
+ * - layerChannel: Active layer, channel, and visibility
+ */
+import type { IToolModeState, IDrawingConfig, IViewConfig, ILayerChannelState } from "./coreType";
+export declare class GuiState {
+    readonly mode: IToolModeState;
+    readonly drawing: IDrawingConfig;
+    readonly viewConfig: IViewConfig;
+    readonly layerChannel: ILayerChannelState;
+    constructor(options?: {
+        defaultPaintCursor?: string;
+        defaultFillColor?: string;
+        defaultBrushColor?: string;
+        layers?: string[];
+    });
+}

package/dist/types/Utils/segmentation/coreTools/NrrdState.d.ts

@@ -0,0 +1,25 @@
+/**
+ * NrrdState — Grouped state management for NRRD annotation data.
+ *
+ * Replaces the flat INrrdStates object with 5 semantic sub-groups:
+ * - image:       Read-mostly metadata set during NRRD loading
+ * - view:        Runtime display/navigation state
+ * - interaction: Mouse/cursor tracking
+ * - sphere:      SphereTool-specific data
+ * - flags:       Internal operational flags
+ *
+ * Phase 4 of the State Management Refactor.
+ */
+import type { IImageMetadata, IViewState, IInteractionState, ISphereState, IInternalFlags } from "./coreType";
+export declare class NrrdState {
+    readonly image: IImageMetadata;
+    readonly view: IViewState;
+    readonly interaction: IInteractionState;
+    readonly sphere: ISphereState;
+    readonly flags: IInternalFlags;
+    constructor(baseCanvasesSize?: number, layers?: string[]);
+    /** Set zoom factor with clamping [1, 8] */
+    setZoomFactor(factor: number): void;
+    /** Reset all sphere state to defaults */
+    resetSphereState(): void;
+}