@wandelbots/wandelbots-js-react-components/dist/components/utils/interpolation.d.ts

React UI toolkit for building applications on top of the Wandelbots platform

/**
 * Smooth value interpolation utility using spring physics with tension and friction.
 * Designed for React Three Fiber applications with smooth, natural animations.
 *
 * Features:
 * - Spring physics with configurable tension and friction
 * - Frame-rate independent using delta timing
 * - Handles irregular frame timing and rapid target updates
 * - Manual update() calls for useFrame integration (no automatic RAF loop)
 * - Direct mutation for performance
 *
 * @example
 * ```tsx
 * // Basic spring animation
 * const interpolator = new ValueInterpolator([0, 0, 0], {
 *   tension: 120, // Higher = faster, stiffer spring (default: 120)
 *   friction: 20, // Higher = more damping, less oscillation (default: 20)
 *   onChange: (values) => {
 *     robot.joints.forEach((joint, i) => {
 *       joint.rotation.y = values[i]
 *     })
 *   }
 * })
 *
 * interpolator.setTarget([1.5, -0.8, 2.1])
 *
 * // React Three Fiber usage
 * function MyComponent() {
 *   const [interpolator] = useInterpolation([0, 0, 0])
 *
 *   useFrame((state, delta) => {
 *     interpolator.update(delta)
 *   })
 *
 *   useEffect(() => {
 *     interpolator.setTarget([1, 2, 3])
 *   }, [])
 *
 *   return <mesh position={interpolator.getCurrentValues()} />
 * }
 * ```
 */
export interface InterpolationOptions {
    /** Spring tension (higher = faster, stiffer spring) - default: 120 */
    tension?: number;
    /** Spring friction (higher = more damping, less oscillation) - default: 20 */
    friction?: number;
    /** Minimum threshold to consider interpolation complete - default: 0.001 */
    threshold?: number;
    /** Callback when values change during interpolation */
    onChange?: (values: number[]) => void;
    /** Callback when interpolation reaches target values */
    onComplete?: (values: number[]) => void;
}
export declare class ValueInterpolator {
    private currentValues;
    private targetValues;
    private previousTargetValues;
    private targetUpdateTime;
    private animationId;
    private options;
    private updateCount;
    private velocities;
    constructor(initialValues?: number[], options?: InterpolationOptions);
    /**
     * Update interpolation using spring physics
     *
     * Call this method every frame for smooth animation. In React Three Fiber,
     * call from within useFrame callback with the provided delta time.
     *
     * @param delta - Time elapsed since last update in seconds (e.g., 1/60 ≈ 0.0167 for 60fps)
     * @returns true when interpolation is complete (all values reached their targets)
     */
    update(delta?: number): boolean;
    /**
     * Set new target values for the interpolation to move towards
     *
     * Includes smart blending for very rapid target updates (faster than 120fps)
     * to prevent jarring movements when targets change frequently.
     */
    setTarget(newValues: number[]): void;
    /**
     * Get a copy of all current interpolated values
     */
    getCurrentValues(): number[];
    /**
     * Get a single interpolated value by its array index
     */
    getValue(index: number): number;
    /**
     * Check if automatic interpolation is currently running
     *
     * This only tracks auto-interpolation started with startAutoInterpolation().
     * Manual update() calls are not tracked by this method.
     */
    isInterpolating(): boolean;
    /**
     * Stop automatic interpolation if it's running
     *
     * This cancels the internal animation frame loop but does not affect
     * manual update() calls.
     */
    stop(): void;
    /**
     * Instantly set values without interpolation
     */
    setImmediate(values: number[]): void;
    /**
     * Update interpolation options
     */
    updateOptions(newOptions: Partial<InterpolationOptions>): void;
    /**
     * Start automatic interpolation with an animation loop
     *
     * This begins a requestAnimationFrame loop that calls update() automatically.
     * For React Three Fiber components, prefer using manual update() calls
     * within useFrame hooks instead.
     */
    startAutoInterpolation(): void;
    /**
     * Clean up all resources and stop any running animations
     *
     * This cancels any active animation frames and resets internal state.
     * Call this when the component unmounts or is no longer needed.
     */
    destroy(): void;
    private startInterpolation;
    private animate;
}
/**
 * React hook for using the ValueInterpolator with useFrame
 *
 * This hook creates a ValueInterpolator that uses spring physics for smooth,
 * natural animations. Call interpolator.update(delta) in your useFrame callback.
 *
 * @example
 * ```tsx
 * function AnimatedMesh() {
 *   const [interpolator] = useInterpolation([0, 0, 0], {
 *     tension: 120, // Higher = faster spring
 *     friction: 20  // Higher = more damping
 *   })
 *   const meshRef = useRef()
 *
 *   useFrame((state, delta) => {
 *     if (interpolator.update(delta)) {
 *       // Animation complete
 *     }
 *     // Apply current values directly to mesh
 *     const [x, y, z] = interpolator.getCurrentValues()
 *     meshRef.current.position.set(x, y, z)
 *   })
 *
 *   return <mesh ref={meshRef} />
 * }
 * ```
 */
export declare function useInterpolation(initialValues?: number[], options?: InterpolationOptions): [ValueInterpolator];
//# sourceMappingURL=interpolation.d.ts.map