copper3d 3.0.1 → 3.1.0

package/dist/Utils/segmentation/tools/SphereTool.js

@@ -1,14 +1,84 @@
 /**
  * SphereTool - Sphere drawing and calculator sphere operations
  *
+ * Provides 3D sphere placement across multiple slice views.
+ * Supports 4 sphere types: tumour, skin, nipple, ribcage.
+ * Each type maps to a specific layer and channel for future MaskVolume integration.
+ *
+ * ## Interaction Flow
+ * 1. Sphere mode activated (gui_states.sphere = true)
+ *    - Draw mode (Shift key) is disabled
+ *    - Crosshair toggle is disabled
+ * 2. Left-click down: record sphere center (mouseX, mouseY, sliceIndex)
+ *    - Remove zoom/slice wheel event
+ *    - Bind sphere wheel event
+ *    - Draw preview circle on sphereCanvas
+ * 3. While holding left-click, scroll wheel adjusts sphereRadius [1, 50]
+ * 4. Left-click up:
+ *    - Fire getSphere / getCalculateSpherePositions callbacks
+ *    - (Plan B) Draw 3D sphere across x/y/z axes into sphereMaskVolume
+ *    - Remove sphere wheel event
+ *    - Restore zoom/slice wheel event
+ *
+ * ## Channel Mapping
+ * Each sphere type defaults to layer1 with a specific channel:
+ * - tumour  → layer1, channel 1
+ * - ribcage → layer1, channel 3
+ * - skin    → layer1, channel 4
+ * - nipple  → layer1, channel 5
+ *
+ * ## SphereMaskVolume
+ * Sphere 3D data is stored in a dedicated MaskVolume (nrrd_states.sphereMaskVolume)
+ * separate from the layer draw mask volumes, to avoid polluting layer1's draw data.
+ * This volume is created in setAllSlices() and cleared in reset().
+ *
+ * ## Future: Writing to Layer MaskVolume
+ * Currently sphere data does NOT write to layer1's MaskVolume.
+ * The channel mapping and interfaces are reserved for future integration.
+ * When enabled, use SPHERE_CHANNEL_MAP to determine the target layer & channel,
+ * then call volume.setVoxel() or similar to persist sphere data.
+ *
  * Extracted from DrawToolCore.ts:
  * - drawSphere / drawSphereCore / clearSphereCanvas
  * - drawSphereOnEachViews / drawCalculatorSphereOnEachViews
  * - storeSphereImages / setSphereCanvasSize
  * - drawCalculatorSphere / configMouseSphereWheel
- * - getSpherePosition / clearSpherePrintStoreImages
+ * - getSpherePosition
  */
 import { BaseTool } from "./BaseTool";
