three-low-poly 0.9.17 → 0.9.18

package/dist/index.d.ts

@@ -45,6 +45,48 @@ export declare function addWaterDisplacement<T extends Material>(material: T, {
     waveAmplitude?: number | undefined;
 }): void;
 
+/**
+ * Generates spherical curve profile points, for use with geometry.
+ * Enables connective geometry via holes at the top and bottom of the sphere.
+ *
+ * Example usage:
+ *
+ * Tube that connect with a sphere on the bottom:
+ * ```
+ *    const points: Vector2[] = [
+ *       new Vector2(1, 0),
+ *       ...appendSphericalCurve(
+ *         2,  // Radius x
+ *         2,  // Radius y
+ *         5,  // Start y
+ *         0,  // Hole top radius
+ *         1,  // Hole bottom radius
+ *         32, // Segments
+ *       ),
+ *     ];
+ *
+ *     const latheGeometry = new LatheGeometry(points, 32);
+ * ```
+ *
+ * Tube that connect with a sphere on the top:
+ * ```
+ *    const points: Vector2[] = [
+ *       ...appendSphericalCurve(
+ *         2,  // Radius x
+ *         2,  // Radius y
+ *         1,  // Start y
+ *         1,  // Hole top radius
+ *         0,  // Hole bottom radius
+ *         32, // Segments
+ *       ),
+ *       new Vector2(1, 5),
+ *     ];
+ *
+ *     const latheGeometry = new LatheGeometry(points, 32);
+ * ```
+ */
+export declare function appendSphericalCurve(sphereRadiusX: number, sphereRadiusY: number, sphereStartY: number, holeTopRadius?: number, holeBottomRadius?: number, segments?: number): Vector2[];
+
 /**
  * Atmospheric scattering shader.
  *
@@ -439,6 +481,100 @@ export declare function calculateXFromSlopeIntercept(x1: number, y1: number, x2:
  */
 export declare function calculateYFromSlopeIntercept(x1: number, y1: number, x2: number, y2: number, x: number): number;
 
