copper3d 3.0.1 → 3.0.2

package/dist/Utils/segmentation/NrrdTools.js

@@ -1,8 +1,9 @@
 import { setupGui } from "./coreTools/gui";
-import { autoFocusDiv } from "./coreTools/divControlTools";
+import { autoFocusDiv, enableDownload } from "./coreTools/divControlTools";
 import { DragOperator } from "./DragOperator";
 import { DrawToolCore } from "./DrawToolCore";
-import { MaskVolume, CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss } from "./core";
+import { MaskVolume, CHANNEL_HEX_COLORS, MASK_CHANNEL_COLORS, rgbaToHex, rgbaToCss } from "./core";
+import { SPHERE_CHANNEL_MAP, SPHERE_LABELS } from "./tools/SphereTool";
 /**
  * Core NRRD annotation tool for medical image segmentation.
  *
@@ -21,15 +22,19 @@ export class NrrdTools extends DrawToolCore {
         this.initState = true;
         this._sliceRAFId = null;
         this._pendingSliceStep = 0;
+        /** Whether calculator mode is active (not part of gui_states interface) */
+        this._calculatorActive = false;
+        /** Stored closure callbacks from gui.ts setupGui() */
+        this.guiCallbacks = null;
         this.container = container;
-        this.protectedData.previousDrawingImage =
-            this.protectedData.ctxes.emptyCtx.createImageData(1, 1);
         this.init();
         this.dragOperator = new DragOperator(this.container, this.nrrd_states, this.gui_states, this.protectedData, this.drawingPrameters, this.setSyncsliceNum.bind(this), this.setIsDrawFalse.bind(this), this.flipDisplayImageByAxis.bind(this), this.setEmptyCanvasSize.bind(this), this.getOrCreateSliceBuffer.bind(this), this.renderSliceToCanvas.bind(this));
         // Inject EventRouter into DragOperator for centralized event handling
         if (this.eventRouter) {
             this.dragOperator.setEventRouter(this.eventRouter);
         }
+        // Wire sphere overlay refresh callback into DragOperator → DragSliceTool
+        this.dragOperator.setRefreshSphereOverlay(() => this.refreshSphereOverlay());
     }
     /**
      * core function for drag slices
@@ -83,8 +88,8 @@ export class NrrdTools extends DrawToolCore {
             protectedData: this.protectedData,
             removeDragMode: this.dragOperator.removeDragMode,
             configDragMode: this.dragOperator.configDragMode,
-            clearPaint: this.clearPaint,
-            clearStoreImages: this.clearStoreImages,
+            clearActiveLayer: this.clearActiveLayer,
+            clearActiveSlice: this.clearActiveSlice,
             updateSlicesContrast: this.updateSlicesContrast,
             setMainAreaSize: this.setMainAreaSize,
             resetPaintAreaUIPosition: this.resetPaintAreaUIPosition,
@@ -94,81 +99,361 @@ export class NrrdTools extends DrawToolCore {
             resetLayerCanvas: this.resetLayerCanvas,
             redrawDisplayCanvas: this.redrawDisplayCanvas,
             flipDisplayImageByAxis: this.flipDisplayImageByAxis,
-            filterDrawedImage: this.filterDrawedImage,
             setEmptyCanvasSize: this.setEmptyCanvasSize,
-            storeAllImages: this.storeAllImages,
+            syncLayerSliceData: this.syncLayerSliceData,
             drawImageOnEmptyImage: this.drawImageOnEmptyImage,
-            storeEachLayerImage: this.storeEachLayerImage,
-            storeImageToLayer: this.storeImageToLayer,
             getRestLayer: this.getRestLayer,
             setIsDrawFalse: this.setIsDrawFalse,
             getVolumeForLayer: this.getVolumeForLayer.bind(this),
+            undoLastPainting: this.undoLastPainting.bind(this),
+            redoLastPainting: this.redoLastPainting.bind(this),
+            resetZoom: () => this.executeAction("resetZoom"),
+            downloadCurrentMask: () => this.executeAction("downloadCurrentMask"),
         };
         this.guiParameterSettings = setupGui(guiOptions);
+        // Store closure callbacks for programmatic access (Phase 1 Task 1.2)
+        this.guiCallbacks = {
+            updatePencilState: this.guiParameterSettings.pencil.onChange,
+            updateEraserState: this.guiParameterSettings.eraser.onChange,
+            updateBrushAndEraserSize: this.guiParameterSettings.brushAndEraserSize.onChange,
+            updateSphereState: this.guiParameterSettings.sphere.onChange,
+            updateCalDistance: this.guiParameterSettings.activeSphereType.onChange,
+            updateWindowHigh: this.guiParameterSettings.windowHigh.onChange,
+            updateWindowLow: this.guiParameterSettings.windowLow.onChange,
+            finishContrastAdjustment: this.guiParameterSettings.windowHigh.onFinished,
+        };
     }
-    getGuiSettings() {
-        if (!!this.guiParameterSettings) {
-            // update image volume
+    /**
+     * Sync guiParameterSettings with current volume metadata.
+     * Called internally when slices are loaded or switched.
+     */
+    syncGuiParameterSettings() {
+        if (this.guiParameterSettings && this.protectedData.mainPreSlices) {
             this.guiParameterSettings.windowHigh.value = this.guiParameterSettings.windowLow.value = this.protectedData.mainPreSlices.volume;
             this.guiParameterSettings.windowHigh.max = this.guiParameterSettings.windowLow.max = this.protectedData.mainPreSlices.volume.max;
             this.guiParameterSettings.windowHigh.min = this.guiParameterSettings.windowLow.min = this.protectedData.mainPreSlices.volume.min;
         }
-        return {
-            guiState: this.gui_states,
-            guiSetting: this.guiParameterSettings,
-        };
     }
     // ── Layer & Channel Management API ─────────────────────────────────────
     /**
      * Set the active layer and update fillColor/brushColor to match the active channel.
      */
     setActiveLayer(layerId) {
-        this.gui_states.layer = layerId;
+        this.gui_states.layerChannel.layer = layerId;
         this.syncBrushColor();
     }
     /**
      * Set the active channel (1-8) and update fillColor/brushColor.
      */
     setActiveChannel(channel) {
-        this.gui_states.activeChannel = channel;
+        this.gui_states.layerChannel.activeChannel = channel;
         this.syncBrushColor();
     }