+import { CHANNEL_HEX_COLORS } from "../core";
+/**
+ * Default layer and channel for each sphere type.
+ *
+ * This mapping is used to:
+ * 1. Determine the color for sphere preview rendering
+ * 2. (Future) Write sphere data into the corresponding layer's MaskVolume channel
+ *
+ * @example
+ * ```ts
+ * const { layer, channel } = SPHERE_CHANNEL_MAP['tumour'];
+ * // layer = 'layer1', channel = 1
+ * ```
+ */
+export const SPHERE_CHANNEL_MAP = {
+    tumour: { layer: 'layer1', channel: 1 },
+    nipple: { layer: 'layer1', channel: 2 },
+    ribcage: { layer: 'layer1', channel: 3 },
+    skin: { layer: 'layer1', channel: 4 },
+};
+// SPHERE_COLORS was removed to enforce dynamic color lookups.
+/**
+ * Label values for sphere types stored in sphereMaskVolume.
+ * Regular sphere mode uses SPHERE_LABEL (1).
+ * Calculator mode uses type-specific labels (1-4).
+ */
+export const SPHERE_LABELS = {
+    default: 1,
+    tumour: 1,
+    nipple: 2,
+    ribcage: 3,
+    skin: 4,
+};
 export class SphereTool extends BaseTool {
     constructor(ctx, callbacks) {
         super(ctx);
@@ -17,25 +87,84 @@ export class SphereTool extends BaseTool {
     setCallbacks(callbacks) {
         this.callbacks = callbacks;
     }
+    // ===== Sphere Type Helpers =====
+    /**
+     * Get the channel number for a sphere type.
+     *
+     * @param type - Sphere type ('tumour', 'skin', 'ribcage', 'nipple')
+     * @returns Channel number (1-8) mapped to this sphere type
+     *
+     * @example
+     * ```ts
+     * sphereTool.getChannelForSphereType('tumour');  // → 1
+     * sphereTool.getChannelForSphereType('skin');    // → 4
+     * ```
+     */
+    getChannelForSphereType(type) {
+        return SPHERE_CHANNEL_MAP[type].channel;
+    }
+    /**
+     * Get the default layer for a sphere type.
+     *
+     * @param type - Sphere type
+     * @returns Layer ID (e.g. 'layer1')
+     */
+    getLayerForSphereType(type) {
+        return SPHERE_CHANNEL_MAP[type].layer;
+    }
+    /**
+     * Get the preview color for a sphere type.
+     *
+     * If a volume is available for the target layer, uses the volume's
+     * custom color map (respects per-layer color customization).
+     * Otherwise falls back to SPHERE_COLORS (derived from CHANNEL_HEX_COLORS).
+     *
+     * @param type - Sphere type
+     * @returns CSS color string (hex)
+     */
+    getColorForSphereType(type) {
+        const { layer, channel } = SPHERE_CHANNEL_MAP[type];
+        const volumes = this.ctx.protectedData.maskData.volumes;
+        const volume = volumes[layer];
+        if (volume) {
+            // Use per-layer custom color if available
+            const rgba = volume.getChannelColor(channel);
+            // Convert RGBA to hex
+            const r = rgba.r.toString(16).padStart(2, '0');
+            const g = rgba.g.toString(16).padStart(2, '0');
+            const b = rgba.b.toString(16).padStart(2, '0');
+            return `#${r}${g}${b}`;
+        }
+        return CHANNEL_HEX_COLORS[channel];
+    }
     // ===== Sphere Canvas Size =====
     setSphereCanvasSize(axis) {
         const nrrd = this.ctx.nrrd_states;
         switch (axis !== null && axis !== void 0 ? axis : this.ctx.protectedData.axis) {
             case "x":
-                this.ctx.protectedData.canvases.drawingSphereCanvas.width = nrrd.nrrd_z_mm;
-                this.ctx.protectedData.canvases.drawingSphereCanvas.height = nrrd.nrrd_y_mm;
+                this.ctx.protectedData.canvases.drawingSphereCanvas.width = nrrd.image.nrrd_z_mm;
+                this.ctx.protectedData.canvases.drawingSphereCanvas.height = nrrd.image.nrrd_y_mm;
                 break;
             case "y":
-                this.ctx.protectedData.canvases.drawingSphereCanvas.width = nrrd.nrrd_x_mm;
-                this.ctx.protectedData.canvases.drawingSphereCanvas.height = nrrd.nrrd_z_mm;
+                this.ctx.protectedData.canvases.drawingSphereCanvas.width = nrrd.image.nrrd_x_mm;
+                this.ctx.protectedData.canvases.drawingSphereCanvas.height = nrrd.image.nrrd_z_mm;
                 break;
             case "z":
-                this.ctx.protectedData.canvases.drawingSphereCanvas.width = nrrd.nrrd_x_mm;
-                this.ctx.protectedData.canvases.drawingSphereCanvas.height = nrrd.nrrd_y_mm;
+                this.ctx.protectedData.canvases.drawingSphereCanvas.width = nrrd.image.nrrd_x_mm;
+                this.ctx.protectedData.canvases.drawingSphereCanvas.height = nrrd.image.nrrd_y_mm;
                 break;
         }
     }
     // ===== Core Sphere Drawing =====
+    /**
+     * Draw a filled circle on the given context.
+     *
+     * @param ctx - Canvas 2D context
+     * @param x - Center X coordinate
+     * @param y - Center Y coordinate
+     * @param radius - Circle radius in pixels
+     * @param color - Fill color (CSS string)
+     */
     drawSphereCore(ctx, x, y, radius, color) {
         ctx.beginPath();
         ctx.arc(x, y, radius, 0, 2 * Math.PI);
@@ -57,50 +186,84 @@ export class SphereTool extends BaseTool {
             this.ctx.protectedData.ctxes.drawingSphereCtx,
         ];
     }
+    /**
+     * Draw a sphere preview circle on the sphere canvas using the current
+     * gui_states.fillColor. Called during sphere mode pointer-down.
+     *
+     * NOTE: Does NOT composite to master canvas — the start() render loop
+     * draws the sphere canvas directly to drawingCtx for proper layering.
+     */
     drawSphere(mouseX, mouseY, radius) {
-        const [canvas, ctx] = this.clearSphereCanvas();
-        this.drawSphereCore(ctx, mouseX, mouseY, radius, this.ctx.gui_states.fillColor);
-        this.ctx.protectedData.ctxes.drawingLayerMasterCtx.drawImage(canvas, 0, 0, this.ctx.nrrd_states.changedWidth, this.ctx.nrrd_states.changedHeight);
+        const [, ctx] = this.clearSphereCanvas();
+        const color = this.getColorForSphereType(this.ctx.gui_states.mode.activeSphereType);
+        drawSphereCore(ctx, mouseX, mouseY, radius, color);
     }
     // ===== Sphere Wheel =====
+    /**
+     * Returns a wheel event handler that adjusts sphere radius while the user
+     * holds left-click in sphere mode.
+     *
+     * Radius is clamped to [1, 50].
+     */
     configMouseSphereWheel() {
         return (e) => {
             e.preventDefault();
             if (e.deltaY < 0) {
-                this.ctx.nrrd_states.sphereRadius += 1;
+                this.ctx.nrrd_states.sphere.sphereRadius += 1;
             }
             else {
-                this.ctx.nrrd_states.sphereRadius -= 1;
+                this.ctx.nrrd_states.sphere.sphereRadius -= 1;
             }
-            this.ctx.nrrd_states.sphereRadius = Math.max(1, Math.min(this.ctx.nrrd_states.sphereRadius, 50));
-            const mouseX = this.ctx.nrrd_states.sphereOrigin[this.ctx.protectedData.axis][0];
-            const mouseY = this.ctx.nrrd_states.sphereOrigin[this.ctx.protectedData.axis][1];
-            this.drawSphere(mouseX, mouseY, this.ctx.nrrd_states.sphereRadius);
+            this.ctx.nrrd_states.sphere.sphereRadius = Math.max(1, Math.min(this.ctx.nrrd_states.sphere.sphereRadius, 50));
+            const mouseX = this.ctx.nrrd_states.sphere.sphereOrigin[this.ctx.protectedData.axis][0];
+            const mouseY = this.ctx.nrrd_states.sphere.sphereOrigin[this.ctx.protectedData.axis][1];
+            this.drawSphere(mouseX, mouseY, this.ctx.nrrd_states.sphere.sphereRadius);
         };
     }
     // ===== Store Sphere Images =====
-    storeSphereImages(index, axis) {
-        this.callbacks.setEmptyCanvasSize(axis);
-        this.callbacks.drawImageOnEmptyImage(this.ctx.protectedData.canvases.drawingSphereCanvas);
-        const imageData = this.ctx.protectedData.ctxes.emptyCtx.getImageData(0, 0, this.ctx.protectedData.canvases.emptyCanvas.width, this.ctx.protectedData.canvases.emptyCanvas.height);
-        this.callbacks.storeImageToAxis(index, imageData, axis);
+    /**
+     * Store sphere slice image into SphereMaskVolume.
+     *
+     * Currently a no-op — sphere slice data is rendered as overlay only.
+     *
+     * TODO: Future — write sphere circle data into nrrd_states.sphereMaskVolume
+     * at the specified slice index and axis. Use SPHERE_CHANNEL_MAP to determine
+     * the target channel when integrating with layer MaskVolume.
+     */
+    storeSphereImages(_index, _axis) {
+        // No-op: sphere slice storage is rendered as overlay.
+        // Future: write to nrrd_states.sphereMaskVolume here.
     }
     // ===== Multi-View Sphere =====
+    /**
+     * Draw a sphere cross-section at a given decay distance from center,
+     * for a specific axis view.
+     *
+     * Called for each decay value [0..sphereRadius] for all 3 axes,
+     * creating the 3D sphere effect.
+     *
+     * The sphere circle radius at each slice = sphereRadius - decay (linear decay).
+     *
+     * @param decay - Distance from sphere center slice
+     * @param axis - Axis to render on ('x', 'y', 'z')
+     */
     drawSphereOnEachViews(decay, axis) {
         this.setSphereCanvasSize(axis);
-        const mouseX = this.ctx.nrrd_states.sphereOrigin[axis][0];
-        const mouseY = this.ctx.nrrd_states.sphereOrigin[axis][1];
-        const originIndex = this.ctx.nrrd_states.sphereOrigin[axis][2];
+        const mouseX = this.ctx.nrrd_states.sphere.sphereOrigin[axis][0];
+        const mouseY = this.ctx.nrrd_states.sphere.sphereOrigin[axis][1];
+        const originIndex = this.ctx.nrrd_states.sphere.sphereOrigin[axis][2];
         const preIndex = originIndex - decay;
         const nextIndex = originIndex + decay;
         const ctx = this.ctx.protectedData.ctxes.drawingSphereCtx;
         const canvas = this.ctx.protectedData.canvases.drawingSphereCanvas;
+        // Use the dynamic type color instead of the static fillColor
+        const color = this.getColorForSphereType(this.ctx.gui_states.mode.activeSphereType);
         if (preIndex === nextIndex) {
-            this.drawSphereCore(ctx, mouseX, mouseY, this.ctx.nrrd_states.sphereRadius, this.ctx.gui_states.fillColor);
+            this.drawSphereCore(ctx, mouseX, mouseY, this.ctx.nrrd_states.sphere.sphereRadius, color);
             this.storeSphereImages(preIndex, axis);
         }
         else {
-            this.drawSphereCore(ctx, mouseX, mouseY, this.ctx.nrrd_states.sphereRadius - decay, this.ctx.gui_states.fillColor);
+            this.drawSphereCore(ctx, mouseX, mouseY, this.ctx.nrrd_states.sphere.sphereRadius - decay, color);
             this.callbacks.drawImageOnEmptyImage(canvas);
             this.storeSphereImages(preIndex, axis);
             this.storeSphereImages(nextIndex, axis);
@@ -115,22 +278,31 @@ export class SphereTool extends BaseTool {
             z: position[axis][2],
         };
     }
+    /**
+     * Draw all 4 calculator sphere types on each view axis.
+     *
+     * Groups sphere positions by their slice index so that spheres on the
+     * same slice are drawn together before storing.
+     *
+     * Uses SPHERE_COLORS for each sphere type instead of nrrd_states.*Color.
+     */
     drawCalculatorSphereOnEachViews(axis) {
         this.setSphereCanvasSize(axis);
         const ctx = this.ctx.protectedData.ctxes.drawingSphereCtx;
         const canvas = this.ctx.protectedData.canvases.drawingSphereCanvas;
         const nrrd = this.ctx.nrrd_states;
-        const tumourPosition = nrrd.tumourSphereOrigin
-            ? Object.assign(this.getSpherePosition(nrrd.tumourSphereOrigin, axis), { color: nrrd.tumourColor })
+        // Build position list with dynamic sphere type colors
+        const tumourPosition = nrrd.sphere.tumourSphereOrigin
+            ? Object.assign(this.getSpherePosition(nrrd.sphere.tumourSphereOrigin, axis), { color: this.getColorForSphereType('tumour') })
             : null;
-        const skinPosition = nrrd.skinSphereOrigin
-            ? Object.assign(this.getSpherePosition(nrrd.skinSphereOrigin, axis), { color: nrrd.skinColor })
+        const skinPosition = nrrd.sphere.skinSphereOrigin
+            ? Object.assign(this.getSpherePosition(nrrd.sphere.skinSphereOrigin, axis), { color: this.getColorForSphereType('skin') })
             : null;
-        const ribcagePosition = nrrd.ribSphereOrigin
-            ? Object.assign(this.getSpherePosition(nrrd.ribSphereOrigin, axis), { color: nrrd.ribcageColor })
+        const ribcagePosition = nrrd.sphere.ribSphereOrigin
+            ? Object.assign(this.getSpherePosition(nrrd.sphere.ribSphereOrigin, axis), { color: this.getColorForSphereType('ribcage') })
             : null;
-        const nipplePosition = nrrd.nippleSphereOrigin
-            ? Object.assign(this.getSpherePosition(nrrd.nippleSphereOrigin, axis), { color: nrrd.nippleColor })
+        const nipplePosition = nrrd.sphere.nippleSphereOrigin
+            ? Object.assign(this.getSpherePosition(nrrd.sphere.nippleSphereOrigin, axis), { color: this.getColorForSphereType('nipple') })
             : null;
         const positionGroup = [];
         if (tumourPosition)
@@ -162,32 +334,325 @@ export class SphereTool extends BaseTool {
         });
         rePositionGroup.forEach((group) => {
             group.forEach((p) => {
-                this.drawSphereCore(ctx, p.x, p.y, nrrd.sphereRadius, p.color);
+                this.drawSphereCore(ctx, p.x, p.y, nrrd.sphere.sphereRadius, p.color);
             });
             this.storeSphereImages(group[0].z, axis);
             ctx.clearRect(0, 0, canvas.width, canvas.height);
         });
     }
+    /**
+     * Draw all placed calculator spheres on the current slice.
+     *
+     * Called every frame to show existing sphere markers on the current view.
+     * Uses SPHERE_COLORS for consistent type-based coloring.
+     *
+     * @param radius - Sphere radius to draw
+     */
     drawCalculatorSphere(radius) {
-        const [canvas, ctx] = this.clearSphereCanvas();
+        const [, ctx] = this.clearSphereCanvas();
         const nrrd = this.ctx.nrrd_states;
         const axis = this.ctx.protectedData.axis;
-        if (nrrd.tumourSphereOrigin && nrrd.tumourSphereOrigin[axis][2] === nrrd.currentIndex) {
-            this.drawSphereCore(ctx, nrrd.tumourSphereOrigin[axis][0], nrrd.tumourSphereOrigin[axis][1], radius, nrrd.tumourColor);
+        if (nrrd.sphere.tumourSphereOrigin && nrrd.sphere.tumourSphereOrigin[axis][2] === nrrd.view.currentSliceIndex) {
+            this.drawSphereCore(ctx, nrrd.sphere.tumourSphereOrigin[axis][0], nrrd.sphere.tumourSphereOrigin[axis][1], radius, this.getColorForSphereType('tumour'));
         }
-        if (nrrd.skinSphereOrigin && nrrd.skinSphereOrigin[axis][2] === nrrd.currentIndex) {
-            this.drawSphereCore(ctx, nrrd.skinSphereOrigin[axis][0], nrrd.skinSphereOrigin[axis][1], radius, nrrd.skinColor);
+        if (nrrd.sphere.skinSphereOrigin && nrrd.sphere.skinSphereOrigin[axis][2] === nrrd.view.currentSliceIndex) {
+            this.drawSphereCore(ctx, nrrd.sphere.skinSphereOrigin[axis][0], nrrd.sphere.skinSphereOrigin[axis][1], radius, this.getColorForSphereType('skin'));
         }
-        if (nrrd.ribSphereOrigin && nrrd.ribSphereOrigin[axis][2] === nrrd.currentIndex) {
-            this.drawSphereCore(ctx, nrrd.ribSphereOrigin[axis][0], nrrd.ribSphereOrigin[axis][1], radius, nrrd.ribcageColor);
+        if (nrrd.sphere.ribSphereOrigin && nrrd.sphere.ribSphereOrigin[axis][2] === nrrd.view.currentSliceIndex) {
+            this.drawSphereCore(ctx, nrrd.sphere.ribSphereOrigin[axis][0], nrrd.sphere.ribSphereOrigin[axis][1], radius, this.getColorForSphereType('ribcage'));
         }
-        if (nrrd.nippleSphereOrigin && nrrd.nippleSphereOrigin[axis][2] === nrrd.currentIndex) {
-            this.drawSphereCore(ctx, nrrd.nippleSphereOrigin[axis][0], nrrd.nippleSphereOrigin[axis][1], radius, nrrd.nippleColor);
+        if (nrrd.sphere.nippleSphereOrigin && nrrd.sphere.nippleSphereOrigin[axis][2] === nrrd.view.currentSliceIndex) {
+            this.drawSphereCore(ctx, nrrd.sphere.nippleSphereOrigin[axis][0], nrrd.sphere.nippleSphereOrigin[axis][1], radius, this.getColorForSphereType('nipple'));
         }
-        this.ctx.protectedData.ctxes.drawingLayerMasterCtx.drawImage(canvas, 0, 0, nrrd.changedWidth, nrrd.changedHeight);
+        // NOTE: Does NOT composite to master canvas — the start() render loop
+        // draws the sphere canvas directly to drawingCtx for proper layering.
     }
-    clearSpherePrintStoreImages() {
-        // No-op: sphere images are no longer stored in Phase 3 volumetric model
+    // ===== Sphere Click & PointerUp (extracted from DrawToolCore) =====
+    /**
+     * Handle left-click in sphere mode — record origin, draw preview.
+     *
+     * Performs all data operations for sphere placement:
+     * 1. Record sphere origin for current axis
+     * 2. Convert origin to all three axes via setUpSphereOrigins
+     * 3. Store origin for the active sphere type
+     * 4. Enable crosshair at click position
+     * 5. Draw calculator sphere preview
+     *
+     * Event binding (wheel, pointerup) stays in DrawToolCore as orchestration.
+     */
+    onSphereClick(e) {
+        const mouseX = e.offsetX / this.ctx.nrrd_states.view.sizeFactor;
+        const mouseY = e.offsetY / this.ctx.nrrd_states.view.sizeFactor;
+        const axis = this.ctx.protectedData.axis;
+        // Record sphere origin for current axis
+        this.ctx.nrrd_states.sphere.sphereOrigin[axis] = [
+            mouseX,
+            mouseY,
+            this.ctx.nrrd_states.view.currentSliceIndex,
+        ];
+        this.callbacks.setUpSphereOrigins(mouseX, mouseY, this.ctx.nrrd_states.view.currentSliceIndex);
+        // Store origin for the active sphere type
+        const originCopy = JSON.parse(JSON.stringify(this.ctx.nrrd_states.sphere.sphereOrigin));
+        switch (this.ctx.gui_states.mode.activeSphereType) {
+            case "tumour":
+                this.ctx.nrrd_states.sphere.tumourSphereOrigin = originCopy;
+                break;
+            case "skin":
+                this.ctx.nrrd_states.sphere.skinSphereOrigin = originCopy;
+                break;
+            case "nipple":
+                this.ctx.nrrd_states.sphere.nippleSphereOrigin = originCopy;
+                break;
+            case "ribcage":
+                this.ctx.nrrd_states.sphere.ribSphereOrigin = originCopy;
+                break;
+        }
+        // Enable crosshair at click position
+        this.ctx.nrrd_states.interaction.cursorPageX = mouseX;
+        this.ctx.nrrd_states.interaction.cursorPageY = mouseY;
+        this.callbacks.enableCrosshair();
+        // Draw calculator sphere preview
+        this.drawCalculatorSphere(this.ctx.nrrd_states.sphere.sphereRadius);
+    }
+    /**
+     * Handle pointer-up in sphere mode — write to volume, fire callbacks.
+     *
+     * Performs:
+     * 1. Write all placed calculator spheres to sphereMaskVolume
+     * 2. Refresh sphere canvas overlay from volume
+     * 3. Fire onSphereChanged and onCalculatorPositionsChanged callbacks
+     *
+     * Event cleanup (wheel, pointerup listener removal) stays in DrawToolCore.
+     */
+    onSpherePointerUp() {
+        this.writeAllCalculatorSpheresToVolume();
+        this.refreshSphereCanvas();
+        this.ctx.callbacks.onSphereChanged(this.ctx.nrrd_states.sphere.sphereOrigin.z, this.ctx.nrrd_states.sphere.sphereRadius /
+            this.ctx.nrrd_states.view.sizeFactor);
+        this.ctx.callbacks.onCalculatorPositionsChanged(this.ctx.nrrd_states.sphere.tumourSphereOrigin, this.ctx.nrrd_states.sphere.skinSphereOrigin, this.ctx.nrrd_states.sphere.ribSphereOrigin, this.ctx.nrrd_states.sphere.nippleSphereOrigin, this.ctx.protectedData.axis);
     }
+    // ===== 3D Sphere Volume Write =====
+    /**
+     * Convert canvas (mm-space) coordinates to 3D voxel coordinates.
+     *
+     * @param canvasX - X position in canvas mm-space
+     * @param canvasY - Y position in canvas mm-space
+     * @param sliceIndex - Slice index along the viewing axis
+     * @param axis - Viewing axis where the sphere was placed
+     * @returns 3D voxel coordinates { x, y, z }
+     */
+    canvasToVoxelCenter(canvasX, canvasY, sliceIndex, axis) {
+        const nrrd = this.ctx.nrrd_states;
+        switch (axis) {
+            case 'z':
+                return {
+                    x: canvasX * nrrd.image.nrrd_x_pixel / nrrd.image.nrrd_x_mm,
+                    y: canvasY * nrrd.image.nrrd_y_pixel / nrrd.image.nrrd_y_mm,
+                    z: sliceIndex,
+                };
+            case 'y':
+                return {
+                    x: canvasX * nrrd.image.nrrd_x_pixel / nrrd.image.nrrd_x_mm,
+                    y: sliceIndex,
+                    z: (nrrd.image.nrrd_z_mm - canvasY) * nrrd.image.nrrd_z_pixel / nrrd.image.nrrd_z_mm,
+                };
+            case 'x':
+                return {
+                    x: sliceIndex,
+                    y: canvasY * nrrd.image.nrrd_y_pixel / nrrd.image.nrrd_y_mm,
+                    z: canvasX * nrrd.image.nrrd_z_pixel / nrrd.image.nrrd_z_mm,
+                };
+        }
+    }
+    /**
+     * Write a 3D solid sphere to sphereMaskVolume.
+     *
+     * Converts the sphere center from canvas mm-space to voxel coordinates,
+     * then iterates over a bounding box and sets voxels within the sphere.
+     * The sphere is an ellipsoid in voxel space to appear circular in
+     * physical (mm) space on all axis views.
+     *
+     * @param label - Label value to write (1-4, default 1)
+     */
+    write3DSphereToVolume(label = SPHERE_LABELS.default) {
+        const vol = this.ctx.nrrd_states.sphere.sphereMaskVolume;
+        if (!vol)
+            return;
+        const nrrd = this.ctx.nrrd_states;
+        const axis = this.ctx.protectedData.axis;
+        const dims = vol.getDimensions();
+        const origin = nrrd.sphere.sphereOrigin[axis];
+        const center = this.canvasToVoxelCenter(origin[0], origin[1], origin[2], axis);
+        const radius = nrrd.sphere.sphereRadius;
+        // Convert mm radius to voxels in each direction
+        const rx = radius * nrrd.image.nrrd_x_pixel / nrrd.image.nrrd_x_mm;
+        const ry = radius * nrrd.image.nrrd_y_pixel / nrrd.image.nrrd_y_mm;
+        const rz = radius * nrrd.image.nrrd_z_pixel / nrrd.image.nrrd_z_mm;
+        // Bounding box clamped to volume
+        const minX = Math.max(0, Math.floor(center.x - rx));
+        const maxX = Math.min(dims.width - 1, Math.ceil(center.x + rx));
+        const minY = Math.max(0, Math.floor(center.y - ry));
+        const maxY = Math.min(dims.height - 1, Math.ceil(center.y + ry));
+        const minZ = Math.max(0, Math.floor(center.z - rz));
+        const maxZ = Math.min(dims.depth - 1, Math.ceil(center.z + rz));
+        for (let z = minZ; z <= maxZ; z++) {
+            for (let y = minY; y <= maxY; y++) {
+                for (let x = minX; x <= maxX; x++) {
+                    const dx = rx > 0 ? (x - center.x) / rx : 0;
+                    const dy = ry > 0 ? (y - center.y) / ry : 0;
+                    const dz = rz > 0 ? (z - center.z) / rz : 0;
+                    if (dx * dx + dy * dy + dz * dz <= 1.0) {
+                        vol.setVoxel(x, y, z, label);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Write a calculator sphere type to sphereMaskVolume.
+     * Uses the stored origin for the specified sphere type.
+     *
+     * @param type - Sphere type ('tumour', 'skin', 'nipple', 'ribcage')
+     */
+    writeCalculatorSphereToVolume(type) {
+        const nrrd = this.ctx.nrrd_states;
+        const vol = nrrd.sphere.sphereMaskVolume;
+        if (!vol)
+            return;
+        let origin = null;
+        switch (type) {
+            case 'tumour':
+                origin = nrrd.sphere.tumourSphereOrigin;
+                break;
+            case 'skin':
+                origin = nrrd.sphere.skinSphereOrigin;
+                break;
+            case 'nipple':
+                origin = nrrd.sphere.nippleSphereOrigin;
+                break;
+            case 'ribcage':
+                origin = nrrd.sphere.ribSphereOrigin;
+                break;
+        }
+        if (!origin)
+            return;
+        const dims = vol.getDimensions();
+        const radius = nrrd.sphere.sphereRadius;
+        // Use z-axis representation for consistent voxel mapping
+        const cx = origin.z[0] * nrrd.image.nrrd_x_pixel / nrrd.image.nrrd_x_mm;
+        const cy = origin.z[1] * nrrd.image.nrrd_y_pixel / nrrd.image.nrrd_y_mm;
+        const cz = origin.z[2];
+        const rx = radius * nrrd.image.nrrd_x_pixel / nrrd.image.nrrd_x_mm;
+        const ry = radius * nrrd.image.nrrd_y_pixel / nrrd.image.nrrd_y_mm;
+        const rz = radius * nrrd.image.nrrd_z_pixel / nrrd.image.nrrd_z_mm;
+        const label = SPHERE_LABELS[type];
+        const minX = Math.max(0, Math.floor(cx - rx));
+        const maxX = Math.min(dims.width - 1, Math.ceil(cx + rx));
+        const minY = Math.max(0, Math.floor(cy - ry));
+        const maxY = Math.min(dims.height - 1, Math.ceil(cy + ry));
+        const minZ = Math.max(0, Math.floor(cz - rz));
+        const maxZ = Math.min(dims.depth - 1, Math.ceil(cz + rz));
+        for (let z = minZ; z <= maxZ; z++) {
+            for (let y = minY; y <= maxY; y++) {
+                for (let x = minX; x <= maxX; x++) {
+                    const dx = rx > 0 ? (x - cx) / rx : 0;
+                    const dy = ry > 0 ? (y - cy) / ry : 0;
+                    const dz = rz > 0 ? (z - cz) / rz : 0;
+                    if (dx * dx + dy * dy + dz * dz <= 1.0) {
+                        vol.setVoxel(x, y, z, label);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Write all placed calculator spheres to the volume.
+     * Clears the volume first, then writes each placed sphere type.
+     */
+    writeAllCalculatorSpheresToVolume() {
+        const nrrd = this.ctx.nrrd_states;
+        const vol = nrrd.sphere.sphereMaskVolume;
+        if (!vol)
+            return;
+        vol.clear();
+        if (nrrd.sphere.tumourSphereOrigin)
+            this.writeCalculatorSphereToVolume('tumour');
+        if (nrrd.sphere.skinSphereOrigin)
+            this.writeCalculatorSphereToVolume('skin');
+        if (nrrd.sphere.nippleSphereOrigin)
+            this.writeCalculatorSphereToVolume('nipple');
+        if (nrrd.sphere.ribSphereOrigin)
+            this.writeCalculatorSphereToVolume('ribcage');
+    }
+    // ===== Sphere Overlay Rendering from Volume =====
+    /**
+     * Render the current slice of sphereMaskVolume to drawingSphereCanvas.
+     *
+     * Called after any operation that changes the view (slice, axis, zoom)
+     * to keep the sphere overlay visible. Uses the same render pipeline as
+     * layer masks (emptyCanvas → sphere canvas at display scale).
+     */
+    refreshSphereCanvas() {
+        const vol = this.ctx.nrrd_states.sphere.sphereMaskVolume;
+        const sphereCtx = this.ctx.protectedData.ctxes.drawingSphereCtx;
+        const sphereCanvas = this.ctx.protectedData.canvases.drawingSphereCanvas;
+        const nrrd = this.ctx.nrrd_states;
+        const axis = this.ctx.protectedData.axis;
+        // Set sphere canvas to origin (mm) dimensions — matches preview approach
+        this.setSphereCanvasSize(axis);
+        if (!vol)
+            return;
+        const sliceIndex = nrrd.view.currentSliceIndex;
+        try {
+            const dims = vol.getDimensions();
+            const maxSlice = axis === 'x' ? dims.width : axis === 'y' ? dims.height : dims.depth;
+            if (sliceIndex < 0 || sliceIndex >= maxSlice)
+                return;
+            // Get slice dimensions (voxel space)
+            const [sliceW, sliceH] = axis === 'z' ? [dims.width, dims.height]
+                : axis === 'y' ? [dims.width, dims.depth]
+                    : [dims.depth, dims.height];
+            const imageData = new ImageData(sliceW, sliceH);
+            vol.renderLabelSliceInto(sliceIndex, axis, imageData, undefined, 1.0);
+            // Quick check if any data on this slice
+            let hasContent = false;
+            for (let i = 3; i < imageData.data.length; i += 4) {
+                if (imageData.data[i] > 0) {
+                    hasContent = true;
+                    break;
+                }
+            }
+            if (!hasContent)
+                return;
+            // Draw via emptyCanvas (same pattern as renderSliceToCanvas)
+            this.callbacks.setEmptyCanvasSize(axis);
+            this.ctx.protectedData.ctxes.emptyCtx.putImageData(imageData, 0, 0);
+            sphereCtx.imageSmoothingEnabled = true;
+            // Coronal axis ('y') needs vertical flip to match display coordinate system
+            if (axis === 'y') {
+                sphereCtx.save();
+                sphereCtx.scale(1, -1);
+                sphereCtx.translate(0, -sphereCanvas.height);
+            }
+            sphereCtx.drawImage(this.ctx.protectedData.canvases.emptyCanvas, 0, 0, sphereCanvas.width, sphereCanvas.height);
+            if (axis === 'y') {
+                sphereCtx.restore();
+            }
+        }
+        catch (_a) {
+            // Volume not ready or slice out of bounds
+        }
+    }
+}
+/**
+ * Standalone helper — draw a filled circle.
+ * Used internally and by drawSphere() for preview rendering.
+ */
+function drawSphereCore(ctx, x, y, radius, color) {
+    ctx.beginPath();
+    ctx.arc(x, y, radius, 0, 2 * Math.PI);
+    ctx.fillStyle = color;
+    ctx.fill();
+    ctx.closePath();
 }
 //# sourceMappingURL=SphereTool.js.map