copper3d 3.0.1 → 3.1.0

package/dist/types/Utils/segmentation/tools/DrawingTool.d.ts

@@ -0,0 +1,85 @@
+/**
+ * DrawingTool - Pencil/Brush/Eraser drawing on canvas layers
+ *
+ * Extracted from DrawToolCore.paintOnCanvas() closure (Phase 3).
+ * Handles left-click drawing operations: pencil stroke + fill, brush strokes,
+ * eraser, and undo snapshot capture/push.
+ */
+import { BaseTool } from "./BaseTool";
+import type { ToolContext } from "./BaseTool";
+import type { DrawingHostDeps } from "./ToolHost";
+export declare class DrawingTool extends BaseTool {
+    /** Left mouse button currently held (draw mode) */
+    private leftClicked;
+    /** True while actively painting (between pointerdown and pointerup) */
+    private isPainting;
+    /** Accumulated pencil stroke points for fill-on-release */
+    private drawingLines;
+    /** Eraser arc function, assigned once per paintOnCanvas() call */
+    private clearArcFn;
+    /** Snapshot of the active layer's slice captured on mouse-down (before drawing) */
+    private preDrawSlice;
+    private preDrawAxis;
+    private preDrawSliceIndex;
+    private callbacks;
+    constructor(ctx: ToolContext, callbacks: DrawingHostDeps);
+    /** Whether a draw operation is currently active */
+    get isActive(): boolean;
+    /** Whether paint strokes are being recorded */
+    get painting(): boolean;
+    /**
+     * Reset drawing state. Called at start of each paintOnCanvas() cycle.
+     * @param clearArcFn - Eraser function for this paint cycle
+     */
+    reset(clearArcFn: (x: number, y: number, size: number) => void): void;
+    /**
+     * Called on left-click pointerdown in draw mode.
+     * Sets up drawing state, cursor, undo snapshot, and start position.
+     */
+    onPointerDown(e: MouseEvent): void;
+    /**
+     * Called on pointermove during an active drawing operation.
+     * Handles eraser clearing or brush/pencil stroke accumulation.
+     */
+    onPointerMove(e: MouseEvent): void;
+    /**
+     * Called on pointerup in draw mode.
+     * Completes stroke, fills pencil path, syncs volume, pushes undo delta.
+     */
+    onPointerUp(_e: MouseEvent): void;
+    /**
+     * Called on pointerleave during drawing.
+     * Resets painting state and cleans up leftClicked.
+     * @returns true if drawing was in progress when leave occurred
+     */
+    onPointerLeave(): boolean;
+    /**
+     * Create a self-managing mouseover/mouseout/mousemove handler
+     * that tracks brush hover position for the preview circle.
+     *
+     * The returned function should be registered on drawingCanvas for
+     * "mouseover" and "mouseout" events.  It adds/removes a "mousemove"
+     * listener on itself to keep mouseOverX/Y up-to-date while the
+     * cursor is inside the canvas.
+     */
+    createBrushTrackingHandler(): (e: MouseEvent) => void;
+    /**
+     * Render brush circle preview on the drawing context.
+     * Called from the start() render loop when in draw mode and not
+     * actively painting.  Skipped in pencil/eraser mode.
+     */
+    renderBrushPreview(ctx: CanvasRenderingContext2D, width: number, height: number): void;
+    /** Capture pre-draw slice snapshot for undo */
+    private capturePreDrawSnapshot;
+    /** Push delta to UndoManager after drawing completes */
+    private pushUndoDelta;
+    /**
+     * Redraws persisted layer data onto ctx before new pencil fill.
+     * Extracted from DrawToolCore.
+     */
+    private redrawPreviousImageToLayerCtx;
+    /** Draw a line segment on a layer canvas */
+    private drawLinesOnLayer;
+    /** Paint a segment on the current layer canvas and composite to master */
+    private paintOnCanvasLayer;
+}

package/dist/types/Utils/segmentation/tools/ImageStoreHelper.d.ts

