vectreal
vctrl/hooks
Note: This library is still undergoing heavy development until the first major version is released. This may lead to breaking changes in upcoming updates.
Overview
@vctrl/hooks is a React hooks package designed to simplify 3D model loading, optimization, and exporting within React applications. It's part of the vectreal-core ecosystem and is fully integrated into the official website application.
The package provides powerful hooks for:
- Loading various 3D model file formats (
useLoadModel) - Optimizing 3D models (
useOptimizeModel) - Exporting 3D models from Three.js scenes (
useExportModel)
It also includes a React context (ModelContext) for easy state management and an event system for handling different stages of the model loading process.
Table of Contents
Installation
To install the package, use npm or yarn:
npm install @vctrl/hooks
# or
yarn add @vctrl/hooksHooks
useLoadModel
Overview
useLoadModel is a React hook for loading and managing 3D model files in your application. It supports various file formats and integrates with Three.js for rendering.
Features
- Supports direct 3D model file loading (GLTF, GLB, USDZ)
- Provides loading progress updates
- Emits events during the loading process
- Integrates with Three.js
- Supports multiple file uploads (e.g.,
.gltfwith associated.binand texture files) - Integrates with
useOptimizeModelfor model optimization - TypeScript support
Usage
Here's a basic example of how to use useLoadModel:
import React from 'react';
import { useLoadModel } from '@vctrl/hooks/use-load-model';
function ModelLoader() {
const { load, file, progress, isLoading } = useLoadModel();
const onFileChange = (event) => {
const files = Array.from(event.target.files);
load(files);
};
return (
<div>
<input type="file" onChange={onFileChange} multiple />
{isLoading && <p>Loading: {progress}%</p>}
{file && <p>Model loaded: {file.name}</p>}
</div>
);
}Note: Multiple files can be handled, e.g., when uploading a
.gltfmodel along with its.binfile and relevant texture files (e.g.,.jpeg,.png).
You can also use the ModelProvider and useModelContext to access the model state across your application:
// App.jsx
import React from 'react';
import { ModelProvider } from '@vctrl/hooks/use-load-model';
import ModelConsumer from './ModelConsumer';
function App() {
return (
<ModelProvider>
<ModelConsumer />
</ModelProvider>
);
}
// ModelConsumer.jsx
import React from 'react';
import { useModelContext } from '@vctrl/hooks/use-load-model';
function ModelConsumer() {
const { file, isLoading, progress, load } = useModelContext();
// Use the context values
return (
// ... your component logic
);
}Note: When using the React context, load models using the
useModelContexthook.
API Reference
The useLoadModel hook returns the following:
file: The loaded file object (ModelFile | null).isLoading: A boolean indicating whether a file is currently being loaded.progress: A number between 0 and 100 representing the loading progress.load(files): A function to handle file uploads. It accepts an array ofFileobjects or a mixed array ofFileobjects and directory entries.reset(): A function to reset the internal state back to its initial values.on(event, handler): A function to subscribe to events.off(event, handler): A function to unsubscribe from events.optimize: An object populated by theuseOptimizeModelhook integration, providing optimization functions (see below).
Optimization Integration
If you pass an instance of useOptimizeModel to useLoadModel, it will integrate optimization functions into the optimize object:
import React from 'react';
import { useLoadModel } from '@vctrl/hooks/use-load-model';
import { useOptimizeModel } from '@vctrl/hooks/use-optimize-model';
function ModelLoader() {
const optimizer = useOptimizeModel();
const { load, file, optimize } = useLoadModel(optimizer);
const handleSimplify = async () => {
await optimize.simplifyOptimization();
// The optimized model is now in file.model
};
return (
// ... your component logic
);
}The optimize object includes quick access optimization:
simplifyOptimization(options): Simplifies the model using mesh simplification.dedupOptimization(options): Removes duplicate vertices and meshes.quantizeOptimization(options): Reduces the precision of vertex attributes.normalsOptimization(options): Overrides the normals of each object in the scene.texturesCompressionOptimization(options): Compresses the relevant textures in the model file using texture compression.
useOptimizeModel
Overview
useOptimizeModel is a React hook used to optimize 3D models, particularly GLTF-based scenes. It can be used in conjunction with useLoadModel or independently.
Features
- Simplifies 3D models using mesh optimization algorithms
- Provides deduplication and quantization optimizations
- Integrates with
useLoadModelandModelContext - TypeScript support
Usage
There are two ways to use the useOptimizeModel hook:
Directly with
useLoadModelimport React from 'react'; import { useLoadModel } from '@vctrl/hooks/use-load-model'; import { useOptimizeModel } from '@vctrl/hooks/use-optimize-model'; function ModelLoader() { const optimizer = useOptimizeModel(); const { load, file, optimize } = useLoadModel(optimizer); const handleSimplify = async () => { await optimize.simplifyOptimization(); // The optimized model is now in file.model }; const handleDedup = async () => { await optimize.dedupOptimization(); }; const handleQuantize = async () => { await optimize.quantizeOptimization(); }; return ( <div> <input type="file" onChange={(e) => load(Array.from(e.target.files))} multiple /> <button onClick={handleSimplify}>Simplify Model</button> <button onClick={handleDedup}>Deduplicate Model</button> <button onClick={handleQuantize}>Quantize Model</button> </div> ); }Note: Changes are applied to the
file.modelfield fromuseLoadModelautomatically when using optimizations.With
ModelProvideranduseModelContext// App.jsx import React from 'react'; import { ModelProvider } from '@vctrl/hooks/use-load-model'; import { useOptimizeModel } from '@vctrl/hooks/use-optimize-model'; import Scene from './Scene'; function App() { const optimizer = useOptimizeModel(); return ( <ModelProvider optimizer={optimizer}> <Scene /> </ModelProvider> ); } // Scene.jsx import React from 'react'; import { useModelContext } from '@vctrl/hooks/use-load-model'; function Scene() { const { optimize } = useModelContext(); const handleSimplify = async () => { await optimize.simplifyOptimization(); }; const handleDedup = async () => { await optimize.dedupOptimization(); }; const handleQuantize = async () => { await optimize.quantizeOptimization(); }; return ( <div> <button onClick={handleSimplify}>Simplify Model</button> <button onClick={handleDedup}>Deduplicate Model</button> <button onClick={handleQuantize}>Quantize Model</button> </div> ); }
API Reference
The useOptimizeModel hook returns the following:
load(model): Loads a Three.jsObject3Dmodel into the optimizer.getModel(): Retrieves the optimized model as a binary array buffer.simplifyOptimization(options): Simplifies the current model using theMeshoptSimplifier.dedupOptimization(options): Removes duplicate vertices and meshes.quantizeOptimization(options): Reduces the precision of vertex attributes.normalsOptimization: Overrides normalstexturesOptimization(options): Compresses related textures.getSize(): Object with byte size of gltf scene and a formatted megabyte stringreset(): Resets the current optimizer model and report state.report: @gltf-transform gltf report object with relevant details about a gltf sceneerror: Stores any possible optimization errorsloading: Boolean for when the model is being loaded
useExportModel
Overview
useExportModel is a React hook for exporting 3D models from a Three.js scene.
Features
- Exports models in GLTF or GLB format
- Handles embedded resources and textures
- Integrates with Three.js scenes
- TypeScript support
Usage
import React from 'react';
import { useExportModel } from '@vctrl/hooks/use-export-model';
function ExportButton({ file }) {
const { handleGltfExport } = useExportModel(
() => console.log('Export complete'),
(error) => console.error('Export error:', error),
);
const exportAsGlb = () => {
handleGltfExport(file, true); // Export as GLB (binary)
};
const exportAsGltf = () => {
handleGltfExport(file, false); // Export as GLTF
};
return (
<div>
<button onClick={exportAsGlb}>Export as GLB</button>
<button onClick={exportAsGltf}>Export as GLTF</button>
</div>
);
}API Reference
The useExportModel hook returns the following:
handleGltfExport(file, binary): Function to handle exporting the model.file: TheModelFileobject to export.binary: A boolean indicating whether to export in binary format (truefor GLB,falsefor GLTF).- The function exports the model and triggers file download.
ModelContext
ModelContext is a React context that provides the state and functions from useLoadModel (and optionally useOptimizeModel) to child components.
import { ModelProvider, useModelContext } from '@vctrl/hooks/use-load-model';
function App() {
return (
<ModelProvider>
<ModelConsumer />
</ModelProvider>
);
}
function ModelConsumer() {
const { file, isLoading, progress, load, optimize } = useModelContext();
// Use the context values
}Note: When using the React context, load models using the
useModelContexthook.
Common Concepts
Supported File Types
The package currently supports the following 3D model file formats:
- GLTF (
.gltf) - GLB (
.glb) - USDZ (
.usdz)
These are defined in the ModelFileTypes enum in types.ts.
File Loading Process
The file loading process, particularly for GLTF files, is handled internally by the hooks. The process includes:
- Parsing the GLTF file content.
- Embedding external resources (buffers and images) into the GLTF content.
- Using Three.js
GLTFLoaderto parse the modified GLTF content. - Updating the state with the loaded model.
- Integrating with the optimizer if provided.
The loading process includes progress updates, which are communicated through the event system.
State Management
The package uses a reducer pattern for state management. The state includes:
file: The currently loaded model file.isLoading: A boolean indicating if a file is being loaded.progress: The current loading progress.supportedFileTypes: An array of supported file types.
Actions for updating the state are defined in the Action type in types.ts.
Integration with Three.js
The package integrates with Three.js for handling 3D model rendering and manipulation. The loaded models are compatible with Three.js scenes, with the model stored as a Three.js Object3D in the ModelFile interface.
Development
This package is part of a monorepo workspace managed with Nx. To contribute or modify the package:
- Clone the monorepo from vectreal-core.
- Install dependencies:
npm installoryarn install. - Make your changes.
- Build the package:
nx build vctrl/hooks. - Test your changes:
nx test vctrl/hooks.
License
This project is licensed under the GNU Affero General Public License v3.0. Please refer to the LICENSE file in the package root for licensing information.
Contributing
Contributions are welcome! Please read the contributing guidelines in the vectreal-core monorepo before submitting pull requests.
Support
For issues, feature requests, or questions, please file an issue in the GitHub repository.