@fusefactory/fuse-three-forcegraph 1.0.5 → 1.0.7

package/README.md

@@ -15,25 +15,33 @@ A high-performance GPU-accelerated force-directed graph visualization library bu
 ### Core Components
 
 #### Engine (`core/Engine.ts`)
+
 The main orchestrator that owns and coordinates all components:
+
 - Manages shared GPU buffers (SimulationBuffers, StaticAssets, PickBuffer)
 - Coordinates GraphStore, GraphScene, and ForceSimulation
 - Handles the render loop and user interactions
 
 #### SimulationBuffers (`textures/SimulationBuffers.ts`)
+
 Manages dynamic render targets updated by force simulation:
+
 - Position buffers (current, previous, original) for ping-pong rendering
 - Velocity buffers for force accumulation
 - Automatically sizes textures based on node count
 
 #### StaticAssets (`textures/StaticAssets.ts`)
+
 Manages read-only GPU textures:
+
 - Node radii and colors
 - Link indices and properties
 - Created once at initialization, updated only on mode changes
 
 #### GraphScene (`rendering/GraphScene.ts`)
+
 Manages the 3D scene and visual rendering:
+
 - Node and link renderers
 - Camera controls
 - Visual mode application
@@ -43,7 +51,9 @@ Manages the 3D scene and visual rendering:
 The simulation uses a **pass-based architecture** where each force type is implemented as an independent pass:
 
 #### BasePass (`simulation/BasePass.ts`)
+
 Abstract base class for all force passes. Provides:
+
 - Material management
 - Uniform updates
 - Enable/disable control
@@ -63,7 +73,9 @@ Located in `simulation/passes/`:
 8. **IntegratePass** - Updates positions from velocities
 
 #### ForceSimulation (`simulation/ForceSimulation.ts`)
+
 Manages and executes force passes:
+
 ```typescript
 // Add custom force pass
 simulation.addPass('myForce', new MyCustomPass(config))
@@ -121,43 +133,42 @@ engine.setData(graphData)
 // Start simulation and rendering
 engine.start()
 
-  GRAPH.styleRegistry.setNodeStyles({
-      'root': { color: 0xE53E3E, size: 55 },
-      'series': { color: 0x38A169, size: 33 },
-      'artwork': { color: 0x3182CE, size: 22 },
-    })
-
-  // Get simulation config - direct access, changes take effect immediately
-  const simulation = engine.getSimulation()
-  const config = simulation.config
+GRAPH.styleRegistry.setNodeStyles({
+  root: { color: 0xE53E3E, size: 55 },
+  series: { color: 0x38A169, size: 33 },
+  artwork: { color: 0x3182CE, size: 22 },
+})
 
-  // Create Tweakpane
-  pane = new Pane()
+// Get simulation config - direct access, changes take effect immediately
+const simulation = engine.getSimulation()
+const config = simulation.config
 
-  // Bind simulation parameters - changes to config work directly, no sync needed
-  const simFolder = pane.addFolder({ title: 'Simulation' })
-  simFolder.addBinding(config, 'alpha', { min: 0, max: 1 })
-  simFolder.addBinding(config, 'alphaDecay', { min: 0, max: 0.1 })
-  simFolder.addBinding(config, 'damping', { min: 0, max: 1 })
+// Create Tweakpane
+pane = new Pane()
 
-  // Many-body force, check uniforms that can be added in binding...
-  const manyBodyFolder = pane.addFolder({ title: 'Many-Body Force' })
-  manyBodyFolder.addBinding(config, 'enableManyBody')
-  manyBodyFolder.addBinding(config, 'manyBodyStrength', { min: 0, max: 100 })
+// Bind simulation parameters - changes to config work directly, no sync needed
+const simFolder = pane.addFolder({ title: 'Simulation' })
+simFolder.addBinding(config, 'alpha', { min: 0, max: 1 })
+simFolder.addBinding(config, 'alphaDecay', { min: 0, max: 0.1 })
+simFolder.addBinding(config, 'damping', { min: 0, max: 1 })
 
+// Many-body force, check uniforms that can be added in binding...
+const manyBodyFolder = pane.addFolder({ title: 'Many-Body Force' })
+manyBodyFolder.addBinding(config, 'enableManyBody')
+manyBodyFolder.addBinding(config, 'manyBodyStrength', { min: 0, max: 100 })
 
-  // Set up attractors - each pulls specific categories
-  simulation.setAttractors([
+// Set up attractors - each pulls specific categories
+simulation.setAttractors([
   {
     id: 'center',
     position: { x: 0, y: 0.0, z: 0 },
-    categories: ['root'],  
-    strength: 55.
-  },])
-
-  // Adjust global attractor strength
-  simulation.config.attractorStrength = 0.03
+    categories: ['root'],
+    strength: 55.0
+  },
+])
 
+// Adjust global attractor strength
+simulation.config.attractorStrength = 0.03
 
 ```
 