@@ -2,19 +2,16 @@
  * ImageStoreHelper - Cross-axis image storage
  *
  * Extracted from DrawToolCore.ts:
- * - storeAllImages / storeImageToAxis / storeImageToLayer / storeEachLayerImage
+ * - syncLayerSliceData
  *
  * Phase 3: MaskVolume is the sole storage backend. All IPaintImages params removed.
  */
 import { BaseTool } from "./BaseTool";
 import type { ToolContext } from "./BaseTool";
-export interface ImageStoreCallbacks {
-    setEmptyCanvasSize: (axis?: "x" | "y" | "z") => void;
-    drawImageOnEmptyImage: (canvas: HTMLCanvasElement) => void;
-}
+import type { ImageStoreHostDeps } from "./ToolHost";
 export declare class ImageStoreHelper extends BaseTool {
     private callbacks;
-    constructor(ctx: ToolContext, callbacks: ImageStoreCallbacks);
+    constructor(ctx: ToolContext, callbacks: ImageStoreHostDeps);
     /**
      * Get MaskVolume for a specific layer.
      * Delegates to the volumes stored in protectedData.maskData.
@@ -23,40 +20,23 @@ export declare class ImageStoreHelper extends BaseTool {
      * @returns MaskVolume for the given layer, or layer1 as fallback
      */
     private getVolumeForLayer;
-    /**
-     * Get MaskVolume for the currently active layer.
-     */
-    private getCurrentVolume;
     /**
      * Get the canvas element for a specific layer.
      */
     private getCanvasForLayer;
     /**
-     * Phase 3: No-op — MaskVolume storage happens in storeAllImages.
-     */
-    storeImageToAxis(_index: number, _imageData: ImageData, _axis?: "x" | "y" | "z"): void;
-    /**
-     * Retrieve the drawn image for a given axis and slice.
+     * Vertically flip an ImageData buffer in-place (swap rows top↔bottom).
      *
-     * Phase 3: Reads exclusively from MaskVolume.
-     */
-    filterDrawedImage(axis: "x" | "y" | "z", sliceIndex: number): {
-        index: number;
-        image: ImageData;
-    } | undefined;
-    /**
-     * Store all layer images for the current slice (cross-axis sync).
-     *
-     * Phase 2: Also writes into the current layer's MaskVolume.
-     */
-    storeAllImages(index: number, layer: string): void;
-    /**
-     * Store a single layer's canvas data to its MaskVolume.
-     * Reads from the individual layer canvas (not master) and uses RGB→channel reverse lookup.
+     * Used to compensate for the Z-axis direction reversal between sagittal
+     * and coronal views. On coronal, Z runs along the canvas j-axis (vertical),
+     * and the display flip (scale(1,-1)) reverses Z relative to sagittal's
+     * horizontal Z mapping. This row-swap aligns the Z ordering so that
+     * MaskVolume stores data in a consistent coordinate system.
      */
-    storeEachLayerImage(index: number, layer: string): void;
+    private flipImageDataVertically;
     /**
-     * Extract ImageData from canvas (MaskVolume storage is handled in storeAllImages).
+     * Sync the current layer canvas to its MaskVolume slice and notify the parent
+     * via getMask. This is the primary write path after any draw/erase operation.
      */
-    storeImageToLayer(_index: number, canvas: HTMLCanvasElement): ImageData;
+    syncLayerSliceData(index: number, layer: string): void;
 }

package/dist/types/Utils/segmentation/tools/LayerChannelManager.d.ts