+    /**
+     * Set the active sphere type for the SphereTool.
+     * Replaces direct mutation of `gui_states.activeSphereType`.
+     *
+     * @example
+     * ```ts
+     * nrrdTools.setActiveSphereType('nipple');
+     * ```
+     */
+    setActiveSphereType(type) {
+        this.gui_states.mode.activeSphereType = type;
+        // Apply color side-effect: update fillColor/brushColor from sphere channel map
+        const mapping = SPHERE_CHANNEL_MAP[type];
+        if (mapping) {
+            const volume = this.getVolumeForLayer(mapping.layer);
+            const color = volume
+                ? rgbaToHex(volume.getChannelColor(mapping.channel))
+                : (CHANNEL_HEX_COLORS[mapping.channel] || '#00ff00');
+            this.gui_states.drawing.fillColor = color;
+            this.gui_states.drawing.brushColor = color;
+        }
+    }
+    /**
+     * Get the currently active sphere type.
+     */
+    getActiveSphereType() {
+        return this.gui_states.mode.activeSphereType;
+    }
+    // ── Phase 1: GUI API — Mode Management ──────────────────────────────────
+    /**
+     * 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) {
+        if (!this.guiCallbacks)
+            return;
+        const prevSphere = this.gui_states.mode.sphere;
+        const prevCalculator = this._calculatorActive;
+        // Reset all mode flags
+        this.gui_states.mode.pencil = false;
+        this.gui_states.mode.eraser = false;
+        this.gui_states.mode.sphere = false;
+        this._calculatorActive = false;
+        // Activate new mode
+        switch (mode) {
+            case "pencil":
+                this.gui_states.mode.pencil = true;
+                this.guiCallbacks.updatePencilState();
+                break;
+            case "brush":
+                // brush = pencil off + eraser off (default brush mode)
+                this.guiCallbacks.updatePencilState();
+                break;
+            case "eraser":
+                this.gui_states.mode.eraser = true;
+                this.guiCallbacks.updateEraserState();
+                break;
+            case "sphere":
+                this.gui_states.mode.sphere = true;
+                break;
+            case "calculator":
+                this.gui_states.mode.sphere = true;
+                this._calculatorActive = true;
+                break;
+        }
+        // Handle sphere mode transitions
+        if (prevSphere && !this.gui_states.mode.sphere) {
+            this.guiCallbacks.updateSphereState(); // exits sphere mode
+        }
+        if (!prevSphere && this.gui_states.mode.sphere) {
+            this.guiCallbacks.updateSphereState(); // enters sphere mode
+        }
+        // Handle calculator exit side-effect
+        if (prevCalculator && !this._calculatorActive) {
+            // calculator was exited — sphere onChange already handled above
+        }
+    }
+    /**
+     * Get the current tool mode based on gui_states flags.
+     */
+    getMode() {
+        if (this._calculatorActive)
+            return "calculator";
+        if (this.gui_states.mode.sphere)
+            return "sphere";
+        if (this.gui_states.mode.eraser)
+            return "eraser";
+        if (this.gui_states.mode.pencil)
+            return "pencil";
+        return "brush";
+    }
+    /**
+     * Check if calculator mode is active.
+     */
+    isCalculatorActive() {
+        return this._calculatorActive;
+    }
+    // ── Phase 1: GUI API — Slider Methods ───────────────────────────────────
+    /**
+     * Set mask overlay opacity.
+     * @param value Opacity value [0.1, 1]
+     */
+    setOpacity(value) {
+        this.gui_states.drawing.globalAlpha = Math.max(0.1, Math.min(1, value));
+    }
+    /**
+     * Get the current mask overlay opacity.
+     */
+    getOpacity() {
+        return this.gui_states.drawing.globalAlpha;
+    }
+    /**
+     * Set brush and eraser size, and trigger cursor update.
+     * @param size Brush size [5, 50]
+     */
+    setBrushSize(size) {
+        var _a;
+        this.gui_states.drawing.brushAndEraserSize = Math.max(5, Math.min(50, size));
+        (_a = this.guiCallbacks) === null || _a === void 0 ? void 0 : _a.updateBrushAndEraserSize();
+    }
+    /**
+     * Get the current brush/eraser size.
+     */
+    getBrushSize() {
+        return this.gui_states.drawing.brushAndEraserSize;
+    }
+    /**
+     * Set window high (image contrast) value.
+     * Call finishWindowAdjustment() when the user finishes dragging.
+     */
+    setWindowHigh(value) {
+        var _a;
+        this.gui_states.viewConfig.readyToUpdate = false;
+        (_a = this.guiCallbacks) === null || _a === void 0 ? void 0 : _a.updateWindowHigh(value);
+    }
+    /**
+     * Set window low (image center) value.
+     * Call finishWindowAdjustment() when the user finishes dragging.
+     */
+    setWindowLow(value) {
+        var _a;
+        this.gui_states.viewConfig.readyToUpdate = false;
+        (_a = this.guiCallbacks) === null || _a === void 0 ? void 0 : _a.updateWindowLow(value);
+    }
+    /**
+     * Finish a window/contrast adjustment (repaint all contrast slices).
+     */
+    finishWindowAdjustment() {
+        var _a;
+        (_a = this.guiCallbacks) === null || _a === void 0 ? void 0 : _a.finishContrastAdjustment();
+    }
+    /**
+     * Adjust contrast by delta, used for drag-based contrast adjustment.
+     * @param type "windowHigh" or "windowLow"
+     * @param delta Delta amount to adjust
+     */
+    adjustContrast(type, delta) {
+        var _a, _b;
+        if (!this.guiParameterSettings)
+            return;
+        const setting = this.guiParameterSettings[type];
+        // setting.value is the volume object at runtime (typed as null in interface)
+        const vol = setting.value;
+        const currentValue = type === "windowHigh"
+            ? ((_a = vol === null || vol === void 0 ? void 0 : vol.windowHigh) !== null && _a !== void 0 ? _a : 0)
+            : ((_b = vol === null || vol === void 0 ? void 0 : vol.windowLow) !== null && _b !== void 0 ? _b : 0);
+        const newValue = currentValue + delta;
+        if (newValue >= setting.max || newValue <= 0)
+            return;
+        if (type === "windowHigh") {
+            this.setWindowHigh(newValue);
+        }
+        else {
+            this.setWindowLow(newValue);
+        }
+    }
+    /**
+     * 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) {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        if (!this.guiParameterSettings)
+            return null;
+        const setting = this.guiParameterSettings[key];
+        if (!setting)
+            return null;
+        let value;
+        if (key === "windowHigh") {
+            value = (_b = (_a = setting.value) === null || _a === void 0 ? void 0 : _a.windowHigh) !== null && _b !== void 0 ? _b : 0;
+        }
+        else if (key === "windowLow") {
+            value = (_d = (_c = setting.value) === null || _c === void 0 ? void 0 : _c.windowLow) !== null && _d !== void 0 ? _d : 0;
+        }
+        else {
+            value = (_e = this.gui_states.drawing[key]) !== null && _e !== void 0 ? _e : 0;
+        }
+        return {
+            min: (_f = setting.min) !== null && _f !== void 0 ? _f : 0,
+            max: (_g = setting.max) !== null && _g !== void 0 ? _g : 100,
+            step: (_h = setting.step) !== null && _h !== void 0 ? _h : 1,
+            value,
+        };
+    }
+    // ── Phase 1: GUI API — Color & Action Methods ──────────────────────────
+    /**
+     * Set the pencil stroke color.
+     */
+    setPencilColor(hex) {
+        this.gui_states.drawing.color = hex;
+    }
+    /**
+     * Get the current pencil stroke color.
+     */
+    getPencilColor() {
+        return this.gui_states.drawing.color;
+    }
+    /**
+     * 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) {
+        switch (action) {
+            case "undo":
+                this.undo();
+                break;
+            case "redo":
+                this.redo();
+                break;
+            case "clearActiveSliceMask":
+                this.clearActiveSlice();
+                break;
+            case "clearActiveLayerMask": {
+                const text = "Are you sure remove annotations on All slice?";
+                if (confirm(text) === true) {
+                    this.nrrd_states.flags.clearAllFlag = true;
+                    this.clearActiveSlice();
+                    this.clearActiveLayer();
+                }
+                this.nrrd_states.flags.clearAllFlag = false;
+                break;
+            }
+            case "resetZoom":
+                this.nrrd_states.view.sizeFactor = this.baseCanvasesSize;
+                this.gui_states.viewConfig.mainAreaSize = this.baseCanvasesSize;
+                this.resizePaintArea(this.nrrd_states.view.sizeFactor);
+                this.resetPaintAreaUIPosition();
+                break;
+            case "downloadCurrentMask": {
+                const config = {
+                    axis: this.protectedData.axis,
+                    currentSliceIndex: this.nrrd_states.view.currentSliceIndex,
+                    drawingCanvas: this.protectedData.canvases.drawingCanvas,
+                    originWidth: this.nrrd_states.image.originWidth,
+                    originHeight: this.nrrd_states.image.originHeight,
+                };
+                enableDownload(config);
+                break;
+            }
+        }
+    }
     /**
      * Sync brush/fill color from the active layer's volume color map.
      * Falls back to global CHANNEL_HEX_COLORS if volume not available.
      */
     syncBrushColor() {
-        const channel = this.gui_states.activeChannel || 1;
-        const layer = this.gui_states.layer;
+        const channel = this.gui_states.layerChannel.activeChannel || 1;
+        const layer = this.gui_states.layerChannel.layer;
         const volume = this.protectedData.maskData.volumes[layer];
         if (volume) {
             const hex = rgbaToHex(volume.getChannelColor(channel));
-            this.gui_states.fillColor = hex;
-            this.gui_states.brushColor = hex;
+            this.gui_states.drawing.fillColor = hex;
+            this.gui_states.drawing.brushColor = hex;
         }
         else {
             const hex = CHANNEL_HEX_COLORS[channel] || '#00ff00';
-            this.gui_states.fillColor = hex;
-            this.gui_states.brushColor = hex;
+            this.gui_states.drawing.fillColor = hex;
+            this.gui_states.drawing.brushColor = hex;
         }
     }
     /**
      * Get the currently active layer id.
      */
     getActiveLayer() {
-        return this.gui_states.layer;
+        return this.gui_states.layerChannel.layer;
     }
     /**
      * Get the currently active channel value.
      */
     getActiveChannel() {
-        return this.gui_states.activeChannel;
+        return this.gui_states.layerChannel.activeChannel;
     }
     /**
      * Set visibility of a layer and re-render.
      */
     setLayerVisible(layerId, visible) {
-        this.gui_states.layerVisibility[layerId] = visible;
+        this.gui_states.layerChannel.layerVisibility[layerId] = visible;
         this.reloadMasksFromVolume();
     }
     /**
@@ -176,14 +461,14 @@ export class NrrdTools extends DrawToolCore {
      */
     isLayerVisible(layerId) {
         var _a;
-        return (_a = this.gui_states.layerVisibility[layerId]) !== null && _a !== void 0 ? _a : true;
+        return (_a = this.gui_states.layerChannel.layerVisibility[layerId]) !== null && _a !== void 0 ? _a : true;
     }
     /**
      * Set visibility of a specific channel within a layer and re-render.
      */
     setChannelVisible(layerId, channel, visible) {
-        if (this.gui_states.channelVisibility[layerId]) {
-            this.gui_states.channelVisibility[layerId][channel] = visible;
+        if (this.gui_states.layerChannel.channelVisibility[layerId]) {
+            this.gui_states.layerChannel.channelVisibility[layerId][channel] = visible;
         }
         this.reloadMasksFromVolume();
     }
@@ -192,21 +477,21 @@ export class NrrdTools extends DrawToolCore {
      */
     isChannelVisible(layerId, channel) {
         var _a, _b;
-        return (_b = (_a = this.gui_states.channelVisibility[layerId]) === null || _a === void 0 ? void 0 : _a[channel]) !== null && _b !== void 0 ? _b : true;
+        return (_b = (_a = this.gui_states.layerChannel.channelVisibility[layerId]) === null || _a === void 0 ? void 0 : _a[channel]) !== null && _b !== void 0 ? _b : true;
     }
     /**
      * Get the full layer visibility map.
      */
     getLayerVisibility() {
-        return Object.assign({}, this.gui_states.layerVisibility);
+        return Object.assign({}, this.gui_states.layerChannel.layerVisibility);
     }
     /**
      * Get the full channel visibility map.
      */
     getChannelVisibility() {
         const result = {};
-        for (const layerId of this.nrrd_states.layers) {
-            result[layerId] = Object.assign({}, this.gui_states.channelVisibility[layerId]);
+        for (const layerId of this.nrrd_states.image.layers) {
+            result[layerId] = Object.assign({}, this.gui_states.layerChannel.channelVisibility[layerId]);
         }
         return result;
     }
@@ -255,11 +540,11 @@ export class NrrdTools extends DrawToolCore {
             return;
         }
         volume.setChannelColor(channel, color);
-        if (layerId === this.gui_states.layer && channel === this.gui_states.activeChannel) {
+        if (layerId === this.gui_states.layerChannel.layer && channel === this.gui_states.layerChannel.activeChannel) {
             this.syncBrushColor();
         }
         this.reloadMasksFromVolume();
-        this.nrrd_states.onChannelColorChanged(layerId, channel, color);
+        this.annotationCallbacks.onChannelColorChanged(layerId, channel, color);
     }
     /**
      * Get the current color for a specific channel in a specific layer.
@@ -310,7 +595,7 @@ export class NrrdTools extends DrawToolCore {
         for (const [ch, color] of Object.entries(colorMap)) {
             volume.setChannelColor(Number(ch), color);
         }
-        if (layerId === this.gui_states.layer) {
+        if (layerId === this.gui_states.layerChannel.layer) {
             this.syncBrushColor();
         }
         this.reloadMasksFromVolume();
@@ -322,13 +607,13 @@ export class NrrdTools extends DrawToolCore {
      * @param color    RGBAColor object
      */
     setAllLayersChannelColor(channel, color) {
-        for (const layerId of this.nrrd_states.layers) {
+        for (const layerId of this.nrrd_states.image.layers) {
             const volume = this.protectedData.maskData.volumes[layerId];
             if (volume) {
                 volume.setChannelColor(channel, color);
             }
         }
-        if (channel === this.gui_states.activeChannel) {
+        if (channel === this.gui_states.layerChannel.activeChannel) {
             this.syncBrushColor();
         }
         this.reloadMasksFromVolume();
@@ -347,7 +632,7 @@ export class NrrdTools extends DrawToolCore {
      * ```
      */
     resetChannelColors(layerId, channel) {
-        const layers = layerId ? [layerId] : this.nrrd_states.layers;
+        const layers = layerId ? [layerId] : this.nrrd_states.image.layers;
         for (const lid of layers) {
             const volume = this.protectedData.maskData.volumes[lid];
             if (volume) {
@@ -522,28 +807,39 @@ export class NrrdTools extends DrawToolCore {
     setAllSlices(allSlices) {
         this.protectedData.allSlicesArray = [...allSlices];
         const randomSlice = this.protectedData.allSlicesArray[0];
-        this.nrrd_states.nrrd_x_mm = randomSlice.z.canvas.width;
-        this.nrrd_states.nrrd_y_mm = randomSlice.z.canvas.height;
-        this.nrrd_states.nrrd_z_mm = randomSlice.x.canvas.width;
-        this.nrrd_states.nrrd_x_pixel = randomSlice.x.volume.dimensions[0];
-        this.nrrd_states.nrrd_y_pixel = randomSlice.x.volume.dimensions[1];
-        this.nrrd_states.nrrd_z_pixel = randomSlice.x.volume.dimensions[2];
-        this.nrrd_states.voxelSpacing = randomSlice.x.volume.spacing;
-        this.nrrd_states.ratios.x = randomSlice.x.volume.spacing[0];
-        this.nrrd_states.ratios.y = randomSlice.x.volume.spacing[1];
-        this.nrrd_states.ratios.z = randomSlice.x.volume.spacing[2];
-        this.nrrd_states.dimensions = randomSlice.x.volume.dimensions;
+        this.nrrd_states.image.nrrd_x_mm = randomSlice.z.canvas.width;
+        this.nrrd_states.image.nrrd_y_mm = randomSlice.z.canvas.height;
+        this.nrrd_states.image.nrrd_z_mm = randomSlice.x.canvas.width;
+        this.nrrd_states.image.nrrd_x_pixel = randomSlice.x.volume.dimensions[0];
+        this.nrrd_states.image.nrrd_y_pixel = randomSlice.x.volume.dimensions[1];
+        this.nrrd_states.image.nrrd_z_pixel = randomSlice.x.volume.dimensions[2];
+        this.nrrd_states.image.voxelSpacing = randomSlice.x.volume.spacing;
+        this.nrrd_states.image.ratios.x = randomSlice.x.volume.spacing[0];
+        this.nrrd_states.image.ratios.y = randomSlice.x.volume.spacing[1];
+        this.nrrd_states.image.ratios.z = randomSlice.x.volume.spacing[2];
+        this.nrrd_states.image.dimensions = randomSlice.x.volume.dimensions;
         // Phase 2 Day 9: Re-initialize MaskVolume with real NRRD dimensions.
         // This replaces the 1×1×1 placeholders from CommToolsData constructor
         // and "turns on" all Day 7/8 volume read/write paths.
         // Invalidate reusable buffer from previous dataset
         this.invalidateSliceBuffer();
-        const [vw, vh, vd] = this.nrrd_states.dimensions;
-        this.protectedData.maskData.volumes = this.nrrd_states.layers.reduce((acc, id) => {
+        const [vw, vh, vd] = this.nrrd_states.image.dimensions;
+        this.protectedData.maskData.volumes = this.nrrd_states.image.layers.reduce((acc, id) => {
             acc[id] = new MaskVolume(vw, vh, vd, 1);
             return acc;
         }, {});
-        this.nrrd_states.spaceOrigin = randomSlice.x.volume.header.space_origin.map((item) => {
+        // Create dedicated SphereMaskVolume for 3D sphere data.
+        // Separate from layer volumes to avoid polluting draw mask data.
+        // Cleared in reset() when switching cases.
+        this.nrrd_states.sphere.sphereMaskVolume = new MaskVolume(vw, vh, vd, 1);
+        // Derive sphere label colors from SPHERE_CHANNEL_MAP → MASK_CHANNEL_COLORS
+        // so that volume rendering matches the preview circle colors.
+        for (const [type, { channel }] of Object.entries(SPHERE_CHANNEL_MAP)) {
+            const label = SPHERE_LABELS[type];
+            const c = MASK_CHANNEL_COLORS[channel];
+            this.nrrd_states.sphere.sphereMaskVolume.setChannelColor(label, { r: c.r, g: c.g, b: c.b, a: c.a });
+        }
+        this.nrrd_states.image.spaceOrigin = randomSlice.x.volume.header.space_origin.map((item) => {
             return item * 1;
         });
         this.protectedData.allSlicesArray.forEach((item, index) => {
@@ -552,13 +848,13 @@ export class NrrdTools extends DrawToolCore {
             item.z.contrastOrder = index;
         });
         // Phase 3: initPaintImages removed (MaskVolume initialized separately)
-        // this.initPaintImages(this.nrrd_states.dimensions);
+        // this.initPaintImages(this.nrrd_states.image.dimensions);
         // init displayslices array, the axis default is "z"
         this.setDisplaySlicesBaseOnAxis();
         this.afterLoadSlice();
     }
     loadingMaskByLayer(masks, index, imageData) {
-        let imageDataLable = this.protectedData.ctxes.emptyCtx.createImageData(this.nrrd_states.nrrd_x_pixel, this.nrrd_states.nrrd_y_pixel);
+        let imageDataLable = this.protectedData.ctxes.emptyCtx.createImageData(this.nrrd_states.image.nrrd_x_pixel, this.nrrd_states.image.nrrd_y_pixel);
         this.setEmptyCanvasSize();
         for (let j = 0; j < masks[index].data.length; j++) {
             imageDataLable.data[j] = masks[index].data[j];
@@ -569,7 +865,7 @@ export class NrrdTools extends DrawToolCore {
     // need to remove
     setMasksData(masksData, loadingBar) {
         if (!!masksData) {
-            this.nrrd_states.loadMaskJson = true;
+            this.nrrd_states.flags.loadingMaskData = true;
             if (loadingBar) {
                 let { loadingContainer, progress } = loadingBar;
                 loadingContainer.style.display = "flex";
@@ -578,32 +874,22 @@ export class NrrdTools extends DrawToolCore {
             this.setEmptyCanvasSize();
             const len = masksData["layer1"].length;
             for (let i = 0; i < len; i++) {
-                let imageData = this.protectedData.ctxes.emptyCtx.createImageData(this.nrrd_states.nrrd_x_pixel, this.nrrd_states.nrrd_y_pixel);
-                let imageDataLayer1, imageDataLayer2, imageDataLayer3;
+                let imageData = this.protectedData.ctxes.emptyCtx.createImageData(this.nrrd_states.image.nrrd_x_pixel, this.nrrd_states.image.nrrd_y_pixel);
                 if (masksData["layer1"][i].data.length > 0) {
-                    this.setEmptyCanvasSize();
-                    imageDataLayer1 = this.loadingMaskByLayer(masksData["layer1"], i, imageData);
-                    this.protectedData.ctxes.emptyCtx.putImageData(imageDataLayer1, 0, 0);
-                    this.storeEachLayerImage(i, "layer1");
+                    this.loadingMaskByLayer(masksData["layer1"], i, imageData);
                 }
                 if (masksData["layer2"][i].data.length > 0) {
-                    this.setEmptyCanvasSize();
-                    imageDataLayer2 = this.loadingMaskByLayer(masksData["layer2"], i, imageData);
-                    this.protectedData.ctxes.emptyCtx.putImageData(imageDataLayer2, 0, 0);
-                    this.storeEachLayerImage(i, "layer2");
+                    this.loadingMaskByLayer(masksData["layer2"], i, imageData);
                 }
                 if (masksData["layer3"][i].data.length > 0) {
-                    this.setEmptyCanvasSize();
-                    imageDataLayer3 = this.loadingMaskByLayer(masksData["layer3"], i, imageData);
-                    this.protectedData.ctxes.emptyCtx.putImageData(imageDataLayer3, 0, 0);
-                    this.storeEachLayerImage(i, "layer3");
+                    this.loadingMaskByLayer(masksData["layer3"], i, imageData);
                 }
                 this.setEmptyCanvasSize();
                 this.protectedData.ctxes.emptyCtx.putImageData(imageData, 0, 0);
-                this.storeAllImages(i, "default");
+                this.syncLayerSliceData(i, "default");
             }
-            this.nrrd_states.loadMaskJson = false;
-            this.gui_states.resetZoom();
+            this.nrrd_states.flags.loadingMaskData = false;
+            this.executeAction("resetZoom");
             if (loadingBar) {
                 loadingBar.loadingContainer.style.display = "none";
             }
@@ -645,7 +931,7 @@ export class NrrdTools extends DrawToolCore {
             }
             // Reload the current slice from MaskVolume to canvas
             this.reloadMasksFromVolume();
-            this.gui_states.resetZoom();
+            this.executeAction("resetZoom");
         }
         catch (error) {
             console.error("Error loading NIfTI masks:", error);
@@ -657,31 +943,69 @@ export class NrrdTools extends DrawToolCore {
         }
     }
     setShowInMainArea() {
-        this.nrrd_states.showContrast = true;
+        this.nrrd_states.view.showContrast = true;
     }
     getCurrentImageDimension() {
-        return this.nrrd_states.dimensions;
+        return this.nrrd_states.image.dimensions;
     }
     getVoxelSpacing() {
-        return this.nrrd_states.voxelSpacing;
+        return this.nrrd_states.image.voxelSpacing;
     }
     getSpaceOrigin() {
-        return this.nrrd_states.spaceOrigin;
+        return this.nrrd_states.image.spaceOrigin;
     }
     getMaskData() {
         return this.protectedData.maskData;
     }
-    // set calculate distance sphere position
+    /**
+     * 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, y, sliceIndex, cal_position) {
-        this.nrrd_states.sphereRadius = 5;
-        // move to tumour slice
-        const steps = sliceIndex - this.nrrd_states.currentIndex;
+        this.nrrd_states.sphere.sphereRadius = 5;
+        // move to target slice
+        const steps = sliceIndex - this.nrrd_states.view.currentSliceIndex;
         this.setSliceMoving(steps * this.protectedData.displaySlices.length);
-        // mock mouse down
-        // if user zoom the panel, we need to consider the size factor 
-        this.drawCalSphereDown(x * this.nrrd_states.sizeFoctor, y * this.nrrd_states.sizeFoctor, sliceIndex, cal_position);
-        // mock mouse up
-        this.drawCalSphereUp();
+        // --- simulate mouse-down (mirrors DrawToolCore.handleSphereClick) ---
+        // if user has zoomed the panel, we need to consider the size factor
+        const mouseX = x * this.nrrd_states.view.sizeFactor;
+        const mouseY = y * this.nrrd_states.view.sizeFactor;
+        // 1. record origin on current axis
+        this.nrrd_states.sphere.sphereOrigin[this.protectedData.axis] = [
+            mouseX, mouseY, sliceIndex,
+        ];
+        // compute origins for all 3 axes (crosshairTool is protected)
+        this.crosshairTool.setUpSphereOrigins(mouseX, mouseY, sliceIndex);
+        // 2. store a deep copy of the origin for the specific sphere type
+        const originCopy = JSON.parse(JSON.stringify(this.nrrd_states.sphere.sphereOrigin));
+        switch (cal_position) {
+            case "tumour":
+                this.nrrd_states.sphere.tumourSphereOrigin = originCopy;
+                break;
+            case "skin":
+                this.nrrd_states.sphere.skinSphereOrigin = originCopy;
+                break;
+            case "nipple":
+                this.nrrd_states.sphere.nippleSphereOrigin = originCopy;
+                break;
+            case "ribcage":
+                this.nrrd_states.sphere.ribSphereOrigin = originCopy;
+                break;
+        }
+        // 3. draw sphere preview on canvas
+        this.drawCalculatorSphere(this.nrrd_states.sphere.sphereRadius);
+        // --- simulate mouse-up ---
+        // 4. write all placed calculator spheres into sphereMaskVolume
+        this.sphereTool.writeAllCalculatorSpheresToVolume();
+        // 5. re-render sphere overlay from volume
+        this.sphereTool.refreshSphereCanvas();
     }
     /**
      * Switch all contrast slices' orientation
@@ -690,24 +1014,24 @@ export class NrrdTools extends DrawToolCore {
     setSliceOrientation(axisTo) {
         var _a;
         let convetObj;
-        if (((_a = this.eventRouter) === null || _a === void 0 ? void 0 : _a.isCrosshairEnabled()) || this.gui_states.sphere) {
+        if (((_a = this.eventRouter) === null || _a === void 0 ? void 0 : _a.isCrosshairEnabled()) || this.gui_states.mode.sphere) {
             if (this.protectedData.axis === "z") {
-                this.cursorPage.z.index = this.nrrd_states.currentIndex;
-                this.cursorPage.z.cursorPageX = this.nrrd_states.cursorPageX;
-                this.cursorPage.z.cursorPageY = this.nrrd_states.cursorPageY;
+                this.cursorPage.z.index = this.nrrd_states.view.currentSliceIndex;
+                this.cursorPage.z.cursorPageX = this.nrrd_states.interaction.cursorPageX;
+                this.cursorPage.z.cursorPageY = this.nrrd_states.interaction.cursorPageY;
             }
             else if (this.protectedData.axis === "x") {
-                this.cursorPage.x.index = this.nrrd_states.currentIndex;
-                this.cursorPage.x.cursorPageX = this.nrrd_states.cursorPageX;
-                this.cursorPage.x.cursorPageY = this.nrrd_states.cursorPageY;
+                this.cursorPage.x.index = this.nrrd_states.view.currentSliceIndex;
+                this.cursorPage.x.cursorPageX = this.nrrd_states.interaction.cursorPageX;
+                this.cursorPage.x.cursorPageY = this.nrrd_states.interaction.cursorPageY;
             }
             else if (this.protectedData.axis === "y") {
-                this.cursorPage.y.index = this.nrrd_states.currentIndex;
-                this.cursorPage.y.cursorPageX = this.nrrd_states.cursorPageX;
-                this.cursorPage.y.cursorPageY = this.nrrd_states.cursorPageY;
+                this.cursorPage.y.index = this.nrrd_states.view.currentSliceIndex;
+                this.cursorPage.y.cursorPageX = this.nrrd_states.interaction.cursorPageX;
+                this.cursorPage.y.cursorPageY = this.nrrd_states.interaction.cursorPageY;
             }
             if (axisTo === "z") {
-                if (this.nrrd_states.isCursorSelect && !this.cursorPage.z.updated) {
+                if (this.nrrd_states.interaction.isCursorSelect && !this.cursorPage.z.updated) {
                     if (this.protectedData.axis === "x") {
                         // convert x to z
                         convetObj = this.convertCursorPoint("x", "z", this.cursorPage.x.cursorPageX, this.cursorPage.x.cursorPageY, this.cursorPage.x.index);
@@ -719,15 +1043,15 @@ export class NrrdTools extends DrawToolCore {
                 }
                 else {
                     // not cursor select, freedom to switch x -> z or y -> z and z -> x or z -> y
-                    this.nrrd_states.currentIndex = this.cursorPage.z.index;
-                    this.nrrd_states.oldIndex =
-                        this.cursorPage.z.index * this.nrrd_states.ratios.z;
-                    this.nrrd_states.cursorPageX = this.cursorPage.z.cursorPageX;
-                    this.nrrd_states.cursorPageY = this.cursorPage.z.cursorPageY;
+                    this.nrrd_states.view.currentSliceIndex = this.cursorPage.z.index;
+                    this.nrrd_states.view.preSliceIndex =
+                        this.cursorPage.z.index * this.nrrd_states.image.ratios.z;
+                    this.nrrd_states.interaction.cursorPageX = this.cursorPage.z.cursorPageX;
+                    this.nrrd_states.interaction.cursorPageY = this.cursorPage.z.cursorPageY;
                 }
             }
             else if (axisTo === "x") {
-                if (this.nrrd_states.isCursorSelect && !this.cursorPage.x.updated) {
+                if (this.nrrd_states.interaction.isCursorSelect && !this.cursorPage.x.updated) {
                     if (this.protectedData.axis === "z") {
                         // convert z to x
                         convetObj = this.convertCursorPoint("z", "x", this.cursorPage.z.cursorPageX, this.cursorPage.z.cursorPageY, this.cursorPage.z.index);
@@ -739,15 +1063,15 @@ export class NrrdTools extends DrawToolCore {
                 }
                 else {
                     // not cursor select, freedom to switch z -> x or y -> x and x -> z or x -> y
-                    this.nrrd_states.currentIndex = this.cursorPage.x.index;
-                    this.nrrd_states.oldIndex =
-                        this.cursorPage.x.index * this.nrrd_states.ratios.x;
-                    this.nrrd_states.cursorPageX = this.cursorPage.x.cursorPageX;
-                    this.nrrd_states.cursorPageY = this.cursorPage.x.cursorPageY;
+                    this.nrrd_states.view.currentSliceIndex = this.cursorPage.x.index;
+                    this.nrrd_states.view.preSliceIndex =
+                        this.cursorPage.x.index * this.nrrd_states.image.ratios.x;
+                    this.nrrd_states.interaction.cursorPageX = this.cursorPage.x.cursorPageX;
+                    this.nrrd_states.interaction.cursorPageY = this.cursorPage.x.cursorPageY;
                 }
             }
             else if (axisTo === "y") {
-                if (this.nrrd_states.isCursorSelect && !this.cursorPage.y.updated) {
+                if (this.nrrd_states.interaction.isCursorSelect && !this.cursorPage.y.updated) {
                     if (this.protectedData.axis === "z") {
                         // convert z to y
                         convetObj = this.convertCursorPoint("z", "y", this.cursorPage.z.cursorPageX, this.cursorPage.z.cursorPageY, this.cursorPage.z.index);
@@ -759,19 +1083,19 @@ export class NrrdTools extends DrawToolCore {
                 }
                 else {
                     // not cursor select, freedom to switch z -> y or x -> y and y -> z or y -> x
-                    this.nrrd_states.currentIndex = this.cursorPage.y.index;
-                    this.nrrd_states.oldIndex =
-                        this.cursorPage.y.index * this.nrrd_states.ratios.y;
-                    this.nrrd_states.cursorPageX = this.cursorPage.y.cursorPageX;
-                    this.nrrd_states.cursorPageY = this.cursorPage.y.cursorPageY;
+                    this.nrrd_states.view.currentSliceIndex = this.cursorPage.y.index;
+                    this.nrrd_states.view.preSliceIndex =
+                        this.cursorPage.y.index * this.nrrd_states.image.ratios.y;
+                    this.nrrd_states.interaction.cursorPageX = this.cursorPage.y.cursorPageX;
+                    this.nrrd_states.interaction.cursorPageY = this.cursorPage.y.cursorPageY;
                 }
             }
             if (convetObj) {
                 // update convert cursor point, when cursor select
-                this.nrrd_states.currentIndex = convetObj.currentIndex;
-                this.nrrd_states.oldIndex = convetObj.oldIndex;
-                this.nrrd_states.cursorPageX = convetObj.convertCursorNumX;
-                this.nrrd_states.cursorPageY = convetObj.convertCursorNumY;
+                this.nrrd_states.view.currentSliceIndex = convetObj.currentNewSliceIndex;
+                this.nrrd_states.view.preSliceIndex = convetObj.preSliceIndex;
+                this.nrrd_states.interaction.cursorPageX = convetObj.convertCursorNumX;
+                this.nrrd_states.interaction.cursorPageY = convetObj.convertCursorNumY;
                 convetObj = undefined;
                 switch (axisTo) {
                     case "x":
@@ -789,47 +1113,52 @@ export class NrrdTools extends DrawToolCore {
                 this.cursorPage.y.updated &&
                 this.cursorPage.z.updated) {
                 // one point convert to all axis, reset all updated status
-                this.nrrd_states.isCursorSelect = false;
+                this.nrrd_states.interaction.isCursorSelect = false;
             }
         }
         this.protectedData.axis = axisTo;
         this.resetDisplaySlicesStatus();
-        // for sphere plan a
-        if (this.gui_states.sphere && !this.nrrd_states.spherePlanB) {
-            this.drawSphere(this.nrrd_states.sphereOrigin[axisTo][0] * this.nrrd_states.sizeFoctor, this.nrrd_states.sphereOrigin[axisTo][1] * this.nrrd_states.sizeFoctor, this.nrrd_states.sphereRadius);
-        }
     }
     addSkip(index) {
         this.protectedData.skipSlicesDic[index] =
             this.protectedData.backUpDisplaySlices[index];
         if (index >= this.protectedData.displaySlices.length) {
-            this.nrrd_states.contrastNum = this.protectedData.displaySlices.length;
+            this.nrrd_states.view.contrastNum = this.protectedData.displaySlices.length;
         }
         else {
-            this.nrrd_states.contrastNum = index;
+            this.nrrd_states.view.contrastNum = index;
         }
         this.resetDisplaySlicesStatus();
     }
     removeSkip(index) {
         this.protectedData.skipSlicesDic[index] = undefined;
-        this.nrrd_states.contrastNum = 0;
+        this.nrrd_states.view.contrastNum = 0;
         this.resetDisplaySlicesStatus();
     }
-    clear() {
+    /**
+     * 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() {
         // To effectively reduce the js memory garbage
         this.protectedData.allSlicesArray.length = 0;
         this.protectedData.displaySlices.length = 0;
         // Phase 6: Clear all undo/redo stacks
         this.undoManager.clearAll();
         // Phase 3: Reset MaskVolume storage to 1×1×1 placeholders
-        this.protectedData.maskData.volumes = this.nrrd_states.layers.reduce((acc, id) => {
+        this.protectedData.maskData.volumes = this.nrrd_states.image.layers.reduce((acc, id) => {
             acc[id] = new MaskVolume(1, 1, 1, 1);
             return acc;
         }, {});
+        // Clear dedicated SphereMaskVolume
+        this.nrrd_states.sphere.sphereMaskVolume = null;
         // Invalidate reusable slice buffer
         this.invalidateSliceBuffer();
         this.clearDictionary(this.protectedData.skipSlicesDic);
-        // this.nrrd_states.previousPanelL = this.nrrd_states.previousPanelT = -99999;
+        // this.nrrd_states.view.previousPanelL = this.nrrd_states.view.previousPanelT = -99999;
         this.protectedData.canvases.displayCanvas.style.left =
             this.protectedData.canvases.drawingCanvas.style.left = "";
         this.protectedData.canvases.displayCanvas.style.top =
@@ -837,21 +1166,19 @@ export class NrrdTools extends DrawToolCore {
         this.protectedData.backUpDisplaySlices.length = 0;
         this.protectedData.mainPreSlices = undefined;
         this.protectedData.currentShowingSlice = undefined;
-        this.protectedData.previousDrawingImage =
-            this.protectedData.ctxes.emptyCtx.createImageData(1, 1);
         this.initState = true;
         this.protectedData.axis = "z";
-        this.nrrd_states.sizeFoctor = this.baseCanvasesSize;
-        this.gui_states.mainAreaSize = this.baseCanvasesSize;
+        this.nrrd_states.view.sizeFactor = this.baseCanvasesSize;
+        this.gui_states.viewConfig.mainAreaSize = this.baseCanvasesSize;
         this.resetLayerCanvas();
         this.protectedData.canvases.drawingCanvas.width =
             this.protectedData.canvases.drawingCanvas.width;
         this.protectedData.canvases.displayCanvas.width =
             this.protectedData.canvases.displayCanvas.width;
-        this.nrrd_states.tumourSphereOrigin = null;
-        this.nrrd_states.ribSphereOrigin = null;
-        this.nrrd_states.skinSphereOrigin = null;
-        this.nrrd_states.nippleSphereOrigin = null;
+        this.nrrd_states.sphere.tumourSphereOrigin = null;
+        this.nrrd_states.sphere.ribSphereOrigin = null;
+        this.nrrd_states.sphere.skinSphereOrigin = null;
+        this.nrrd_states.sphere.nippleSphereOrigin = null;
     }
     setSliceMoving(step) {
         if (this.protectedData.mainPreSlices) {
@@ -864,7 +1191,7 @@ export class NrrdTools extends DrawToolCore {
                 this._sliceRAFId = null;
                 const totalStep = this._pendingSliceStep;
                 this._pendingSliceStep = 0;
-                this.protectedData.Is_Draw = true;
+                this.protectedData.isDrawing = true;
                 this.setSyncsliceNum();
                 this.dragOperator.updateIndex(totalStep);
                 this.setIsDrawFalse(1000);
@@ -872,14 +1199,14 @@ export class NrrdTools extends DrawToolCore {
         }
     }
     setMainAreaSize(factor) {
-        this.nrrd_states.sizeFoctor = factor;
-        if (this.nrrd_states.sizeFoctor >= 8) {
-            this.nrrd_states.sizeFoctor = 8;
+        this.nrrd_states.view.sizeFactor = factor;
+        if (this.nrrd_states.view.sizeFactor >= 8) {
+            this.nrrd_states.view.sizeFactor = 8;
         }
-        else if (this.nrrd_states.sizeFoctor <= 1) {
-            this.nrrd_states.sizeFoctor = 1;
+        else if (this.nrrd_states.view.sizeFactor <= 1) {
+            this.nrrd_states.view.sizeFactor = 1;
         }
-        this.resizePaintArea(this.nrrd_states.sizeFoctor);
+        this.resizePaintArea(this.nrrd_states.view.sizeFactor);
         this.resetPaintAreaUIPosition();
         // this.setIsDrawFalse(1000);
     }
@@ -893,27 +1220,27 @@ export class NrrdTools extends DrawToolCore {
         return this.nrrd_states;
     }
     getMaxSliceNum() {
-        if (this.nrrd_states.showContrast) {
+        if (this.nrrd_states.view.showContrast) {
             return [
-                this.nrrd_states.maxIndex,
-                this.nrrd_states.maxIndex * this.protectedData.displaySlices.length,
+                this.nrrd_states.view.maxIndex,
+                this.nrrd_states.view.maxIndex * this.protectedData.displaySlices.length,
             ];
         }
         else {
-            return [this.nrrd_states.maxIndex];
+            return [this.nrrd_states.view.maxIndex];
         }
     }
     getCurrentSlicesNumAndContrastNum() {
         return {
-            currentIndex: this.nrrd_states.currentIndex,
-            contrastIndex: this.nrrd_states.contrastNum,
+            currentSliceIndex: this.nrrd_states.view.currentSliceIndex,
+            contrastIndex: this.nrrd_states.view.contrastNum,
         };
     }
     getCurrentSliceIndex() {
-        return Math.ceil(this.protectedData.mainPreSlices.index / this.nrrd_states.RSARatio);
+        return Math.ceil(this.protectedData.mainPreSlices.index / this.nrrd_states.image.RSARatio);
     }
     getIsShowContrastState() {
-        return this.nrrd_states.showContrast;
+        return this.nrrd_states.view.showContrast;
     }
     /**
      * Give a delay time to finish the last drawing before upcoming interrupt opreations.
@@ -923,7 +1250,7 @@ export class NrrdTools extends DrawToolCore {
      */
     setIsDrawFalse(target) {
         this.preTimer = setTimeout(() => {
-            this.protectedData.Is_Draw = false;
+            this.protectedData.isDrawing = false;
             if (this.preTimer) {
                 window.clearTimeout(this.preTimer);
                 this.preTimer = undefined;
@@ -978,35 +1305,37 @@ export class NrrdTools extends DrawToolCore {
         // (also calls resizePaintArea → reloads masks, resizes canvases)
         this.setOriginCanvasAndPre();
         // update the show number div on top area
-        this.dragOperator.updateShowNumDiv(this.nrrd_states.contrastNum);
+        this.dragOperator.updateShowNumDiv(this.nrrd_states.view.contrastNum);
         // repaint all contrast images
         this.repraintCurrentContrastSlice();
         // Refresh display after contrast repaint (no need for full resizePaintArea
         // since canvases were already resized in setOriginCanvasAndPre above)
         this.redrawDisplayCanvas();
         this.compositeAllLayers();
+        // Sync slider metadata with current volume (replaces old getGuiSettings() side-effect)
+        this.syncGuiParameterSettings();
     }
     setMainPreSlice() {
         this.protectedData.mainPreSlices = this.protectedData.displaySlices[0];
         if (this.protectedData.mainPreSlices) {
-            this.nrrd_states.RSARatio = this.protectedData.mainPreSlices.RSARatio;
+            this.nrrd_states.image.RSARatio = this.protectedData.mainPreSlices.RSARatio;
         }
     }
     setOriginCanvasAndPre() {
         if (this.protectedData.mainPreSlices) {
-            if (this.nrrd_states.oldIndex > this.nrrd_states.maxIndex)
-                this.nrrd_states.oldIndex = this.nrrd_states.maxIndex;
+            if (this.nrrd_states.view.preSliceIndex > this.nrrd_states.view.maxIndex)
+                this.nrrd_states.view.preSliceIndex = this.nrrd_states.view.maxIndex;
             if (this.initState) {
-                this.nrrd_states.oldIndex =
+                this.nrrd_states.view.preSliceIndex =
                     this.protectedData.mainPreSlices.initIndex *
-                        this.nrrd_states.RSARatio;
-                this.nrrd_states.currentIndex =
+                        this.nrrd_states.image.RSARatio;
+                this.nrrd_states.view.currentSliceIndex =
                     this.protectedData.mainPreSlices.initIndex;
             }
             else {
                 // !need to change
                 // todo
-                this.protectedData.mainPreSlices.index = this.nrrd_states.oldIndex;
+                this.protectedData.mainPreSlices.index = this.nrrd_states.view.preSliceIndex;
             }
             this.protectedData.canvases.originCanvas =
                 this.protectedData.mainPreSlices.canvas;
@@ -1017,34 +1346,35 @@ export class NrrdTools extends DrawToolCore {
         this.setMainPreSlice();
         this.setOriginCanvasAndPre();
         this.protectedData.currentShowingSlice = this.protectedData.mainPreSlices;
-        this.nrrd_states.oldIndex =
-            this.protectedData.mainPreSlices.initIndex * this.nrrd_states.RSARatio;
-        this.nrrd_states.currentIndex = this.protectedData.mainPreSlices.initIndex;
+        this.nrrd_states.view.preSliceIndex =
+            this.protectedData.mainPreSlices.initIndex * this.nrrd_states.image.RSARatio;
+        this.nrrd_states.view.currentSliceIndex = this.protectedData.mainPreSlices.initIndex;
         // Phase 6: Reset undo/redo stacks on new dataset load
         this.undoManager.clearAll();
         // compute max index
         this.updateMaxIndex();
-        this.dragOperator.updateShowNumDiv(this.nrrd_states.contrastNum);
+        this.dragOperator.updateShowNumDiv(this.nrrd_states.view.contrastNum);
+        this.syncGuiParameterSettings();
         this.initState = false;
     }
     updateMaxIndex() {
         if (this.protectedData.mainPreSlices) {
-            this.nrrd_states.maxIndex = this.protectedData.mainPreSlices.MaxIndex;
+            this.nrrd_states.view.maxIndex = this.protectedData.mainPreSlices.MaxIndex;
         }
     }
     /**
      * 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() {
-        this.nrrd_states.originWidth =
+        this.nrrd_states.image.originWidth =
             this.protectedData.canvases.originCanvas.width;
-        this.nrrd_states.originHeight =
+        this.nrrd_states.image.originHeight =
             this.protectedData.canvases.originCanvas.height;
         // Let resizePaintArea be the sole setter of changedWidth/changedHeight.
         // Setting them here would defeat the sizeChanged detection in resizePaintArea,
         // causing canvas elements to keep stale dimensions after axis switches.
-        this.resizePaintArea(this.nrrd_states.sizeFoctor);
+        this.resizePaintArea(this.nrrd_states.view.sizeFactor);
         this.resetPaintAreaUIPosition();
     }
     /**
@@ -1061,17 +1391,24 @@ export class NrrdTools extends DrawToolCore {
     appendLoadingbar(loadingbar) {
         this.protectedData.mainAreaContainer.appendChild(loadingbar);
     }
-    clearStoreImages() {
+    /**
+     * 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() {
         // Phase 3 Task 3.1: Only clear the active layer's MaskVolume
-        if (this.nrrd_states.dimensions.length === 3) {
-            const [w, h, d] = this.nrrd_states.dimensions;
-            const activeLayer = this.gui_states.layer;
+        if (this.nrrd_states.image.dimensions.length === 3) {
+            const [w, h, d] = this.nrrd_states.image.dimensions;
+            const activeLayer = this.gui_states.layerChannel.layer;
             // Re-init only the active layer's MaskVolume
             this.protectedData.maskData.volumes[activeLayer] = new MaskVolume(w, h, d, 1);
             // Phase 6 Task 6.6: Clear undo/redo stack for this layer (volume too large to snapshot)
             this.undoManager.clearLayer(activeLayer);
             // Phase 3 Task 3.2: Notify external that this layer's volume was cleared
-            this.nrrd_states.onClearLayerVolume(activeLayer);
+            this.annotationCallbacks.onLayerVolumeCleared(activeLayer);
         }
         // Invalidate reusable slice buffer
         this.invalidateSliceBuffer();
@@ -1110,6 +1447,59 @@ export class NrrdTools extends DrawToolCore {
             target.canvas.width = target.canvas.width;
         }
     }
+    /**
+     * 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() {
+        var _a;
+        // Disable left-click drag for slice navigation
+        this.dragOperator.removeDragMode();
+        // Tell EventRouter we're in sphere mode so Shift/draw is blocked
+        (_a = this.eventRouter) === null || _a === void 0 ? void 0 : _a.setGuiTool('sphere');
+        // Clear all layer canvases (NOT MaskVolumes — just visual canvas)
+        const w = this.nrrd_states.view.changedWidth;
+        const h = this.nrrd_states.view.changedHeight;
+        for (const layerId of this.nrrd_states.image.layers) {
+            const target = this.protectedData.layerTargets.get(layerId);
+            if (target) {
+                target.ctx.clearRect(0, 0, target.canvas.width, target.canvas.height);
+            }
+        }
+        // Clear master composite canvas
+        this.protectedData.ctxes.drawingLayerMasterCtx.clearRect(0, 0, w, h);
+        // Refresh sphere overlay from volume (shows existing sphere data on re-entry)
+        this.refreshSphereOverlay();
+    }
+    /**
+     * 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() {
+        var _a;
+        // Restore left-click drag for slice navigation
+        this.dragOperator.configDragMode();
+        // Restore EventRouter guiTool to pencil (default drawing tool)
+        (_a = this.eventRouter) === null || _a === void 0 ? void 0 : _a.setGuiTool('pencil');
+        // Clear sphere canvas overlay
+        this.protectedData.ctxes.drawingSphereCtx.clearRect(0, 0, this.protectedData.canvases.drawingSphereCanvas.width, this.protectedData.canvases.drawingSphereCanvas.height);
+        // resetLayerCanvas clears the layer canvas elements
+        this.resetLayerCanvas();
+        // Temporarily lift sphere guard so reloadMasksFromVolume can run.
+        // gui_states.sphere is already set to false by the caller before
+        // calling this method, so reloadMasksFromVolume will proceed normally.
+        this.reloadMasksFromVolume();
+    }
     redrawMianPreOnDisplayCanvas() {
         var _a;
         this.protectedData.canvases.displayCanvas.width =
@@ -1121,8 +1511,8 @@ export class NrrdTools extends DrawToolCore {
         if (this.protectedData.mainPreSlices) {
             this.protectedData.mainPreSlices.repaint.call(this.protectedData.mainPreSlices);
             this.flipDisplayImageByAxis();
-            (_a = this.protectedData.ctxes.displayCtx) === null || _a === void 0 ? void 0 : _a.drawImage(this.protectedData.canvases.originCanvas, 0, 0, this.nrrd_states.changedWidth, this.nrrd_states.changedHeight);
-            this.resizePaintArea(this.nrrd_states.sizeFoctor);
+            (_a = this.protectedData.ctxes.displayCtx) === null || _a === void 0 ? void 0 : _a.drawImage(this.protectedData.canvases.originCanvas, 0, 0, this.nrrd_states.view.changedWidth, this.nrrd_states.view.changedHeight);
+            this.resizePaintArea(this.nrrd_states.view.sizeFactor);
         }
     }
     /**
@@ -1130,10 +1520,10 @@ export class NrrdTools extends DrawToolCore {
      * @param factor number
      */
     resizePaintArea(factor) {
-        const newWidth = Math.floor(this.nrrd_states.originWidth * factor);
-        const newHeight = Math.floor(this.nrrd_states.originHeight * factor);
-        const sizeChanged = newWidth !== this.nrrd_states.changedWidth ||
-            newHeight !== this.nrrd_states.changedHeight;
+        const newWidth = Math.floor(this.nrrd_states.image.originWidth * factor);
+        const newHeight = Math.floor(this.nrrd_states.image.originHeight * factor);
+        const sizeChanged = newWidth !== this.nrrd_states.view.changedWidth ||
+            newHeight !== this.nrrd_states.view.changedHeight;
         // Always clear display/drawing/origin canvases (needed for contrast updates)
         this.protectedData.canvases.originCanvas.width =
             this.protectedData.canvases.originCanvas.width;
@@ -1146,8 +1536,8 @@ export class NrrdTools extends DrawToolCore {
             // Skipping this avoids the expensive reloadMasksFromVolume() call
             // during contrast toggle (where size stays the same).
             this.resetLayerCanvas();
-            this.nrrd_states.changedWidth = newWidth;
-            this.nrrd_states.changedHeight = newHeight;
+            this.nrrd_states.view.changedWidth = newWidth;
+            this.nrrd_states.view.changedHeight = newHeight;
             this.protectedData.canvases.displayCanvas.width = newWidth;
             this.protectedData.canvases.displayCanvas.height = newHeight;
             this.protectedData.canvases.drawingCanvas.width = newWidth;
@@ -1169,18 +1559,25 @@ export class NrrdTools extends DrawToolCore {
             // valid data, just recomposite to master for the start() render loop.
             this.compositeAllLayers();
         }
+        // Refresh sphere overlay from volume after resize/contrast change
+        this.refreshSphereOverlay();
     }
     /**
      * Phase 3: Reload all mask layers from MaskVolume using buffer reuse
      * Replaces the old reloadMaskToLayer approach
      */
     reloadMasksFromVolume() {
+        // When sphere mode is active, do NOT redraw layer masks.
+        // Layer mask data should remain hidden until the user exits sphere mode.
+        if (this.gui_states.mode.sphere) {
+            return;
+        }
         const axis = this.protectedData.axis;
-        let sliceIndex = this.nrrd_states.currentIndex;
+        let sliceIndex = this.nrrd_states.view.currentSliceIndex;
         // Clamp sliceIndex to valid range for current axis
-        // (currentIndex may not be updated yet when switching axes)
+        // (currentSliceIndex may not be updated yet when switching axes)
         try {
-            const vol = this.getVolumeForLayer(this.nrrd_states.layers[0]);
+            const vol = this.getVolumeForLayer(this.nrrd_states.image.layers[0]);
             const dims = vol.getDimensions();
             const maxSlice = axis === "x" ? dims.width : axis === "y" ? dims.height : dims.depth;
             if (sliceIndex >= maxSlice)
@@ -1193,10 +1590,10 @@ export class NrrdTools extends DrawToolCore {
         const buffer = this.getOrCreateSliceBuffer(axis);
         if (!buffer)
             return;
-        const w = this.nrrd_states.changedWidth;
-        const h = this.nrrd_states.changedHeight;
+        const w = this.nrrd_states.view.changedWidth;
+        const h = this.nrrd_states.view.changedHeight;
         // Clear and render each layer using the shared buffer
-        for (const layerId of this.nrrd_states.layers) {
+        for (const layerId of this.nrrd_states.image.layers) {
             const target = this.protectedData.layerTargets.get(layerId);
             if (!target)
                 continue;
@@ -1217,15 +1614,15 @@ export class NrrdTools extends DrawToolCore {
         var _a, _b, _c, _d, _e, _f;
         if (this.protectedData.axis === "x") {
             (_a = this.protectedData.ctxes.displayCtx) === null || _a === void 0 ? void 0 : _a.scale(-1, -1);
-            (_b = this.protectedData.ctxes.displayCtx) === null || _b === void 0 ? void 0 : _b.translate(-this.nrrd_states.changedWidth, -this.nrrd_states.changedHeight);
+            (_b = this.protectedData.ctxes.displayCtx) === null || _b === void 0 ? void 0 : _b.translate(-this.nrrd_states.view.changedWidth, -this.nrrd_states.view.changedHeight);
         }
         else if (this.protectedData.axis === "z") {
             (_c = this.protectedData.ctxes.displayCtx) === null || _c === void 0 ? void 0 : _c.scale(1, -1);
-            (_d = this.protectedData.ctxes.displayCtx) === null || _d === void 0 ? void 0 : _d.translate(0, -this.nrrd_states.changedHeight);
+            (_d = this.protectedData.ctxes.displayCtx) === null || _d === void 0 ? void 0 : _d.translate(0, -this.nrrd_states.view.changedHeight);
         }
         else if (this.protectedData.axis === "y") {
             (_e = this.protectedData.ctxes.displayCtx) === null || _e === void 0 ? void 0 : _e.scale(1, -1);
-            (_f = this.protectedData.ctxes.displayCtx) === null || _f === void 0 ? void 0 : _f.translate(0, -this.nrrd_states.changedHeight);
+            (_f = this.protectedData.ctxes.displayCtx) === null || _f === void 0 ? void 0 : _f.translate(0, -this.nrrd_states.view.changedHeight);
         }
     }
     clearDictionary(dic) {
@@ -1242,21 +1639,21 @@ export class NrrdTools extends DrawToolCore {
         switch (!!axis ? axis : this.protectedData.axis) {
             case "x":
                 this.protectedData.canvases.emptyCanvas.width =
-                    this.nrrd_states.nrrd_z_pixel;
+                    this.nrrd_states.image.nrrd_z_pixel;
                 this.protectedData.canvases.emptyCanvas.height =
-                    this.nrrd_states.nrrd_y_pixel;
+                    this.nrrd_states.image.nrrd_y_pixel;
                 break;
             case "y":
                 this.protectedData.canvases.emptyCanvas.width =
-                    this.nrrd_states.nrrd_x_pixel;
+                    this.nrrd_states.image.nrrd_x_pixel;
                 this.protectedData.canvases.emptyCanvas.height =
-                    this.nrrd_states.nrrd_z_pixel;
+                    this.nrrd_states.image.nrrd_z_pixel;
                 break;
             case "z":
                 this.protectedData.canvases.emptyCanvas.width =
-                    this.nrrd_states.nrrd_x_pixel;
+                    this.nrrd_states.image.nrrd_x_pixel;
                 this.protectedData.canvases.emptyCanvas.height =
-                    this.nrrd_states.nrrd_y_pixel;
+                    this.nrrd_states.image.nrrd_y_pixel;
                 break;
         }
     }
@@ -1278,7 +1675,7 @@ export class NrrdTools extends DrawToolCore {
             this.protectedData.currentShowingSlice.repaint.call(this.protectedData.currentShowingSlice);
             (_a = this.protectedData.ctxes.displayCtx) === null || _a === void 0 ? void 0 : _a.save();
             this.flipDisplayImageByAxis();
-            (_b = this.protectedData.ctxes.displayCtx) === null || _b === void 0 ? void 0 : _b.drawImage(this.protectedData.currentShowingSlice.canvas, 0, 0, this.nrrd_states.changedWidth, this.nrrd_states.changedHeight);
+            (_b = this.protectedData.ctxes.displayCtx) === null || _b === void 0 ? void 0 : _b.drawImage(this.protectedData.currentShowingSlice.canvas, 0, 0, this.nrrd_states.view.changedWidth, this.nrrd_states.view.changedHeight);
             (_c = this.protectedData.ctxes.displayCtx) === null || _c === void 0 ? void 0 : _c.restore();
         }
     }