+/**
+ * Dolly backward
+ *
+ * Example:
+ * ```
+ * dollyAnimation(camera, 5, 3000, () => {
+ *   console.log("Dolly animation complete");
+ * });
+ * ```
+ */
+export declare function cameraDollyAnimation(camera: Camera, distance: number, duration: number, onComplete?: () => void): void;
+
+/**
+ * The camera flies through a sequence of points, ideal for showcasing specific elements in the scene.
+ *
+ * Example:
+ * ```
+ * flythroughAnimation(
+ *   camera,
+ *   [
+ *     new THREE.Vector3(0, 5, 5),
+ *     new THREE.Vector3(0, 5, -25.5),
+ *     new THREE.Vector3(-20.5, 5, 0),
+ *   ],
+ *   6000,
+ *   () => {
+ *     console.log("Flythrough animation complete");
+ *   }
+ * );
+ * ```
+ */
+export declare function cameraFlythroughAnimation(camera: Camera, waypoints: Vector3[], duration: number, onComplete?: () => void): void;
+
+/**
+ * Orbit around a target
+ *
+ * Example:
+ * ```
+ * orbitAnimation(camera, new THREE.Vector3(0, 0, 0), 10, 5000, () => {
+ *   console.log("Orbit animation complete");
+ * });
+ * ```
+ */
+export declare function cameraOrbitAnimation(camera: Camera, target: Vector3, radius: number, duration: number, onComplete?: () => void): void;
+
+/**
+ * The camera swings back and forth like a pendulum.
+ *
+ * Example:
+ * ```
+ * pendulumAnimation(camera, new THREE.Vector3(0, 5, 5), 0.5, 9000, 3, () => {
+ *   console.log("Pendulum animation complete");
+ * });
+ * ```
+ */
+export declare function cameraPendulumAnimation(camera: Camera, center: Vector3, radius: number, duration: number, oscillations: number, onComplete?: () => void): void;
+
+/**
+ * The camera spirals upward, perfect for revealing a large scene or structure.
+ *
+ * Example:
+ * ```
+ * spiralAscensionAnimation(camera, new THREE.Vector3(0, 0, 0), 10, 300, 7, 12000, () => {
+ *   console.log("Spiral ascension animation complete");
+ * });
+ * ```
+ */
+export declare function cameraSpiralAscensionAnimation(camera: Camera, center: Vector3, radius: number, height: number, revolutions: number, duration: number, onComplete?: () => void): void;
+
+/**
+ * Add a slight random wobble for intensity or realism (e.g., during an explosion).
+ *
+ * Example:
+ * ```
+ * wobbleAnimation(camera, 0.5, 1000, () => {
+ *   console.log("Wobble animation complete");
+ * });
+ * ```
+ */
+export declare function cameraWobbleAnimation(camera: Camera, intensity: number, duration: number, onComplete?: () => void): void;
+
+/**
+ * The camera smoothly zooms in toward a target, focusing attention on a specific point,
+ * and resets to its original FOV after completion.
+ *
+ * Example:
+ * ```
+ * zoomInAnimation(camera, new THREE.Vector3(0, 0, 0), 120, 75, 2000, () => {
+ *   console.log("Zoom in animation complete");
+ * });
+ * ```
+ */
+export declare function cameraZoomInAnimation(camera: PerspectiveCamera, target: Vector3, startFov: number, endFov: number, duration: number, onComplete?: () => void): void;
+
 export declare class Candle extends Group {
     private candle;
     private flame;
@@ -964,18 +1100,6 @@ export declare const Direction: {
  */
 export declare const displacementBrush: <T extends BufferGeometry>(geometry: T, position: Vector3, radius: number, strength: number, direction?: Vector3, falloffFn?: (distance: number, radius: number) => number) => void;
 
-/**
- * Dolly backward
- *
- * Example:
- * ```
- * dollyAnimation(camera, 5, 3000, () => {
- *   console.log("Dolly animation complete");
- * });
- * ```
- */
-export declare function dollyAnimation(camera: Camera, distance: number, duration: number, onComplete?: () => void): void;
-
 /**
  * Easing functions for interpolating values over time.
  */
@@ -1020,18 +1144,26 @@ export declare class EllipticLeafGeometry extends BufferGeometry {
 }
 
 /**
- * Emissive pulse effect, designed for flickering lights.
+ * Emissive pulse animation, producing a flickering light effect for materials that have emissive properties.
  * 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.
+ *
+ *  Example usage:
+ *  ```
+ *  const pulseAnimation = new EmissivePulseAnimation();
+ *  const clock = new THREE.Clock();
+ *
+ *  function animate() {
+ *    pulseAnimation.update(clock.getElapsedTime());
+ *  }
+ *  ```
  */
-export declare class EmissivePulseEffect {
+export declare class EmissivePulseAnimation {
     speed: number;
     maxIntensity: number;
     minIntensity: number;
@@ -1118,10 +1250,6 @@ export declare function findClosestColor(inputColor: number, dataset: number[]):
 
 export declare function findClosestColorChannelWise(inputColor: number, dataset: number[]): number | null;
 
-export declare class Flask extends Group {
-    constructor();
-}
-
 /**
  * Flattens vertices to a given plane defined by a target height or normal direction.
  */
@@ -1135,27 +1263,6 @@ export declare class FlorenceFlaskGeometry extends BufferGeometry {
     constructor();
 }
 
-/**
- * The camera flies through a sequence of points, ideal for showcasing specific elements in the scene.
- *
- * Example:
- * ```
- * flythroughAnimation(
- *   camera,
- *   [
- *     new THREE.Vector3(0, 5, 5),
- *     new THREE.Vector3(0, 5, -25.5),
- *     new THREE.Vector3(-20.5, 5, 0),
- *   ],
- *   6000,
- *   () => {
- *     console.log("Flythrough animation complete");
- *   }
- * );
- * ```
- */
-export declare function flythroughAnimation(camera: Camera, waypoints: Vector3[], duration: number, onComplete?: () => void): void;
-
 export declare const gaussian: (t: number) => number;
 
 export declare class Gear extends Mesh {
@@ -1192,7 +1299,7 @@ export declare function hexToHsl(hex: number): [number, number, number];
  */
 export declare function hexToRgb(hex: number): [number, number, number];
 
-export declare class Hill extends Mesh {
+export declare class Hill extends Mesh<HillGeometry, MeshStandardMaterial> {
     constructor({ radius, //
         height, widthSegments, heightSegments, phiStart, phiLength, }?: {
         radius?: number | undefined;
@@ -1246,6 +1353,24 @@ export declare function interpolateCurve(curveFunction: (t: number) => number, s
 
 export declare const inverse: (t: number) => number;
 
+/**
+ * Material indices
+ * 0. Jar
+ * 1. Cork
+ */
+export declare class Jar extends Mesh<JarGeometry, MeshStandardMaterial[]> {
+    constructor();
+}
+
+/**
+ * Group indices
+ * 0. Jar
+ * 1. Cork
+ */
+export declare class JarGeometry extends BufferGeometry {
+    constructor();
+}
+
 export declare class Lantern extends Group {
     constructor(height?: number, baseWidth?: number);
 }
@@ -1274,7 +1399,7 @@ export declare class LeverPanel extends Group {
 }
 
 /**
- * A lightning effect that can be used to simulate a lightning storm.
+ * A lightning animation that can be used to simulate a lightning storm.
  * This effect is applied to a light source.
  *
  * Example usage:
@@ -1283,12 +1408,14 @@ export declare class LeverPanel extends Group {
  * scene.add(lightning);
  * lightning.position.set(5, 10, -5);
  *
+ * const lightningAnimation = new LightningAnimation();
+ *
  * setRandomInterval(() => {
  *   lightningEffect.triggerLightning();
  * }, 250, 1250);
  * ```
  */
-export declare class LightningEffect {
+export declare class LightningAnimation {
     private light?;
     minIntensity: number;
     maxIntensity: number;
@@ -1401,7 +1528,21 @@ export declare class MortarGeometry extends BufferGeometry {
     constructor();
 }
 
-export declare class MossyRocks extends Group {
+/**
+ * Material indices:
+ * 0. Rocks
+ * 1. Moss
+ */
+export declare class MossyRocks extends Mesh<MossyRocksGeometry, MeshStandardMaterial[]> {
+    constructor();
+}
+
+/**
+ * Group indices:
+ * 0. Rocks
+ * 1. Moss
+ */
+export declare class MossyRocksGeometry extends BufferGeometry {
     constructor();
 }
 
@@ -1422,7 +1563,7 @@ export declare class MossyRocks extends Group {
  * }
  * ```
  */
-export declare class Mound extends Mesh {
+export declare class Mound extends Mesh<MoundGeometry, MeshStandardMaterial> {
     constructor({ radius, //
         widthSegments, heightSegments, phiStart, phiLength, thetaLength, }?: {
         radius?: number | undefined;
@@ -1562,18 +1703,6 @@ declare interface ObeliskHeadstoneOptions {
     totalHeight?: number;
 }
 
-/**
- * Orbit around a target
- *
- * Example:
- * ```
- * orbitAnimation(camera, new THREE.Vector3(0, 0, 0), 10, 5000, () => {
- *   console.log("Orbit animation complete");
- * });
- * ```
- */
-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.
@@ -1636,18 +1765,6 @@ export declare const ParametricCurveUtils: {
  */
 export declare function parseHexCode(hex: string): [number, number, number];
 
-/**
- * The camera swings back and forth like a pendulum.
- *
- * Example:
- * ```
- * pendulumAnimation(camera, new THREE.Vector3(0, 5, 5), 0.5, 9000, 3, () => {
- *   console.log("Pendulum animation complete");
- * });
- * ```
- */
-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).
@@ -1772,7 +1889,11 @@ export declare class RockGeometry extends BufferGeometry {
     constructor(radius?: number, widthSegments?: number, heightSegments?: number);
 }
 
-export declare class Rocks extends Group {
+export declare class Rocks extends Mesh<RocksGeometry, MeshStandardMaterial> {
+    constructor();
+}
+
+export declare class RocksGeometry extends BufferGeometry {
     constructor();
 }
 
@@ -1892,18 +2013,6 @@ export declare function sphericalUVMapping(vertices: [number, number, number][])
  */
 export declare const spikeBrush: <T extends BufferGeometry>(geometry: T, position: Vector3, radius: number, strength: number, inward?: boolean, falloffFn?: (distance: number, radius: number) => number) => void;
 
-/**
- * The camera spirals upward, perfect for revealing a large scene or structure.
- *
- * Example:
- * ```
- * spiralAscensionAnimation(camera, new THREE.Vector3(0, 0, 0), 10, 300, 7, 12000, () => {
- *   console.log("Spiral ascension animation complete");
- * });
- * ```
- */
-export declare function spiralAscensionAnimation(camera: Camera, center: Vector3, radius: number, height: number, revolutions: number, duration: number, onComplete?: () => void): void;
-
 export declare class SpiralStaircaseGeometry extends BufferGeometry {
     constructor(stepWidth?: number, stepDepth?: number, stepHeight?: number, numSteps?: number, radius?: number, angleIncrement?: number);
 }
@@ -1971,7 +2080,21 @@ export declare class StoneFencePostGeometry extends BufferGeometry {
     });
 }
 
-export declare class TeslaCoil extends Group {
+/**
+ * Material indices
+ * 0: Base
+ * 1: Coil
+ */
+export declare class TeslaCoil extends Mesh<TeslaCoilGeometry, MeshStandardMaterial[]> {
+    constructor();
+}
+
+/**
+ * Group indices
+ * 0: Base
+ * 1: Coil
+ */
+export declare class TeslaCoilGeometry extends BufferGeometry {
     constructor();
 }
 
@@ -1987,6 +2110,21 @@ export declare class TestTubeRack extends Group {
     constructor(count?: number, colors?: number[]);
 }
 
+/**
+ * Calculate the thetaLength to achieve a specific hole radius in a sphere.
+ *   thetaLength = asin(w / (2 * R))
+ *
+ * Returns the thetaLength in radians.
+ *
+ * Example usage:
+ * ```
+ * const sphereRadius = 5; // Radius of the sphere
+ * const holeRadius = 1;   // Desired radius of the hole at the top
+ * const thetaLength = thetaLengthForRadius(sphereRadius, holeRadius);
+ * ```
+ */
+export declare const thetaLengthForRadius: (sphereRadius: number, holeRadius: number) => number;
+
 /**
  * Material indices:
  * 0. Trunk
@@ -2076,18 +2214,6 @@ export declare class WineBottleGeometry extends BufferGeometry {
     });
 }
 
-/**
- * Add a slight random wobble for intensity or realism (e.g., during an explosion).
- *
- * Example:
- * ```
- * wobbleAnimation(camera, 0.5, 1000, () => {
- *   console.log("Wobble animation complete");
- * });
- * ```
- */
-export declare function wobbleAnimation(camera: Camera, intensity: number, duration: number, onComplete?: () => void): void;
-
 export declare class WroughtIronBar extends Mesh<WroughtIronBarGeometry, MeshStandardMaterial> {
     constructor({ barHeight, //
         barRadius, spikeHeight, spikeRadius, spikeScaleZ, radialSegments, }?: {
@@ -2149,17 +2275,4 @@ export declare class WroughtIronFenceGeometry extends BufferGeometry {
     });
 }
 
-/**
- * The camera smoothly zooms in toward a target, focusing attention on a specific point,
- * and resets to its original FOV after completion.
- *
- * Example:
- * ```
- * zoomInAnimation(camera, new THREE.Vector3(0, 0, 0), 120, 75, 2000, () => {
- *   console.log("Zoom in animation complete");
- * });
- * ```
- */
-export declare function zoomInAnimation(camera: PerspectiveCamera, target: Vector3, startFov: number, endFov: number, duration: number, onComplete?: () => void): void;
-
 export { }