force-3d-graph

Force 3D Graph

A high-performance 3D force-directed graph visualization library built with Three.js. This library allows you to visualize complex network structures with interactive nodes, edges, and smooth animations.

Features

• High Performance: Optimized using spatial indexing (Octree) and Level of Detail (LOD) for handling large graphs.
• Interactive: Support for node clicking, hovering, and tooltips.
• Dynamic: Real-time addition and removal of nodes and edges.
• Customizable: Extensive options for appearance and physics behavior.
• Expandable: Built-in support for expanding nodes (fetching more data on interaction).

Installation

You can install the library via npm:

npm install force-3d-graph

Local Development

If you want to use the library locally without publishing to npm, see LOCAL_DEVELOPMENT.md.

1. Build the Library

In the force-graph directory, run:

npm install
npm run build

2. Link the Library

To use it in another project on the same machine:

# In the force-graph directory
npm link

# In your project directory
npm link force-3d-graph

Alternatively, you can install it via file path:

npm install /path/to/force-graph

Quick Start

import { ForceGraph3D } from 'force-3d-graph';

// Data format
const data = {
  nodes: [
    { id: '1', label: 'Node 1', color: 0xff0000 },
    { id: '2', label: 'Node 2', color: 0x00ff00 }
  ],
  edges: [
    { source: '1', target: '2', relationship: 'connected' }
  ]
};

// Initialize the graph
const graph = new ForceGraph3D(document.getElementById('graph-container'), {
  backgroundColor: '#0a0a0a',
  onNodeClick: (node) => {
    console.log('Clicked node:', node);
    graph.focusOnNode(node.id);
  }
});

// Set data
graph.setData(data);

API Reference

ForceGraph3D(container, options)

Constructor to create a new graph instance.

• container: HTMLElement where the graph will be rendered.
• options: ForceGraph3DOptions object.

Methods

Method	Description
setData(data: GraphData)	Load a complete graph data set.
addNode(node: NodeData)	Add a single node. Returns boolean (success).
removeNode(nodeId: string)	Remove a node and its connected edges.
addEdge(edge: Edge)	Add an edge between two existing nodes.
removeEdge(source, target)	Remove an edge.
focusOnNode(nodeId, distance)	Smoothly animate camera to focus on a node.
expandNode(nodeId, depth)	Trigger node expansion (requires onExpand callback).
searchNodes(query)	Search nodes by label or ID.
getAllNodes()	Get array of all current nodes.

Events

Register listeners using graph.on(eventName, callback):

• nodeClick: (node: NodeData)
• nodeHover: (node: NodeData | null)
• edgeHover: (edge: Edge | null)
• ready: ()

Data Format & Conversion

The library expects data in a specific GraphData format. For detailed instructions on how to convert your existing data structures, see DATA_CONVERSION.md.

Local Development Setup

For more details on how to integrate this library into your project without npm publishing, see LOCAL_DEVELOPMENT.md.