@@ -0,0 +1,52 @@
+import { BaseTool } from "./BaseTool";
+import type { ToolContext } from "./BaseTool";
+import type { ChannelValue, RGBAColor, ChannelColorMap } from "../core";
+import type { SphereType } from "./SphereTool";
+import type { LayerChannelHostDeps } from "./ToolHost";
+/**
+ * Manages layer/channel state: active selection, visibility, and channel colors.
+ *
+ * Extracted from NrrdTools.ts to reduce its size.
+ * Follows the same BaseTool + ToolContext + Callbacks pattern as other tools.
+ */
+export declare class LayerChannelManager extends BaseTool {
+    private callbacks;
+    constructor(ctx: ToolContext, callbacks: LayerChannelHostDeps);
+    /****************************Active Layer/Channel****************************************************/
+    setActiveLayer(layerId: string): void;
+    getActiveLayer(): string;
+    setActiveChannel(channel: ChannelValue): void;
+    getActiveChannel(): number;
+    /**
+     * Set the active sphere type and sync brush/fill color.
+     *
+     * @example
+     * ```ts
+     * nrrdTools.setActiveSphereType('nipple');
+     * ```
+     */
+    setActiveSphereType(type: SphereType): void;
+    getActiveSphereType(): SphereType;
+    /****************************Visibility****************************************************/
+    setLayerVisible(layerId: string, visible: boolean): void;
+    isLayerVisible(layerId: string): boolean;
+    setChannelVisible(layerId: string, channel: ChannelValue, visible: boolean): void;
+    isChannelVisible(layerId: string, channel: ChannelValue): boolean;
+    getLayerVisibility(): Record<string, boolean>;
+    getChannelVisibility(): Record<string, Record<number, boolean>>;
+    hasLayerData(layerId: string): boolean;
+    /****************************Channel Colors****************************************************/
+    setChannelColor(layerId: string, channel: number, color: RGBAColor): void;
+    getChannelColor(layerId: string, channel: number): RGBAColor;
+    getChannelHexColor(layerId: string, channel: number): string;
+    getChannelCssColor(layerId: string, channel: number): string;
+    setChannelColors(layerId: string, colorMap: Partial<ChannelColorMap>): void;
+    setAllLayersChannelColor(channel: number, color: RGBAColor): void;
+    resetChannelColors(layerId?: string, channel?: number): void;
+    /****************************Private Helpers****************************************************/
+    /**
+     * Sync brush/fill color from the active layer's volume channel color.
+     * Falls back to global CHANNEL_HEX_COLORS if volume not available.
+     */
+    private syncBrushColor;
+}

package/dist/types/Utils/segmentation/tools/PanTool.d.ts

@@ -0,0 +1,47 @@
+/**
+ * PanTool - Right-click pan/drag navigation
+ *
+ * Extracted from DrawToolCore.paintOnCanvas() closure.
+ * Handles right-click drag to reposition the canvas view.
+ */
+import { BaseTool } from "./BaseTool";
+import type { ToolContext } from "./BaseTool";
+import type { PanHostDeps } from "./ToolHost";
+export declare class PanTool extends BaseTool {
+    /** Right mouse button currently held */
+    private rightClicked;
+    /** Pan drag offset X (clientX − canvas.offsetLeft at drag start) */
+    private panMoveInnerX;
+    /** Pan drag offset Y (clientY − canvas.offsetTop at drag start) */
+    private panMoveInnerY;
+    private callbacks;
+    /**
+     * Bound handler reference for pointermove so we can add/remove it.
+     * Arrow function preserves `this` binding.
+     */
+    private readonly boundPointerMove;
+    constructor(ctx: ToolContext, callbacks: PanHostDeps);
+    /** Whether a pan drag is currently active */
+    get isActive(): boolean;
+    /**
+     * Called on right-click pointerdown.
+     * Captures initial offsets and registers pointermove listener.
+     */
+    onPointerDown(e: MouseEvent): void;
+    /**
+     * Called on pointerup (button === 2).
+     * Cleans up listeners and restores cursor.
+     */
+    onPointerUp(e: MouseEvent, defaultCursor: string): void;
+    /**
+     * Called on pointerleave while pan is active.
+     * Resets state and removes listener.
+     */
+    onPointerLeave(): void;
+    /** Reset pan state (called when paintOnCanvas re-initializes) */
+    reset(): void;
+    /**
+     * Pointermove handler — updates canvas position during drag.
+     */
+    private handlePointerMove;
+}

