copper3d 2.2.3 → 3.0.0

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

@@ -1,17 +1,33 @@
 import { nrrdSliceType, storeExportPaintImageType, loadingBarType } from "../../types/types";
 import { GUI } from "dat.gui";
-import { IPaintImages, IStoredPaintImages, IMaskData, IDragOpts, IGuiParameterSettings } from "./coreTools/coreType";
+import { IMaskData, IDragOpts, IGuiParameterSettings, IKeyBoardSettings } from "./coreTools/coreType";
 import { DragOperator } from "./DragOperator";
 import { DrawToolCore } from "./DrawToolCore";
+import type { ChannelValue, RGBAColor, ChannelColorMap } from "./core";
+/**
+ * Core NRRD annotation tool for medical image segmentation.
+ *
+ * @example
+ * ```ts
+ * // Default 3 layers: layer1, layer2, layer3
+ * const tools = new NrrdTools(container);
+ *
+ * // Custom layers
+ * const tools = new NrrdTools(container, { layers: ["layer1", "layer2"] });
+ * ```
+ */
 export declare class NrrdTools extends DrawToolCore {
     container: HTMLDivElement;
     dragOperator: DragOperator;
-    storedPaintImages: IStoredPaintImages | undefined;
     private paintedImage;
     private initState;
     private preTimer;
     private guiParameterSettings;
-    constructor(container: HTMLDivElement);
+    private _sliceRAFId;
+    private _pendingSliceStep;
+    constructor(container: HTMLDivElement, options?: {
+        layers?: string[];
+    });
     /**
      * core function for drag slices
      * @param opts
@@ -37,6 +53,250 @@ export declare class NrrdTools extends DrawToolCore {
         guiState: import("./coreTools/coreType").IGUIStates;
         guiSetting: IGuiParameterSettings | undefined;
     };
+    /**
+     * Set the active layer and update fillColor/brushColor to match the active channel.
+     */
+    setActiveLayer(layerId: string): void;
+    /**
+     * Set the active channel (1-8) and update fillColor/brushColor.
+     */
+    setActiveChannel(channel: ChannelValue): void;
+    /**
+     * Sync brush/fill color from the active layer's volume color map.
+     * Falls back to global CHANNEL_HEX_COLORS if volume not available.
+     */
+    private syncBrushColor;
+    /**
+     * Get the currently active layer id.
+     */
+    getActiveLayer(): string;
+    /**
+     * Get the currently active channel value.
+     */
+    getActiveChannel(): number;
+    /**
+     * Set visibility of a layer and re-render.
+     */
+    setLayerVisible(layerId: string, visible: boolean): void;
+    /**
+     * Check if a layer is visible.
+     */
+    isLayerVisible(layerId: string): boolean;
+    /**
+     * Set visibility of a specific channel within a layer and re-render.
+     */
+    setChannelVisible(layerId: string, channel: ChannelValue, visible: boolean): void;
+    /**
+     * Check if a specific channel within a layer is visible.
+     */
+    isChannelVisible(layerId: string, channel: ChannelValue): boolean;
+    /**
+     * Get the full layer visibility map.
+     */
+    getLayerVisibility(): Record<string, boolean>;
+    /**
+     * Get the full channel visibility map.
+     */
+    getChannelVisibility(): Record<string, Record<number, boolean>>;
+    /**
+     * Check if a specific layer contains any non-zero mask data.
+     *
+     * This is useful for determining if a layer has actual annotations
+     * before saving or exporting to avoid processing empty layers.
+     *
+     * @param layerId - The layer to check ('layer1', 'layer2', or 'layer3')
+     * @returns True if the layer has any non-zero voxel data, false if empty
+     *
+     * @example
+     * ```ts
+     * if (nrrdTools.hasLayerData('layer1')) {
+     *   await useSaveMasks(caseId, 'layer1');
+     * }
+     * ```
+     */
+    hasLayerData(layerId: string): boolean;
+    /**
+     * Set a custom color for a specific channel in a specific layer.
+     * Only affects this layer; other layers remain unchanged.
+     *
+     * @param layerId  Layer to customize (e.g. 'layer1', 'layer2')
+     * @param channel  Channel label (1-8)
+     * @param color    RGBAColor object { r, g, b, a } (each 0-255)
+     *
+     * @example
+     * ```ts
+     * // Make channel 2 in layer2 orange
+     * nrrdTools.setChannelColor('layer2', 2, { r: 255, g: 128, b: 0, a: 255 });
+     * ```
+     */
+    setChannelColor(layerId: string, channel: number, color: RGBAColor): void;
+    /**
+     * Get the current color for a specific channel in a specific layer.
+     *
+     * @param layerId  Layer to query
+     * @param channel  Channel label (1-8)
+     * @returns RGBAColor object (copy, safe to mutate)
+     */
+    getChannelColor(layerId: string, channel: number): RGBAColor;
+    /**
+     * Get a hex color string for a channel in a layer (e.g. '#ff8000').
+     */
+    getChannelHexColor(layerId: string, channel: number): string;
+    /**
+     * Get a CSS rgba() color string for a channel in a layer.
+     */
+    getChannelCssColor(layerId: string, channel: number): string;
+    /**
+     * Batch-set multiple channel colors for a single layer (single re-render).
+     *
+     * @param layerId  Layer to customize
+     * @param colorMap Partial map of channel -> RGBAColor
+     *
+     * @example
+     * ```ts
+     * nrrdTools.setChannelColors('layer2', {
+     *   2: { r: 255, g: 128, b: 0, a: 255 },
+     *   3: { r: 100, g: 200, b: 50, a: 255 },
+     * });
+     * ```
+     */
+    setChannelColors(layerId: string, colorMap: Partial<ChannelColorMap>): void;
+    /**
+     * Set the same color for a specific channel across ALL layers (single re-render).
+     *
+     * @param channel  Channel label (1-8)
+     * @param color    RGBAColor object
+     */
+    setAllLayersChannelColor(channel: number, color: RGBAColor): void;
+    /**
+     * Reset channel colors to system defaults.
+     *
+     * @param layerId  Optional. If omitted, resets all layers.
+     * @param channel  Optional. If omitted, resets all channels in the layer(s).
+     *
+     * @example
+     * ```ts
+     * nrrdTools.resetChannelColors('layer2', 2);  // Reset only ch2 in layer2
+     * nrrdTools.resetChannelColors('layer2');       // Reset all channels in layer2
+     * nrrdTools.resetChannelColors();               // Reset all layers
+     * ```
+     */
+    resetChannelColors(layerId?: string, channel?: number): void;
+    /**
+     * Programmatically trigger an undo operation.
+     *
+     * Equivalent to pressing Ctrl+Z. Reverts the most recent drawing stroke
+     * on the currently active layer and syncs the result to the backend via
+     * the `getMask` callback.
+     *
+     * @example
+     * ```ts
+     * undoBtn.addEventListener('click', () => nrrdTools.undo());
+     * ```
+     */
+    undo(): void;
+    /**
+     * Programmatically trigger a redo operation.
+     *
+     * Equivalent to pressing Ctrl+Y. Re-applies the most recently undone
+     * drawing stroke on the currently active layer and syncs the result to
+     * the backend via the `getMask` callback.
+     *
+     * @example
+     * ```ts
+     * redoBtn.addEventListener('click', () => nrrdTools.redo());
+     * ```
+     */
+    redo(): void;
+    /**
+     * Enter keyboard-configuration mode.
+     *
+     * While active, every keydown/keyup handler in DrawToolCore and DragOperator
+     * is suppressed so the user can press arbitrary keys in the settings dialog
+     * without accidentally triggering drawing, undo, or contrast shortcuts.
+     *
+     * Always pair with {@link exitKeyboardConfig} when the dialog closes.
+     *
+     * @example
+     * ```ts
+     * dialog.addEventListener('open', () => nrrdTools.enterKeyboardConfig());
+     * ```
+     */
+    enterKeyboardConfig(): void;
+    /**
+     * Exit keyboard-configuration mode and resume normal shortcut handling.
+     *
+     * @example
+     * ```ts
+     * dialog.addEventListener('close', () => nrrdTools.exitKeyboardConfig());
+     * ```
+     */
+    exitKeyboardConfig(): void;
+    /**
+     * Enable or disable the contrast window/level shortcut (Ctrl/Meta key).
+     *
+     * When disabled:
+     * - Holding Ctrl no longer enters contrast mode
+     * - If contrast mode is currently active it is immediately exited
+     * - All other Ctrl-based shortcuts (Ctrl+Z undo, Ctrl+Y redo) are
+     *   unaffected because they are checked in the keydown handler before
+     *   the contrast guard runs
+     *
+     * @param enabled - Pass `false` to disable, `true` to re-enable.
+     *
+     * @example
+     * ```ts
+     * // Disable contrast when sphere tool is active
+     * nrrdTools.setContrastShortcutEnabled(false);
+     *
+     * // Re-enable when returning to draw mode
+     * nrrdTools.setContrastShortcutEnabled(true);
+     * ```
+     */
+    setContrastShortcutEnabled(enabled: boolean): void;
+    /**
+     * Returns whether the contrast shortcut is currently enabled.
+     */
+    isContrastShortcutEnabled(): boolean;
+    /**
+     * Update keyboard shortcut bindings.
+     *
+     * Synchronises both the internal class field (read by every keydown handler)
+     * and the EventRouter's internal copy (used for modifier-key mode tracking)
+     * so the two never drift apart.  If `mouseWheel` is changed the wheel event
+     * listener is automatically re-bound via {@link updateMouseWheelEvent}.
+     *
+     * Only the fields you supply are updated; omitted fields keep their
+     * current values.
+     *
+     * @param settings - Partial keyboard settings to override.
+     *
+     * @example
+     * ```ts
+     * nrrdTools.setKeyboardSettings({
+     *   undo: 'z',
+     *   redo: 'y',
+     *   crosshair: 'c',
+     *   mouseWheel: 'Scroll:Slice',
+     * });
+     * ```
+     */
+    setKeyboardSettings(settings: Partial<IKeyBoardSettings>): void;
+    /**
+     * Get a snapshot of the current keyboard shortcut bindings.
+     *
+     * Returns a shallow copy so callers cannot accidentally mutate internal
+     * state. To update settings use {@link setKeyboardSettings} instead.
+     *
+     * @returns Current keyboard settings.
+     *
+     * @example
+     * ```ts
+     * const { undo, redo } = nrrdTools.getKeyboardSettings();
+     * console.log(`Undo: Ctrl+${undo}, Redo: Ctrl+${redo}`);
+     * ```
+     */
+    getKeyboardSettings(): IKeyBoardSettings;
     /**
      * A initialise function for nrrd_tools
      */
@@ -54,21 +314,24 @@ export declare class NrrdTools extends DrawToolCore {
    
      */
     setAllSlices(allSlices: Array<nrrdSliceType>): void;
-    private loadingMaskByLabel;
+    private loadingMaskByLayer;
     setMasksData(masksData: storeExportPaintImageType, loadingBar?: loadingBarType): void;
+    /**
+     * Load raw voxel data into MaskVolume layers.
+     *
+     * Expects pre-extracted voxel bytes (e.g. from useNiftiVoxelData).
+     *
+     * @param layerVoxels Map of layer ID to raw voxel Uint8Array
+     *   Keys should be 'layer1', 'layer2', 'layer3'
+     * @param loadingBar Optional loading bar UI
+     */
+    setMasksFromNIfTI(layerVoxels: Map<string, Uint8Array>, loadingBar?: loadingBarType): void;
     private setShowInMainArea;
     getCurrentImageDimension(): number[];
     getVoxelSpacing(): number[];
     getSpaceOrigin(): number[];
     getMaskData(): IMaskData;
     setCalculateDistanceSphere(x: number, y: number, sliceIndex: number, cal_position: "tumour" | "skin" | "nipple" | "ribcage"): void;
-    private getSharedPlace;
-    /**
-     * init all painted images for store images
-     * @param dimensions
-     */
-    private initPaintImages;
-    createEmptyPaintImage(dimensions: Array<number>, paintImages: IPaintImages): void;
     /**
      * Switch all contrast slices' orientation
      * @param {string} aixs:"x" | "y" | "z"
@@ -135,11 +398,10 @@ export declare class NrrdTools extends DrawToolCore {
      */
     resizePaintArea(factor: number): void;
     /**
-     * Used to init the mask on each label and reload
-     * @param paintImages
-     * @param ctx
+     * Phase 3: Reload all mask layers from MaskVolume using buffer reuse
+     * Replaces the old reloadMaskToLayer approach
      */
-    private reloadMaskToLabel;
+    private reloadMasksFromVolume;
     /**
      * flip the canvas to a correct position.
      * This is because the slice canvas from threejs is not in a correct 2D postion.