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:

``bash
npm install force-3d-graph
`

$3

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:
`bash
npm install
npm run build
`

#### 2. Link the Library
To use it in another project on the same machine:
`bash


In the force-graph directory

npm link

In your project directory

npm link force-3d-graph
`

Alternatively, you can install it via file path:
`bash
npm install /path/to/force-graph
`

Quick Start

`javascript
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

$3

Constructor to create a new graph instance.

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

$3

| 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. |

$3

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.