package/dist/types/Utils/segmentation/tools/SliceRenderPipeline.d.ts

@@ -0,0 +1,80 @@
+import { BaseTool } from "./BaseTool";
+import type { ToolContext } from "./BaseTool";
+import type { SliceRenderHostDeps } from "./ToolHost";
+/**
+ * Manages slice rendering pipeline: slice setup, canvas rendering, and view helpers.
+ *
+ * Extracted from NrrdTools.ts to reduce its size.
+ * Follows the same BaseTool + ToolContext + Callbacks pattern as other tools.
+ */
+export declare class SliceRenderPipeline extends BaseTool {
+    private callbacks;
+    private initState;
+    constructor(ctx: ToolContext, callbacks: SliceRenderHostDeps);
+    /**
+     * Reset initState to true (called from NrrdTools.reset() when switching datasets).
+     */
+    resetInitState(): void;
+    /****************************Slice Setup****************************************************/
+    setDisplaySlicesBaseOnAxis(): void;
+    private loadDisplaySlicesArray;
+    resetDisplaySlicesStatus(): void;
+    private setupConfigs;
+    private setMainPreSlice;
+    private setOriginCanvasAndPre;
+    afterLoadSlice(): void;
+    private updateMaxIndex;
+    /****************************Rendering****************************************************/
+    /**
+     * Phase 3: Reload all mask layers from MaskVolume using buffer reuse
+     * Replaces the old reloadMaskToLayer approach
+     */
+    reloadMasksFromVolume(): void;
+    /******************************** redraw display canvas  ***************************************/
+    /**
+     * Redraw current contrast image to display canvas.
+     * It is more related to change the contrast slice image's window width or center.
+     */
+    redrawDisplayCanvas(): void;
+    redrawMianPreOnDisplayCanvas(): void;
+    /**
+     * flip the canvas to a correct position.
+     * This is because the slice canvas from threejs is not in a correct 2D postion.
+     * Thus, everytime when we redraw the display canvas, we need to flip to draw the origin canvas from threejs.
+     * Under different axis(sagittal, Axial, Coronal), the flip orientation is different.
+     */
+    flipDisplayImageByAxis(): void;
+    /**
+     * Set the empty canvas width and height based on the axis (pixel distance not the mm), to reduce duplicate codes.
+     *
+     * @param axis
+     */
+    setEmptyCanvasSize(axis?: "x" | "y" | "z"): void;
+    /**
+     * Clear masks on drawingCanvas layers.
+     */
+    resetLayerCanvas(): void;
+    /****************************View/Canvas Helpers****************************************************/
+    /**
+     * Resize the draw and display canvas size based on the input size factor number.
+     * @param factor number
+     */
+    resizePaintArea(factor: number): void;
+    /**
+     * Reset the draw and display canvases layout after mouse pan.
+     * If no params in, then center the draw and display canvases.
+     * @param l number, Offset to the left
+     * @param t number, Offset to the top
+     */
+    resetPaintAreaUIPosition(l?: number, t?: number): void;
+    /**
+     * 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 sizeFactor.
+     */
+    updateOriginAndChangedWH(): void;
+    /**
+     * Keep all contrast slice index to same.
+     * Synchronize the slice indexes of all the contrasts so that they are consistent with the main slice's index.
+     */
+    setSyncsliceNum(): void;
+}

package/dist/types/Utils/segmentation/tools/SphereTool.d.ts

