Three.js Graph Geometry

An extension for Three.js that turns graphs (nodes + edges) into reusable 3D geometries with a modular, extensible architecture.

✨ Features

• 🎯 14 Built-in Graph Presets: From basic shapes (cube, pyramid) to complex networks (star, lattice, paths)
• 🎨 Customizable Styling: Full control over node/edge colors, sizes, and materials
• 🏹 Directed Graph Support: 3D arrow visualization for directed edges
• 🎛️ Interactive GUI: Real-time parameter adjustment with lil-gui integration
• 🧩 Modular Architecture: Clean separation of concerns with organized modules
• 🔧 Custom Preset System: Register your own graph generation functions
• 📐 Per-Node Customization: Individual node radii and colors
• 🎪 Path Merging: Smart vertex merging for complex path networks

📦 Installation

npm install three-graph-geometry

🚀 Quick Start

Basic Usage

import * as THREE from 'three';
import { GraphGeometry } from 'three-graph-geometry';

const scene = new THREE.Scene();

// Create a cube graph
const cubeGraph = new GraphGeometry('cube', 1, { includeFaceCenters: true }, {
  nodeColor: 0x4ecdc4,
  edgeColor: 0x45b7d1,
  nodeRadius: 0.12,
  edgeRadius: 0.02
});
scene.add(cubeGraph);

// Create a star network with custom styling
const starGraph = new GraphGeometry('star', 8, 2, {
  nodeColor: 0xff6b6b,
  edgeColor: 0x4ecdc4,
  nodeRadius: 0.2,
  directed: true
});
scene.add(starGraph);

With Full Demo Setup

import { SceneManager } from 'three-graph-geometry/core/Scene';
import { GraphGeometry } from 'three-graph-geometry';
import { ParameterManager } from 'three-graph-geometry/gui/ParameterManager';
import { GUIController } from 'three-graph-geometry/gui/GUIController';

class GraphApp {
  constructor() {
    this.sceneManager = new SceneManager('canvas-id');
    this.parameterManager = new ParameterManager();
    this.guiController = new GUIController(
      this.parameterManager, 
      () => this.updateGraph()
    );
    
    this.updateGraph();
    this.sceneManager.start();
  }

  updateGraph() {
    // Remove old graph
    if (this.currentGraph) {
      this.sceneManager.remove(this.currentGraph);
      this.currentGraph.dispose();
    }

    // Create new graph
    this.parameterManager.allocatePerNodeArrays();
    const styleOptions = this.parameterManager.getStyleOptions();
    const presetParams = this.parameterManager.getPresetParameters();

    this.currentGraph = new GraphGeometry(
      this.parameterManager.params.preset,
      ...presetParams,
      styleOptions
    );

    this.sceneManager.add(this.currentGraph);
  }
}

new GraphApp();

📋 API Documentation

GraphGeometry Class

new GraphGeometry(type, ...params, options)

Parameters:

• type (string): Preset name or registered custom preset
• ...params: Preset-specific parameters
• options (object): Styling and rendering options

Options Object:

{
  nodeRadius: 0.12,      // Default node radius
  edgeRadius: 0.02,      // Default edge radius  
  nodeColor: 0x00ffff,   // Default node color (hex)
  edgeColor: 0xffffff,   // Default edge color (hex)
  nodeSegments: 16,      // Node sphere detail
  edgeSegments: 8,       // Edge cylinder detail
  directed: false,       // Enable 3D arrows
  arrowSize: 0.18,       // Arrow size multiplier
  arrowSegments: 8,      // Arrow cone detail
  nodeRadii: null,       // Per-node radius array
  nodeColors: null       // Per-node color array/function
}

Custom Preset Registration

import { registerPreset } from 'three-graph-geometry';

registerPreset('myCustomGraph', (param1, param2) => {
  const nodes = [
    new THREE.Vector3(0, 0, 0),
    new THREE.Vector3(param1, 0, 0),
    new THREE.Vector3(0, param2, 0)
  ];
  
  const edges = [[0, 1], [1, 2], [2, 0]];
  
  return { nodes, edges };
});

// Use your custom preset
const customGraph = new GraphGeometry('myCustomGraph', 2, 3, {
  nodeColor: 0xff0000
});

🎨 Available Presets

Basic Shapes

| Preset | Parameters | Description | |--------|------------|-------------| | cube | size, options | 8-node cube wireframe (supports includeFaceCenters option) | | pyramid | baseSize, height | 5-node pyramid (4 base + 1 apex) | | prism | width, height, depth | Rectangular prism wireframe | | octahedron | size | 6-node octahedron | | triangle | size | 3-node triangle | | line | length | 2-node line segment | | cone | radius, height, baseSegments, options | Cone with base ring (supports includeFaceCenters option) |

Network Structures

