@tonybfox/threejs-tools 1.0.0

package/README.md

@@ -0,0 +1,321 @@
+# ThreeJS Tools
+
+A collection of utilities and tools for Three.js development, organized as a monorepo with separate packages for different functionalities. The root `@tonybfox/threejs-tools` package now bundles every tool so you can install a single npm package while still importing submodules (for example `@tonybfox/threejs-tools/camera` or `@tonybfox/threejs-tools/terrain`).
+
+## 📦 Packages
+
+- **[@tonybfox/threejs-camera](./packages/camera/)** - Camera utilities and controls
+- **[@tonybfox/threejs-grid](./packages/grid/)** - Infinite grid component
+- **[@tonybfox/threejs-measurements](./packages/measurements/)** - Measurement tools for 3D scenes
+- **[@tonybfox/threejs-asset-loader](./packages/asset-loader/)** - Universal asset loader with progress tracking and caching
+
+## 🛠️ Prerequisites
+
+Make sure you have the following installed on your system:
+
+- **Node.js** (version 16 or higher)
+- **pnpm** (recommended package manager)
+
+If you don't have pnpm installed, you can install it globally:
+
+```bash
+npm install -g pnpm
+```
+
+## 🚀 Installation
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/tonybfox/threejs-tools.git
+   cd threejs-tools
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   pnpm install
+   ```
+
+   This will install all dependencies for the root workspace and all packages.
+
+## 🔨 Building
+
+### Build the publishable bundle
+
+```bash
+pnpm build
+```
+
+Generates the aggregated `dist/` folder that is published to npm (includes CommonJS, ESM, and type declarations for every tool).
+
+### Build individual workspace packages
+
+```bash
+pnpm build:packages
+```
+
+Builds each package inside `packages/` – useful for local development and examples.
+
+### Build everything including examples
+
+To build both packages and examples:
+
+```bash
+pnpm build:all
+```
+
+### Build only examples
+
+To build just the examples:
+
+```bash
+pnpm build:examples
+```
+
+### Clean build artifacts
+
+To clean all build outputs:
+
+```bash
+pnpm clean
+```
+
+## 🎮 Running Examples
+
+The project includes interactive examples demonstrating each package's functionality.
+
+### Development Mode
+
+1. **Install dependencies and build packages:**
+
+   ```bash
+   pnpm install
+   pnpm build:packages
+   ```
+
+2. **Start the development server:**
+
+   ```bash
+   cd examples
+   pnpm dev
+   ```
+
+3. **Open your browser** and navigate to `http://localhost:5173`
+
+### Production Preview
+
+To preview the built examples:
+
+```bash
+cd examples
+pnpm build
+pnpm preview
+```
+
+## 📁 Examples Overview
+
+### 🔧 Grid Package Example
+
+- **Location:** `/examples/grid/`
+- **Features:**
+  - Interactive InfiniteGrid component
+  - Adjustable grid size and divisions
+  - Multiple grid instances
+  - Grid positioning and rotation
+- **Controls:** Use the control panel to modify grid properties
+
+### 📷 Camera Package Example
+
+- **Location:** `/examples/camera/`
+- **Features:**
+  - Camera position presets (Front, Side, Top, Isometric)
+  - Smooth camera animations
+  - Orbit animation mode
+  - Perspective vs Orthographic camera switching
+  - Real-time camera info display
+- **Controls:** Click buttons to change camera views and modes
+
+### 📏 Measurements Package Example
+
+- **Location:** `/examples/measurements/`
+- **Features:**
+  - Distance measurement tool
+  - Angle measurement (3-point)
+  - Area calculation tool
+  - Grid snap functionality
+  - Unit switching (meters/feet)
+  - Interactive labels
+- **Usage:** Select a tool and click in the 3D scene to measure
+
+### 📦 Asset Loader Package Example
+
+- **Location:** `/examples/asset-loader/`
+- **Features:**
+  - Universal loader for GLTF, FBX, and OBJ formats
+  - Visual placeholder with shader fill effect
+  - Real-time progress tracking
+  - Asset caching for performance
+  - Optional low-res model loading
+  - Event-driven architecture
+- **Usage:** Use the control panel to create placeholders and see the loading system in action
+
+### 🎮 Interactive Features
+
+Each example includes:
+
+- **Mouse Controls:** Orbit, zoom, and pan with OrbitControls
+- **Responsive Design:** Automatic window resize handling
+- **Visual Feedback:** Hover effects and interactive elements
+- **Real-time Updates:** Live parameter adjustment
+- **Performance Monitoring:** Optional FPS and render statistics
+
+### 🛠 Example Development
+
+#### Shared Utilities
+
+The `/examples/shared/utils.js` file contains common utilities for:
+
+- Scene setup and configuration
+- Object creation helpers
+- UI component helpers
+- Performance monitoring
+
+#### Adding New Examples
+
+1. Create a new folder in `/examples/`
+2. Add `index.html` and `main.js` files
+3. Update `vite.config.js` to include the new example
+4. Update the main `index.html` with a link to your example
+
+#### Configuration
+
+Examples use Vite for development with:
+
+- ES modules support
+- Hot module replacement
+- Multi-page application setup
+- Three.js optimization
+- Workspace linking for package imports
+
+## 📦 Publishing to npm
+
+Steps to publish the unified `threejs-tools` package:
+
+1. Ensure you are logged in: `pnpm login`
+2. Build the bundle: `pnpm build`
+3. Publish from the repository root: `pnpm publish --access public`
+
+The published package exposes:
+
+- `@tonybfox/threejs-tools` – combined exports (tree-shakeable)
+- `@tonybfox/threejs-tools/<tool>` – direct submodule imports for each tool (`camera`, `terrain`, `measurements`, etc.)
+
+## 🏗️ Development Workflow
+
+### Working on packages
+
+1. **Make changes** to any package in the `packages/` directory
+2. **Build the packages:**
+   ```bash
+   pnpm build
+   ```
+3. **Test your changes** in the examples:
+   ```bash
+   cd examples
+   pnpm dev
+   ```
+
+The examples use workspace references (`workspace:*`), so your local changes will be automatically reflected.
+
+### Adding new packages
+
+1. Create a new directory in `packages/`
+2. Add a `package.json` with the `@tonybfox/threejs-*` naming convention
+3. The workspace will automatically include it
+
+## 📝 Code Formatting
+
+This project uses Prettier for code formatting:
+
+```bash
+# Format all files
+pnpm format
+
+# Check formatting without making changes
+pnpm format:check
+```
+
+## 🏛️ Project Structure
+
+```
+threejs-tools/
+├── packages/                    # Library packages
+│   ├── camera/                 # Camera utilities
+│   ├── core/                   # Core functionality
+│   ├── grid/                   # Grid components
+│   └── measurements/           # Measurement tools
+├── examples/                   # Interactive examples
+│   ├── camera/                 # Camera example
+│   ├── grid/                   # Grid example
+│   ├── measurements/           # Measurements example
+│   └── shared/                 # Shared example utilities
+├── package.json                # Root workspace configuration
+├── pnpm-workspace.yaml         # pnpm workspace definition
+└── tsconfig.json               # TypeScript configuration
+```
+
+## 🔧 Scripts Reference
+
+| Script                | Description                            |
+| --------------------- | -------------------------------------- |
+| `pnpm build`          | Build all packages (excludes examples) |
+| `pnpm build:all`      | Build packages and examples            |
+| `pnpm build:examples` | Build only examples                    |
+| `pnpm clean`          | Clean all build artifacts              |
+| `pnpm format`         | Format all files with Prettier         |
+| `pnpm format:check`   | Check code formatting                  |
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+1. **Package not found:** Run `pnpm build` from root directory
+2. **Vite not starting:** Check Node.js version compatibility (20.18+)
+3. **Import errors:** Ensure packages are built and workspace is properly configured
+4. **WebGL errors:** Check browser WebGL support
+
+### Performance Tips
+
+- Use the built-in performance monitor in examples
+- Test with different device capabilities
+- Monitor memory usage with large scenes
+- Use appropriate LOD for complex geometries
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests and formatting (`pnpm format`)
+5. Build packages (`pnpm build`)
+6. Test examples (`cd examples && pnpm dev`)
+7. Commit your changes (`git commit -m 'Add some amazing feature'`)
+8. Push to the branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🐛 Issues & Support
+
+If you encounter any issues or have questions:
+
+1. Check existing [GitHub Issues](https://github.com/tonybfox/threejs-tools/issues)
+2. Create a new issue with detailed information
+3. Include steps to reproduce and expected behavior
+
+---
+
+Made with ❤️ for the Three.js community

package/dist/asset-loader/index.cjs

@@ -0,0 +1,376 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/asset-loader/src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  AssetLoader: () => AssetLoader
+});
+module.exports = __toCommonJS(src_exports);
+
+// packages/asset-loader/src/AssetLoader.ts
+var THREE = __toESM(require("three"));
+var import_GLTFLoader = require("three/examples/jsm/loaders/GLTFLoader.js");
+var import_FBXLoader = require("three/examples/jsm/loaders/FBXLoader.js");
+var import_OBJLoader = require("three/examples/jsm/loaders/OBJLoader.js");
+var AssetLoader = class extends THREE.EventDispatcher {
+  constructor() {
+    super();
+    this.cache = /* @__PURE__ */ new Map();
+    this.placeholder = null;
+    this.loadedAsset = null;
+    this.lowResAsset = null;
+    this.errorColor = 16729156;
+    this.errorOpacity = 0.5;
+    this.gltfLoader = new import_GLTFLoader.GLTFLoader();
+    this.fbxLoader = new import_FBXLoader.FBXLoader();
+    this.objLoader = new import_OBJLoader.OBJLoader();
+  }
+  /**
+   * Create a placeholder cube with shader effect
+   */
+  createPlaceholder(size, color = 5227511, opacity = 0.3) {
+    const [width, height, depth] = size;
+    const geometry = new THREE.BoxGeometry(width, height, depth);
+    const material = new THREE.ShaderMaterial({
+      side: THREE.DoubleSide,
+      depthWrite: false,
+      blending: THREE.AdditiveBlending,
+      transparent: true,
+      uniforms: {
+        color: { value: new THREE.Color(color) },
+        opacity: { value: opacity },
+        fillProgress: { value: 0 },
+        time: { value: 0 },
+        isError: { value: 0 }
+      },
+      vertexShader: `
+        varying vec3 vPosition;
+        void main() {
+          vPosition = position;
+          gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+        }
+      `,
+      fragmentShader: `
+        uniform vec3 color;
+        uniform float opacity;
+        uniform float fillProgress;
+        uniform float time;
+        uniform float isError;
+        varying vec3 vPosition;
+        
+        void main() {
+          float normalizedY = (vPosition.y + 1.0) / 2.0; // Normalize from -1,1 to 0,1
+          float alpha = opacity;
+          
+          // Create fill-up effect
+          if (normalizedY > fillProgress) {
+            alpha *= 0.3; // Reduce opacity for unfilled parts
+          }
+          
+          // Error state effects
+          if (isError > 0.5) {
+            // Add pulsing effect for error state
+            float pulse = 0.5 + 0.5 * sin(time * 4.0);
+            alpha *= (0.3 + 0.4 * pulse);
+            
+            // Add error pattern
+            float stripe = sin(vPosition.y * 20.0 + time * 2.0);
+            alpha *= (0.7 + 0.3 * step(0.0, stripe));
+          }
+          
+          // Add edge glow
+          vec3 viewDirection = normalize(cameraPosition - vPosition);
+          float edgeIntensity = pow(1.0 - abs(dot(viewDirection, normalize(vPosition))), 2.0);
+          
+          vec3 finalColor = color + edgeIntensity * 0.5;
+          gl_FragColor = vec4(finalColor, alpha);
+        }
+      `
+    });
+    const mesh = new THREE.Mesh(geometry, material);
+    this.positionAssetAtBottomCenter(mesh);
+    return mesh;
+  }
+  /**
+   * Update placeholder fill progress based on loading progress
+   */
+  updatePlaceholder(progress) {
+    if (this.placeholder && this.placeholder instanceof THREE.Mesh) {
+      const material = this.placeholder.material;
+      if (material.uniforms && material.uniforms.fillProgress) {
+        material.uniforms.fillProgress.value = progress;
+      }
+    }
+  }
+  /**
+   * Set placeholder to error state with configurable color and opacity
+   */
+  setPlaceholderError() {
+    if (this.placeholder && this.placeholder instanceof THREE.Mesh) {
+      const material = this.placeholder.material;
+      if (material.uniforms) {
+        if (material.uniforms.color) {
+          material.uniforms.color.value = new THREE.Color(this.errorColor);
+        }
+        if (material.uniforms.opacity) {
+          material.uniforms.opacity.value = this.errorOpacity;
+        }
+        if (material.uniforms.fillProgress) {
+          material.uniforms.fillProgress.value = 0;
+        }
+        if (material.uniforms.isError) {
+          material.uniforms.isError.value = 1;
+        }
+      }
+    }
+  }
+  /**
+   * Update placeholder animation time (call this in your render loop)
+   */
+  updatePlaceholderAnimation(deltaTime) {
+    if (this.placeholder && this.placeholder instanceof THREE.Mesh) {
+      const material = this.placeholder.material;
+      if (material.uniforms && material.uniforms.time) {
+        material.uniforms.time.value += deltaTime;
+      }
+    }
+  }
+  /**
+   * Reposition an asset so that its bottom-center sits at the local origin.
+   */
+  positionAssetAtBottomCenter(object) {
+    object.updateMatrixWorld(true);
+    const boundingBox = new THREE.Box3().setFromObject(object);
+    if (boundingBox.isEmpty()) {
+      return;
+    }
+    const center = boundingBox.getCenter(new THREE.Vector3());
+    const bottomCenter = new THREE.Vector3(
+      center.x,
+      boundingBox.min.y + 0.01,
+      center.z
+    );
+    if (!Number.isFinite(bottomCenter.x) || !Number.isFinite(bottomCenter.y) || !Number.isFinite(bottomCenter.z)) {
+      return;
+    }
+    object.position.sub(bottomCenter);
+    object.userData.bottomCenterOffset = bottomCenter;
+    object.updateMatrixWorld(true);
+  }
+  ensureBottomCenterOffset(object) {
+    const offset = object.userData.bottomCenterOffset;
+    if (offset instanceof THREE.Vector3) {
+      return offset;
+    }
+    if (offset && typeof offset === "object") {
+      const {
+        x = 0,
+        y = 0,
+        z = 0
+      } = offset;
+      const normalized = new THREE.Vector3(x ?? 0, y ?? 0, z ?? 0);
+      object.userData.bottomCenterOffset = normalized;
+      return normalized;
+    }
+    return null;
+  }
+  normalizeBottomCenterData(object) {
+    const hasOffset = this.ensureBottomCenterOffset(object) !== null;
+    object.children.forEach((child) => this.normalizeBottomCenterData(child));
+    return hasOffset;
+  }
+  /**
+   * Load an asset with the specified options
+   */
+  async load(options) {
+    const {
+      type,
+      url,
+      size,
+      lowResUrl,
+      enableCaching = true,
+      placeholderColor = 5227511,
+      placeholderOpacity = 0.8,
+      errorColor = 16729156,
+      errorOpacity = 0.5
+    } = options;
+    if (enableCaching && this.cache.has(url)) {
+      const cachedClone = this.cache.get(url).clone(true);
+      const hasOffset = this.normalizeBottomCenterData(cachedClone);
+      if (!hasOffset) {
+        this.positionAssetAtBottomCenter(cachedClone);
+      } else {
+        cachedClone.updateMatrixWorld(true);
+      }
+      this.loadedAsset = cachedClone;
+      this.dispatchEvent({ type: "loaded", asset: cachedClone });
+      return cachedClone;
+    }
+    this.errorColor = errorColor;
+    this.errorOpacity = errorOpacity;
+    if (size) {
+      this.placeholder = this.createPlaceholder(
+        size,
+        placeholderColor,
+        placeholderOpacity
+      );
+      this.dispatchEvent({
+        type: "placeholderCreated",
+        placeholder: this.placeholder
+      });
+    }
+    try {
+      if (lowResUrl) {
+        const lowRes = await this.loadModel(type, lowResUrl, true);
+        this.lowResAsset = lowRes;
+        this.dispatchEvent({ type: "lowResLoaded", lowRes });
+      }
+      const asset = await this.loadModel(type, url, false);
+      this.loadedAsset = asset;
+      if (enableCaching) {
+        const cacheEntry = asset.clone(true);
+        const hasOffset = this.normalizeBottomCenterData(cacheEntry);
+        if (!hasOffset) {
+          this.positionAssetAtBottomCenter(cacheEntry);
+        } else {
+          cacheEntry.updateMatrixWorld(true);
+        }
+        this.cache.set(url, cacheEntry);
+      }
+      this.dispatchEvent({ type: "loaded", asset });
+      return asset;
+    } catch (error) {
+      this.setPlaceholderError();
+      this.dispatchEvent({ type: "error", error });
+      throw error;
+    }
+  }
+  /**
+   * Load a model based on type
+   */
+  loadModel(type, url, isLowRes) {
+    return new Promise((resolve, reject) => {
+      const onProgress = (event) => {
+        const percentage = event.loaded / event.total * 100;
+        this.dispatchEvent({
+          type: "progress",
+          loaded: event.loaded,
+          total: event.total,
+          percentage
+        });
+        if (!isLowRes) {
+          this.updatePlaceholder(percentage / 100);
+        }
+      };
+      const onError = (error) => {
+        reject(error);
+      };
+      switch (type) {
+        case "gltf":
+          this.gltfLoader.load(
+            url,
+            (gltf) => {
+              const scene = gltf.scene;
+              this.positionAssetAtBottomCenter(scene);
+              resolve(scene);
+            },
+            onProgress,
+            onError
+          );
+          break;
+        case "fbx":
+          this.fbxLoader.load(
+            url,
+            (fbx) => {
+              this.positionAssetAtBottomCenter(fbx);
+              resolve(fbx);
+            },
+            onProgress,
+            onError
+          );
+          break;
+        case "obj":
+          this.objLoader.load(
+            url,
+            (obj) => {
+              this.positionAssetAtBottomCenter(obj);
+              resolve(obj);
+            },
+            onProgress,
+            onError
+          );
+          break;
+        default:
+          reject(new Error(`Unsupported asset type: ${type}`));
+      }
+    });
+  }
+  /**
+   * Get the placeholder object
+   */
+  getPlaceholder() {
+    return this.placeholder;
+  }
+  /**
+   * Get the loaded asset
+   */
+  getAsset() {
+    return this.loadedAsset;
+  }
+  /**
+   * Get the low-res asset
+   */
+  getLowResAsset() {
+    return this.lowResAsset;
+  }
+  /**
+   * Clear the cache
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+  /**
+   * Remove an item from cache
+   */
+  removeFromCache(url) {
+    this.cache.delete(url);
+  }
+  /**
+   * Get cache size
+   */
+  getCacheSize() {
+    return this.cache.size;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AssetLoader
+});
+//# sourceMappingURL=index.cjs.map