copper3d 3.4.8 → 3.5.0

package/dist/index.d.ts

@@ -17,14 +17,15 @@ import { GaussianSmoother } from "./Utils/segmentation/core/GaussianSmoother";
 import { Copper3dTrackballControls } from "./Controls/Copper3dTrackballControls";
 import { MeshNodeTool } from "./Utils/MeshNodeTool";
 import { removeGuiFolderChilden } from "./Utils/segmentation/coreTools/gui";
-import { nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, exportPaintImageType, IOptVTKLoader } from "./types/types";
+import { nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, exportPaintImageType, IOptVTKLoader, aligned4DSurfaceType, aligned4DOptsType, Aligned4DController } from "./types/types";
 import { IPaintImage, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, IGuiMeta } from "./Utils/segmentation/core/types";
 import { NrrdState } from "./Utils/segmentation/coreTools/NrrdState";
 import { GuiState } from "./Utils/segmentation/coreTools/GuiState";
 import type { ToolMode, IAnnotationCallbacks } from "./Utils/segmentation/core/types";
-import { CHANNEL_COLORS, CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss } from "./Utils/segmentation/core/index";
+import { CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss } from "./Utils/segmentation/core/index";
 import type { LayerId, ChannelValue } from "./Utils/segmentation/core/index";
+import type { AiPromptTool, AiPromptPoint, AiPromptPayload, AiMaskResult } from "./Utils/segmentation/tools/AiAssistTool";
 import "./css/style.css";
-export declare const REVISION = "v3.4.8-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, GaussianSmoother, };
-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, };
+export declare const REVISION = "v3.5.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, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, GaussianSmoother, };
+export type { positionType, screenPosType, optsType, nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, IPaintImage, exportPaintImageType, IOptVTKLoader, aligned4DSurfaceType, aligned4DOptsType, Aligned4DController, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, NrrdState, GuiState, IGuiMeta, ToolMode, IAnnotationCallbacks, LayerId, ChannelValue, AiPromptTool, AiPromptPoint, AiPromptPayload, AiMaskResult, };

package/dist/index.js

@@ -19,9 +19,9 @@ import { GaussianSmoother } from "./Utils/segmentation/core/GaussianSmoother";
 import { Copper3dTrackballControls } from "./Controls/Copper3dTrackballControls";
 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 { CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss } from "./Utils/segmentation/core/index";
 import "./css/style.css";
-export const REVISION = "v3.4.8-beta";
+export const REVISION = "v3.5.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, GaussianSmoother, };
+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, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, GaussianSmoother, };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/types/Loader/copperDicomLoader.d.ts

@@ -1,5 +1,11 @@
-import { copperVolumeType } from "../types/types";
+import { copperVolumeType, planeCorners } from "../types/types";
 export declare function copperDicomLoader(url: string, callback?: (copperVolume: copperVolumeType) => void): void;