| Preset | Parameters | Description | |--------|------------|-------------| | circular | count, radius | Nodes in circle, connected in ring | | star | count, radius | Complete graph (all nodes connected) | | grid | rows, cols, spacing | 2D grid network | | lattice | nx, ny, nz, spacing | 3D lattice/grid | | spokes | count, length, angleOffset | Hub with radiating spokes |

Path-Based

| Preset | Parameters | Description | |--------|------------|-------------| | polyline | points[] | Connected line through points | | paths | paths[], options | Multiple polylines with merging |

Usage Examples

// Basic shapes
const cube = new GraphGeometry('cube', 2);
const cubeWithFaceCenters = new GraphGeometry('cube', 2, { includeFaceCenters: true });
const pyramid = new GraphGeometry('pyramid', 3, 2);
const cone = new GraphGeometry('cone', 2, 3, 8);
const coneWithBaseCenter = new GraphGeometry('cone', 2, 3, 8, { includeFaceCenters: true });

// Networks  
const star = new GraphGeometry('star', 6, 2);
const grid = new GraphGeometry('grid', 3, 3, 2);
const lattice3D = new GraphGeometry('lattice', 2, 2, 2, 1.5);

// Paths
const polyline = new GraphGeometry('polyline', [
  {x: 0, y: 0, z: 0},
  {x: 1, y: 1, z: 0}, 
  {x: 2, y: 0, z: 1}
]);

const paths = new GraphGeometry('paths', [
  [{x: 0, y: 0, z: 0}, {x: 1, y: 0, z: 0}],
  [{x: 1, y: 0, z: 0}, {x: 1, y: 1, z: 0}]
], { merge: true, mergeTolerance: 1e-6 });

⚙️ Configuration Options

Per-Node Customization

// Random node sizes
const nodeRadii = [0.1, 0.2, 0.15, 0.3];

// Alternating colors  
const nodeColors = [0xff0000, 0x00ff00, 0xff0000, 0x00ff00];

// Color function
const nodeColors = (index) => index % 2 ? 0xff0000 : 0x0000ff;

const graph = new GraphGeometry('cube', 2, {
  nodeRadii,
  nodeColors
});

Directed Graphs

const directedGraph = new GraphGeometry('grid', 3, 3, 2, {
  directed: true,
  arrowSize: 0.3,
  edgeColor: 0x00ff00
});

Advanced Edge Styling

// Edges can be objects with custom properties
const customEdges = [
  {a: 0, b: 1, color: 0xff0000, radius: 0.05},
  {a: 1, b: 2, color: 0x00ff00, radius: 0.02}
];

🏗️ Project Structure

src/
├── core/                    # Core system modules
│   ├── Scene.js            # Three.js scene management
│   ├── GraphRenderer.js    # Graph rendering engine
│   └── PresetManager.js    # Preset registration system
├── presets/                # Graph generation presets
│   ├── basic/BasicShapes.js      # Geometric shapes
│   ├── structures/Networks.js    # Network topologies  
│   └── paths/PathGeometry.js     # Path-based graphs
├── gui/                    # User interface
│   ├── ParameterManager.js # Parameter handling
│   └── GUIController.js    # lil-gui integration
├── materials/              # Material creation
│   └── MaterialFactory.js  # Material utilities
├── utils/                  # Utility functions
│   ├── MathHelpers.js      # Math utilities
│   └── GeometryUtils.js    # Three.js geometry helpers
├── GraphGeometry.js        # Main class
├── main.js                 # Demo application
└── index.js               # Package exports

🔧 Technical Requirements

• Three.js: >=0.170.0
• lil-gui: ^0.20.0 (optional, for demo GUI)
• ES6+ Support: Uses ES modules
• WebGL: Requires WebGL-capable browser

🎯 Development Scripts

npm run dev          # Start development server
npm run build        # Build for production  
npm run preview      # Preview build
npm run docs:dev     # Start documentation
npm run docs:build   # Build documentation

🤝 Contributing

Architecture Guidelines

1. Separation of Concerns: Each module has a single responsibility
2. Preset Pattern: All graph types follow the same {nodes, edges} interface
3. Extensibility: New presets are easy to add via registration system
4. Three.js Integration: Seamless integration with existing Three.js workflows

Adding New Presets

1. Built-in Presets: Add to appropriate module in src/presets/
2. External Presets: Use registerPreset() function
3. Return Format: Always return {nodes: Vector3[], edges: [number, number][]}

Code Style

• Use ES6+ features
• Follow existing naming conventions
• Document complex algorithms
• Keep preset functions pure (no side effects)

Testing

• Test all presets with various parameters
• Verify edge cases (empty graphs, single nodes)
• Check memory cleanup (dispose() methods)

📄 License

MIT License - see LICENSE file for details.

👨‍💻 Author

Gonzalo Martinesse [email protected]

🔗 Links

• Repository
• Issues
• Three.js Documentation