@@ -167,9 +178,9 @@ For testing and prototyping, you can generate random graph data:
 
 ```typescript
 // Utility function to create random nodes and links
-const createRandomData = (nodeCount: number = 10, linkCount: number = 15) => {
+function createRandomData(nodeCount: number = 10, linkCount: number = 15) {
   const groups = ['root', 'series', 'artwork', 'character', 'location']
-  
+
   // Generate random nodes
   const nodes = Array.from({ length: nodeCount }, (_, i) => ({
     id: (i + 1).toString(),
@@ -178,23 +189,23 @@ const createRandomData = (nodeCount: number = 10, linkCount: number = 15) => {
     y: (Math.random() - 0.5) * 2,
     z: (Math.random() - 0.5) * 2
   }))
-  
+
   // Generate random links
   const links = Array.from({ length: linkCount }, () => {
     const sourceId = Math.floor(Math.random() * nodeCount) + 1
     let targetId = Math.floor(Math.random() * nodeCount) + 1
-    
+
     // Ensure source and target are different
     while (targetId === sourceId) {
       targetId = Math.floor(Math.random() * nodeCount) + 1
     }
-    
+
     return {
       source: sourceId.toString(),
       target: targetId.toString()
     }
   })
-  
+
   return { nodes, links }
 }
 
@@ -205,7 +216,8 @@ engine.setData(createRandomData(100, 70))
 ### Custom Force Pass
 
 ```typescript
-import { BasePass, type PassContext } from './simulation/BasePass'
+import type { PassContext } from './simulation/BasePass'
+import { BasePass } from './simulation/BasePass'
 
 class CustomForcePass extends BasePass {
   private strength: number = 1.0
@@ -228,12 +240,13 @@ class CustomForcePass extends BasePass {
   }
 
   updateUniforms(context: PassContext): void {
-    if (!this.material) return
-    
-    this.material.uniforms.uPositionsTexture.value = 
-      context.simBuffers.getCurrentPositionTexture()
-    this.material.uniforms.uVelocityTexture.value = 
-      context.simBuffers.getCurrentVelocityTexture()
+    if (!this.material)
+      return
+
+    this.material.uniforms.uPositionsTexture.value
+      = context.simBuffers.getCurrentPositionTexture()
+    this.material.uniforms.uVelocityTexture.value
+      = context.simBuffers.getCurrentVelocityTexture()
     this.material.uniforms.uAlpha.value = context.alpha
     this.material.uniforms.uStrength.value = this.strength
   }
@@ -309,12 +322,14 @@ fuse-three-forcegraph/
 ## GPU Texture Layout
 
 ### Position/Velocity Buffers
+
 - Format: `RGBA Float`
 - Layout: Grid where each pixel = one node
 - Channels: `(x, y, z, unused)`
 - Size: Next power-of-2 square ≥ √nodeCount
 
 ### Static Assets
+
 - **Radii**: `Red Float` (1 channel)
 - **Colors**: `RGBA Float` (4 channels)
 - **Link Indices**: `RGBA Float` (source_x, source_y, target_x, target_y)
@@ -332,9 +347,10 @@ fuse-three-forcegraph/
 The library implements a three-tiered interaction system for progressive engagement:
 
 ### 1. Hover
+
 - **Trigger**: Mouse cursor enters node boundary
 - **Purpose**: Lightweight preview and visual feedback
-- **Response**: 
+- **Response**:
   - Node highlight/glow effect
   - Cursor change
   - Optional tooltip display
@@ -342,6 +358,7 @@ The library implements a three-tiered interaction system for progressive engagem
 - **Use Case**: Quick scanning and exploration
 
 ### 2. Pop (Dwell/Long Hover)
+
 - **Trigger**: Cursor remains over node for defined duration (e.g., 500ms)
 - **Purpose**: Detailed information display without commitment
 - **Response**:
@@ -352,6 +369,7 @@ The library implements a three-tiered interaction system for progressive engagem
 - **Use Case**: Examining node details and immediate connections
 
 ### 3. Click
+
 - **Trigger**: Primary mouse button click on node
 - **Purpose**: Full interaction and state change
 - **Response**:
@@ -363,6 +381,7 @@ The library implements a three-tiered interaction system for progressive engagem
 - **Use Case**: Focused analysis and permanent selection
 
 ### Interaction Pipeline
+
 ```typescript
 // Hover
 interactionManager.on('hover', ({ node, position }) => {
@@ -394,4 +413,3 @@ This progressive disclosure pattern prevents overwhelming users while enabling d
 - **three.js** - 3D rendering engine
 - **camera-controls** - Camera manipulation
 - **gsap** - Animation and transitions
-