copper3d 3.3.3 → 3.4.1

package/dist/index.d.ts

@@ -25,6 +25,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.3.3-beta";
+export declare const REVISION = "v3.4.1-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, };

package/dist/index.js

@@ -21,7 +21,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.3.3-beta";
+export const REVISION = "v3.4.1-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, };
 //# sourceMappingURL=index.js.map

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

@@ -51,11 +51,17 @@ export declare class RenderingUtils {
      */
     getOrCreateSliceBuffer(axis: "x" | "y" | "z"): ImageData | null;
     /**
-     * Render a layer's slice into a reusable buffer and draw to the target canvas.
+     * Render a layer's slice onto the target canvas as vector contours.
      *
-     * Uses MaskVolume.renderLabelSliceInto() for zero-allocation rendering.
+     * Uses marching-squares to extract voxel-truthful Path2D contours per
+     * label, then `ctx.fill()` them at the display canvas resolution. This
+     * eliminates the bilinear-upscale blur and zoom-dependent shape drift
+     * that plagued the old putImageData → drawImage pipeline.
+     *
+     * The `buffer` parameter is kept for backward-compatible signature but
+     * is no longer used on this path — callers may pass any valid ImageData.
      */
-    renderSliceToCanvas(layer: string, axis: "x" | "y" | "z", sliceIndex: number, buffer: ImageData, targetCtx: CanvasRenderingContext2D, scaledWidth: number, scaledHeight: number): void;
+    renderSliceToCanvas(layer: string, axis: "x" | "y" | "z", sliceIndex: number, _buffer: ImageData, targetCtx: CanvasRenderingContext2D, scaledWidth: number, scaledHeight: number): void;
     /**
      * Invalidate the reusable buffer (e.g. when switching datasets).
      */

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

@@ -0,0 +1,72 @@
+/**
+ * MarchingSquares — Extract vector contours from a 2D voxel label grid.
+ *
+ * For each label, produces a `Path2D` whose subpaths are small per-cell
+ * polygons. The polygons tile the region occupied by the target label; the
+ * union (via `ctx.fill(path, 'nonzero')`) is the label's silhouette on the
+ * voxel grid.
+ *
+ * Coordinate convention:
+ *   - Voxel (i, j) occupies the unit square [i, i+1] × [j, j+1] in render
+ *     space, with its center at (i+0.5, j+0.5). This matches ITK-SNAP /
+ *     standard imaging viewers and the existing `renderSliceToCanvas`
+ *     `scale(scaledW / W, scaledH / H)` mapping.
+ *   - Marching squares treats voxels as point samples at their centers:
+ *     cell (i, j) has corners at voxel centers (i+0.5, j+0.5),
+ *     (i+1.5, j+0.5), (i+1.5, j+1.5), (i+0.5, j+1.5).
+ *   - This produces 45°-cut contours (diamonds for isolated voxels, rounded
+ *     corners for connected regions) that stay within the voxel-square
+ *     bounds, so the rendered silhouette is a slightly-inset version of the
+ *     ITK-SNAP silhouette with smooth diagonals.
+ *
+ * Saddle cases (5 and 10) use a fixed convention: the two in-corners are
+ * treated as disconnected within the cell (4-connectivity interpretation).
+ */
+export interface ContourBBox {
+    /** Inclusive left voxel (0 ≤ x0 ≤ width). */
+    x0: number;
+    /** Inclusive top voxel (0 ≤ y0 ≤ height). */
+    y0: number;
+    /** Exclusive right voxel (x1 > x0). */
+    x1: number;
+    /** Exclusive bottom voxel (y1 > y0). */
+    y1: number;
+}
+/** A single polygon's vertices in voxel-space coordinates. */
+export type ContourPolygon = ReadonlyArray<readonly [number, number]>;
+/**
+ * Emit all per-cell polygons covering the voxels where `labels === targetLabel`.
+ * Pure geometry function — no Canvas dependency. Consumers can build a Path2D
+ * (see {@link extractLabelContours}) or walk the vertex arrays directly
+ * (tests, export, stroke rendering).
+ */
+export declare function extractLabelPolygons(labels: Uint8Array, width: number, height: number, targetLabel: number, stride?: number, channelOffset?: number, bbox?: ContourBBox): ContourPolygon[];
+/**
+ * Extract a `Path2D` covering all voxels equal to `targetLabel`.
+ *
+ * @param labels      Flat label array. Addressed as
+ *                    `labels[(y * width + x) * stride + channelOffset]`.
+ * @param width       Grid width in voxels.
+ * @param height      Grid height in voxels.
+ * @param targetLabel Label value to extract (1..255; 0 is background).
+ * @param stride      Bytes per voxel (default 1). Use MaskVolume.numChannels
+ *                    when reading interleaved slices.
+ * @param channelOffset Offset within each voxel's channels to sample.
+ *                    Default 0 (first channel = label id).
+ * @param bbox        Optional voxel-space bbox to limit extraction.
+ *                    Cells in a 1-voxel halo around the bbox are still
+ *                    visited so the contour closes correctly at the bbox edges.
+ */
+export declare function extractLabelContours(labels: Uint8Array, width: number, height: number, targetLabel: number, stride?: number, channelOffset?: number, bbox?: ContourBBox): Path2D;
+/**
+ * Detect the distinct non-zero labels present in a slice region.
+ *
+ * @param labels        Flat label array (see {@link extractLabelContours}).
+ * @param width         Grid width.
+ * @param height        Grid height.
+ * @param stride        Bytes per voxel.
+ * @param channelOffset Offset within each voxel.
+ * @param bbox          Optional region to scan (defaults to full grid).
+ * @returns Sorted array of distinct label values (0 omitted).
+ */
+export declare function findLabelsInSlice(labels: Uint8Array, width: number, height: number, stride?: number, channelOffset?: number, bbox?: ContourBBox): number[];

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

@@ -72,3 +72,5 @@ export { RenderMode, MASK_CHANNEL_COLORS, MASK_CHANNEL_CSS_COLORS, CHANNEL_COLOR
 export { MaskVolume } from './MaskVolume';
 export type { MaskDelta, UndoEntry } from './UndoManager';
 export { UndoManager } from './UndoManager';
+export type { ContourBBox, ContourPolygon } from './MarchingSquares';
+export { extractLabelContours, extractLabelPolygons, findLabelsInSlice, } from './MarchingSquares';

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

@@ -88,6 +88,15 @@ export declare class EventRouter {
     isCtrlHeld(): boolean;
     isLeftButtonDown(): boolean;
     isRightButtonDown(): boolean;
+    /**
+     * Whether the user is currently performing a slice-drag (left-button held
+     * in idle mode with a non-sphere tool). In this state the mouse wheel is
+     * suppressed so that slice switching via drag and slice/zoom via wheel
+     * cannot fight each other. Draw / contrast / crosshair set `mode` away
+     * from 'idle', and sphere-family tools use left-drag for their own
+     * purposes, so both are correctly excluded.
+     */
+    isDragSliceActive(): boolean;
     /**
      * Update keyboard settings.
      */

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

@@ -4,6 +4,10 @@
  * Extracted from DrawToolCore.paintOnCanvas() closure (Phase 3).
  * Handles left-click drawing operations: pencil stroke + fill, brush strokes,
  * eraser, and undo snapshot capture/push.
+ *
+ * Phase B: Brush mode now writes voxels directly during mousemove and
+ * re-renders via marching squares, eliminating the visual "snap" between
+ * the smooth canvas stroke and the voxel-based post-release render.
  */
 import { BaseTool } from "./BaseTool";
 import type { ToolContext } from "./BaseTool";
@@ -21,6 +25,8 @@ export declare class DrawingTool extends BaseTool {
     private preDrawSlice;
     private preDrawAxis;
     private preDrawSliceIndex;
+    /** Previous voxel-space position for Bresenham interpolation (brush mode) */
+    private prevVoxel;
     private callbacks;
     constructor(ctx: ToolContext, callbacks: DrawingHostDeps);
     /** Whether a draw operation is currently active */
@@ -56,30 +62,49 @@ export declare class DrawingTool extends BaseTool {
     /**
      * 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;
+    /**
+     * Convert display (zoomed) coordinates to 3D voxel coordinates.
+     * Same logic as SphereBrushTool.canvasToVoxelCenter.
+     */
+    private canvasToVoxel3D;
+    /**
+     * Get voxel-space brush radius for visible axes.
+     * Converts display-pixel brush size to voxel units.
+     */
+    private getVoxelBrushRadius;
+    /**
+     * Paint a 2D ellipse of voxels on the current slice.
+     * Only the two visible axes are iterated; the slice-direction axis is fixed.
+     */
+    private paintVoxelEllipse;
+    /**
+     * Brush mode mousemove: write voxels along stroke segment, then re-render.
+     * Uses linear interpolation between prev and current positions to ensure
+     * no gaps when the mouse moves fast.
+     */
+    private paintBrushVoxelMove;
+    /**
+     * Re-render the active layer's canvas from MaskVolume via marching squares,
+     * then composite all layers to master.
+     */
+    private refreshLayerFromVolume;
     /** 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.
+     * Delegates to the host's vector renderSliceToCanvas for consistency.
      */
     private redrawPreviousImageToLayerCtx;
-    /** Draw a line segment on a layer canvas */
+    /** Draw a line segment on a layer canvas (pencil mode only) */
     private drawLinesOnLayer;
-    /** Paint a segment on the current layer canvas and composite to master */
+    /** Paint a segment on the current layer canvas and composite to master (pencil mode) */
     private paintOnCanvasLayer;
 }

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

@@ -19,7 +19,11 @@ 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 */
+    /**
+     * Recorded sphere center in display (zoomed) coordinates.
+     * Used for both preview redraw and voxel calculation — the voxel conversion
+     * uses `changedWidth/Height` as the display scale, so no mm detour is needed.
+     */
     private centerX;
     private centerY;
     private centerSlice;
@@ -27,18 +31,42 @@ export declare class SphereBrushTool extends BaseTool {
     private active;
     /** Current operation mode for the active placement */
     private mode;
-    /** Cumulative "before" snapshots for drag-erase undo (z-index → slice data) */
+    /** Cumulative "before" snapshots for drag undo (z-index → slice data) — used by both brush and eraser drag */
     private dragBeforeSnapshots;
-    /** Whether a drag-erase has actually moved (vs. simple click-release) */
+    /** Whether a drag has actually moved (vs. simple click-release) */
     private dragMoved;
+    /**
+     * Latest cursor position in display (zoomed) coords. Used by the wheel
+     * handler to redraw the preview at the cursor, not the original mousedown
+     * point, during mid-drag radius changes.
+     */
+    private lastDisplayX;
+    private lastDisplayY;
+    private lastSliceIndex;
+    /**
+     * All sphere centers written during the current stroke. The wheel handler
+     * retroactively re-renders the entire stroke at the new radius by restoring
+     * `dragBeforeSnapshots` and replaying every entry here.
+     */
+    private strokeCenters;
     constructor(ctx: ToolContext, callbacks: SphereBrushHostDeps);
     setCallbacks(callbacks: SphereBrushHostDeps): void;
     /**
-     * Convert canvas mm-space coordinates to 3D voxel coordinates.
+     * Convert display (zoomed) coordinates to 3D voxel coordinates.
+     *
+     * Uses `changedWidth/Height` as the display scale directly (instead of
+     * going through mm via `/sizeFactor`). This keeps the write pixel-exact
+     * with the preview circle, which is drawn on a `changedWidth x changedHeight`
+     * sized sphere canvas — avoiding floating-point drift at high zoom levels.
      */
     private canvasToVoxelCenter;
     /**
      * Convert mm radius to per-axis voxel radii.
+     *
+     * For the two axes visible in the current view, scale via
+     * `changedWidth/Height` so the rendered ellipsoid cross-section matches
+     * the preview pixel radius exactly. The third (slice-direction) axis is
+     * not visible, so it uses the plain mm-based ratio.
      */
     private getVoxelRadii;
     /**
@@ -83,11 +111,41 @@ export declare class SphereBrushTool extends BaseTool {
      */
     configSphereBrushWheel(): (e: WheelEvent) => void;
     /**
-     * Handle pointer-down in sphereBrush mode (direct click, no Shift needed).
+     * Retroactively re-render the current stroke at the current radius.
+     *
+     * Step 1: walk every recorded stroke center and expand
+     *   `dragBeforeSnapshots` to cover the new (larger) bounding box. Slices
+     *   newly included here are still pristine because the original stroke
+     *   never touched them.
+     * Step 2: restore every snapshotted slice from its pristine backup.
+     * Step 3: replay every stroke center at the new radius.
+     *
+     * Step 3 produces the same final state as if the user had used the new
+     * radius from the start. Undo still captures the full stroke as one group
+     * at pointerup.
+     */
+    private replayStrokeWithCurrentRadius;
+    /**
+     * Handle pointer-down in sphereBrush mode (3D Slicer-style).
+     *
+     * Captures pristine snapshots at the mousedown location but does NOT
+     * write any voxels yet — the user may wheel-adjust the radius before
+     * dragging. The first sphere is written either by the first pointermove
+     * or by pointerup (single-click fallback).
      */
     onSphereBrushClick(e: MouseEvent): void;
     /**
-     * Handle pointer-up in sphereBrush mode — write sphere to volume.
+     * Handle pointer-move in sphereBrush mode — drag to continuously paint.
+     *
+     * Mirrors sphereEraser drag: writes a new sphere at each move position,
+     * extends the cumulative before-snapshot to cover any newly-touched Z
+     * slices, and repaints the preview. Never notifies the backend; pointerup
+     * does that once for the whole stroke.
+     */
+    onSphereBrushMove(e: MouseEvent): void;
+    /**
+     * Handle pointer-up in sphereBrush mode — finalize stroke + push undo group
+     * + single batched backend notify for all Z slices touched during the drag.
      */
     onSphereBrushPointerUp(): void;
     /**
@@ -104,6 +162,12 @@ export declare class SphereBrushTool extends BaseTool {
      * Works for both click-release and drag-release.
      */
     onSphereEraserPointerUp(): void;
+    /**
+     * Clear per-stroke state after pointerup or cancel. Kept as a helper so
+     * brush/eraser pointerup and cancelActivePlacement all reset the same set
+     * of fields — if a new drag-state field is added, only one place to update.
+     */
+    private finalizeStrokeState;
     /**
      * Expand cumulative "before" snapshots to cover z range [minZ, maxZ].
      * Only captures slices not yet in the map (preserves original state).
@@ -120,8 +184,21 @@ export declare class SphereBrushTool extends BaseTool {
      * @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.
+     * @param notifyBackend - When false, only refresh the local canvas and skip
+     *   the onMaskChanged callback. Used during drag to avoid per-frame HTTP;
+     *   pointerup then calls with `true` to send a single batched update.
      */
     private refreshDisplay;
     /** Whether a sphere placement is currently in progress */
     get isActive(): boolean;
+    /**
+     * Defensively cancel any in-progress sphere placement and clear the preview.
+     *
+     * Called when crosshair mode is entered so any lingering sphere preview
+     * (e.g. red dashed eraser outline) is wiped immediately. In normal flow
+     * `leftButtonDown === true` blocks crosshair toggle, so this shouldn't
+     * fire mid-stroke — but if it ever does, we drop the drag snapshot
+     * rather than committing a partial undo entry.
+     */
+    cancelActivePlacement(): void;
 }

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

@@ -64,7 +64,7 @@ export type ZoomHostDeps = Pick<ToolHost, 'resetPaintAreaUIPosition' | 'resizePa
 /** 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'>;
+export type DrawingHostDeps = Pick<ToolHost, 'setCurrentLayer' | 'compositeAllLayers' | 'syncLayerSliceData' | 'filterDrawedImage' | 'getVolumeForLayer' | 'pushUndoDelta' | 'getEraserUrls' | 'renderSliceToCanvas' | 'getOrCreateSliceBuffer'>;
 /** DragSliceTool host dependencies */
 export type DragSliceHostDeps = Pick<ToolHost, 'setSyncsliceNum' | 'setIsDrawFalse' | 'flipDisplayImageByAxis' | 'setEmptyCanvasSize' | 'getOrCreateSliceBuffer' | 'renderSliceToCanvas' | 'refreshSphereOverlay' | 'compositeAllLayers'>;
 /** LayerChannelManager host dependencies */

package/dist/types/index.d.ts

@@ -25,6 +25,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.3.3-beta";
+export declare const REVISION = "v3.4.1-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, };

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