@@ -1,36 +1,249 @@
 /**
  * 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 type { ToolContext } from "./BaseTool";
+import type { SphereHostDeps } from "./ToolHost";
+/** The 4 supported sphere marker types. */
+export type SphereType = 'tumour' | 'skin' | 'nipple' | 'ribcage';
 /**
- * Callbacks that DrawToolCore must provide for sphere operations.
+ * 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 interface SphereCallbacks {
-    setEmptyCanvasSize: (axis?: "x" | "y" | "z") => void;
-    drawImageOnEmptyImage: (canvas: HTMLCanvasElement) => void;
-    storeImageToAxis: (index: number, imageData: ImageData, axis?: "x" | "y" | "z") => void;
-}
+export declare const SPHERE_CHANNEL_MAP: Record<SphereType, {
+    layer: string;
+    channel: number;
+}>;
+/**
+ * Label values for sphere types stored in sphereMaskVolume.
+ * Regular sphere mode uses SPHERE_LABEL (1).
+ * Calculator mode uses type-specific labels (1-4).
+ */
+export declare const SPHERE_LABELS: Record<SphereType | 'default', number>;
 export declare class SphereTool extends BaseTool {
     private callbacks;
-    constructor(ctx: ToolContext, callbacks: SphereCallbacks);
-    setCallbacks(callbacks: SphereCallbacks): void;
+    constructor(ctx: ToolContext, callbacks: SphereHostDeps);
+    setCallbacks(callbacks: SphereHostDeps): void;
+    /**
+     * 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: SphereType): number;
+    /**
+     * Get the default layer for a sphere type.
+     *
+     * @param type - Sphere type
+     * @returns Layer ID (e.g. 'layer1')
+     */
+    getLayerForSphereType(type: SphereType): string;
+    /**
+     * 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: SphereType): string;
     setSphereCanvasSize(axis?: "x" | "y" | "z"): void;
+    /**
+     * 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: CanvasRenderingContext2D, x: number, y: number, radius: number, color: string): void;
     clearSphereCanvas(): [HTMLCanvasElement, CanvasRenderingContext2D];
+    /**
+     * 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: number, mouseY: number, radius: number): void;
+    /**
+     * 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(): (e: WheelEvent) => void;
+    /**
+     * 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.
+     */
     private storeSphereImages;
+    /**
+     * 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: number, axis: "x" | "y" | "z"): void;
     private getSpherePosition;
+    /**
+     * 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: "x" | "y" | "z"): void;
+    /**
+     * 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: number): void;
-    clearSpherePrintStoreImages(): void;
+    /**
+     * 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: MouseEvent): void;
+    /**
+     * 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(): void;
+    /**
+     * 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: number, canvasY: number, sliceIndex: number, axis: "x" | "y" | "z"): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * 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?: number): void;
+    /**
+     * 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: SphereType): void;
+    /**
+     * Write all placed calculator spheres to the volume.
+     * Clears the volume first, then writes each placed sphere type.
+     */
+    writeAllCalculatorSpheresToVolume(): void;
+    /**
+     * 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(): void;
 }

package/dist/types/Utils/segmentation/tools/ToolHost.d.ts

@@ -0,0 +1,74 @@
+/**
+ * ToolHost — Unified host interface for all tools.
+ *
+ * Replaces the 10 individual *Callbacks interfaces with a single definition.
+ * Each tool picks only the methods it needs via `Pick<ToolHost, ...>`.
+ *
+ * @see issue3_unify_callbacks_plan.md
+ */
+import type { MaskVolume, MaskDelta } from "../core";
+import type { RGBAColor } from "../core";
+/**
+ * Unified host interface — all methods that tools may call back into.
+ *
+ * Each tool picks only the methods it needs via `Pick<ToolHost, ...>`.
+ */
+export interface ToolHost {
+    setEmptyCanvasSize(axis?: "x" | "y" | "z"): void;
+    drawImageOnEmptyImage(canvas: HTMLCanvasElement): void;
+    compositeAllLayers(): void;
+    renderSliceToCanvas(layer: string, axis: "x" | "y" | "z", sliceIndex: number, buffer: ImageData, targetCtx: CanvasRenderingContext2D, scaledWidth: number, scaledHeight: number): void;
+    getOrCreateSliceBuffer(axis: "x" | "y" | "z"): ImageData | null;
+    flipDisplayImageByAxis(): void;
+    redrawDisplayCanvas(): void;
+    refreshSphereOverlay(): void;
+    reloadMasksFromVolume(): void;
+    getVolumeForLayer(layer: string): MaskVolume;
+    setIsDrawFalse(target: number): void;
+    setSyncsliceNum(): void;
+    resetPaintAreaUIPosition(l?: number, t?: number): void;
+    resizePaintArea(moveDistance: number): void;
+    resetZoom(): void;
+    invalidateSliceBuffer(): void;
+    clearUndoHistory(): void;
+    setCurrentLayer(): {
+        ctx: CanvasRenderingContext2D;
+        canvas: HTMLCanvasElement;
+    };
+    syncLayerSliceData(index: number, layer: string): void;
+    filterDrawedImage(axis: "x" | "y" | "z", index: number): {
+        image: ImageData;
+    } | undefined;
+    pushUndoDelta(delta: MaskDelta): void;
+    getEraserUrls(): string[];
+    enableCrosshair(): void;
+    setUpSphereOrigins(mouseX: number, mouseY: number, sliceIndex: number): void;
+    zoomActionAfterDrawSphere(): void;
+    setDisplaySlicesBaseOnAxis(): void;
+    afterLoadSlice(): void;
+    syncGuiParameterSettings(): void;
+    repraintCurrentContrastSlice(): void;
+    updateShowNumDiv(contrastNum: number): void;
+    updateCurrentContrastSlice(): void;
+    onChannelColorChanged(layerId: string, channel: number, color: RGBAColor): void;
+}
+/** ImageStoreHelper host dependencies */
+export type ImageStoreHostDeps = Pick<ToolHost, 'setEmptyCanvasSize' | 'drawImageOnEmptyImage'>;
+/** PanTool host dependencies */
+export type PanHostDeps = Pick<ToolHost, 'zoomActionAfterDrawSphere'>;
+/** ContrastTool host dependencies */
+export type ContrastHostDeps = Pick<ToolHost, 'setIsDrawFalse' | 'setSyncsliceNum'>;
+/** ZoomTool host dependencies */
+export type ZoomHostDeps = Pick<ToolHost, 'resetPaintAreaUIPosition' | 'resizePaintArea' | 'setIsDrawFalse'>;
+/** SphereTool host dependencies */
+export type SphereHostDeps = Pick<ToolHost, 'setEmptyCanvasSize' | 'drawImageOnEmptyImage' | 'enableCrosshair' | 'setUpSphereOrigins'>;
+/** DrawingTool host dependencies */
+export type DrawingHostDeps = Pick<ToolHost, 'setCurrentLayer' | 'compositeAllLayers' | 'syncLayerSliceData' | 'filterDrawedImage' | 'getVolumeForLayer' | 'pushUndoDelta' | 'getEraserUrls'>;
+/** DragSliceTool host dependencies */
+export type DragSliceHostDeps = Pick<ToolHost, 'setSyncsliceNum' | 'setIsDrawFalse' | 'flipDisplayImageByAxis' | 'setEmptyCanvasSize' | 'getOrCreateSliceBuffer' | 'renderSliceToCanvas' | 'refreshSphereOverlay'>;
+/** LayerChannelManager host dependencies */
+export type LayerChannelHostDeps = Pick<ToolHost, 'reloadMasksFromVolume' | 'getVolumeForLayer' | 'onChannelColorChanged'>;
+/** SliceRenderPipeline host dependencies */
+export type SliceRenderHostDeps = Pick<ToolHost, 'compositeAllLayers' | 'getOrCreateSliceBuffer' | 'renderSliceToCanvas' | 'getVolumeForLayer' | 'refreshSphereOverlay' | 'syncGuiParameterSettings' | 'repraintCurrentContrastSlice' | 'clearUndoHistory' | 'updateShowNumDiv' | 'updateCurrentContrastSlice'>;
+/** DataLoader host dependencies */
+export type DataLoaderHostDeps = Pick<ToolHost, 'invalidateSliceBuffer' | 'setDisplaySlicesBaseOnAxis' | 'afterLoadSlice' | 'setEmptyCanvasSize' | 'syncLayerSliceData' | 'reloadMasksFromVolume' | 'resetZoom'>;