@vctrl/hooks 0.11.1 → 0.17.0

package/src/use-optimize-model/use-optimize-model.ts

@@ -1,467 +0,0 @@
-/* vectreal-core | vctrl/hooks
-Copyright (C) 2024 Moritz Becker
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU Affero General Public License for more details.
-
-You should have received a copy of the GNU Affero General Public License
-along with this program. If not, see <http://www.gnu.org/licenses/>. */
-
-import { toSerializedAssetBytes } from '@vctrl/core'
-import {
-	type DedupOptions,
-	ModelOptimizer,
-	type NormalsOptions,
-	type QuantizeOptions,
-	type SimplifyOptions,
-	type TextureCompressOptions
-} from '@vctrl/core/model-optimizer'
-import { useCallback, useEffect, useReducer, useRef } from 'react'
-import { Object3D } from 'three'
-
-import { initialState, reducer } from './state'
-import { useCalcOptimizationInfo } from './use-calc-optimization-info'
-import { optimizeTextures } from './utils'
-
-import type { JSONDocument } from '@gltf-transform/core'
-import type { ServerSceneData } from '@vctrl/core'
-
-/**
- * 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 (server-side only)
- * - Progress tracking and error handling
- * - Optimization reports with before/after metrics
- *
- * @example
- * const optimizer = useOptimizeModel()
- *
- * // Load a model
- * await optimizer.load(threeJsScene)
- *
- * // Apply optimizations
- * await optimizer.simplifyOptimization({ ratio: 0.5 })
- * await optimizer.quantizeOptimization({ bits: 12 })
- *
- * // Get optimized model
- * const optimizedBinary = await optimizer.getModel()
- *
- * @returns Object containing optimization methods, state, and report data
- */
-const useOptimizeModel = () => {
-	// Manage state with useReducer for complex state transitions
-	const [state, dispatch] = useReducer(reducer, initialState)
-	const { report, error, loading } = state
-
-	// Calculate optimization statistics (file size reduction, etc.)
-	const { info, reset: resetInfo } = useCalcOptimizationInfo(state)
-
-	// Store the ModelOptimizer instance in a ref to persist across renders
-	const optimizerRef = useRef<ModelOptimizer>(new ModelOptimizer())
-
-	/**
-	 * Initialize the optimizer and set up progress tracking.
-	 * Cleanup function resets the optimizer when component unmounts.
-	 */
-	useEffect(() => {
-		const optimizer = optimizerRef.current
-
-		// Set up progress callback for optimization operations
-		// Can be extended to dispatch progress updates to state if needed
-		// TODO: dispatch({ type: 'UPDATE_PROGRESS', payload: progress })
-		// optimizer.onProgress((progress: OperationProgress) => {
-		// })
-
-		// Cleanup: reset optimizer when component unmounts
-		return () => {
-			optimizer.reset()
-		}
-	}, [])
-
-	/**
-	 * Loads a Three.js Object3D model into the optimizer for processing.
-	 * Converts the Three.js scene to glTF format and generates an initial optimization report.
-	 *
-	 * @param model - The Three.js Object3D scene to optimize
-	 * @returns Promise that resolves when the model is loaded and ready for optimization
-	 */
-	const load = useCallback(async (model: Object3D): Promise<void> => {
-		dispatch({ type: 'LOAD_START' })
-
-		try {
-			const optimizer = optimizerRef.current
-
-			// Convert Three.js scene to glTF document for optimization
-			await optimizer.loadFromThreeJS(model)
-
-			const report = await optimizer.getReport()
-			dispatch({
-				type: 'LOAD_SUCCESS',
-				payload: { report }
-			})
-		} catch (err) {
-			dispatch({ type: 'LOAD_ERROR', payload: err as Error })
-			console.error('Error loading model:', err)
-		}
-	}, [])
-
-	const loadFromServerSceneData = useCallback(
-		async (sceneData: ServerSceneData): Promise<void> => {
-			dispatch({ type: 'LOAD_START' })
-
-			try {
-				const optimizer = optimizerRef.current
-				const resources: Record<string, Uint8Array> = {}
-
-				for (const asset of Object.values(sceneData.assetData ?? {})) {
-					resources[asset.fileName] = toSerializedAssetBytes(asset)
-				}
-
-				const jsonDocument = {
-					json: sceneData.gltfJson as unknown as JSONDocument['json'],
-					resources
-				}
-
-				await optimizer.loadFromJSON(jsonDocument)
-
-				const report = await optimizer.getReport()
-				dispatch({
-					type: 'LOAD_SUCCESS',
-					payload: { report }
-				})
-			} catch (err) {
-				dispatch({ type: 'LOAD_ERROR', payload: err as Error })
-				console.error('Error loading server scene into optimizer:', err)
-				throw err
-			}
-		},
-		[]
-	)
-
-	/**
-	 * Simplifies the loaded model by reducing polygon count using MeshoptSimplifier.
-	 * This reduces file size and improves rendering performance while maintaining visual quality.
-	 *
-	 * @param options - Configuration options for simplification
-	 * @param options.ratio - Target ratio of triangles to keep (0.0-1.0). Default: 0.5
-	 * @param options.error - Maximum allowed error threshold. Default: 0.01
-	 * @returns Promise that resolves when simplification is complete
-	 */
-	const simplifyOptimization = useCallback(
-		async (options?: SimplifyOptions): Promise<void> => {
-			// Guard: ensure a model is loaded before attempting optimization
-			if (!optimizerRef.current.hasModel()) return
-
-			try {
-				// Apply mesh simplification
-				await optimizerRef.current.simplify(options)
-
-				// Generate updated report with new metrics
-				const report = await optimizerRef.current.getReport()
-
-				// Update state with optimized model
-				dispatch({
-					type: 'LOAD_SUCCESS',
-					payload: {
-						report
-					}
-				})
-			} catch (err) {
-				console.error('Simplification failed:', err)
-			}
-		},
-		[]
-	)
-
-	/**
-	 * De-duplicates geometry and material data in the model.
-	 * Removes redundant vertices, primitives, and other duplicate data to reduce file size.
-	 *
-	 * @param options - Configuration options for deduplication
-	 * @returns Promise that resolves when deduplication is complete
-	 */
-	const dedupOptimization = useCallback(
-		async (options?: DedupOptions): Promise<void> => {
-			// Guard: ensure a model is loaded before attempting optimization
-			if (!optimizerRef.current.hasModel()) return
-
-			try {
-				// Remove duplicate geometry and material data
-				await optimizerRef.current.deduplicate(options)
-
-				// Generate updated report
-				const report = await optimizerRef.current.getReport()
-
-				// Update state with optimized model
-				dispatch({
-					type: 'LOAD_SUCCESS',
-					payload: { report }
-				})
-			} catch (err) {
-				console.error('Deduplication failed:', err)
-			}
-		},
-		[]
-	)
-
-	/**
-	 * Quantizes vertex attributes (positions, normals, UVs) to use fewer bits.
-	 * Reduces file size with minimal visual quality loss by storing data with lower precision.
-	 *
-	 * @param options - Configuration options for quantization
-	 * @param options.bits - Number of bits to use for quantization. Default: 14
-	 * @returns Promise that resolves when quantization is complete
-	 */
-	const quantizeOptimization = useCallback(
-		async (options?: QuantizeOptions): Promise<void> => {
-			// Guard: ensure a model is loaded before attempting optimization
-			if (!optimizerRef.current.hasModel()) return
-
-			try {
-				// Apply vertex attribute quantization
-				await optimizerRef.current.quantize(options)
-
-				// Generate updated report
-				const report = await optimizerRef.current.getReport()
-
-				// Update state with optimized model
-				dispatch({
-					type: 'LOAD_SUCCESS',
-					payload: { report }
-				})
-			} catch (err) {
-				console.error('Quantization failed:', err)
-			}
-		},
-		[]
-	)
-
-	/**
-	 * Optimizes normal vectors in the model.
-	 * Can remove, generate, or clean up normal data to improve rendering quality or reduce file size.
-	 *
-	 * @param options - Configuration options for normal optimization
-	 * @returns Promise that resolves when normal optimization is complete
-	 */
-	const normalsOptimization = useCallback(
-		async (options?: NormalsOptions): Promise<void> => {
-			// Guard: ensure a model is loaded before attempting optimization
-			if (!optimizerRef.current.hasModel()) return
-
-			try {
-				// Apply normal vector optimizations
-				await optimizerRef.current.optimizeNormals(options)
-
-				// Generate updated report
-				const report = await optimizerRef.current.getReport()
-
-				// Update state with optimized model
-				dispatch({
-					type: 'LOAD_SUCCESS',
-					payload: { report }
-				})
-			} catch (err) {
-				console.error('Normals optimization failed:', err)
-			}
-		},
-		[]
-	)
-
-	/**
-	 * Compresses textures in the model using advanced compression formats.
-	 * Significantly reduces file size while maintaining visual quality.
-	 *
-	 * **Note:** This optimization requires server-side processing (Sharp library)
-	 * and may not work in browser-only environments.
-	 *
-	 * @param options - Configuration options for texture compression
-	 * @param options.format - Target compression format (e.g.,  from '@shared/ui', 'ktx2')
-	 * @param options.quality - Compression quality (0-100)
-	 * @returns Promise that resolves when texture compression is complete
-	 * @throws Error if Sharp is not available or compression fails
-	 */
-	const texturesOptimization = useCallback(
-		async (options?: TextureCompressOptions): Promise<void> => {
-			try {
-				// Apply texture compression using utility function
-				// This handles Sharp availability checks and fallbacks
-				await optimizeTextures(optimizerRef.current, options)
-
-				// Generate updated report
-				const report = await optimizerRef.current.getReport()
-
-				// Update state with optimized model
-				dispatch({
-					type: 'LOAD_SUCCESS',
-					payload: { report }
-				})
-			} catch (err) {
-				console.error('Texture optimization failed:', err)
-				// Re-throw to allow caller to handle compression failures
-				throw err
-			}
-		},
-		[]
-	)
-
-	/**
-	 * Exports the current optimized model as a binary Uint8Array.
-	 * The model is exported in glTF binary (.glb) format.
-	 *
-	 * @returns Promise that resolves with the model binary, or null if no model is loaded
-	 */
-	const getModel = useCallback(async (): Promise<Uint8Array | null> => {
-		// Guard: return null if no model is currently loaded
-		if (!optimizerRef.current.hasModel()) return null
-
-		try {
-			// Export model as Uint8Array binary data
-			return await optimizerRef.current.export()
-		} catch (err) {
-			console.error('Error getting model binary:', err)
-			return null
-		}
-	}, [])
-
-	const getDocument = useCallback(() => {
-		if (!optimizerRef.current.hasModel()) {
-			return null
-		}
-
-		return optimizerRef.current.document
-	}, [])
-
-	const isReady = Boolean(getDocument()) && !loading
-
-	/**
-	 * Resets the optimizer to its initial state.
-	 * Clears the loaded model, all optimization data, reports, and calculated info.
-	 */
-	const reset = useCallback((): void => {
-		// Reset the core optimizer instance
-		optimizerRef.current.reset()
-
-		// Reset React state to initial values
-		dispatch({ type: 'RESET' })
-
-		// Reset calculated optimization info
-		resetInfo()
-	}, [resetInfo])
-
-	return {
-		/**
-		 * 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,
-
-		loadFromServerSceneData,
-
-		/**
-		 * 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,
-
-		isReady,
-
-		/**
-		 * Exposes the underlying ModelOptimizer document instance for advanced use cases.
-		 */
-		_getDocument: getDocument, // Expose document for advanced use cases --- IGNORE ---
-
-		/**
-		 * Resets the optimizer, clearing all model data, reports, and state.
-		 */
-		reset,
-
-		/**
-		 * Error object if any optimization operation failed, otherwise null.
-		 */
-		error,
-
-		/**
-		 * Boolean indicating if an optimization operation is currently in progress.
-		 */
-		loading,
-
-		/**
-		 * Detailed optimization report containing metrics about the model
-		 * (vertex count, triangle count, file size, etc.) before and after optimizations.
-		 */
-		report, // Keep report in state for direct access --- IGNORE ---
-
-		/**
-		 * Calculated optimization information including file size reduction percentages
-		 * and comparative metrics.
-		 */
-		info,
-
-		/**
-		 * 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,
-
-		/**
-		 * 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,
-
-		/**
-		 * 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,
-
-		/**
-		 * 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,
-
-		/**
-		 * Compresses textures using advanced formats (requires server-side processing).
-		 * Note: Only works in Node.js environments with Sharp library available.
-		 *
-		 * @param options - Texture compression options (format, quality)
-		 * @returns Promise that resolves when compression is complete
-		 * @throws Error if Sharp is not available
-		 */
-		texturesOptimization
-	}
-}
-
-export default useOptimizeModel

package/src/use-optimize-model/utils/index.ts

@@ -1,29 +0,0 @@
-/* vectreal-core | vctrl/hooks
-Copyright (C) 2024 Moritz Becker
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU Affero General Public License for more details.
-
-You should have received a copy of the GNU Affero General Public License
-along with this program. If not, see <http://www.gnu.org/licenses/>. */
-
-// Texture optimization utilities
-export {
-	optimizeTextures,
-	performClientSideTextureOptimization,
-	performServerSideTextureOptimization,
-	shouldUseServerOptimization
-} from './texture-optimization'
-
-// Validation utilities
-export {
-	validateResponseContentType,
-	validateServerResponse
-} from './validation'