three-low-poly 0.9.14 → 0.9.15

package/dist/index.d.ts

@@ -5,8 +5,13 @@ import { Color } from 'three';
 import { DataTexture } from 'three';
 import { Group } from 'three';
 import { InstancedMesh } from 'three';
+import { Light } from 'three';
 import { Material } from 'three';
 import { Mesh } from 'three';
+import { MeshLambertMaterial } from 'three';
+import { MeshPhongMaterial } from 'three';
+import { MeshPhysicalMaterial } from 'three';
+import { MeshStandardMaterial } from 'three';
 import { PerspectiveCamera } from 'three';
 import { ShaderMaterial } from 'three';
 import { Shape } from 'three';
@@ -21,10 +26,10 @@ import { Vector3 } from 'three';
  * @param {Object} options - Options for noise modification.
  * @param {number} [options.time=0.0] - The time value for the noise function.
  * @param {number} [options.intensity=1.0] - The intensity of the displacement.
- * @param {Vector3} [options.direction=new Vector3(1, 1, 1)] - The direction of displacement.
+ * @param {Vector3} [options.axis=new Vector3(1, 1, 1)] - The axis of displacement.
  * @param {number} [options.scale=10.0] - The scale of the noise effect.
  */
-export declare function addNoiseDisplacement<T extends Material>(material: T, { time, intensity, direction, scale }?: NoiseDisplacementOptions): void;
+export declare function addNoiseDisplacement<T extends Material>(material: T, { time, intensity, axis, scale }?: NoiseDisplacementOptions): void;
 
 /**
  * Utility function to add water-like vertex displacement to an existing Three.js material.
@@ -139,13 +144,132 @@ export declare class AtmosphericSkybox extends Mesh {
     sunPosition(theta: number, phi: number): void;
 }
 
-export declare class Beaker extends Group {
-    constructor();
-}
-
-export declare class BeakerGeometry extends BufferGeometry {
-    constructor();
-}
+/**
+ * Geometric and mathematical role of the vectors as axes in 3D space.
+ *
+ * Example usages:
+ *
+ * Defining a geometry's up vector:
+ * ```
+ * const upVector = Axis.Z; // Set the Z-axis as the "up" direction
+ * object.up.copy(upVector);
+ * ```
+ *
+ * Rotating or Orienting an Object
+ * ```
+ * const axis = Axis.XY; // Diagonal upward
+ * object.lookAt(object.position.clone().add(axis));
+ * ```
+ *
+ * Rotate around axis:
+ * ```
+ * const angle = Math.PI / 4; // 45-degree rotation
+ * const rotationAxis = Axis.Y; // Rotate around the Y-axis
+ *
+ * object.rotateOnAxis(rotationAxis, angle);
+ * ```
+ *
+ * Scaling along an axis:
+ * ```
+ * const scalingAxis = Axis.XZ; // Scale equally along X and Z
+ * const scaleFactor = 2;
+ *
+ * object.scale.multiply(scalingAxis.clone().multiplyScalar(scaleFactor));
+ * ```
+ *
+ * Aligning a Camera
+ * ```
+ * const cameraAxis = Axis.XZ; // Align the camera diagonally on the XZ plane
+ *
+ * camera.lookAt(camera.position.clone().add(cameraAxis));
+ * ```
+ *
+ * Directional lighting
+ * ```
+ * const lightDirection = Axis.YZ; // Diagonal light along Y and Z axes
+ * directionalLight.position.copy(lightDirection.clone().multiplyScalar(10));
+ * ```
+ *
+ * Aligning an Object
+ * ```
+ * const axis = Axis.X; // Align object to the X-axis
+ * object.lookAt(object.position.clone().add(axis));
+ * ```
+ *
+ * Spawning objects along an axis
+ * ```
+ * const spawnAxis = Axis.XZ; // Arrange objects diagonally on XZ
+ * const count = 10;
+ * const spacing = 5;
+ *
+ * for (let i = 0; i < count; i++) {
+ *   const position = spawnAxis.clone().multiplyScalar(i * spacing);
+ *   const newObject = object.clone();
+ *   newObject.position.copy(position);
+ *   scene.add(newObject);
+ * }
+ * ```
+ *
+ * Vector projections
+ * ```
+ * const vector = new Vector3(3, 5, 7);
+ * const projectionAxis = Axis.Z; // Project the vector onto the Z-axis
+ *
+ * const projection = vector.clone().projectOnVector(projectionAxis);
+ * ```
+ *
+ * Plane definitions
+ * ```
+ * const normal = Axis.Y; // Y-axis is the normal for a horizontal plane
+ * const distanceFromOrigin = 5;
+ *
+ * const plane = new THREE.Plane(normal, distanceFromOrigin);
+ * ```
+ *
+ * Plane intersections
+ * ```
+ * const planeNormal = Axis.Y; // Define a plane normal (horizontal plane)
+ * const plane = new THREE.Plane(planeNormal);
+ *
+ * const rayDirection = Axis.Z; // Ray pointing along Z-axis
+ * const rayOrigin = new Vector3(0, 5, 0);
+ * const ray = new THREE.Ray(rayOrigin, rayDirection);
+ *
+ * // Find intersection point
+ * const intersectionPoint = new Vector3();
+ * plane.intersectLine(new THREE.Line3(rayOrigin, rayOrigin.clone().add(rayDirection)), intersectionPoint);
+ * ```
+ *
+ * Defining bounds
+ * ```
+ * const boundsAxis = Axis.XY; // Restrict an object’s movement within XY bounds
+ * const maxBounds = 10;
+ *
+ * object.position.clamp(
+ *   new Vector3(-maxBounds, -maxBounds, -Infinity),
+ *   new Vector3(maxBounds, maxBounds, Infinity)
+ * );
+ * ```
+ *
+ * Procedural Geometry
+ * ```
+ * const vertex = new Vector3(0, 0, 0);
+ * const axis = Axis.XZ; // Diagonal axis on XZ plane
+ *
+ * const offset = axis.clone().multiplyScalar(5);
+ * vertex.add(offset); // Move vertex in axis
+ * geometry.vertices.push(vertex);
+ * ```
+ */
+export declare const Axis: {
+    X: Vector3;
+    Y: Vector3;
+    Z: Vector3;
+    XY: Vector3;
+    XZ: Vector3;
+    YZ: Vector3;
+    XYZ: Vector3;
+};
 
 export declare class BifurcatedStaircaseGeometry extends BufferGeometry {
     constructor(stepWidth?: number, stepHeight?: number, stepDepth?: number, numStepsCentral?: number, numStepsBranch?: number, branchAngle?: number);
@@ -253,6 +377,20 @@ export declare class BurstShape extends Shape {
     constructor(sides?: number, innerRadius?: number, outerRadius?: number);
 }
 
+/**
+ * Compute normal based on the quad’s vertices (using the cross product of two edges).
+ */
+export declare function calculateNormal(p1: [number, number, number], p2: [number, number, number], p3: [number, number, number]): [number, number, number];
+
+/**
+ * Finding Bounds for a List of UVs
+ * calculate the min and max values dynamically.
+ */
+export declare function calculateUVBounds(uvs: [number, number][]): {
+    minBounds: [number, number];
+    maxBounds: [number, number];
+};
+
 export declare class Candle extends Group {
     private candle;
     private flame;
@@ -418,6 +556,59 @@ export declare const createLogarithmicCurvePoints: (start: Vector2, end: Vector2
  */
 export declare const createParabolicCurvePoints: (start: Vector2, end: Vector2, a: number, b: number, c: number, segments?: number) => Vector2[];
 
+/**
+ * Generates vertices for two triangles based upon a quad.
+ *
+ * Example usages:
+ *
+ * Create a face of a box:
+ * ```
+ * const frontQuad = createQuad(
+ *   [-1, -1,  1], // Bottom-left
+ *   [ 1, -1,  1], // Bottom-right
+ *   [-1,  1,  1], // Top-left
+ *   [ 1,  1,  1], // Top-right
+ *   [ 0,  0,  1]  // Normal (facing forward)
+ * );
+ * ```
+ *
+ * Assembling a box:
+ * ```
+ * const vertices = [
+ *   ...createQuad([-1, -1, 1], [1, -1, 1], [-1, 1, 1], [1, 1, 1], [0, 0, 1]),       // Front face
+ *   ...createQuad([1, -1, -1], [-1, -1, -1], [1, 1, -1], [-1, 1, -1], [0, 0, -1]),  // Back face
+ *   ...createQuad([-1, 1, 1], [1, 1, 1], [-1, 1, -1], [1, 1, -1], [0, 1, 0]),       // Top face
+ *   ...createQuad([-1, -1, -1], [1, -1, -1], [-1, -1, 1], [1, -1, 1], [0, -1, 0]),  // Bottom face
+ *   ...createQuad([-1, -1, -1], [-1, -1, 1], [-1, 1, -1], [-1, 1, 1], [-1, 0, 0]),  // Left face
+ *   ...createQuad([1, -1, 1], [1, -1, -1], [1, 1, 1], [1, 1, -1], [1, 0, 0]),       // Right face
+ * ];
+ * ```
+ *
+ * Generating Buffer Geometry:
+ * ```
+ * const positions = [];
+ * const normals = [];
+ * const uvs = [];
+ *
+ * for (const vertex of vertices) {
+ *   positions.push(...vertex.pos);
+ *   normals.push(...vertex.norm);
+ *   uvs.push(...vertex.uv);
+ * }
+ *
+ * const geometry = new THREE.BufferGeometry();
+ * geometry.setAttribute('position', new THREE.BufferAttribute(new Float32Array(positions), 3));
+ * geometry.setAttribute('normal', new THREE.BufferAttribute(new Float32Array(normals), 3));
+ * geometry.setAttribute('uv', new THREE.BufferAttribute(new Float32Array(uvs), 2));
+ * ```
+ */
+export declare function createQuad(p1: [number, number, number], //
+p2: [number, number, number], p3: [number, number, number], p4: [number, number, number], normal?: [number, number, number], uv1?: [number, number], uv2?: [number, number], uv3?: [number, number], uv4?: [number, number]): {
+    pos: [number, number, number];
+    norm: [number, number, number];
+    uv: [number, number];
+}[];
+
 /**
  * Function to create quadratic Bezier curve points
  *
@@ -474,6 +665,45 @@ export declare const cubicEaseInOut: (t: number) => number;
 
 export declare const cubicEaseOut: (t: number) => number;
 
+/**
+ * Cubic UV Mapping
+ * Applies a texture by projecting UVs along each face of a cube.
+ *
+ * Example usage:
+ * ```
+ * const cubeVertices = [
+ *   [-1, -1, 1],
+ *   [1, -1, 1],
+ *   [-1, 1, 1],
+ *   [1, 1, 1],
+ * ];
+ *
+ * const cubeUVs = cubicUVMappingBatch(cubeVertices);
+ * ```
+ */
+export declare function cubicUVMapping(vertex: [number, number, number]): [number, number];
+
+export declare function cubicUVMappingBatch(vertices: [number, number, number][]): [number, number][];
+
+/**
+ * Cylindrical UV Mapping
+ * Projects UV coordinates onto the surface as though the texture is
+ * wrapped around the cylinder's height and circumference.
+ *
+ * Example usage:
+ * ```
+ * const cylinderVertices = [
+ *   [1, 0, 0],   // Vertex on the "equator"
+ *   [0, 1, 0],   // Vertex on the top
+ *   [0, -1, 1],  // Vertex on the bottom
+ *   [-1, 0, 0],  // Opposite side of the equator
+ * ];
+ *
+ * const cylinderUVs = cylindricalUVMapping(cylinderVertices);
+ * ```
+ */
+export declare function cylindricalUVMapping(vertices: [number, number, number][]): [number, number][];
+
 export declare const dampedCurve: (t: number, damping?: number) => number;
 
 export declare class DaySkybox extends Mesh {
@@ -515,7 +745,13 @@ export declare interface DaySkyUniforms {
     bottomColor: Uniform<Color>;
 }
 
-export declare class Desk extends Group {
+export declare class Desk extends Mesh {
+    geometry: DeskGeometry;
+    material: MeshStandardMaterial[];
+    constructor();
+}
+
+export declare class DeskGeometry extends BufferGeometry {
     constructor();
 }
 
@@ -524,7 +760,9 @@ export declare class DioramaGeometry extends BufferGeometry {
 }
 
 /**
- * Examples
+ * Movement or orientation in a specific direction.
+ *
+ * Example usages:
  *
  * Moving an Object Along a Direction
  * ```
@@ -542,22 +780,6 @@ export declare class DioramaGeometry extends BufferGeometry {
  * object.position.copy(targetPosition.clone().add(snapDirection.clone().multiplyScalar(10)));
  * ```
  *
- * Rotating or Orienting an Object
- * ```
- * const targetDirection = Direction.XY; // Diagonal upward
- * object.lookAt(object.position.clone().add(targetDirection));
- * ```
- *
- * Procedural Geometry
- * ```
- * const vertex = new Vector3(0, 0, 0);
- * const direction = Direction.XZ; // Diagonal direction on XZ plane
- *
- * const offset = direction.clone().multiplyScalar(5);
- * vertex.add(offset); // Move vertex in direction
- * geometry.vertices.push(vertex);
- * ```
- *
  * Animating Along a Direction
  * ```
  * const distance = 10; // Total distance to travel
@@ -610,13 +832,6 @@ export declare const Direction: {
     RIGHT: Vector3;
     FORWARD: Vector3;
     BACKWARD: Vector3;
-    X: Vector3;
-    Y: Vector3;
-    Z: Vector3;
-    XY: Vector3;
-    XZ: Vector3;
-    YZ: Vector3;
-    XYZ: Vector3;
 };
 
 /**
@@ -679,6 +894,45 @@ export declare class EllipticLeafGeometry extends BufferGeometry {
     constructor(size?: number);
 }
 
+/**
+ * Emissive pulse effect, designed for flickering lights.
+ * The emissive intensity of the material will oscillate between `minIntensity` and `maxIntensity`.
+ *
+ * Use with materials that have emissive properties.
+ *
+ * Oscillation time = 2π / speed
+ *  - Low speed values (e.g., 0.5) will result in a slow pulse
+ *  - High speed values (e.g., 10) will result in a rapid flicker
+ *
+ *  Requires `update()` frame handler with `clock.getElapsedTime()` for animation.
+ */
+export declare class EmissivePulseEffect {
+    speed: number;
+    maxIntensity: number;
+    minIntensity: number;
+    material: MeshStandardMaterial | MeshPhysicalMaterial | MeshLambertMaterial | MeshPhongMaterial;
+    constructor(options: EmissivePulseEffectOptions);
+    /**
+     * Update the emissive intensity of the material.
+     *
+     * Use Three.Clock getElapsedTime()
+     *
+     * Example:
+     * ```
+     * const clock = new THREE.Clock();
+     * effect.update(clock.getElapsedTime());
+     * ```
+     */
+    update(elapsedTime?: number): void;
+}
+
+export declare interface EmissivePulseEffectOptions {
+    speed?: number;
+    maxIntensity?: number;
+    minIntensity?: number;
+    material: MeshStandardMaterial | MeshPhysicalMaterial | MeshLambertMaterial | MeshPhongMaterial;
+}
+
 export declare class ErlenmeyerFlask extends Mesh {
     constructor({ flaskRadius, //
         neckRadius, height, neckHeight, radialSegments, }?: {
@@ -759,6 +1013,16 @@ export declare class Flask extends Group {
  */
 export declare const flattenBrush: <T extends BufferGeometry>(geometry: T, position: Vector3, radius: number, targetHeight: number, strength: number, direction?: Vector3, falloffFn?: (distance: number, radius: number) => number) => void;
 
+export declare class FlorenceFlask extends Mesh {
+    geometry: FlorenceFlaskGeometry;
+    material: MeshPhysicalMaterial;
+    constructor();
+}
+
+export declare class FlorenceFlaskGeometry extends BufferGeometry {
+    constructor();
+}
+
 /**
  * The camera flies through a sequence of points, ideal for showcasing specific elements in the scene.
  *
@@ -865,6 +1129,41 @@ export declare class LeverPanel extends Group {
     constructor();
 }
 
+/**
+ * A lightning effect that can be used to simulate a lightning storm.
+ * This effect is applied to a light source.
+ *
+ * Example usage:
+ * ```
+ * const lightning = new THREE.DirectionalLight(0xffffff, 0);
+ * scene.add(lightning);
+ * lightning.position.set(5, 10, -5);
+ *
+ * setRandomInterval(() => {
+ *   lightningEffect.triggerLightning();
+ * }, 250, 1250);
+ * ```
+ */
+export declare class LightningEffect {
+    private light?;
+    minIntensity: number;
+    maxIntensity: number;
+    minDuration: number;
+    maxDuration: number;
+    constructor({ light, //
+        minIntensity, maxIntensity, minDuration, maxDuration, }?: LightningEffectOptions);
+    triggerLightning(): void;
+    update(): void;
+}
+
+declare interface LightningEffectOptions {
+    light?: Light;
+    minIntensity?: number;
+    maxIntensity?: number;
+    minDuration?: number;
+    maxDuration?: number;
+}
+
 export declare const linear: (t: number) => number;
 
 export declare const logarithmic: (t: number) => number;
@@ -1036,10 +1335,35 @@ export declare const noiseBrush: <T extends BufferGeometry>(geometry: T, positio
 declare interface NoiseDisplacementOptions {
     time?: number;
     intensity?: number;
-    direction?: Vector3;
+    axis?: Vector3;
     scale?: number;
 }
 
+/**
+ * Generic Normalization Function
+ * This function will normalize 2D UV coordinates based on given bounds.
+ *
+ * Full pipeline:
+ * - Compute UVs
+ * - Calculate bounds
+ * - Normalize UVs
+ *
+ * Example usage:
+ * ```
+ * const planarMapping = (vertex: [number, number, number]) => [vertex[0], vertex[1]];
+ * const uvs = vertices.map(mappingFunction);
+ * const { minBounds, maxBounds } = calculateUVBounds(uvs);
+ * const normalizedUVs = normalizeUVBatch(uvs, minBounds, maxBounds);
+ * ```
+ */
+export declare function normalizeUV(uv: [number, number], minU: number, maxU: number, minV: number, maxV: number): [number, number];
+
+/**
+ * Batch Normalization for Multiple UVs
+ * If you have multiple UVs, normalize them all based on the overall min/max bounds.
+ */
+export declare function normalizeUVBatch(uvs: [number, number][], minBounds: [number, number], maxBounds: [number, number]): [number, number][];
+
 export declare class ObeliskHeadstone extends Mesh {
     constructor({ totalHeight, baseWidth }?: ObeliskHeadstoneOptions);
 }
@@ -1065,6 +1389,40 @@ declare interface ObeliskHeadstoneOptions {
  */
 export declare function orbitAnimation(camera: Camera, target: Vector3, radius: number, duration: number, onComplete?: () => void): void;
 
+/**
+ * Prefab for a panel.
+ * Designed to be used as a control panel for switches, lights, levels, dials, and gauges.
+ */
+export declare class Panel extends Mesh {
+    geometry: BoxGeometry;
+    material: MeshStandardMaterial;
+    constructor({ width, height, depth }?: PanelOptions);
+}
+
+/**
+ * Prefab for a panel light.
+ * Designed to appear as a LED light
+ */
+export declare class PanelLight extends Mesh {
+    geometry: SphereGeometry;
+    material: MeshStandardMaterial;
+    constructor({ radius, //
+        color, emissive, emissiveIntensity, }?: PanelLightOptions);
+}
+
+export declare interface PanelLightOptions {
+    radius?: number;
+    color?: number;
+    emissive?: number;
+    emissiveIntensity?: number;
+}
+
+export declare interface PanelOptions {
+    width?: number;
+    height?: number;
+    depth?: number;
+}
+
 export declare const parabolicCurve: (t: number, a?: number, b?: number, c?: number) => number;
 
 export declare const ParametricCurve: {
@@ -1100,6 +1458,40 @@ export declare const ParametricCurveUtils: {
  */
 export declare function pendulumAnimation(camera: Camera, center: Vector3, radius: number, duration: number, oscillations: number, onComplete?: () => void): void;
 
+/**
+ * Planar UV Mapping
+ * Projects UVs onto the geometry from a single direction (like shining a projector onto a surface).
+ *
+ * Example:
+ * ```
+ * const vertices = [
+ *   [-1, -1, 1],
+ *   [1, -1, 1],
+ *   [-1, 1, 1],
+ *   [1, 1, 1],
+ * ];
+ *
+ * const uvs = planarUVMapping(vertices, 'z'); // Project onto the Z-axis
+ */
+export declare function planarUVMapping(vertices: [number, number, number][], axis: 'x' | 'y' | 'z'): [number, number][];
+
+/**
+ * Polar UV Mapping
+ * Map textures onto circular or radial geometries, such as discs or dome-like structures.
+ * Maps the radial distance from the center of the geometry to the v coordinate
+ * and the angular position to the u coordinate.
+ *
+ * const discVertices = [
+ *   [1, 0, 0],   // Vertex at (1, 0, 0)
+ *   [0, 0, 1],   // Vertex at (0, 0, 1)
+ *   [-1, 0, 0],  // Vertex at (-1, 0, 0)
+ *   [0, 0, -1],  // Vertex at (0, 0, -1)
+ * ];
+ *
+ * const polarUVs = polarUVMapping(discVertices);
+ */
+export declare function polarUVMapping(vertices: [number, number, number][]): [number, number][];
+
 export declare const quadraticCurve: (t: number, p0: number, p1: number, p2: number) => number;
 
 export declare const quadraticEaseIn: (t: number) => number;
@@ -1142,7 +1534,7 @@ export declare function randomFloat(min?: number, max?: number): number;
  */
 export declare function randomInteger(min?: number, max?: number): number;
 
-export declare function randomTransformVertices<T extends BufferGeometry>(geometry: T, direction?: Vector3, minScale?: number, maxScale?: number): T;
+export declare function randomTransformVertices<T extends BufferGeometry>(geometry: T, axis?: Vector3, minScale?: number, maxScale?: number): T;
 
 export declare class Rock extends Mesh {
     constructor(radius?: number, widthSegments?: number, heightSegments?: number);
@@ -1198,6 +1590,30 @@ declare interface RowOfBooksOptions<T extends Material = Material> {
     scaleZMax?: number;
 }
 
+/**
+ * Set a random interval that will call the callback function with a random delay between minDelay and maxDelay.
+ *
+ * Example usage:
+ * ```
+ * const clearRandomInterval = setRandomInterval(() => {
+ *   console.log('Random interval executed!');
+ * }, 500, 1500); // Random delay between 500ms and 1500ms
+ * ```
+ */
+export declare function setRandomInterval(callback: () => void, minDelay: number, maxDelay: number): () => void;
+
+/**
+ * Set a random timeout that will call the callback function with a random delay between minDelay and maxDelay.
+ *
+ * Example usage:
+ * ```
+ * setRandomTimeout(() => {
+ *   console.log(`Callback ${i} executed!`);
+ * }, 100, 500); // Random timeout between 100ms and 500ms
+ * ```
+ */
+export declare function setRandomTimeout(callback: () => void, minDelay: number, maxDelay: number): NodeJS.Timeout;
+
 export declare const sigmoidCurve: (t: number, a?: number) => number;
 
 export declare const sineEaseIn: (t: number) => number;
@@ -1226,6 +1642,23 @@ export declare const sphericalToCartesian: (radius: number, theta: number, phi:
     z: number;
 };
 
+/**
+ * Spherical UV Mapping
+ * Wraps UVs around the geometry as if the texture were projected from a globe.
+ *
+ * Example usage:
+ * ```
+ * const sphereVertices = [
+ *   [1, 0, 0],
+ *   [0, 1, 0],
+ *   [0, 0, 1],
+ * ];
+ *
+ * const sphereUVs = sphericalUVMapping(sphereVertices);
+ * ```
+ */
+export declare function sphericalUVMapping(vertices: [number, number, number][]): [number, number][];
+
 /**
  * Creates spikes or depressions centered on the target position, pushing vertices away or pulling them towards the center.
  */
@@ -1266,6 +1699,8 @@ export declare class StaircaseGeometry extends BufferGeometry {
 }
 
 export declare class Stand extends Mesh {
+    geometry: StandGeometry;
+    material: MeshStandardMaterial;
     constructor({ radius, //
         height, count, thickness, radialSegments, }?: {
         radius?: number | undefined;