copper3d 3.1.1 → 3.2.0

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/types/Scene/copperScene.d.ts

@@ -29,6 +29,7 @@ export declare class copperScene extends baseScene {
         y?: number;
         z?: number;
     }): void;
+    loadView(viewpointData: CameraViewPoint): void;
     resetView(): void;
     updateCamera(viewpoint: CameraViewPoint): void;
     getCurrentTime(): number;

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

@@ -10,6 +10,7 @@ import { EraserTool } from "./tools/EraserTool";
 import { PanTool } from "./tools/PanTool";
 import { DrawingTool } from "./tools/DrawingTool";
 import { ImageStoreHelper } from "./tools/ImageStoreHelper";
+import { SphereBrushTool } from "./tools/SphereBrushTool";
 import { UndoManager } from "./core";
 /**
  * DrawToolCore — Tool orchestration and event routing.
@@ -41,6 +42,7 @@ export declare class DrawToolCore {
     protected panTool: PanTool;
     protected drawingTool: DrawingTool;
     protected imageStoreHelper: ImageStoreHelper;
+    protected sphereBrushTool: SphereBrushTool;
     /** Slice index recorded when paintOnCanvas() starts, guards stale-click */
     private paintSliceIndex;
     /** Wheel event dispatch mode — replaces manual wheel add/remove (Phase 2) */
@@ -131,4 +133,8 @@ export declare class DrawToolCore {
     enterSphereMode(): void;
     /** Override in NrrdTools */
     exitSphereMode(): void;
+    /** Override in NrrdTools */
+    reloadMasksFromVolume(): void;
+    /** Override in NrrdTools */
+    updateMouseWheelEvent(): void;
 }

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

