@tonybfox/threejs-tools 1.0.0

package/dist/measurements/index.d.ts

@@ -0,0 +1,449 @@
+import * as THREE from 'three';
+import { CSS2DObject } from 'three/examples/jsm/renderers/CSS2DRenderer';
+
+/**
+ * Defines how a measurement point is attached to a scene object.
+ */
+interface MeasurementAnchor {
+    /** Object the point is attached to */
+    object: THREE.Object3D;
+    /** Local position relative to the object */
+    localPosition: THREE.Vector3;
+}
+/**
+ * Represents a measurement point in world space with an optional anchor.
+ */
+interface MeasurementPoint {
+    /** World position of the measurement point */
+    position: THREE.Vector3;
+    /** Optional attachment data for dynamic updates */
+    anchor?: MeasurementAnchor;
+}
+/**
+ * Per-measurement configuration captured at creation time.
+ */
+interface MeasurementOptions {
+    /** Render color for the measurement line */
+    lineColor: number;
+    /** Render color for the measurement label text */
+    labelColor: string;
+    /** Width of the rendered line */
+    lineWidth: number;
+    /** Font size for label text */
+    fontSize: number;
+    /** Font family for label text */
+    fontFamily: string;
+    /** Snapping mode used when the measurement was created */
+    snapMode: SnapMode;
+    /** Whether snapping was enabled for this measurement */
+    snapEnabled: boolean;
+    /** Snap distance threshold for this measurement */
+    snapDistance: number;
+    /** Targets that were considered for snapping */
+    targets: THREE.Object3D[];
+    /** Whether this measurement should remain linked to scene objects */
+    isDynamic: boolean;
+}
+/**
+ * Runtime representation of a measurement inside the scene.
+ */
+interface Measurement {
+    /** Unique identifier for the measurement */
+    id: string;
+    /** Starting point of the measurement */
+    start: MeasurementPoint;
+    /** Ending point of the measurement */
+    end: MeasurementPoint;
+    /** The line geometry representing the measurement */
+    line: THREE.Line;
+    /** The CSS2D label showing the distance */
+    label: CSS2DObject;
+    /** The calculated distance between start and end points */
+    distance: number;
+    /** Config that should be reused when editing this measurement */
+    options: MeasurementOptions;
+}
+/**
+ * Options accepted when creating or importing a measurement.
+ */
+interface MeasurementCreationOptions {
+    /** Explicit measurement identifier */
+    id?: string;
+    /** Objects that should be considered for snapping/intersections */
+    targets?: THREE.Object3D[];
+    /** Whether snapping should be enabled */
+    snapEnabled?: boolean;
+    /** Snap distance threshold */
+    snapDistance?: number;
+    /** Snapping mode */
+    snapMode?: SnapMode;
+    /** Line color */
+    lineColor?: number;
+    /** Label color */
+    labelColor?: string;
+    /** Line width */
+    lineWidth?: number;
+    /** Label font size */
+    fontSize?: number;
+    /** Label font family */
+    fontFamily?: string;
+    /** Whether the measurement should stay linked to objects */
+    isDynamic?: boolean;
+    /** Object the start point should follow */
+    startObject?: THREE.Object3D;
+    /** Local position relative to startObject (defaults to world position converted to local) */
+    startLocalPosition?: THREE.Vector3;
+    /** Object the end point should follow */
+    endObject?: THREE.Object3D;
+    /** Local position relative to endObject (defaults to world position converted to local) */
+    endLocalPosition?: THREE.Vector3;
+}
+/**
+ * Serializable measurement point data for export/import.
+ */
+interface MeasurementPointData {
+    /** Position as array [x, y, z] */
+    position: [number, number, number];
+    /** UUID of the anchor object if the point is dynamic */
+    anchorObjectId?: string;
+    /** Local position relative to the anchor object */
+    anchorLocalPosition?: [number, number, number];
+}
+/**
+ * Serializable measurement configuration data.
+ */
+interface SerializedMeasurementOptions {
+    /** Snapping mode used by the measurement */
+    snapMode: SnapMode;
+    /** Whether snapping was enabled for the measurement */
+    snapEnabled: boolean;
+    /** Snap distance threshold used by the measurement */
+    snapDistance: number;
+    /** Measurement line color */
+    lineColor: number;
+    /** Measurement label color */
+    labelColor: string;
+    /** Measurement line width */
+    lineWidth: number;
+    /** Measurement label font size */
+    fontSize: number;
+    /** Measurement label font family */
+    fontFamily: string;
+    /** Whether the measurement should stay linked to objects */
+    isDynamic: boolean;
+    /** UUIDs of the target objects captured for this measurement */
+    targetObjectIds?: string[];
+}
+/**
+ * Serializable measurement data for export/import.
+ */
+interface MeasurementData {
+    /** Unique identifier */
+    id: string;
+    /** Starting point data */
+    start: MeasurementPointData;
+    /** Ending point data */
+    end: MeasurementPointData;
+    /** Calculated distance */
+    distance: number;
+    /** Captured configuration for the measurement */
+    options: SerializedMeasurementOptions;
+}
+/**
+ * Configuration options for the measurement tool
+ */
+interface MeasurementToolOptions {
+    /** DOM element for mouse interactions (required for interactive mode and editing) */
+    domElement?: HTMLElement;
+    /** Camera controls to disable during edit dragging (e.g., OrbitControls) */
+    controls?: {
+        enabled: boolean;
+    };
+}
+/**
+ * Snapping mode options
+ */
+declare enum SnapMode {
+    VERTEX = "vertex",
+    FACE = "face",
+    EDGE = "edge",
+    DISABLED = "disabled"
+}
+/**
+ * Event types dispatched by the measurement tool
+ */
+interface MeasurementToolEvents {
+    /** Fired when a new measurement is created */
+    measurementCreated: {
+        measurement: Measurement;
+    };
+    /** Fired when a measurement is removed */
+    measurementRemoved: {
+        measurement: Measurement;
+    };
+    /** Fired when all measurements are cleared */
+    measurementsCleared: {
+        count: number;
+    };
+    /** Fired when interactive mode starts */
+    started: {};
+    /** Fired when interactive mode ends */
+    ended: {};
+    /** Fired when preview line is updated */
+    previewUpdated: {
+        start: THREE.Vector3;
+        current: THREE.Vector3;
+        distance: number;
+    };
+    /** Fired when edit mode is entered */
+    editModeEntered: {
+        measurement: Measurement;
+    };
+    /** Fired when edit mode is exited */
+    editModeExited: {
+        measurement: Measurement;
+    };
+    /** Fired when a measurement is updated */
+    measurementUpdated: {
+        measurement: Measurement;
+    };
+}
+/**
+ * Raycast result with snapping information
+ */
+interface SnapResult {
+    /** The snapped position */
+    point: THREE.Vector3;
+    /** The original intersection point */
+    originalPoint: THREE.Vector3;
+    /** Whether snapping occurred */
+    snapped: boolean;
+    /** The snap mode that was applied */
+    snapMode: SnapMode;
+    /** The object that was intersected */
+    object: THREE.Object3D;
+}
+
+/**
+ * Main measurement tool class for Three.js scenes
+ * Provides both programmatic and interactive measurement creation
+ *
+ * **Important**: This tool uses CSS2DObject for labels, which requires
+ * CSS2DRenderer to be set up and rendered alongside your main WebGL renderer.
+ *
+ * @example
+ * ```javascript
+ * import { CSS2DRenderer } from 'three/examples/jsm/renderers/CSS2DRenderer.js'
+ *
+ * // Set up CSS2DRenderer
+ * const css2dRenderer = new CSS2DRenderer()
+ * css2dRenderer.setSize(window.innerWidth, window.innerHeight)
+ * css2dRenderer.domElement.style.position = 'absolute'
+ * css2dRenderer.domElement.style.top = '0'
+ * css2dRenderer.domElement.style.pointerEvents = 'none'
+ * document.body.appendChild(css2dRenderer.domElement)
+ *
+ * // In your animation loop:
+ * function animate() {
+ *   renderer.render(scene, camera)        // WebGL rendering
+ *   css2dRenderer.render(scene, camera)   // CSS2D label rendering
+ * }
+ * ```
+ */
+declare class MeasurementTool extends THREE.EventDispatcher<MeasurementToolEvents> {
+    private scene;
+    private camera;
+    private measurements;
+    private raycaster;
+    private isInteractive;
+    private domElement;
+    private controls;
+    private defaultTargets;
+    private activeTargets;
+    private currentMeasurement;
+    private activeInteractionOptions;
+    private pendingMeasurementOptions;
+    private previewLine;
+    private previewLabel;
+    private snapMarker;
+    private originalCursor;
+    private cursorHidden;
+    private defaultOptions;
+    private previewColor;
+    private markerColor;
+    private markerSize;
+    private markerVisible;
+    private isEditMode;
+    private editingMeasurement;
+    private editingPoint;
+    private startEditSprite;
+    private endEditSprite;
+    private editSpriteMaterial;
+    private isDragging;
+    private previewMaterial;
+    private markerMaterial;
+    /**
+     * Create a crosshair texture for the snap marker sprite
+     */
+    private createCrosshairTexture;
+    /**
+     * Create a dot texture for edit point sprites
+     */
+    private createDotTexture;
+    constructor(scene: THREE.Scene, camera: THREE.Camera, options?: MeasurementToolOptions);
+    /**
+     * Create a measurement point that optionally tracks a scene object.
+     */
+    private createMeasurementPoint;
+    /**
+     * Update a measurement point's world position from its anchor (if dynamic)
+     */
+    private updateMeasurementPoint;
+    /**
+     * Add a measurement between two world positions with optional attachments.
+     *
+     * @param start - Starting world position
+     * @param end - Ending world position
+     * @param options - Optional configuration for the measurement
+     */
+    addMeasurement(start: THREE.Vector3, end: THREE.Vector3, options?: MeasurementCreationOptions): Measurement;
+    private resolveMeasurementOptions;
+    private getActiveMeasurementOptions;
+    /**
+     * @deprecated Use addMeasurement(obj1, obj2, { startLocalPos, endLocalPos }) instead
+     * Add a dynamic measurement between two objects
+     */
+    addDynamicMeasurement(startObject: THREE.Object3D, endObject: THREE.Object3D, startLocalPos?: THREE.Vector3, endLocalPos?: THREE.Vector3): Measurement;
+    /**
+     * @deprecated Use addMeasurement(staticPos, targetObject, { endLocalPos }) instead
+     * Add a measurement from a static point to a dynamic object
+     */
+    addMeasurementToObject(staticPos: THREE.Vector3, targetObject: THREE.Object3D, objectLocalPos?: THREE.Vector3): Measurement;
+    /**
+     * Core method to add a measurement from two measurement points
+     */
+    private addMeasurementFromPoints;
+    /**
+     * Update all dynamic measurements in real-time
+     * Call this in your animation loop to keep dynamic measurements up-to-date
+     */
+    updateDynamicMeasurements(): boolean;
+    /**
+     * Set whether interactive measurements should be dynamic or static
+     */
+    setDynamicMode(enabled: boolean): void;
+    /**
+     * Get the current dynamic mode state
+     */
+    getDynamicMode(): boolean;
+    /**
+     * Enter edit mode for a specific measurement
+     * Shows edit sprites at the measurement endpoints
+     * @param measurementIdOrIndex - The measurement ID or index
+     * @param targets - Optional target objects for snapping during edit
+     */
+    enterEditMode(measurementIdOrIndex: string | number, targets?: THREE.Object3D[]): void;
+    /**
+     * Exit edit mode
+     */
+    exitEditMode(): void;
+    /**
+     * Set the DOM element for interactions (both measurement and edit mode)
+     */
+    setDomElement(domElement: HTMLElement): void;
+    /**
+     * Set the camera controls to disable during edit dragging
+     */
+    setControls(controls: {
+        enabled: boolean;
+    }): void;
+    /**
+     * Set target objects for snapping (used in both interactive mode and edit mode)
+     */
+    setTargetObjects(targets: THREE.Object3D[]): void;
+    /**
+     * Update default measurement options used when none are provided explicitly.
+     */
+    setDefaultMeasurementOptions(options: Partial<MeasurementCreationOptions>): void;
+    /**
+     * Disable camera controls (used during edit dragging)
+     */
+    private disableControls;
+    /**
+     * Enable camera controls (used after edit dragging)
+     */
+    private enableControls;
+    /**
+     * Enable interactive measurement mode
+     */
+    enableInteraction(options?: MeasurementCreationOptions): void;
+    /**
+     * Disable interactive measurement mode
+     */
+    disableInteraction(): void;
+    /**
+     * Remove the last measurement (undo)
+     */
+    undoLast(): void;
+    /**
+     * Remove a specific measurement
+     */
+    removeMeasurement(measurement: Measurement): void;
+    /**
+     * Clear all measurements
+     */
+    clearAll(): void;
+    /**
+     * Get all measurements
+     */
+    getMeasurements(): Measurement[];
+    /**
+     * Convert a MeasurementPoint to serializable data
+     */
+    private serializeMeasurementPoint;
+    /**
+     * Serialize measurements to JSON-compatible format
+     * Note: Dynamic measurements will lose their object references and become static when deserialized
+     */
+    serialize(): MeasurementData[];
+    /**
+     * Deserialize measurements from JSON data
+     * Note: Dynamic measurements become static since object references are lost
+     */
+    deserialize(data: MeasurementData[]): void;
+    /**
+     * Dispose of all resources
+     */
+    dispose(): void;
+    private onMouseClick;
+    private onMouseMove;
+    private onKeyDown;
+    private hideCursor;
+    private showCursor;
+    private createSnapMarker;
+    private updateSnapMarker;
+    private hideSnapMarker;
+    private removeSnapMarker;
+    private startMeasurement;
+    private updatePreview;
+    private completeMeasurement;
+    private cancelCurrentMeasurement;
+    private cleanupPreview;
+    private getSnapResult;
+    private performSnapping;
+    private snapToVertex;
+    private createLabel;
+    private updateLabelText;
+    private removeMeasurementFromScene;
+    private getAllMeshes;
+    private generateId;
+    private createEditSprites;
+    private removeEditSprites;
+    private onEditMouseDown;
+    private onEditMouseMove;
+    private onEditMouseUp;
+    private cancelEdit;
+    private updateMeasurementPreview;
+}
+
+export { type Measurement, type MeasurementData, type MeasurementPoint, type MeasurementPointData, MeasurementTool, type MeasurementToolEvents, type MeasurementToolOptions, SnapMode, type SnapResult };

package/dist/measurements/index.mjs

@@ -0,0 +1,9 @@
+import {
+  MeasurementTool,
+  SnapMode
+} from "../chunk-5DP6WDB3.mjs";
+export {
+  MeasurementTool,
+  SnapMode
+};
+//# sourceMappingURL=index.mjs.map

package/dist/measurements/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}