+/**
+ * Compute the 4 world-space corners of a DICOM image plane from its geometry tags.
+ * IPP is the CENTER of pixel (0,0), so corners sit half a pixel out. PixelSpacing is
+ * [rowSpacing, colSpacing]; IOP's first vector is the +column-index direction.
+ */
+export declare function computeImagePlaneCorners(ipp: number[], iop: number[], spacing: number[], cols: number, rows: number): planeCorners;
 export declare function getLut(data: Uint16Array, windowWidth: number, windowCenter: number, invert: boolean, voiLUT: any): {
     minPixelValue: number;
     maxPixelValue: number;

package/dist/types/Renderer/baseRenderer.d.ts

@@ -13,6 +13,7 @@ export declare class baseRenderer {
     currentScene: baseScene;
     pmremGenerator: THREE.PMREMGenerator;
     options: ICopperRenderOpt | undefined;
+    protected running: boolean;
     private state;
     private visualiseFolder;
     private visualCtrls;
@@ -25,6 +26,8 @@ export declare class baseRenderer {
     hideGui(): void;
     closeGui(): void;
     setClearColor(clearColor?: number, alpha?: number): void;
+    stop(): void;
+    dispose(): void;
     addGui(): void;
     updateGui(): void;
 }

package/dist/types/Renderer/copperMSceneRenderer.d.ts

@@ -11,11 +11,14 @@ export declare class copperMSceneRenderer {
     canvas: HTMLCanvasElement;
     sceneInfos: Array<copperMScene>;
     pmremGenerator: THREE.PMREMGenerator;
+    protected running: boolean;
     constructor(container: HTMLDivElement, numberOfScene: number, cameraPosition?: positionType);
     init(): void;
     updateEnvironment(sceneIn: copperMScene): void;
     private getCubeMapTexture;
     renderSceneInfo: (sceneInfo: copperMScene) => void;
     resizeRendererToDisplaySize: () => void;
+    stop(): void;
+    dispose(): void;
     animate: () => void;
 }

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

@@ -5,7 +5,7 @@ import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
 import { baseScene } from "./baseScene";
 import { vtkModels } from "../types/types";
 import { TrackballControls } from "three/examples/jsm/controls/TrackballControls";
-import { ICopperSceneOpts } from "../types/types";
+import { ICopperSceneOpts, aligned4DOptsType, Aligned4DController } from "../types/types";
 export declare class copperScene extends baseScene {
     clock: THREE.Clock;
     controls: Copper3dTrackballControls | OrbitControls | TrackballControls;
@@ -13,7 +13,6 @@ export declare class copperScene extends baseScene {
     private playRate;
     private modelReady;
     private clipAction;
-    private texture2dMesh;
     constructor(container: HTMLDivElement, renderer: THREE.WebGLRenderer, opt?: ICopperSceneOpts);
     loadGltf(url: string, callback?: (content: THREE.Group) => void): void;
     loadPureGLB(url: string, callback?: (mesh: THREE.Group) => void, opts?: {
@@ -22,7 +21,13 @@ export declare class copperScene extends baseScene {
     }): void;
     loadVtk(url: string): void;
     loadVtks(models: Array<vtkModels>): void;
-    texture2d(url: string): void;
+    /**
+     * Load an aligned 4D scene: a cine MRI (one slice, N cardiac phases) rendered as a
+     * world-placed plane, plus 0..N deforming surface sequences (e.g. LV endo/epi). MRI
+     * and surfaces stay in their shared patient coordinate frame (no center/scale), and
+     * advance together off ONE shared frame clock. Returns a controller (play/pause/...).
+     */
+    loadAligned4D(opts: aligned4DOptsType, callback?: (ctrl: Aligned4DController) => void): void;
     getPlayRate(): number;
     setPlayRate(playRate: number): void;
     setModelPosition(model: THREE.Group | THREE.Mesh, position: {

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

@@ -11,6 +11,7 @@ import { PanTool } from "./tools/PanTool";
 import { DrawingTool } from "./tools/DrawingTool";
 import { ImageStoreHelper } from "./tools/ImageStoreHelper";
 import { SphereBrushTool } from "./tools/SphereBrushTool";
+import { AiAssistTool } from "./tools/AiAssistTool";
 import { UndoManager } from "./core";
 /**
  * DrawToolCore — Tool orchestration and event routing.
@@ -42,6 +43,8 @@ export declare class DrawToolCore {
     protected drawingTool: DrawingTool;
     protected imageStoreHelper: ImageStoreHelper;
     protected sphereBrushTool: SphereBrushTool;
+    /** AI-assist interactive prompt tool (experimental). Public so NrrdTools/app can drive it. */
+    aiAssistTool: AiAssistTool;
     /** Slice index recorded when paintOnCanvas() starts, guards stale-click */
     private paintSliceIndex;
     /** Wheel event dispatch mode — replaces manual wheel add/remove (Phase 2) */

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

@@ -4,6 +4,7 @@ import { IMaskData, IDragOpts, IKeyBoardSettings, ToolMode, IGuiMeta } from "./c
 import { DragOperator } from "./DragOperator";
 import type { ChannelValue, RGBAColor, ChannelColorMap } from "./core";
 import type { SphereType } from "./tools/SphereTool";
+import type { AiPromptTool, AiPromptPayload, AiMaskResult } from "./tools/AiAssistTool";
 /**
  * Core NRRD annotation tool for medical image segmentation.
  *
@@ -189,6 +190,59 @@ export declare class NrrdTools {
      * Exit sphere mode.
      */
     exitSphereMode(): void;
+    /** Whether AI-assist mode is currently active. */
+    private _aiAssistActive;
+    /** Layer visibility snapshot taken on enter, restored on exit. */
+    private _aiPrevVisibility;
+    isAiAssistActive(): boolean;
+    /**
+     * Enter AI-assist mode (sandbox): hides the existing layer masks so ONLY the
+     * AI overlay is shown, takes canvas ownership (left-click = prompt), and creates
+     * the scratch volume. Right-drag still pans; wheel/slider still scrub slices.
+     * The hidden masks are restored on exit (merge writes into them first if asked).
+     */
+    enterAiAssistMode(): void;
+    /**
+     * Exit AI-assist mode: drop the scratch volume, restore normal tooling AND the
+     * layer-mask visibility hidden on enter. If the caller merged first, the merged
+     * result is now part of the layer volume and reappears with the restored masks.
+     */
+    exitAiAssistMode(): void;
+    aiSetPromptTool(tool: AiPromptTool): void;
+    aiSetPolarity(label: number): void;
+    /** Set the AI-layer channel (1-8) the predictions paint into. */
+    aiSetChannel(channel: number): void;
+    /** Set the scribble brush radius (px). */
+    aiSetScribbleSize(size: number): void;
+    /** Register the callback invoked when a prompt gesture completes (app → backend). */
+    aiOnPrompt(cb: (payload: AiPromptPayload) => void): void;
+    /** Apply a backend mask result into the scratch volume (overlay repaints next frame). */
+    aiApplyMask(result: AiMaskResult): void;
+    /** Clear the in-progress prompt set (e.g. slice change). */
+    aiClearPrompts(): void;
+    /** "New region": freeze current regions (they persist) + start a fresh prompt set. */
+    aiCommitRegion(): void;
+    /** Discard all AI scratch painting since enter (sandbox discard). */
+    aiDiscard(): void;
+    /** True if the scratch volume holds any predicted voxels. */
+    aiHasData(): boolean;
+    /** Serialize the AI scratch as per-slice RLE for persisting to ai_generated_nii_LPS. */
+    aiGetScratchSlices(): {
+        axis: "z";
+        width: number;
+        height: number;
+        slices: {
+            sliceIndex: number;
+            rle: number[];
+        }[];
+    } | null;
+    /**
+     * Merge the AI scratch into a target layer as a single undoable group (sandbox
+     * merge — best-practice: non-destructive + one Ctrl+Z). The scratch's channel
+     * labels are PRESERVED (each AI channel maps onto the same channel of the
+     * target layer). Scans all z-slices, so voxels painted from any view are caught.
+     */
+    aiCommitToLayer(targetLayer?: string): void;
     clearActiveLayer(): void;
     reset(): void;
     configMouseSliceWheel(): (e: WheelEvent) => void;

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

@@ -68,7 +68,7 @@
  * ```
  */
 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 { RenderMode, MASK_CHANNEL_COLORS, MASK_CHANNEL_CSS_COLORS, CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, } from './types';
 export { MaskVolume } from './MaskVolume';
 export type { MaskDelta, UndoEntry } from './UndoManager';
 export { UndoManager } from './UndoManager';

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

@@ -96,6 +96,16 @@ export declare const CHANNEL_COLORS: Readonly<Record<number, string>>;
  * Hex color strings for each channel (no alpha), used for fillColor/brushColor.
  */
 export declare const CHANNEL_HEX_COLORS: Readonly<Record<number, string>>;
+/**
+ * AI-Assist channel palette. Identical to the default palette EXCEPT:
+ *  - channel 1 = cyan (the AI-Assist accent #5ec8ff), so the 2D AI overlay aligns
+ *    with the cyan ai_generated GLB in the 3D panel;
+ *  - channel 6 takes the emerald that channel 1 vacated, so cyan isn't duplicated.
+ * Applied ONLY to the AI scratch layer (set per-volume in AiAssistTool.enter) —
+ * the global palette above is untouched, so the clinician mask stays emerald.
+ */
+export declare const AI_MASK_CHANNEL_COLORS: Readonly<ChannelColorMap>;
+export declare const AI_CHANNEL_HEX_COLORS: Readonly<Record<number, string>>;
 /**
  * Convert an RGBAColor to a hex string (no alpha), e.g. '#ff0000'.
  */
@@ -118,7 +128,7 @@ export interface ISkipSlicesDictType {
     [key: string]: any;
 }
 /** Tool mode types for segmentation tools */
-export type ToolMode = "pencil" | "brush" | "eraser" | "sphere" | "calculator" | "sphereBrush" | "sphereEraser";
+export type ToolMode = "pencil" | "brush" | "eraser" | "sphere" | "calculator" | "sphereBrush" | "sphereEraser" | "aiAssist";
 export interface IDragPrameters {
     move: number;
     y: number;

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

@@ -15,6 +15,8 @@ export declare class EventRouter {
     private container;
     private canvas;
     private mode;
+    /** Mode to restore after a right-drag pan ends (so pan doesn't drop aiAssist). */
+    private modeBeforePan;
     private guiTool;
     private state;
     private keyboardSettings;

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

@@ -13,12 +13,13 @@
  * - `crosshair`: Crosshair mode enabled (C key toggle)
  * - `sphere`: Sphere placement tool active
  * - `pan`: Right-drag panning the canvas
+ * - `aiAssist`: AI-assist interactive prompt tool active (left-click = prompt point)
  */
-export type InteractionMode = 'idle' | 'draw' | 'drag' | 'contrast' | 'crosshair' | 'sphere' | 'pan';
+export type InteractionMode = 'idle' | 'draw' | 'drag' | 'contrast' | 'crosshair' | 'sphere' | 'pan' | 'aiAssist';
 /**
  * GUI tool selection (set from UI buttons)
  */
-export type GuiTool = 'pencil' | 'brush' | 'eraser' | 'sphere' | 'sphereBrush' | 'sphereEraser';
+export type GuiTool = 'pencil' | 'brush' | 'eraser' | 'sphere' | 'sphereBrush' | 'sphereEraser' | 'aiAssist';
 /**
  * Keyboard event handler type
  */

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

@@ -0,0 +1,146 @@
+/**
+ * AiAssistTool — interactive prompt-based segmentation (experimental).
+ *
+ * The clinician left-clicks foreground / background points (or drags a box /
+ * scribbles) on the current slice; a backend model returns a region mask that
+ * is written into an INDEPENDENT scratch MaskVolume (`aiAssistMaskVolume`,
+ * registered as `maskData.volumes['aiScratch']`) — never the validated layers.
+ *
+ * Network lives in the app layer: this tool only (a) maps screen → voxel-slice
+ * coordinates, (b) accumulates the prompt for the current slice, (c) fires
+ * `onPrompt` so the app can call the backend, and (d) applies the returned mask
+ * via `applyMask`. The app's `useAiAssist` composable wires (c)→(d).
+ *
+ * Sandbox: snapshot on enter (`snapshot`), then on exit either `discard`
+ * (restore snapshot) or merge is handled by NrrdTools (clone + pushGroup).
+ *
+ * Coordinate mapping supports all three views (axial/sagittal/coronal); it
+ * inverts the per-axis display transform of RenderingUtils.renderSliceToCanvas
+ * (only coronal 'y' is vertically flipped). Merge captures painted voxels from
+ * any view (the scratch is a full 3D volume).
+ */
+import { BaseTool } from "./BaseTool";
+import type { ToolContext } from "./BaseTool";
+import { MaskVolume } from "../core";
+import type { SliceRenderHostDeps } from "./ToolHost";
+/** Scratch volume key in maskData.volumes — kept OUT of image.layers so
+ *  compositeAllLayers ignores it (we render it ourselves in start()). */
+export declare const AI_SCRATCH_LAYER = "aiScratch";
+export type AiPromptTool = "point" | "box" | "scribble";
+export interface AiPromptPoint {
+    x: number;
+    y: number;
+    z?: number;
+    label: number;
+}
+export interface AiPromptPayload {
+    axis: "x" | "y" | "z";
+    sliceIndex: number;
+    width: number;
+    height: number;
+    points: AiPromptPoint[];
+    box?: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+        label: number;
+    };
+    scribble?: AiPromptPoint[];
+    scribbleRadius?: number;
+}
+export interface AiMaskResult {
+    axis: "x" | "y" | "z";
+    sliceIndex: number;
+    width: number;
+    height: number;
+    rle: number[];
+    /** 3D result (engine B / nnInteractive): inclusive [lo,hi] slice span + one RLE per slice. */
+    sliceRange?: [number, number];
+    slices?: number[][];
+}
+type AiAssistHostDeps = Pick<SliceRenderHostDeps, "renderSliceToCanvas" | "getOrCreateSliceBuffer">;
+export declare class AiAssistTool extends BaseTool {
+    private host;
+    /** Independent scratch volume (also registered at maskData.volumes['aiScratch']). */
+    private scratchVol;
+    /** Snapshot of the scratch buffer taken on enter (for discard). */
+    private snapshotData;
+    /** Frozen regions ("New region" commits here). Pixels recorded here survive a
+     *  later re-prediction — even on the SAME channel — so multiple separate regions
+     *  can be drawn without the newest prediction wiping the previous ones. Null =
+     *  nothing frozen yet (applySliceRle then behaves as a single live region). */
+    private committedVol;
+    private promptTool;
+    private polarity;
+    /** Target channel/label (1-8) the AI paints into — the "AI layer" channel. */
+    private channel;
+    /** Scribble brush radius (px), user-adjustable via slider. */
+    private scribbleSize;
+    /** Accumulated prompts for the CURRENT slice; reset on slice/axis change. */
+    private points;
+    private scribble;
+    private box;
+    private activeSlice;
+    private dragging;
+    private dragStart;
+    private dragScreenStart;
+    private dragScreen;
+    private screenScribble;
+    private hoverScreen;
+    /** Fired when a prompt gesture completes — app calls backend, then applyMask(). */
+    onPrompt: ((payload: AiPromptPayload) => void) | null;
+    constructor(ctx: ToolContext, host: AiAssistHostDeps);
+    setPromptTool(tool: AiPromptTool): void;
+    setPolarity(label: number): void;
+    setScribbleSize(size: number): void;
+    setChannel(channel: number): void;
+    getChannel(): number;
+    getScratchVolume(): MaskVolume | null;
+    /** Serialize the scratch volume as per-z-slice RLE (only NON-empty slices),
+     *  for persisting to ai_generated_nii_LPS on the backend. Binary (any channel →
+     *  1); RLE is alternating run lengths starting with a 0-run — the exact format
+     *  the backend's rle_decode expects. Uses getSliceUint8 (the same path the
+     *  clinician layer's /api/mask/replace uses) so orientation matches. */
+    getScratchSlices(): {
+        axis: "z";
+        width: number;
+        height: number;
+        slices: {
+            sliceIndex: number;
+            rle: number[];
+        }[];
+    } | null;
+    /** Create (or reuse) the scratch volume sized to the layer grid and register
+     *  it under maskData.volumes['aiScratch']. Snapshots the empty buffer. */
+    enter(): void;
+    /** Remove the scratch volume from the registry and drop references. */
+    exit(): void;
+    /** Discard everything painted since enter() — restore the snapshot. */
+    discard(): void;
+    /** "New region": freeze every voxel painted so far so it survives later
+     *  re-predictions (even on the same channel), then start a fresh prompt set.
+     *  This is what makes drawing multiple separate regions actually work — without
+     *  it the next prediction's same-channel cleanup erases the previous region. */
+    commitRegion(): void;
+    /** Clear the in-progress prompt set (e.g. slice/axis change). Does NOT freeze —
+     *  use commitRegion() for the "New region" action. */
+    resetPrompts(): void;
+    /** Voxel-slice (width,height) for the current axis. */
+    private sliceDims;
+    /** Screen offset → voxel-slice (vx,vy) for the current axis. */
+    private toVoxel;
+    onPointerDown(e: MouseEvent): void;
+    onPointerMove(e: MouseEvent): void;
+    onPointerUp(_e: MouseEvent): void;
+    /** Reset the accumulated prompt set when the user scrubs to a new slice. */
+    private syncSlice;
+    private emit;
+    applyMask(result: AiMaskResult): void;
+    /** Merge one RLE-encoded predicted slice into the scratch volume at sliceIndex.
+     *  Predicted pixels → current channel; stale current-channel pixels cleared
+     *  UNLESS they belong to a frozen (committed) region; OTHER channels preserved. */
+    private applySliceRle;
+    renderOverlay(targetCtx: CanvasRenderingContext2D): void;
+}
+export {};

package/dist/types/Utils/texture2d.d.ts

@@ -1,10 +1,12 @@
 import * as THREE from "three";
 import { copperVolumeType } from "../types/types";
 import { GUI } from "dat.gui";
-export declare function createTexture2D_Zip(url: string, scene: THREE.Scene): void;
-export declare function createTexture2D_NRRD(data: Uint8Array, width: number, height: number, depth: number, callback: (mesh: THREE.Mesh) => void): void;
-export declare function createTexture2D_Array(copperVolume: copperVolumeType, depth: number, scene: THREE.Scene, gui?: GUI): {
-    mesh: THREE.Mesh<THREE.PlaneGeometry, THREE.ShaderMaterial, THREE.Object3DEventMap>;
+export interface texture2dResult {
+    mesh: THREE.Mesh;
     copperVolume: copperVolumeType;
-    updateTexture: (copperVolumeUp: copperVolumeType) => void;
-};
+    updateTexture: (copperVolume: copperVolumeType) => void;
+    setFrame: (i: number) => void;
+    setWindow: (center: number, width: number) => void;
+}
+export declare function createTexture2D_NRRD(data: Uint8Array, width: number, height: number, depth: number, callback: (mesh: THREE.Mesh) => void): void;
+export declare function createTexture2D_Array(copperVolume: copperVolumeType, depth: number, scene: THREE.Scene, gui?: GUI, aligned?: boolean): texture2dResult;

package/dist/types/index.d.ts

@@ -17,14 +17,15 @@ import { GaussianSmoother } from "./Utils/segmentation/core/GaussianSmoother";
 import { Copper3dTrackballControls } from "./Controls/Copper3dTrackballControls";
 import { MeshNodeTool } from "./Utils/MeshNodeTool";
 import { removeGuiFolderChilden } from "./Utils/segmentation/coreTools/gui";
-import { nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, exportPaintImageType, IOptVTKLoader } from "./types/types";
+import { nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, exportPaintImageType, IOptVTKLoader, aligned4DSurfaceType, aligned4DOptsType, Aligned4DController } from "./types/types";
 import { IPaintImage, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, IGuiMeta } from "./Utils/segmentation/core/types";
 import { NrrdState } from "./Utils/segmentation/coreTools/NrrdState";
 import { GuiState } from "./Utils/segmentation/coreTools/GuiState";
 import type { ToolMode, IAnnotationCallbacks } from "./Utils/segmentation/core/types";
-import { CHANNEL_COLORS, CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss } from "./Utils/segmentation/core/index";
+import { CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss } from "./Utils/segmentation/core/index";
 import type { LayerId, ChannelValue } from "./Utils/segmentation/core/index";
+import type { AiPromptTool, AiPromptPoint, AiPromptPayload, AiMaskResult } from "./Utils/segmentation/tools/AiAssistTool";
 import "./css/style.css";
-export declare const REVISION = "v3.4.8-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, GaussianSmoother, };
-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, };
+export declare const REVISION = "v3.5.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, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, GaussianSmoother, };
+export type { positionType, screenPosType, optsType, nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, IPaintImage, exportPaintImageType, IOptVTKLoader, aligned4DSurfaceType, aligned4DOptsType, Aligned4DController, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, NrrdState, GuiState, IGuiMeta, ToolMode, IAnnotationCallbacks, LayerId, ChannelValue, AiPromptTool, AiPromptPoint, AiPromptPayload, AiMaskResult, };

package/dist/types/types/types.d.ts

@@ -149,6 +149,12 @@ interface vtkModels {
     urls: Array<string>;
     opts?: IOptVTKLoader;
 }
+interface planeCorners {
+    tl: [number, number, number];
+    tr: [number, number, number];
+    bl: [number, number, number];
+    br: [number, number, number];
+}
 interface copperVolumeType {
     tags: any;
     width: number;
@@ -159,6 +165,42 @@ interface copperVolumeType {
     uint16: Uint16Array;
     uint8: Uint8ClampedArray;
     order: number;
+    instanceNumber?: number;
+    imagePositionPatient?: number[];
+    imageOrientationPatient?: number[];
+    pixelSpacing?: number[];
+    corners?: planeCorners;
+}
+interface aligned4DSurfaceType {
+    name: string;
+    urls: Array<string>;
+    opts?: IOptVTKLoader;
+    offset?: number;
+}
+interface aligned4DOptsType {
+    dicomUrls: Array<string>;
+    surfaces?: Array<aligned4DSurfaceType>;
+    cycleMs?: number;
+    window?: {
+        center: number;
+        width: number;
+    };
+}
+interface Aligned4DController {
+    plane: THREE.Mesh;
+    surfaceMeshes: Record<string, THREE.Mesh>;
+    frameCount: number;
+    play: () => void;
+    pause: () => void;
+    toggle: () => void;
+    setSpeed: (x: number) => void;
+    setFrame: (i: number) => void;
+    setFrameOffset: (name: string, n: number) => void;
+    setWindow: (center: number, width: number) => void;
+    setPlaneOpacity: (v: number) => void;
+    setSurfaceOpacity: (name: string, v: number) => void;
+    setSurfaceVisible: (name: string, visible: boolean) => void;
+    dispose: () => void;
 }
 interface dicomLoaderOptsType {
     gui?: GUI;
@@ -185,4 +227,4 @@ interface IMeshNodes {
     nodes: INodes;
     elements: IElements;
 }
-export type { SceneMapType, ICopperRenderOpt, stateType, modelVisualisationDataType, preRenderCallbackFunctionType, baseStateType, nrrdMeshesType, nrrdSliceType, loadingBarType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, SerialService_kiwrious, kiwriousType, mouseMovePositionType, positionType, optionsGltfExporterType, vtkModels, copperVolumeType, dicomLoaderOptsType, exportPaintImagesType, exportPaintImageType, storeExportPaintImageType, IOptVTKLoader, ICopperSceneOpts, IMeshNodes, };
+export type { SceneMapType, ICopperRenderOpt, stateType, modelVisualisationDataType, preRenderCallbackFunctionType, baseStateType, nrrdMeshesType, nrrdSliceType, loadingBarType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, SerialService_kiwrious, kiwriousType, mouseMovePositionType, positionType, optionsGltfExporterType, vtkModels, planeCorners, copperVolumeType, aligned4DSurfaceType, aligned4DOptsType, Aligned4DController, dicomLoaderOptsType, exportPaintImagesType, exportPaintImageType, storeExportPaintImageType, IOptVTKLoader, ICopperSceneOpts, IMeshNodes, };

package/dist/types/types.d.ts

@@ -149,6 +149,12 @@ interface vtkModels {
     urls: Array<string>;
     opts?: IOptVTKLoader;
 }
+interface planeCorners {
+    tl: [number, number, number];
+    tr: [number, number, number];
+    bl: [number, number, number];
+    br: [number, number, number];
+}
 interface copperVolumeType {
     tags: any;
     width: number;
@@ -159,6 +165,42 @@ interface copperVolumeType {
     uint16: Uint16Array;
     uint8: Uint8ClampedArray;
     order: number;
+    instanceNumber?: number;
+    imagePositionPatient?: number[];
+    imageOrientationPatient?: number[];
+    pixelSpacing?: number[];
+    corners?: planeCorners;
+}
+interface aligned4DSurfaceType {
+    name: string;
+    urls: Array<string>;
+    opts?: IOptVTKLoader;
+    offset?: number;
+}
+interface aligned4DOptsType {
+    dicomUrls: Array<string>;
+    surfaces?: Array<aligned4DSurfaceType>;
+    cycleMs?: number;
+    window?: {
+        center: number;
+        width: number;
+    };
+}
+interface Aligned4DController {
+    plane: THREE.Mesh;
+    surfaceMeshes: Record<string, THREE.Mesh>;
+    frameCount: number;
+    play: () => void;
+    pause: () => void;
+    toggle: () => void;
+    setSpeed: (x: number) => void;
+    setFrame: (i: number) => void;
+    setFrameOffset: (name: string, n: number) => void;
+    setWindow: (center: number, width: number) => void;
+    setPlaneOpacity: (v: number) => void;
+    setSurfaceOpacity: (name: string, v: number) => void;
+    setSurfaceVisible: (name: string, visible: boolean) => void;
+    dispose: () => void;
 }
 interface dicomLoaderOptsType {
     gui?: GUI;
@@ -185,4 +227,4 @@ interface IMeshNodes {
     nodes: INodes;
     elements: IElements;
 }
-export type { SceneMapType, ICopperRenderOpt, stateType, modelVisualisationDataType, preRenderCallbackFunctionType, baseStateType, nrrdMeshesType, nrrdSliceType, loadingBarType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, SerialService_kiwrious, kiwriousType, mouseMovePositionType, positionType, optionsGltfExporterType, vtkModels, copperVolumeType, dicomLoaderOptsType, exportPaintImagesType, exportPaintImageType, storeExportPaintImageType, IOptVTKLoader, ICopperSceneOpts, IMeshNodes, };
+export type { SceneMapType, ICopperRenderOpt, stateType, modelVisualisationDataType, preRenderCallbackFunctionType, baseStateType, nrrdMeshesType, nrrdSliceType, loadingBarType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, SerialService_kiwrious, kiwriousType, mouseMovePositionType, positionType, optionsGltfExporterType, vtkModels, planeCorners, copperVolumeType, aligned4DSurfaceType, aligned4DOptsType, Aligned4DController, dicomLoaderOptsType, exportPaintImagesType, exportPaintImageType, storeExportPaintImageType, IOptVTKLoader, ICopperSceneOpts, IMeshNodes, };

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.4.8",
+  "version": "3.5.0",
   "main": "dist/bundle.umd.js",
   "moudle": "dist/bundle.esm.js",
   "types": "dist/types/index.d.ts",