force-3d-graph 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +114 -0
- package/dist/force-3d-graph.js +2625 -0
- package/dist/force-3d-graph.js.map +1 -0
- package/dist/force-3d-graph.umd.cjs +336 -0
- package/dist/force-3d-graph.umd.cjs.map +1 -0
- package/dist/index.d.ts +320 -0
- package/package.json +55 -0
package/README.md
ADDED
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Force 3D Graph
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **High Performance**: Optimized using spatial indexing (Octree) and Level of Detail (LOD) for handling large graphs.
|
|
8
|
+
- **Interactive**: Support for node clicking, hovering, and tooltips.
|
|
9
|
+
- **Dynamic**: Real-time addition and removal of nodes and edges.
|
|
10
|
+
- **Customizable**: Extensive options for appearance and physics behavior.
|
|
11
|
+
- **Expandable**: Built-in support for expanding nodes (fetching more data on interaction).
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
You can install the library via npm:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install force-3d-graph
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
### Local Development
|
|
22
|
+
|
|
23
|
+
If you want to use the library locally without publishing to npm, see [LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md).
|
|
24
|
+
|
|
25
|
+
#### 1. Build the Library
|
|
26
|
+
In the `force-graph` directory, run:
|
|
27
|
+
```bash
|
|
28
|
+
npm install
|
|
29
|
+
npm run build
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
#### 2. Link the Library
|
|
33
|
+
To use it in another project on the same machine:
|
|
34
|
+
```bash
|
|
35
|
+
# In the force-graph directory
|
|
36
|
+
npm link
|
|
37
|
+
|
|
38
|
+
# In your project directory
|
|
39
|
+
npm link force-3d-graph
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Alternatively, you can install it via file path:
|
|
43
|
+
```bash
|
|
44
|
+
npm install /path/to/force-graph
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Quick Start
|
|
48
|
+
|
|
49
|
+
```javascript
|
|
50
|
+
import { ForceGraph3D } from 'force-3d-graph';
|
|
51
|
+
|
|
52
|
+
// Data format
|
|
53
|
+
const data = {
|
|
54
|
+
nodes: [
|
|
55
|
+
{ id: '1', label: 'Node 1', color: 0xff0000 },
|
|
56
|
+
{ id: '2', label: 'Node 2', color: 0x00ff00 }
|
|
57
|
+
],
|
|
58
|
+
edges: [
|
|
59
|
+
{ source: '1', target: '2', relationship: 'connected' }
|
|
60
|
+
]
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
// Initialize the graph
|
|
64
|
+
const graph = new ForceGraph3D(document.getElementById('graph-container'), {
|
|
65
|
+
backgroundColor: '#0a0a0a',
|
|
66
|
+
onNodeClick: (node) => {
|
|
67
|
+
console.log('Clicked node:', node);
|
|
68
|
+
graph.focusOnNode(node.id);
|
|
69
|
+
}
|
|
70
|
+
});
|
|
71
|
+
|
|
72
|
+
// Set data
|
|
73
|
+
graph.setData(data);
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## API Reference
|
|
77
|
+
|
|
78
|
+
### `ForceGraph3D(container, options)`
|
|
79
|
+
|
|
80
|
+
Constructor to create a new graph instance.
|
|
81
|
+
|
|
82
|
+
- `container`: HTMLElement where the graph will be rendered.
|
|
83
|
+
- `options`: [ForceGraph3DOptions](#forcegraph3doptions) object.
|
|
84
|
+
|
|
85
|
+
### Methods
|
|
86
|
+
|
|
87
|
+
| Method | Description |
|
|
88
|
+
| :--- | :--- |
|
|
89
|
+
| `setData(data: GraphData)` | Load a complete graph data set. |
|
|
90
|
+
| `addNode(node: NodeData)` | Add a single node. Returns boolean (success). |
|
|
91
|
+
| `removeNode(nodeId: string)` | Remove a node and its connected edges. |
|
|
92
|
+
| `addEdge(edge: Edge)` | Add an edge between two existing nodes. |
|
|
93
|
+
| `removeEdge(source, target)` | Remove an edge. |
|
|
94
|
+
| `focusOnNode(nodeId, distance)` | Smoothly animate camera to focus on a node. |
|
|
95
|
+
| `expandNode(nodeId, depth)` | Trigger node expansion (requires `onExpand` callback). |
|
|
96
|
+
| `searchNodes(query)` | Search nodes by label or ID. |
|
|
97
|
+
| `getAllNodes()` | Get array of all current nodes. |
|
|
98
|
+
|
|
99
|
+
### Events
|
|
100
|
+
|
|
101
|
+
Register listeners using `graph.on(eventName, callback)`:
|
|
102
|
+
|
|
103
|
+
- `nodeClick`: `(node: NodeData)`
|
|
104
|
+
- `nodeHover`: `(node: NodeData | null)`
|
|
105
|
+
- `edgeHover`: `(edge: Edge | null)`
|
|
106
|
+
- `ready`: `()`
|
|
107
|
+
|
|
108
|
+
## Data Format & Conversion
|
|
109
|
+
|
|
110
|
+
The library expects data in a specific `GraphData` format. For detailed instructions on how to convert your existing data structures, see [DATA_CONVERSION.md](./DATA_CONVERSION.md).
|
|
111
|
+
|
|
112
|
+
## Local Development Setup
|
|
113
|
+
|
|
114
|
+
For more details on how to integrate this library into your project without npm publishing, see [LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md).
|