@@ -79,6 +79,8 @@ export declare class NrrdTools {
     getOpacity(): number;
     setBrushSize(size: number): void;
     getBrushSize(): number;
+    setSphereBrushRadius(radius: number): void;
+    getSphereBrushRadius(): number;
     setWindowHigh(value: number): void;
     setWindowLow(value: number): void;
     finishWindowAdjustment(): void;

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

@@ -19,6 +19,8 @@ export interface MaskDelta {
     /** Full slice data captured after the drawing operation. */
     newSlice: Uint8Array;
 }
+/** A single delta or a group of deltas treated as one undo unit. */
+export type UndoEntry = MaskDelta[];
 export declare class UndoManager {
     private undoStacks;
     private redoStacks;
@@ -26,18 +28,20 @@ export declare class UndoManager {
     constructor();
     /** Set the currently active layer (determines which stack undo/redo operates on). */
     setActiveLayer(layer: string): void;
-    /** Push a delta onto the active layer's undo stack and clear the redo stack. */
+    /** Push a single delta onto the active layer's undo stack and clear the redo stack. */
     push(delta: MaskDelta): void;
+    /** Push a group of deltas as a single undo unit (e.g. 3D sphere spanning multiple slices). */
+    pushGroup(deltas: MaskDelta[]): void;
     /**
      * Undo the last operation on the active layer.
-     * @returns The delta that was undone, or undefined if nothing to undo.
+     * @returns The delta(s) that were undone, or undefined if nothing to undo.
      */
-    undo(): MaskDelta | undefined;
+    undo(): UndoEntry | undefined;
     /**
      * Redo the last undone operation on the active layer.
-     * @returns The delta that was redone, or undefined if nothing to redo.
+     * @returns The delta(s) that were redone, or undefined if nothing to redo.
      */
-    redo(): MaskDelta | undefined;
+    redo(): UndoEntry | undefined;
     canUndo(): boolean;
     canRedo(): boolean;
     /** Clear undo and redo stacks for a specific layer (called on clearActiveLayer). */

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

@@ -70,5 +70,5 @@
 export type { Dimensions, RGBAColor, ChannelColorMap, SliceRenderOptions, LayerId, ChannelValue, ICommXYZ, ICommXY, ISkipSlicesDictType, ToolMode, IDragPrameters, IDrawingEvents, IContrastEvents, IPaintImages, IPaintImage, ILayerRenderTarget, IDownloadImageConfig, INewMaskData, IMaskData, IProtected, IToolModeState, IDrawingConfig, IViewConfig, ILayerChannelState, IGUIStates, IGuiMeta, IGuiParameterSettings, IImageMetadata, IViewState, IInteractionState, ISphereState, IInternalFlags, INrrdStates, IAnnotationCallbacks, IConvertObjType, ICursorPage, IDragOpts, IDrawOpts, IKeyBoardSettings, } from './types';
 export { RenderMode, MASK_CHANNEL_COLORS, MASK_CHANNEL_CSS_COLORS, CHANNEL_COLORS, CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, } from './types';
 export { MaskVolume } from './MaskVolume';
-export type { MaskDelta } from './UndoManager';
+export type { MaskDelta, UndoEntry } from './UndoManager';
 export { UndoManager } from './UndoManager';

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

@@ -118,7 +118,7 @@ export interface ISkipSlicesDictType {
     [key: string]: any;
 }
 /** Tool mode types for segmentation tools */
-export type ToolMode = "pencil" | "brush" | "eraser" | "sphere" | "calculator";
+export type ToolMode = "pencil" | "brush" | "eraser" | "sphere" | "calculator" | "sphereBrush" | "sphereEraser";
 export interface IDragPrameters {
     move: number;
     y: number;
@@ -137,6 +137,7 @@ export interface IDrawingEvents {
     handleOnDrawingBrushCricleMove: (ev: MouseEvent) => void;
     handleMouseZoomSliceWheel: (e: WheelEvent) => void;
     handleSphereWheel: (e: WheelEvent) => void;
+    handleSphereBrushWheel: (e: WheelEvent) => void;
 }
 export interface IContrastEvents {
     move_x: number;
@@ -223,6 +224,8 @@ export interface IToolModeState {
     pencil: boolean;
     eraser: boolean;
     sphere: boolean;
+    sphereBrush: boolean;
+    sphereEraser: boolean;
     activeSphereType: "tumour" | "skin" | "nipple" | "ribcage";
 }
 /** Drawing configuration — brush/pencil appearance and behavior */
@@ -422,6 +425,7 @@ export interface ISphereState {
     /** Dedicated MaskVolume for SphereTool 3D sphere data. Type is `any` to avoid circular deps. */
     sphereMaskVolume: any;
     sphereRadius: number;
+    sphereBrushRadius: number;
 }
 /** Internal flags — transient operational flags */
 export interface IInternalFlags {

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

@@ -18,7 +18,7 @@ export type InteractionMode = 'idle' | 'draw' | 'drag' | 'contrast' | 'crosshair
 /**
  * GUI tool selection (set from UI buttons)
  */
-export type GuiTool = 'pencil' | 'brush' | 'eraser' | 'sphere';
+export type GuiTool = 'pencil' | 'brush' | 'eraser' | 'sphere' | 'sphereBrush' | 'sphereEraser';
 /**
  * Keyboard event handler type
  */

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

@@ -0,0 +1,127 @@
+/**
+ * SphereBrushTool — 3D sphere brush and eraser on layer MaskVolume.
+ *
+ * Unlike SphereTool (which uses its own isolated sphereMaskVolume),
+ * this tool writes/erases directly in the active layer's shared MaskVolume —
+ * the same volume used by pencil/brush/eraser tools.
+ *
+ * Two operation modes handled by one class:
+ * - **sphereBrush**: Direct click to paint a 3D sphere of the active channel label.
+ * - **sphereEraser**: Shift+click to erase a 3D sphere (only voxels matching active channel).
+ *
+ * Interaction:
+ * 1. Pointer-down records sphere center, switches wheel to radius mode.
+ * 2. Scroll wheel adjusts sphereBrushRadius [1, 50].
+ * 3. Pointer-up writes/erases sphere to volume, captures grouped undo, refreshes canvas.
+ */
+import { BaseTool } from "./BaseTool";
+import type { ToolContext } from "./BaseTool";
+import type { SphereBrushHostDeps } from "./ToolHost";
+export declare class SphereBrushTool extends BaseTool {
+    private callbacks;
+    /** Recorded sphere center in canvas mm-space */
+    private centerX;
+    private centerY;
+    private centerSlice;
+    /** Whether a sphere placement is in progress */
+    private active;
+    /** Current operation mode for the active placement */
+    private mode;
+    /** Cumulative "before" snapshots for drag-erase undo (z-index → slice data) */
+    private dragBeforeSnapshots;
+    /** Whether a drag-erase has actually moved (vs. simple click-release) */
+    private dragMoved;
+    constructor(ctx: ToolContext, callbacks: SphereBrushHostDeps);
+    setCallbacks(callbacks: SphereBrushHostDeps): void;
+    /**
+     * Convert canvas mm-space coordinates to 3D voxel coordinates.
+     */
+    private canvasToVoxelCenter;
+    /**
+     * Convert mm radius to per-axis voxel radii.
+     */
+    private getVoxelRadii;
+    /**
+     * Compute clamped bounding box for an ellipsoid in voxel space.
+     */
+    private getBoundingBox;
+    /**
+     * Write a 3D sphere of the active channel label into the layer's MaskVolume.
+     */
+    private write3DSphereToBrush;
+    /**
+     * Erase a 3D sphere from the layer's MaskVolume.
+     * Only clears voxels whose current value equals the active channel label.
+     */
+    private erase3DSphereFromVolume;
+    /**
+     * Capture slice snapshots for all Z-slices in the bounding box.
+     * Used before and after the sphere operation to build MaskDelta groups.
+     *
+     * We always capture along the Z axis since the 3D sphere spans Z slices.
+     */
+    private captureSliceSnapshots;
+    /**
+     * Build MaskDelta group from before/after snapshots.
+     */
+    private buildUndoGroup;
+    /**
+     * Draw a preview circle on the sphere canvas during sphere placement.
+     */
+    drawPreview(mouseX: number, mouseY: number, radius: number, isEraser: boolean): void;
+    /**
+     * Clear the sphere preview canvas.
+     */
+    clearPreview(): void;
+    /**
+     * Get the hex color for the active channel from the layer's MaskVolume.
+     */
+    private getActiveChannelColor;
+    /**
+     * Returns a wheel event handler for adjusting sphereBrushRadius.
+     * Used in both sphereBrush and sphereEraser modes.
+     */
+    configSphereBrushWheel(): (e: WheelEvent) => void;
+    /**
+     * Handle pointer-down in sphereBrush mode (direct click, no Shift needed).
+     */
+    onSphereBrushClick(e: MouseEvent): void;
+    /**
+     * Handle pointer-up in sphereBrush mode — write sphere to volume.
+     */
+    onSphereBrushPointerUp(): void;
+    /**
+     * Handle pointer-down in sphereEraser mode.
+     * Initializes drag tracking for cumulative undo.
+     */
+    onSphereEraserClick(e: MouseEvent): void;
+    /**
+     * Handle pointer-move in sphereEraser mode — drag to continuously erase.
+     */
+    onSphereEraserMove(e: MouseEvent): void;
+    /**
+     * Handle pointer-up in sphereEraser mode — finalize erase + push undo group.
+     * Works for both click-release and drag-release.
+     */
+    onSphereEraserPointerUp(): void;
+    /**
+     * Expand cumulative "before" snapshots to cover z range [minZ, maxZ].
+     * Only captures slices not yet in the map (preserves original state).
+     */
+    private expandDragBeforeSnapshots;
+    /** Get minimum Z index from drag snapshots */
+    private dragMinZ;
+    /** Get maximum Z index from drag snapshots */
+    private dragMaxZ;
+    /**
+     * After writing/erasing the sphere in the volume, re-render the current
+     * slice's layer canvas and composite all layers to master.
+     *
+     * @param changedDeltas - If provided, fire onMaskChanged for ALL changed
+     *   slices (not just the current view slice) so the backend receives the
+     *   full 3D sphere data for NII/GLTF export.
+     */
+    private refreshDisplay;
+    /** Whether a sphere placement is currently in progress */
+    get isActive(): boolean;
+}

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

@@ -40,6 +40,7 @@ export interface ToolHost {
         image: ImageData;
     } | undefined;
     pushUndoDelta(delta: MaskDelta): void;
+    pushUndoGroup(deltas: MaskDelta[]): void;
     getEraserUrls(): string[];
     enableCrosshair(): void;
     setUpSphereOrigins(mouseX: number, mouseY: number, sliceIndex: number): void;
@@ -72,3 +73,5 @@ export type LayerChannelHostDeps = Pick<ToolHost, 'reloadMasksFromVolume' | 'get
 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'>;
+/** SphereBrushTool host dependencies */
+export type SphereBrushHostDeps = Pick<ToolHost, 'getVolumeForLayer' | 'compositeAllLayers' | 'pushUndoGroup' | 'renderSliceToCanvas' | 'getOrCreateSliceBuffer' | 'setEmptyCanvasSize' | 'reloadMasksFromVolume' | 'getEraserUrls'>;

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

@@ -8,13 +8,14 @@
  */
 export { BaseTool } from "./BaseTool";
 export type { ToolContext } from "./BaseTool";
-export type { ToolHost, ImageStoreHostDeps, PanHostDeps, ContrastHostDeps, ZoomHostDeps, SphereHostDeps, DrawingHostDeps, DragSliceHostDeps, LayerChannelHostDeps, SliceRenderHostDeps, DataLoaderHostDeps, } from "./ToolHost";
+export type { ToolHost, ImageStoreHostDeps, PanHostDeps, ContrastHostDeps, ZoomHostDeps, SphereHostDeps, SphereBrushHostDeps, DrawingHostDeps, DragSliceHostDeps, LayerChannelHostDeps, SliceRenderHostDeps, DataLoaderHostDeps, } from "./ToolHost";
 export { EraserTool } from "./EraserTool";
 export { DrawingTool } from "./DrawingTool";
 export { PanTool } from "./PanTool";
 export { ZoomTool } from "./ZoomTool";
 export { SphereTool, SPHERE_CHANNEL_MAP } from "./SphereTool";
 export type { SphereType } from "./SphereTool";
+export { SphereBrushTool } from "./SphereBrushTool";
 export { CrosshairTool } from "./CrosshairTool";
 export { ContrastTool } from "./ContrastTool";
 export { ImageStoreHelper } from "./ImageStoreHelper";

package/dist/types/index.d.ts

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "copper3d",
   "description": "A 3d visualisation package base on threejs provides multiple scenes and Nrrd image load funtion.",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "main": "dist/bundle.umd.js",
   "moudle": "dist/bundle.esm.js",
   "types": "dist/types/index.d.ts",