r3f-peridot 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Christian Dimitri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,333 @@
+# 💎 Peridot
+
+### High-Quality Outlines for React Three Fiber - GLTF, IFC & Beyond
+
+[![npm version](https://badge.fury.io/js/r3f-peridot.svg)](https://www.npmjs.com/package/r3f-peridot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Peridot** brings professional-grade outline rendering to React Three Fiber. Perfect for architectural visualization, BIM workflows, CAD applications, and any 3D model that needs crisp, clean edges.
+
+![Peridot Demo](https://via.placeholder.com/800x400?text=Peridot+Demo)
+
+## ✨ Why Peridot?
+
+- 🏗️ **IFC Support** - First-class support for Building Information Modeling (BIM/IFC) files
+- 📦 **GLTF Ready** - Works seamlessly with GLTF/GLB models
+- 🎨 **High-Quality** - Uses advanced depth, normal, and surface ID detection
+- ⚡ **Performant** - Efficient post-processing shader implementation
+- 🎛️ **Customizable** - Full control over outline appearance
+- 🔍 **Debug Modes** - Multiple visualization modes for fine-tuning
+- 📦 **TypeScript** - Full type definitions included
+- 🌲 **Tree-Shakeable** - Optimized bundle size
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install r3f-peridot
+```
+
+```bash
+yarn add r3f-peridot
+```
+
+```bash
+pnpm add r3f-peridot
+```
+
+### Basic Usage
+
+```tsx
+import { Canvas } from '@react-three/fiber'
+import { OutlineEffect } from 'r3f-peridot'
+
+function Scene() {
+  return (
+    <Canvas>
+      <OutlineEffect outlineColor="#ffffff" />
+      
+      {/* Your 3D content */}
+      <mesh>
+        <boxGeometry />
+        <meshStandardMaterial />
+      </mesh>
+    </Canvas>
+  )
+}
+```
+
+### With GLTF Models
+
+```tsx
+import { useGLTF } from '@react-three/drei'
+import { OutlineEffect } from 'r3f-peridot'
+
+function Model() {
+  const { scene } = useGLTF('/model.glb')
+  return <primitive object={scene} />
+}
+
+function App() {
+  return (
+    <Canvas>
+      <OutlineEffect outlineColor="#00ff00" />
+      <Model />
+    </Canvas>
+  )
+}
+```
+
+### With IFC Models 🏗️
+
+```tsx
+import { IFCLoader } from 'web-ifc-three/IFCLoader'
+import { OutlineEffect } from 'r3f-peridot'
+import { useEffect, useState } from 'react'
+
+function IFCModel({ url }) {
+  const [model, setModel] = useState(null)
+
+  useEffect(() => {
+    const loader = new IFCLoader()
+    loader.load(url, setModel)
+  }, [url])
+
+  return model ? <primitive object={model} /> : null
+}
+
+function App() {
+  return (
+    <Canvas>
+      <OutlineEffect 
+        outlineColor="#0080ff"
+        depthMultiplier={25.0}
+      />
+      <IFCModel url="/building.ifc" />
+    </Canvas>
+  )
+}
+```
+
+## 📖 API Reference
+
+### `<OutlineEffect />`
+
+The main component that adds outline post-processing to your R3F scene.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Enable or disable the effect |
+| `outlineColor` | `string \| THREE.Color` | `'#ffffff'` | Color of the outline |
+| `depthBias` | `number` | `0.9` | Bias for depth-based edge detection (0-2) |
+| `depthMultiplier` | `number` | `20.0` | Multiplier for depth-based edges (0-50) |
+| `normalBias` | `number` | `1.0` | Bias for normal-based edge detection (0-2) |
+| `normalMultiplier` | `number` | `1.0` | Multiplier for normal-based edges (0-10) |
+| `debugVisualize` | `number` | `0` | Debug visualization mode (see below) |
+
+#### Debug Visualization Modes
+
+- `0` - **Outlines V2** (Surface ID based) - Best for CAD/BIM models
+- `1` - **Outlines V1** (Depth/Normal based) - Alternative method
+- `2` - **Original Scene** - No outline effect
+- `3` - **Depth Buffer** - Visualize depth information
+- `4` - **Normal Buffer** - Visualize normal information
+- `5` - **Surface ID Buffer** - Visualize surface IDs (random colors)
+- `6` - **Outlines Only** - Show only the outline effect
+
+## 🎨 Advanced Usage
+
+### Custom Outline Colors
+
+```tsx
+import * as THREE from 'three'
+
+// Using hex string
+<OutlineEffect outlineColor="#ff0000" />
+
+// Using THREE.Color
+<OutlineEffect outlineColor={new THREE.Color('hotpink')} />
+
+// Dynamic colors
+const [color, setColor] = useState('#00ff00')
+<OutlineEffect outlineColor={color} />
+```
+
+### Fine-Tuning for Different Models
+
+```tsx
+// For architectural/BIM models (IFC)
+<OutlineEffect
+  outlineColor="#0080ff"
+  depthBias={0.8}
+  depthMultiplier={25.0}
+  debugVisualize={0} // Use Surface ID mode
+/>
+
+// For organic/smooth models
+<OutlineEffect
+  outlineColor="#ffffff"
+  depthBias={1.2}
+  depthMultiplier={15.0}
+  normalMultiplier={1.5}
+  debugVisualize={1} // Use Depth/Normal mode
+/>
+
+// For mechanical/CAD models
+<OutlineEffect
+  outlineColor="#000000"
+  depthBias={0.6}
+  depthMultiplier={30.0}
+  debugVisualize={0} // Use Surface ID mode
+/>
+```
+
+### Conditional Outlines
+
+```tsx
+function Scene() {
+  const [showOutlines, setShowOutlines] = useState(true)
+  
+  return (
+    <Canvas>
+      <OutlineEffect enabled={showOutlines} />
+      {/* Your scene */}
+    </Canvas>
+  )
+}
+```
+
+## 🏗️ IFC & BIM Workflows
+
+Peridot is designed with AEC (Architecture, Engineering, Construction) workflows in mind:
+
+### Perfect for:
+- 📐 **Architectural Visualization** - Clean edges for buildings
+- 🏢 **BIM Model Review** - Clear element boundaries
+- 🏗️ **Construction Planning** - Highlight different components
+- 📊 **Facility Management** - Visual clarity for complex structures
+- 🎓 **Educational Content** - Clear technical drawings
+
+### IFC Best Practices
+
+```tsx
+// Recommended settings for IFC models
+<OutlineEffect
+  outlineColor="#003366" // Professional dark blue
+  depthBias={0.8}
+  depthMultiplier={25.0}
+  normalBias={1.0}
+  normalMultiplier={1.0}
+  debugVisualize={0} // Surface ID mode for clean element separation
+/>
+```
+
+## 🛠️ Utility Functions
+
+### `FindSurfaces`
+
+Computes surface IDs for meshes based on vertex connectivity.
+
+```tsx
+import { FindSurfaces } from 'r3f-peridot'
+
+const findSurfaces = new FindSurfaces()
+const surfaceIdAttribute = findSurfaces.getSurfaceIdAttribute(mesh)
+```
+
+### `weldVertices`
+
+Merges vertices along edges for improved outline quality.
+
+```tsx
+import { weldVertices } from 'r3f-peridot'
+
+const newIndices = weldVertices(vertices, indices, thresholdAngle)
+```
+
+### `CustomOutlinePass`
+
+Direct access to the Three.js post-processing pass.
+
+```tsx
+import { CustomOutlinePass } from 'r3f-peridot'
+```
+
+## 🎯 Examples
+
+Check out the `/examples` directory for complete working examples:
+
+- **Basic Example** - Simple scene with primitive geometry
+- **GLTF Models** - Loading and outlining GLTF/GLB files
+- **IFC Models** - Working with Building Information Models
+- **Interactive Controls** - Real-time parameter adjustment
+
+To run examples locally:
+
+```bash
+cd examples
+npm install
+npm run dev
+```
+
+## 🎓 How It Works
+
+Peridot uses the [webgl-outlines technique](https://github.com/OmarShehata/webgl-outlines) by Omar Shehata:
+
+1. **Render Passes** - Scene is rendered to depth, normal, and surface ID buffers
+2. **Edge Detection** - Post-process shader detects edges based on buffer differences
+3. **Outline Rendering** - Detected edges are rendered as colored outlines
+4. **Anti-Aliasing** - FXAA pass ensures smooth, crisp edges
+
+This approach provides:
+- ✅ High-quality outlines on any geometry
+- ✅ No special mesh preparation required
+- ✅ Works with any material
+- ✅ Minimal performance impact
+
+## 📊 Performance
+
+- **Bundle Size**: ~27 KB (minified)
+- **Runtime**: < 1ms per frame (typical)
+- **Memory**: Minimal overhead (2-3 render targets)
+- **Compatibility**: WebGL 2.0+ required
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## 📝 License
+
+MIT © Christian Dimitri
+
+## 🙏 Acknowledgments
+
+- [Omar Shehata](https://github.com/OmarShehata) for the original [webgl-outlines](https://github.com/OmarShehata/webgl-outlines) technique
+- [Three.js](https://threejs.org/) for the amazing 3D library
+- [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) for the React renderer
+- [IFC.js](https://ifcjs.github.io/info/) for IFC support
+
+## 📚 Resources
+
+- [Documentation](https://github.com/yourusername/r3f-peridot#readme)
+- [Examples](https://github.com/yourusername/r3f-peridot/tree/main/examples)
+- [Issues](https://github.com/yourusername/r3f-peridot/issues)
+- [WebGL Outlines Blog Post](https://omar-shehata.medium.com/how-to-render-outlines-in-webgl-8253c14724f9)
+
+## 🌟 Show Your Support
+
+If you find Peridot useful, please:
+- ⭐ Star the repository
+- 🐦 Share on social media
+- 📝 Write a blog post
+- 🎥 Create a tutorial
+
+---
+
+**Made with 💚 for the open source community**
+
+*"Precision outlines for every model" - Peridot* 💎

package/dist/index.d.mts

@@ -0,0 +1,125 @@
+import * as react from 'react';
+import * as THREE from 'three';
+import { Pass, FullScreenQuad } from 'three/examples/jsm/postprocessing/Pass.js';
+
+interface OutlineEffectProps {
+    /** Enable or disable the outline effect */
+    enabled?: boolean;
+    /** Color of the outline (THREE.Color or hex string) */
+    outlineColor?: THREE.Color | string;
+    /** Depth bias for edge detection (default: 0.9) */
+    depthBias?: number;
+    /** Depth multiplier for edge detection (default: 20.0) */
+    depthMultiplier?: number;
+    /** Normal bias for edge detection (default: 1.0) */
+    normalBias?: number;
+    /** Normal multiplier for edge detection (default: 1.0) */
+    normalMultiplier?: number;
+    /**
+     * Debug visualization mode (default: 0)
+     * - 0: Outlines V2 (surface ID based)
+     * - 1: Outlines V1 (depth/normal based)
+     * - 2: Original scene
+     * - 3: Depth buffer
+     * - 4: Normal buffer
+     * - 5: SurfaceID debug buffer
+     * - 6: Outlines only V2
+     */
+    debugVisualize?: number;
+    /** Array of objects to apply outlines to (currently not used, reserved for future) */
+    selectedObjects?: THREE.Object3D[];
+}
+interface OutlineEffectRef {
+    /** Update the maximum surface ID for proper normalization */
+    updateMaxSurfaceId: (maxSurfaceId: number) => void;
+}
+/**
+ * OutlineEffect - A React Three Fiber component that adds post-processing outline effects
+ * to your 3D scene using depth, normals, and surface ID detection.
+ *
+ * Based on the webgl-outlines technique by Omar Shehata
+ * https://github.com/OmarShehata/webgl-outlines
+ *
+ * @example
+ * ```tsx
+ * import { Canvas } from '@react-three/fiber'
+ * import { OutlineEffect } from 'r3f-gltf-outlines'
+ *
+ * function Scene() {
+ *   return (
+ *     <>
+ *       <OutlineEffect
+ *         outlineColor="#ffffff"
+ *         depthBias={0.9}
+ *         depthMultiplier={20.0}
+ *       />
+ *       <mesh>
+ *         <boxGeometry />
+ *         <meshStandardMaterial />
+ *       </mesh>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+declare const OutlineEffect: react.ForwardRefExoticComponent<OutlineEffectProps & react.RefAttributes<OutlineEffectRef>>;
+
+declare class FindSurfaces {
+    surfaceId: number;
+    constructor();
+    getSurfaceIdAttribute(mesh: THREE.Mesh): Float32Array;
+    _generateSurfaceIds(mesh: THREE.Mesh): {
+        [key: number]: number;
+    };
+}
+
+declare function getSurfaceIdMaterial(): THREE.ShaderMaterial;
+declare function getDebugSurfaceIdMaterial(): THREE.ShaderMaterial;
+
+/**
+ * CustomOutlinePass - A post-processing pass that renders outlines based on depth,
+ * normals, and surface IDs.
+ *
+ * Based on the webgl-outlines technique by Omar Shehata
+ * https://github.com/OmarShehata/webgl-outlines
+ */
+declare class CustomOutlinePass extends Pass {
+    renderScene: THREE.Scene;
+    renderCamera: THREE.Camera;
+    resolution: THREE.Vector2;
+    fsQuad: FullScreenQuad;
+    surfaceBuffer: THREE.WebGLRenderTarget;
+    normalOverrideMaterial: THREE.MeshNormalMaterial;
+    surfaceIdOverrideMaterial: THREE.ShaderMaterial;
+    surfaceIdDebugOverrideMaterial: THREE.ShaderMaterial;
+    constructor(resolution: THREE.Vector2, scene: THREE.Scene, camera: THREE.Camera);
+    dispose(): void;
+    updateMaxSurfaceId(maxSurfaceId: number): void;
+    setSize(width: number, height: number): void;
+    getDebugVisualizeValue(): any;
+    isUsingSurfaceIds(): boolean;
+    render(renderer: THREE.WebGLRenderer, writeBuffer: THREE.WebGLRenderTarget, readBuffer: THREE.WebGLRenderTarget): void;
+    get vertexShader(): string;
+    get fragmentShader(): string;
+    createOutlinePostProcessMaterial(): THREE.ShaderMaterial;
+}
+
+/**
+ * Merges together vertices along the edges between triangles
+ * whose angle is below the given threshold.
+ *
+ * @param {number[]} vertices - Array of (x,y,z) positions as a flat list.
+ * @param {number[]} indices - Array of indices of (v1, v2, v3) that define the triangles.
+ * @param {number} [thresholdAngle=1] - In degrees. When the angle between the face normals
+ *  of 2 triangles is less than this threshold, the vertices along their shared edge are merged.
+ * @returns {number[]} - A new index buffer without the extra vertices.
+ */
+declare function weldVertices(vertices: number[], indices: number[], thresholdAngle?: number): number[];
+
+/**
+ * Hook that computes and applies surface IDs to all meshes in the scene
+ * This is required for outline V2 (surface ID based outlines) to work
+ */
+declare function useSurfaceIds(enabled?: boolean): void;
+
+export { CustomOutlinePass, FindSurfaces, OutlineEffect, type OutlineEffectProps, type OutlineEffectRef, getDebugSurfaceIdMaterial, getSurfaceIdMaterial, useSurfaceIds, weldVertices };

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+import * as react from 'react';
+import * as THREE from 'three';
+import { Pass, FullScreenQuad } from 'three/examples/jsm/postprocessing/Pass.js';
+
+interface OutlineEffectProps {
+    /** Enable or disable the outline effect */
+    enabled?: boolean;
+    /** Color of the outline (THREE.Color or hex string) */
+    outlineColor?: THREE.Color | string;
+    /** Depth bias for edge detection (default: 0.9) */
+    depthBias?: number;
+    /** Depth multiplier for edge detection (default: 20.0) */
+    depthMultiplier?: number;
+    /** Normal bias for edge detection (default: 1.0) */
+    normalBias?: number;
+    /** Normal multiplier for edge detection (default: 1.0) */
+    normalMultiplier?: number;
+    /**
+     * Debug visualization mode (default: 0)
+     * - 0: Outlines V2 (surface ID based)
+     * - 1: Outlines V1 (depth/normal based)
+     * - 2: Original scene
+     * - 3: Depth buffer
+     * - 4: Normal buffer
+     * - 5: SurfaceID debug buffer
+     * - 6: Outlines only V2
+     */
+    debugVisualize?: number;
+    /** Array of objects to apply outlines to (currently not used, reserved for future) */
+    selectedObjects?: THREE.Object3D[];
+}
+interface OutlineEffectRef {
+    /** Update the maximum surface ID for proper normalization */
+    updateMaxSurfaceId: (maxSurfaceId: number) => void;
+}
+/**
+ * OutlineEffect - A React Three Fiber component that adds post-processing outline effects
+ * to your 3D scene using depth, normals, and surface ID detection.
+ *
+ * Based on the webgl-outlines technique by Omar Shehata
+ * https://github.com/OmarShehata/webgl-outlines
+ *
+ * @example
+ * ```tsx
+ * import { Canvas } from '@react-three/fiber'
+ * import { OutlineEffect } from 'r3f-gltf-outlines'
+ *
+ * function Scene() {
+ *   return (
+ *     <>
+ *       <OutlineEffect
+ *         outlineColor="#ffffff"
+ *         depthBias={0.9}
+ *         depthMultiplier={20.0}
+ *       />
+ *       <mesh>
+ *         <boxGeometry />
+ *         <meshStandardMaterial />
+ *       </mesh>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+declare const OutlineEffect: react.ForwardRefExoticComponent<OutlineEffectProps & react.RefAttributes<OutlineEffectRef>>;
+
+declare class FindSurfaces {
+    surfaceId: number;
+    constructor();
+    getSurfaceIdAttribute(mesh: THREE.Mesh): Float32Array;
+    _generateSurfaceIds(mesh: THREE.Mesh): {
+        [key: number]: number;
+    };
+}
+
+declare function getSurfaceIdMaterial(): THREE.ShaderMaterial;
+declare function getDebugSurfaceIdMaterial(): THREE.ShaderMaterial;
+
+/**
+ * CustomOutlinePass - A post-processing pass that renders outlines based on depth,
+ * normals, and surface IDs.
+ *
+ * Based on the webgl-outlines technique by Omar Shehata
+ * https://github.com/OmarShehata/webgl-outlines
+ */
+declare class CustomOutlinePass extends Pass {
+    renderScene: THREE.Scene;
+    renderCamera: THREE.Camera;
+    resolution: THREE.Vector2;
+    fsQuad: FullScreenQuad;
+    surfaceBuffer: THREE.WebGLRenderTarget;
+    normalOverrideMaterial: THREE.MeshNormalMaterial;
+    surfaceIdOverrideMaterial: THREE.ShaderMaterial;
+    surfaceIdDebugOverrideMaterial: THREE.ShaderMaterial;
+    constructor(resolution: THREE.Vector2, scene: THREE.Scene, camera: THREE.Camera);
+    dispose(): void;
+    updateMaxSurfaceId(maxSurfaceId: number): void;
+    setSize(width: number, height: number): void;
+    getDebugVisualizeValue(): any;
+    isUsingSurfaceIds(): boolean;
+    render(renderer: THREE.WebGLRenderer, writeBuffer: THREE.WebGLRenderTarget, readBuffer: THREE.WebGLRenderTarget): void;
+    get vertexShader(): string;
+    get fragmentShader(): string;
+    createOutlinePostProcessMaterial(): THREE.ShaderMaterial;
+}
+
+/**
+ * Merges together vertices along the edges between triangles
+ * whose angle is below the given threshold.
+ *
+ * @param {number[]} vertices - Array of (x,y,z) positions as a flat list.
+ * @param {number[]} indices - Array of indices of (v1, v2, v3) that define the triangles.
+ * @param {number} [thresholdAngle=1] - In degrees. When the angle between the face normals
+ *  of 2 triangles is less than this threshold, the vertices along their shared edge are merged.
+ * @returns {number[]} - A new index buffer without the extra vertices.
+ */
+declare function weldVertices(vertices: number[], indices: number[], thresholdAngle?: number): number[];
+
+/**
+ * Hook that computes and applies surface IDs to all meshes in the scene
+ * This is required for outline V2 (surface ID based outlines) to work
+ */
+declare function useSurfaceIds(enabled?: boolean): void;
+
+export { CustomOutlinePass, FindSurfaces, OutlineEffect, type OutlineEffectProps, type OutlineEffectRef, getDebugSurfaceIdMaterial, getSurfaceIdMaterial, useSurfaceIds, weldVertices };