@tonybfox/threejs-tools 1.0.4 → 1.0.5

package/dist/index.d.mts

@@ -3,11 +3,179 @@ export { CameraMode, DualCameraControls, DualCameraControlsOptions, ExternalCame
 export { CompassOverlay, CompassOverlayEvent, CompassOverlayOptions } from './compass/index.mjs';
 export { InfiniteGrid } from './grid/index.mjs';
 export { Measurement, MeasurementData, MeasurementPoint, MeasurementPointData, MeasurementTool, MeasurementToolEvents, MeasurementToolOptions, SnapMode, SnapResult } from './measurements/index.mjs';
+import * as THREE from 'three';
 export { SunLightState, SunLightTool, SunLightToolEvents, SunLightToolOptions, SunLightWeather } from './sunlight/index.mjs';
 export { ElevationPoint, GeoCoordinates, TerrainData, TerrainDimensions, TerrainTool, TerrainToolEvents, TerrainToolOptions } from './terrain/index.mjs';
 export { TransformControls, TransformControlsGizmo, TransformControlsPlane, calculateBoundingBoxCenter } from './transform-controls/index.mjs';
 export { ViewHelper, ViewHelperCameraController, ViewHelperEvent, ViewHelperOptions } from './view-helper/index.mjs';
-import 'three';
 import 'camera-controls';
 import 'three/examples/jsm/renderers/CSS2DRenderer';
 import 'three/examples/jsm/renderers/CSS2DRenderer.js';
+
+/**
+ * Configuration options for the OutlineTool
+ */
+interface OutlineOptions {
+    /**
+     * Color of the outline (hex)
+     * @default 0xff0000
+     */
+    outlineColor?: number;
+    /**
+     * Thickness of edge lines in pixels (for both modes)
+     * @default 2
+     */
+    edgeLineWidth?: number;
+    /**
+     * Color of edge lines (hex) - only for 'mesh' mode
+     * @default 0xff0000
+     */
+    edgeLineColor?: number;
+    /**
+     * Angle threshold for edge detection (degrees) - only for 'mesh' mode
+     * Higher values = fewer edges detected
+     * @default 30
+     */
+    edgeThreshold?: number;
+    /**
+     * Scale multiplier for silhouette outline - only for 'mesh' mode
+     * @default 1.02
+     */
+    outlineScale?: number;
+    /**
+     * Enable silhouette outline (inverted hull) - only for 'mesh' mode
+     * @default true
+     */
+    enableSilhouette?: boolean;
+    /**
+     * Enable edge lines - only for 'mesh' mode
+     * @default true
+     */
+    enableEdgeLines?: boolean;
+    /**
+     * Edge strength for postprocess mode (0-1)
+     * @default 1.0
+     */
+    edgeStrength?: number;
+    /**
+     * Custom exclusion function to filter objects
+     * Return true to exclude an object from outlining
+     */
+    excludeFilter?: (object: THREE.Object3D) => boolean;
+}
+/**
+ * Internal data structure for tracking outlined objects
+ */
+interface OutlineData {
+    originalObject: THREE.Object3D;
+    silhouetteMesh?: THREE.Mesh;
+    edgeLines?: any;
+    parent: THREE.Object3D;
+    idColor?: THREE.Color;
+}
+
+/**
+ * OutlineTool - Add outlines and edge lines to Three.js objects
+ *
+ * Features:
+ * - Two rendering modes: mesh-based and post-processing
+ * - Silhouette outlines using inverted hull technique
+ * - Edge lines for geometry visualization
+ * - Automatic updates when objects move/animate
+ * - Exclusion filters for specific object types
+ *
+ * @example
+ * ```typescript
+ * const outlineTool = new OutlineTool(renderer, {
+ *   outlineColor: 0xff0000,
+ *   edgeLineWidth: 2,
+ * })
+ *
+ * outlineTool.addObjects([mesh1, mesh2, mesh3])
+ * ```
+ */
+declare class OutlineTool {
+    private options;
+    private outlineData;
+    private lineMaterial;
+    private renderer;
+    private composer;
+    private idRenderTarget;
+    private idMaterial;
+    /**
+     * Default exclusion filter
+     * Excludes Line2, LineSegments2, helpers, and gizmos
+     */
+    private static defaultExcludeFilter;
+    constructor(renderer: THREE.WebGLRenderer, options?: OutlineOptions);
+    private handleResize;
+    /**
+     * Add objects to be outlined
+     * @param objects - Array of Three.js objects to outline
+     */
+    addObjects(objects: THREE.Object3D[]): void;
+    /**
+     * Add a single object to be outlined
+     * @param object - Three.js object to outline
+     */
+    addObject(object: THREE.Object3D): void;
+    /**
+     * Remove objects from outlining
+     * @param objects - Array of objects to remove outlines from
+     */
+    removeObjects(objects: THREE.Object3D[]): void;
+    /**
+     * Remove a single object's outlines
+     * @param object - Object to remove outlines from
+     */
+    removeObject(object: THREE.Object3D): void;
+    /**
+     * Clear all outlines
+     */
+    clearAll(): void;
+    /**
+     * Update outlines to match current object transforms
+     * Call this in your animation loop (for mesh mode only)
+     */
+    update(): void;
+    /**
+     * Render with outlines (for postprocess mode)
+     * Call this instead of renderer.render() when using postprocess mode
+     */
+    render(scene: THREE.Scene, camera: THREE.Camera): void;
+    /**
+     * Render the ID buffer for edge detection
+     */
+    private renderIdBuffer;
+    /**
+     * Update outline options
+     * @param options - Partial options to update
+     */
+    setOptions(options: Partial<OutlineOptions>): void;
+    /**
+     * Create silhouette outline mesh
+     */
+    private createSilhouette;
+    /**
+     * Create edge lines
+     */
+    private createEdgeLines;
+    /**
+     * Type guard for THREE.Mesh
+     */
+    private isMesh;
+    /**
+     * Dispose mesh and its resources
+     */
+    private disposeMesh;
+    /**
+     * Dispose LineSegments2 and its resources
+     */
+    private disposeLineSegments;
+    /**
+     * Cleanup and dispose resources
+     */
+    dispose(): void;
+}
+
+export { type OutlineData, type OutlineOptions, OutlineTool };

package/dist/index.d.ts

@@ -3,11 +3,179 @@ export { CameraMode, DualCameraControls, DualCameraControlsOptions, ExternalCame
 export { CompassOverlay, CompassOverlayEvent, CompassOverlayOptions } from './compass/index.js';
 export { InfiniteGrid } from './grid/index.js';
 export { Measurement, MeasurementData, MeasurementPoint, MeasurementPointData, MeasurementTool, MeasurementToolEvents, MeasurementToolOptions, SnapMode, SnapResult } from './measurements/index.js';
+import * as THREE from 'three';
 export { SunLightState, SunLightTool, SunLightToolEvents, SunLightToolOptions, SunLightWeather } from './sunlight/index.js';
 export { ElevationPoint, GeoCoordinates, TerrainData, TerrainDimensions, TerrainTool, TerrainToolEvents, TerrainToolOptions } from './terrain/index.js';
 export { TransformControls, TransformControlsGizmo, TransformControlsPlane, calculateBoundingBoxCenter } from './transform-controls/index.js';
 export { ViewHelper, ViewHelperCameraController, ViewHelperEvent, ViewHelperOptions } from './view-helper/index.js';
-import 'three';
 import 'camera-controls';
 import 'three/examples/jsm/renderers/CSS2DRenderer';
 import 'three/examples/jsm/renderers/CSS2DRenderer.js';
+
+/**
+ * Configuration options for the OutlineTool
+ */
+interface OutlineOptions {
+    /**
+     * Color of the outline (hex)
+     * @default 0xff0000
+     */
+    outlineColor?: number;
+    /**
+     * Thickness of edge lines in pixels (for both modes)
+     * @default 2
+     */
+    edgeLineWidth?: number;
+    /**
+     * Color of edge lines (hex) - only for 'mesh' mode
+     * @default 0xff0000
+     */
+    edgeLineColor?: number;
+    /**
+     * Angle threshold for edge detection (degrees) - only for 'mesh' mode
+     * Higher values = fewer edges detected
+     * @default 30
+     */
+    edgeThreshold?: number;
+    /**
+     * Scale multiplier for silhouette outline - only for 'mesh' mode
+     * @default 1.02
+     */
+    outlineScale?: number;
+    /**
+     * Enable silhouette outline (inverted hull) - only for 'mesh' mode
+     * @default true
+     */
+    enableSilhouette?: boolean;
+    /**
+     * Enable edge lines - only for 'mesh' mode
+     * @default true
+     */
+    enableEdgeLines?: boolean;
+    /**
+     * Edge strength for postprocess mode (0-1)
+     * @default 1.0
+     */
+    edgeStrength?: number;
+    /**
+     * Custom exclusion function to filter objects
+     * Return true to exclude an object from outlining
+     */
+    excludeFilter?: (object: THREE.Object3D) => boolean;
+}
+/**
+ * Internal data structure for tracking outlined objects
+ */
+interface OutlineData {
+    originalObject: THREE.Object3D;
+    silhouetteMesh?: THREE.Mesh;
+    edgeLines?: any;
+    parent: THREE.Object3D;
+    idColor?: THREE.Color;
+}
+
+/**
+ * OutlineTool - Add outlines and edge lines to Three.js objects
+ *
+ * Features:
+ * - Two rendering modes: mesh-based and post-processing
+ * - Silhouette outlines using inverted hull technique
+ * - Edge lines for geometry visualization
+ * - Automatic updates when objects move/animate
+ * - Exclusion filters for specific object types
+ *
+ * @example
+ * ```typescript
+ * const outlineTool = new OutlineTool(renderer, {
+ *   outlineColor: 0xff0000,
+ *   edgeLineWidth: 2,
+ * })
+ *
+ * outlineTool.addObjects([mesh1, mesh2, mesh3])
+ * ```
+ */
+declare class OutlineTool {
+    private options;
+    private outlineData;
+    private lineMaterial;
+    private renderer;
+    private composer;
+    private idRenderTarget;
+    private idMaterial;
+    /**
+     * Default exclusion filter
+     * Excludes Line2, LineSegments2, helpers, and gizmos
+     */
+    private static defaultExcludeFilter;
+    constructor(renderer: THREE.WebGLRenderer, options?: OutlineOptions);
+    private handleResize;
+    /**
+     * Add objects to be outlined
+     * @param objects - Array of Three.js objects to outline
+     */
+    addObjects(objects: THREE.Object3D[]): void;
+    /**
+     * Add a single object to be outlined
+     * @param object - Three.js object to outline
+     */
+    addObject(object: THREE.Object3D): void;
+    /**
+     * Remove objects from outlining
+     * @param objects - Array of objects to remove outlines from
+     */
+    removeObjects(objects: THREE.Object3D[]): void;
+    /**
+     * Remove a single object's outlines
+     * @param object - Object to remove outlines from
+     */
+    removeObject(object: THREE.Object3D): void;
+    /**
+     * Clear all outlines
+     */
+    clearAll(): void;
+    /**
+     * Update outlines to match current object transforms
+     * Call this in your animation loop (for mesh mode only)
+     */
+    update(): void;
+    /**
+     * Render with outlines (for postprocess mode)
+     * Call this instead of renderer.render() when using postprocess mode
+     */
+    render(scene: THREE.Scene, camera: THREE.Camera): void;
+    /**
+     * Render the ID buffer for edge detection
+     */
+    private renderIdBuffer;
+    /**
+     * Update outline options
+     * @param options - Partial options to update
+     */
+    setOptions(options: Partial<OutlineOptions>): void;
+    /**
+     * Create silhouette outline mesh
+     */
+    private createSilhouette;
+    /**
+     * Create edge lines
+     */
+    private createEdgeLines;
+    /**
+     * Type guard for THREE.Mesh
+     */
+    private isMesh;
+    /**
+     * Dispose mesh and its resources
+     */
+    private disposeMesh;
+    /**
+     * Dispose LineSegments2 and its resources
+     */
+    private disposeLineSegments;
+    /**
+     * Cleanup and dispose resources
+     */
+    dispose(): void;
+}
+
+export { type OutlineData, type OutlineOptions, OutlineTool };

package/dist/index.mjs

@@ -9,7 +9,7 @@ import {
 } from "./chunk-IAZH4OHC.mjs";
 import {
   AssetLoader
-} from "./chunk-27WUVRGX.mjs";
+} from "./chunk-LUE7VHLK.mjs";
 import {
   DualCameraControls
 } from "./chunk-XA7OKYSM.mjs";
@@ -29,12 +29,350 @@ import {
 import {
   TerrainTool
 } from "./chunk-FBTT6MU6.mjs";
+
+// packages/outline/src/OutlineTool.ts
+import * as THREE from "three";
+import { LineSegments2 } from "three/examples/jsm/lines/LineSegments2.js";
+import { LineSegmentsGeometry } from "three/examples/jsm/lines/LineSegmentsGeometry.js";
+import { LineMaterial } from "three/examples/jsm/lines/LineMaterial.js";
+var _OutlineTool = class _OutlineTool {
+  constructor(renderer, options = {}) {
+    this.outlineData = /* @__PURE__ */ new Map();
+    this.lineMaterial = null;
+    this.composer = null;
+    this.idRenderTarget = null;
+    this.idMaterial = null;
+    this.handleResize = () => {
+      const size = this.renderer.getSize(new THREE.Vector2());
+      if (this.lineMaterial) {
+        this.lineMaterial.resolution.set(size.width, size.height);
+      }
+      if (this.idRenderTarget) {
+        this.idRenderTarget.setSize(size.width, size.height);
+      }
+      if (this.composer) {
+        this.composer.setSize(size.width, size.height);
+      }
+    };
+    this.renderer = renderer;
+    this.options = {
+      outlineColor: options.outlineColor ?? 16711680,
+      edgeLineWidth: options.edgeLineWidth ?? 2,
+      edgeLineColor: options.edgeLineColor ?? 16711680,
+      edgeThreshold: options.edgeThreshold ?? 30,
+      outlineScale: options.outlineScale ?? 1.02,
+      enableSilhouette: options.enableSilhouette ?? true,
+      enableEdgeLines: options.enableEdgeLines ?? true,
+      edgeStrength: options.edgeStrength ?? 1,
+      excludeFilter: options.excludeFilter ?? _OutlineTool.defaultExcludeFilter
+    };
+    const size = renderer.getSize(new THREE.Vector2());
+    this.lineMaterial = new LineMaterial({
+      color: this.options.edgeLineColor,
+      linewidth: this.options.edgeLineWidth,
+      resolution: new THREE.Vector2(size.width, size.height)
+    });
+    window.addEventListener("resize", this.handleResize);
+  }
+  /**
+   * Add objects to be outlined
+   * @param objects - Array of Three.js objects to outline
+   */
+  addObjects(objects) {
+    objects.forEach((obj) => this.addObject(obj));
+  }
+  /**
+   * Add a single object to be outlined
+   * @param object - Three.js object to outline
+   */
+  addObject(object) {
+    const uuid = object.uuid;
+    if (this.outlineData.has(uuid)) {
+      console.warn(`Object ${object.name || uuid} is already outlined`);
+      return;
+    }
+    const outlines = [];
+    object.traverse((child) => {
+      if (!this.isMesh(child) || this.options.excludeFilter(child)) {
+        return;
+      }
+      const mesh = child;
+      const data = {
+        originalObject: mesh,
+        parent: mesh.parent
+      };
+      if (this.options.enableSilhouette) {
+        data.silhouetteMesh = this.createSilhouette(mesh);
+        mesh.parent.add(data.silhouetteMesh);
+      }
+      if (this.options.enableEdgeLines) {
+        data.edgeLines = this.createEdgeLines(mesh);
+        mesh.parent.add(data.edgeLines);
+      }
+      outlines.push(data);
+    });
+    if (outlines.length > 0) {
+      this.outlineData.set(uuid, outlines);
+    }
+  }
+  /**
+   * Remove objects from outlining
+   * @param objects - Array of objects to remove outlines from
+   */
+  removeObjects(objects) {
+    objects.forEach((obj) => this.removeObject(obj));
+  }
+  /**
+   * Remove a single object's outlines
+   * @param object - Object to remove outlines from
+   */
+  removeObject(object) {
+    const uuid = object.uuid;
+    const outlines = this.outlineData.get(uuid);
+    if (!outlines) {
+      return;
+    }
+    outlines.forEach((data) => {
+      if (data.silhouetteMesh) {
+        data.parent.remove(data.silhouetteMesh);
+        this.disposeMesh(data.silhouetteMesh);
+      }
+      if (data.edgeLines) {
+        data.parent.remove(data.edgeLines);
+        this.disposeLineSegments(data.edgeLines);
+      }
+      if (data.originalObject.userData.outlineIdColor) {
+        delete data.originalObject.userData.outlineIdColor;
+      }
+    });
+    this.outlineData.delete(uuid);
+  }
+  /**
+   * Clear all outlines
+   */
+  clearAll() {
+    const objects = Array.from(this.outlineData.keys());
+    objects.forEach((uuid) => {
+      const outlines = this.outlineData.get(uuid);
+      if (outlines && outlines.length > 0) {
+        this.removeObject(outlines[0].originalObject.parent);
+      }
+    });
+  }
+  /**
+   * Update outlines to match current object transforms
+   * Call this in your animation loop (for mesh mode only)
+   */
+  update() {
+    this.outlineData.forEach((outlines) => {
+      outlines.forEach((data) => {
+        const mesh = data.originalObject;
+        if (data.silhouetteMesh) {
+          data.silhouetteMesh.position.copy(mesh.position);
+          data.silhouetteMesh.rotation.copy(mesh.rotation);
+          data.silhouetteMesh.quaternion.copy(mesh.quaternion);
+          data.silhouetteMesh.scale.copy(mesh.scale);
+          data.silhouetteMesh.scale.multiplyScalar(this.options.outlineScale);
+        }
+        if (data.edgeLines) {
+          data.edgeLines.position.copy(mesh.position);
+          data.edgeLines.rotation.copy(mesh.rotation);
+          data.edgeLines.quaternion.copy(mesh.quaternion);
+          data.edgeLines.scale.copy(mesh.scale);
+        }
+      });
+    });
+  }
+  /**
+   * Render with outlines (for postprocess mode)
+   * Call this instead of renderer.render() when using postprocess mode
+   */
+  render(scene, camera) {
+    this.renderIdBuffer(scene, camera);
+    this.composer.render();
+  }
+  /**
+   * Render the ID buffer for edge detection
+   */
+  renderIdBuffer(scene, camera) {
+    if (!this.idRenderTarget || !this.idMaterial) {
+      return;
+    }
+    const oldRT = this.renderer.getRenderTarget();
+    const oldOverride = scene.overrideMaterial;
+    const visibilityMap = /* @__PURE__ */ new Map();
+    scene.traverse((obj) => {
+      visibilityMap.set(obj, obj.visible);
+      if (this.isMesh(obj) && !obj.userData.outlineIdColor) {
+        obj.visible = false;
+      }
+    });
+    scene.overrideMaterial = this.idMaterial;
+    scene.traverse((obj) => {
+      if (!this.isMesh(obj)) return;
+      const mesh = obj;
+      mesh.onBeforeRender = () => {
+        const idColor = mesh.userData.outlineIdColor;
+        if (idColor) {
+          this.idMaterial.color.copy(idColor);
+        }
+      };
+    });
+    this.renderer.setRenderTarget(this.idRenderTarget);
+    this.renderer.clear();
+    this.renderer.render(scene, camera);
+    scene.traverse((obj) => {
+      if (!this.isMesh(obj)) return;
+      obj.onBeforeRender = () => {
+      };
+      const originalVisibility = visibilityMap.get(obj);
+      if (originalVisibility !== void 0) {
+        obj.visible = originalVisibility;
+      }
+    });
+    scene.overrideMaterial = oldOverride;
+    this.renderer.setRenderTarget(oldRT);
+  }
+  /**
+   * Update outline options
+   * @param options - Partial options to update
+   */
+  setOptions(options) {
+    const needsRecreate = options.outlineColor !== void 0 || options.edgeLineColor !== void 0 || options.edgeThreshold !== void 0 || options.enableSilhouette !== void 0 || options.enableEdgeLines !== void 0;
+    Object.assign(this.options, options);
+    if (options.edgeLineWidth !== void 0 && this.lineMaterial) {
+      this.lineMaterial.linewidth = options.edgeLineWidth;
+    }
+    if (options.edgeLineColor !== void 0 && this.lineMaterial) {
+      this.lineMaterial.color.setHex(options.edgeLineColor);
+    }
+    if (needsRecreate) {
+      const objects = [];
+      this.outlineData.forEach((outlines) => {
+        if (outlines.length > 0) {
+          let root = outlines[0].originalObject;
+          while (root.parent && !this.outlineData.has(root.parent.uuid)) {
+            root = root.parent;
+          }
+          objects.push(root);
+        }
+      });
+      this.clearAll();
+      this.addObjects(objects);
+    }
+  }
+  /**
+   * Create silhouette outline mesh
+   */
+  createSilhouette(mesh) {
+    const outlineMesh = mesh.clone();
+    outlineMesh.material = new THREE.MeshBasicMaterial({
+      color: this.options.outlineColor,
+      side: THREE.BackSide
+    });
+    outlineMesh.renderOrder = -1;
+    outlineMesh.scale.multiplyScalar(this.options.outlineScale);
+    outlineMesh.userData.excludeOutline = true;
+    return outlineMesh;
+  }
+  /**
+   * Create edge lines
+   */
+  createEdgeLines(mesh) {
+    if (!this.lineMaterial) {
+      throw new Error("Line material not initialized");
+    }
+    const edges = new THREE.EdgesGeometry(
+      mesh.geometry,
+      this.options.edgeThreshold
+    );
+    const lineGeometry = new LineSegmentsGeometry();
+    const positions = edges.attributes.position.array;
+    lineGeometry.setPositions(positions);
+    const edgeLines = new LineSegments2(lineGeometry, this.lineMaterial);
+    edgeLines.computeLineDistances();
+    edgeLines.scale.copy(mesh.scale);
+    edgeLines.rotation.copy(mesh.rotation);
+    edgeLines.position.copy(mesh.position);
+    edgeLines.userData.excludeOutline = true;
+    edges.dispose();
+    return edgeLines;
+  }
+  /**
+   * Type guard for THREE.Mesh
+   */
+  isMesh(object) {
+    return object.isMesh === true;
+  }
+  /**
+   * Dispose mesh and its resources
+   */
+  disposeMesh(mesh) {
+    if (mesh.geometry) {
+      mesh.geometry.dispose();
+    }
+    if (Array.isArray(mesh.material)) {
+      mesh.material.forEach((mat) => mat.dispose());
+    } else if (mesh.material) {
+      mesh.material.dispose();
+    }
+  }
+  /**
+   * Dispose LineSegments2 and its resources
+   */
+  disposeLineSegments(line) {
+    if (line.geometry) {
+      line.geometry.dispose();
+    }
+  }
+  /**
+   * Cleanup and dispose resources
+   */
+  dispose() {
+    this.clearAll();
+    if (this.lineMaterial) {
+      this.lineMaterial.dispose();
+    }
+    if (this.idRenderTarget) {
+      this.idRenderTarget.dispose();
+    }
+    if (this.idMaterial) {
+      this.idMaterial.dispose();
+    }
+    if (this.composer) {
+      this.composer = null;
+    }
+    window.removeEventListener("resize", this.handleResize);
+  }
+};
+/**
+ * Default exclusion filter
+ * Excludes Line2, LineSegments2, helpers, and gizmos
+ */
+_OutlineTool.defaultExcludeFilter = (object) => {
+  if (object.type === "Line2" || object.type === "LineSegments2") {
+    return true;
+  }
+  if (object.type.includes("Helper")) {
+    return true;
+  }
+  if (object.userData.excludeOutline) {
+    return true;
+  }
+  const name = object.name.toLowerCase();
+  if (name.includes("arrow") || name.includes("gizmo") || name.includes("control")) {
+    return true;
+  }
+  return false;
+};
+var OutlineTool = _OutlineTool;
 export {
   AssetLoader,
   CompassOverlay,
   DualCameraControls,
   InfiniteGrid,
   MeasurementTool,
+  OutlineTool,
   SnapMode,
   SunLightTool,
   TerrainTool,