@vctrl/hooks/use-optimize-model/use-optimize-model.d.ts

vctrl/hooks is a React hooks package designed to simplify 3D model loading and management within React applications. It's part of the vectreal-core ecosystem and is primarily used in the vctrl/viewer React component and the official website application.

import { DedupOptions, NormalsOptions, QuantizeOptions, SimplifyOptions, TextureCompressOptions } from '../../../core/src/model-optimizer/index.ts';
import { Object3D } from 'three';
import { DracoCompressionReport, ServerSceneData } from '../../../core/src/index.ts';
/** Optimizer state produced inside the geometry Web Worker. */
export interface WorkerResultMeta {
    appliedOptimizations: string[];
    dracoReport?: DracoCompressionReport;
}
/**
 * Custom React hook for optimizing 3D models using the ModelOptimizer from @vctrl/core.
 *
 * This hook provides a React-friendly interface to advanced model optimization capabilities,
 * including mesh simplification, deduplication, quantization, normal optimization, and texture compression.
 * It manages the optimization state and provides callbacks for each optimization operation.
 *
 * **Features:**
 * - Mesh simplification using MeshoptSimplifier
 * - Geometry deduplication to remove redundant data
 * - Vertex attribute quantization to reduce file size
 * - Normal vector optimization
 * - Texture compression (browser-native via OffscreenCanvas)
 * - Progress tracking and error handling
 * - Optimization reports with before/after metrics
 *
 * @example
 * const optimizer = useOptimizeModel()
 *
 * // Load a GLB into the optimizer
 * await optimizer.loadFromGlbBuffer(glbBytes)
 *
 * // Geometry optimizations run via Web Worker (use-optimization-process.ts)
 * // Texture compression runs browser-native via texturesOptimization()
 * await optimizer.texturesOptimization({ targetFormat: 'webp', quality: 0.8 })
 *
 * // Sync result back to the Three.js viewer
 * await optimizer.applyOptimization()
 *
 * @returns Object containing optimization methods, state, and report data
 */
declare const useOptimizeModel: () => {
    /**
     * Loads a Three.js Object3D model into the optimizer.
     * Converts the scene to glTF format and generates an initial optimization report.
     *
     * @param model - The Three.js Object3D model to load
     * @returns Promise that resolves when the model is loaded
     */
    load: (model: Object3D) => Promise<void>;
    loadFromServerSceneData: (sceneData: ServerSceneData) => Promise<void>;
    loadFromGlbBuffer: (buffer: Uint8Array, meta?: WorkerResultMeta) => Promise<void>;
    loadFromGLTFWithAssets: (gltfBytes: Uint8Array, assets: Map<string, Uint8Array>) => Promise<void>;
    /**
     * Retrieves the current model as a binary Uint8Array in glTF (.glb) format.
     *
     * @returns Promise that resolves with the model binary or null if no model is loaded
     */
    getModel: () => Promise<Uint8Array | null>;
    isReady: boolean;
    /**
     * Exposes the underlying ModelOptimizer document instance for advanced use cases.
     */
    _getDocument: () => import('@gltf-transform/core').Document | null;
    /**
     * Resets the optimizer, clearing all model data, reports, and state.
     */
    reset: () => void;
    /**
     * Error object if any optimization operation failed, otherwise null.
     */
    error: Error | null;
    /**
     * Boolean indicating if an optimization operation is currently in progress.
     */
    loading: boolean;
    /**
     * Detailed optimization report containing metrics about the model
     * (vertex count, triangle count, file size, etc.) before and after optimizations.
     */
    report: import('../../../core/src/index.ts').OptimizationReport | null;
    /**
     * Calculated optimization information including file size reduction percentages
     * and comparative metrics.
     */
    info: import('./types').OptimizationInfo;
    /**
     * Simplifies the model by reducing polygon count using MeshoptSimplifier.
     * Maintains visual quality while improving performance.
     *
     * @param options - Simplification options (ratio, error threshold)
     * @returns Promise that resolves when simplification is complete
     */
    simplifyOptimization: (options?: SimplifyOptions) => Promise<void>;
    /**
     * Removes duplicate vertices, primitives, and other redundant data.
     * Reduces file size without affecting visual appearance.
     *
     * @param options - Deduplication options
     * @returns Promise that resolves when deduplication is complete
     */
    dedupOptimization: (options?: DedupOptions) => Promise<void>;
    /**
     * Quantizes vertex attributes to use fewer bits per value.
     * Reduces file size with minimal visual quality loss.
     *
     * @param options - Quantization options (bit depth)
     * @returns Promise that resolves when quantization is complete
     */
    quantizeOptimization: (options?: QuantizeOptions) => Promise<void>;
    /**
     * Optimizes normal vectors by removing, generating, or cleaning up normal data.
     *
     * @param options - Normal optimization options
     * @returns Promise that resolves when optimization is complete
     */
    normalsOptimization: (options?: NormalsOptions) => Promise<void>;
    /**
     * Compresses textures using browser-native OffscreenCanvas encoding.
     * No server call is made. Works in any modern browser context.
     *
     * @param options - Texture compression options (targetFormat, quality, resize)
     * @returns Promise that resolves when compression is complete
     * @throws Error if OffscreenCanvas is unavailable or encoding fails
     */
    texturesOptimization: (options?: TextureCompressOptions) => Promise<void>;
};
export default useOptimizeModel;