@vctrl/hooks 0.2.1 → 0.3.1

package/README.md

@@ -4,47 +4,54 @@
 ](https://github.com/Vectreal/vectreal-core/actions/workflows/version-release.yaml)
 [![@vctrl/hooks | NPM Downloads](https://img.shields.io/npm/dm/%40vctrl%2Fhooks?logo=npm&logoColor=%23fc6c18&label=%40vctrl%2Fhooks%20%7C%20NPM%20Downloads&color=%23fc6c18)](https://www.npmjs.com/package/@vctrl/hooks)
 
-> This library is still undergoing heavy development until the first major version is released. This may lead to breaking changes in upcoming updates.
+> **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 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.
+`@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 primarily used in the `@vctrl/viewer` React component and the official website application.
 
-The package provides a powerful hook for loading various 3D model file formats, along with a React context for easy state management and an event system for handling different stages of the model loading process.
+The package provides powerful hooks for:
 
-## Table of contents
+- **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
 
 - [vctrl/hooks](#vctrlhooks)
   - [Overview](#overview)
-  - [Table of contents](#table-of-contents)
-  - [Features](#features)
+    - [Table of Contents](#table-of-contents)
   - [Installation](#installation)
-  - [Usage](#usage)
-  - [API Reference](#api-reference)
+  - [Hooks](#hooks)
     - [useLoadModel](#useloadmodel)
-      - [Returns](#returns)
+      - [Overview](#overview-1)
+      - [Features](#features)
+      - [Usage](#usage)
+      - [API Reference](#api-reference)
+      - [Optimization Integration](#optimization-integration)
     - [useOptimizeModel](#useoptimizemodel)
-      - [Returns](#returns-1)
+      - [Overview](#overview-2)
+      - [Features](#features-1)
+      - [Usage](#usage-1)
+      - [API Reference](#api-reference-1)
+    - [useExportModel](#useexportmodel)
+      - [Overview](#overview-3)
+      - [Features](#features-2)
+      - [Usage](#usage-2)
+      - [API Reference](#api-reference-2)
     - [ModelContext](#modelcontext)
-    - [Event System](#event-system)
-      - [Events](#events)
-  - [Supported File Types](#supported-file-types)
-  - [File Loading Process](#file-loading-process)
-  - [State Management](#state-management)
-  - [Integration with Three.js](#integration-with-threejs)
+  - [Common Concepts](#common-concepts)
+    - [Supported File Types](#supported-file-types)
+    - [File Loading Process](#file-loading-process)
+    - [State Management](#state-management)
+    - [Integration with Three.js](#integration-with-threejs)
   - [Development](#development)
   - [License](#license)
   - [Contributing](#contributing)
   - [Support](#support)
 
-## Features
-
-- Direct 3D model file loading (supports GLTF, GLB, and USDZ formats)
-- React context for state management (ModelContext)
-- Event system for handling loading progress and completion
-- Three.js integration
-- TypeScript support
-
 ## Installation
 
 To install the package, use npm or yarn:
@@ -55,9 +62,27 @@ npm install @vctrl/hooks
 yarn add @vctrl/hooks
 ```
 
-## Usage
+## Hooks
+
+### 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.
 
-The main hook exported by this package is `useLoadModel`. Here's a basic example of how to use it:
+#### 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., `.gltf` with associated `.bin` and texture files)
+- Integrates with `useOptimizeModel` for model optimization
+- TypeScript support
+
+#### Usage
+
+Here's a basic example of how to use `useLoadModel`:
 
 ```jsx
 import React from 'react';
@@ -73,7 +98,7 @@ function ModelLoader() {
 
   return (
     <div>
-      <input type="file" onChange={onFileChange} />
+      <input type="file" onChange={onFileChange} multiple />
       {isLoading && <p>Loading: {progress}%</p>}
       {file && <p>Model loaded: {file.name}</p>}
     </div>
@@ -81,11 +106,101 @@ function ModelLoader() {
 }
 ```
 
-> Multiple files can be handled, e.g. when uploading a `.gltf` model, its `.bin` file and the relavant image texture files as `.jpeg`/`.png` (Other texture file formats have not been tested).
+> **Note**: Multiple files can be handled, e.g., when uploading a `.gltf` model along with its `.bin` file and relevant texture files (e.g., `.jpeg`, `.png`).
+
+You can also use the `ModelProvider` and `useModelContext` to access the model state across your application:
+
+```jsx
+// 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 `useModelContext` hook.
+
+#### 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 of `File` objects or a mixed array of `File` objects 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 the `useOptimizeModel` hook 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:
+
+```jsx
+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:
+
+- `simplifyOptimization()`: Simplifies the model using mesh simplification.
+- `dedupOptimization()`: Removes duplicate vertices and meshes.
+- `quantizeOptimization()`: Reduces the precision of vertex attributes.
+
+### useOptimizeModel
+
+#### Overview
 
-The `useLoadModel` and `useOptimizeModel` hooks may be used together or standalone to optimize gltf based scenes.
+`useOptimizeModel` is a React hook used to optimize 3D models, particularly GLTF-based scenes. It can be used in conjunction with `useLoadModel` or independently.
 
-1. Either use the optimizer directly with the `useLoadModel` hook
+#### Features
+
+- Simplifies 3D models using mesh optimization algorithms
+- Provides deduplication and quantization optimizations
+- Integrates with `useLoadModel` and `ModelContext`
+- TypeScript support
+
+#### Usage
+
+There are two ways to use the `useOptimizeModel` hook:
+
+1. **Directly with `useLoadModel`**
 
    ```jsx
    import React from 'react';
@@ -94,77 +209,150 @@ The `useLoadModel` and `useOptimizeModel` hooks may be used together or standalo
 
    function ModelLoader() {
      const optimizer = useOptimizeModel();
-     const { load: loadFile, file, optimize } = useLoadModel(optimizer);
-     const { load: loadModel, getModel, simplifyOptimization } = optimize;
-
-     async function handleClick() {
-       await simplifyOptimization();
-     }
+     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>
+     );
    }
    ```
 
-> Changes are applied to the `file.model` field from `useLoadModel` automatically when using optimizations
+   > **Note**: Changes are applied to the `file.model` field from `useLoadModel` automatically when using optimizations.
 
-2. Or use the optimizer together with the `ModelProvider`
+2. **With `ModelProvider` and `useModelContext`**
 
    ```jsx
-   // App.tsx
+   // 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();
+     const optimizer = useOptimizeModel();
 
-      return (
-        <ModelProvider optimizer={optimizer}>
-          <Scene>
-        </ModelProvider>
-      )
+     return (
+       <ModelProvider optimizer={optimizer}>
+         <Scene />
+       </ModelProvider>
+     );
    }
-   ```
 
-   ```jsx
-   // Scene.tsx
+   // Scene.jsx
+   import React from 'react';
    import { useModelContext } from '@vctrl/hooks/use-load-model';
 
    function Scene() {
      const { optimize } = useModelContext();
-     const { load, getModel, simplifyOptimization } = optimize;
 
-     //...
+     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
+#### API Reference
 
-### useLoadModel
+The `useOptimizeModel` hook returns the following:
 
-The main hook for loading and managing 3D model files.
+- `load(model)`: Loads a Three.js `Object3D` model into the optimizer.
+- `getModel()`: Retrieves the optimized model as a binary array buffer.
+- `simplifyOptimization()`: Simplifies the current model using the `MeshoptSimplifier`.
+- `dedupOptimization()`: Removes duplicate vertices and meshes.
+- `quantizeOptimization()`: Reduces the precision of vertex attributes.
 
-#### Returns
+### useExportModel
 
-- `file`: The loaded file object of type `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`: A function to handle file upload. It accepts an array of `File` objects or a mixed array of `File` objects and directory entries.
-- `reset`: A function to reset the internal state back to it's initial values.
-- `on`: A function to subscribe to events.
-- `off`: A function to unsubscribe from events.
-- `optimize`: An object optionally populated by the `useOptimizeModel` hook
+#### Overview
 
-### useOptimizeModel
+`useExportModel` is a React hook for exporting 3D models from a Three.js scene.
+
+#### Features
 
-An addon that may be used in conjunction with the `useLoadModel` hook. It populates the `optimize` property returned by the `useLoadModel` and `useModelContext` hooks.
+- Exports models in GLTF or GLB format
+- Handles embedded resources and textures
+- Integrates with Three.js scenes
+- TypeScript support
 
-#### Returns
+#### Usage
 
-- `load`: Loads a Three.js Object3D model into the optimizer.
-- `getModel`: Simplifies the current model document using the MeshoptSimplifier.
-- `simplifyOptimization`: Returns the current model document as a binary array buffer.
+```jsx
+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`: The `ModelFile` object to export.
+  - `binary`: A boolean indicating whether to export in binary format (`true` for GLB, `false` for GLTF).
+  - The function exports the model and triggers file download.
 
 ### ModelContext
 
-A React context that provides the state and functions from `useLoadModel` to child components. It's implemented in `model-context.tsx`.
+`ModelContext` is a React context that provides the state and functions from `useLoadModel` (and optionally `useOptimizeModel`) to child components.
 
 ```jsx
 import { ModelProvider, useModelContext } from '@vctrl/hooks/use-load-model';
@@ -178,95 +366,65 @@ function App() {
 }
 
 function ModelConsumer() {
-  const { file, isLoading, progress, load } = useModelContext();
+  const { file, isLoading, progress, load, optimize } = useModelContext();
   // Use the context values
 }
 ```
 
-> When using the React Context, only load models with the `useModelContext` hook.
-
-### Event System
-
-The package includes a custom event system for handling various stages of the model loading process. The event system is implemented in `event-system.ts` and provides three main methods:
-
-- `emit<T extends EventTypes>(event: T, data: EventData[T]): void`
-- `on<T extends EventTypes>(event: T, handler: EventHandler<T>): void`
-- `off<T extends EventTypes>(event: T, handler: EventHandler<T>): void`
-
-#### Events
-
-You can subscribe to these events using the `on` method:
-
-- `'UPLOAD_PROGRESS'`: Emitted with the current progress (0-100) during file upload.
-- `'UPLOAD_COMPLETE'`: Emitted with the loaded file object when the upload is complete.
-- `'MULTIPLE_3D_MODELS'`: Emitted if multiple supported 3D model files are detected in the upload.
-- `'UNSUPPORTED_FILE_TYPE'`: Emitted if an unsupported file type is uploaded.
+> **Note**: When using the React context, load models using the `useModelContext` hook.
 
-Example usage:
-
-```javascript
-const { on, off } = useLoadModel();
-
-useEffect(() => {
-  const handleProgress = (progress) => {
-    console.log(`Upload progress: ${progress}%`);
-  };
-
-  on('UPLOAD_PROGRESS', handleProgress);
-
-  return () => off('UPLOAD_PROGRESS', handleProgress);
-}, [on, off]);
-```
+## Common Concepts
 
-## Supported File Types
+### Supported File Types
 
 The package currently supports the following 3D model file formats:
 
-- GLTF (.gltf)
-- GLB (.glb)
-- USDZ (.usdz)
+- GLTF (`.gltf`)
+- GLB (`.glb`)
+- USDZ (`.usdz`)
 
 These are defined in the `ModelFileTypes` enum in `types.ts`.
 
-## File Loading Process
+### File Loading Process
 
-The file loading process, particularly for GLTF files, is handled by the `useLoadGltf` hook in `use-load-gltf.ts`. This hook performs the following steps:
+The file loading process, particularly for GLTF files, is handled internally by the hooks. The process includes:
 
-1. Parses the GLTF file content.
-2. Embeds external resources (buffers and images) into the GLTF content.
-3. Uses Three.js GLTFLoader to parse the modified GLTF content.
-4. Dispatches actions to update the state with the loaded model.
+1. Parsing the GLTF file content.
+2. Embedding external resources (buffers and images) into the GLTF content.
+3. Using Three.js `GLTFLoader` to parse the modified GLTF content.
+4. Updating the state with the loaded model.
+5. Integrating with the optimizer if provided.
 
 The loading process includes progress updates, which are communicated through the event system.
 
-## State Management
+### State Management
 
-The package uses a reducer pattern for state management, implemented in `state.ts`. The state includes:
+The package uses a reducer pattern for state management. The state includes:
 
 - `file`: The currently loaded model file.
-- `isFileLoading`: A boolean indicating if a file is being loaded.
+- `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
+### Integration with Three.js
 
-The package integrates with Three.js for handling 3D model rendering. The loaded models are compatible with Three.js scene rendering, with the model stored as a Three.js `Object3D` in the `ModelFile` interface.
+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:
 
-1. Clone the monorepo
-2. Install dependencies: `npm install` or `yarn install`
-3. Make your changes
-4. Build the package: `nx build vctrl/hooks`
-5. Test your changes: `nx test vctrl/hooks`
+1. Clone the monorepo from [vectreal-core](https://github.com/vectreal/vectreal-core).
+2. Install dependencies: `npm install` or `yarn install`.
+3. Make your changes.
+4. Build the package: `nx build vctrl/hooks`.
+5. Test your changes: `nx test vctrl/hooks`.
 
 ## License
 
-Please refer to the LICENSE file in the package root for licensing information.
+This project is licensed under the **GNU Affero General Public License v3.0**. Please refer to the [LICENSE](https://github.com/vectreal/vectreal-core/blob/main/LICENSE) file in the package root for licensing information.
 
 ## Contributing
 
@@ -274,4 +432,4 @@ Contributions are welcome! Please read the contributing guidelines in the [vectr
 
 ## Support
 
-For issues, feature requests, or questions, please file an issue in the GitHub repository.
+For issues, feature requests, or questions, please file an issue in the [GitHub repository](https://github.com/vectreal/vectreal-core/issues).