You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
If you need to build a graph visualization for the web of any kind, such as a tree, force directed graph, network graph, etc., and scale and performance are important to you, then El Grapho is a great option. It was built from the ground up to optimize for CPU and GPU performance.
15
+
If you need to build a graph visualization for the web of any kind, such as a tree, force directed graph, network graph, etc., and scale and performance are important to you, then El Grapho is a great option. El Grapho was built to push the limits of modern browsers.
16
16
17
17
## Live Examples
18
18
@@ -21,7 +21,7 @@ If you need to build a graph visualization for the web of any kind, such as a tr
21
21
22
22
## Getting Started
23
23
24
-
To get started, you can install it from npm like this
24
+
To get started, you can install El Grapho from npm like this
25
25
26
26
```npm install elgrapho```
27
27
@@ -36,26 +36,33 @@ To create a simple El Grapho data visualization, you can instantiate a new graph
36
36
```
37
37
let graph = new ElGrapho({
38
38
container: document.getElementById('container'),
39
-
40
39
model: {
41
-
nodes: {
42
-
xs: [0, -0.4, 0.4, -0.6, -0.2, 0.2, 0.6],
43
-
ys: [0.6, 0, 0, -0.6, -0.6, -0.6, -0.6],
44
-
colors: [0, 1, 1, 2, 2, 2, 2]
45
-
},
46
-
edges: {
47
-
from: [0, 0, 1, 1, 2, 2],
48
-
to: [1, 2, 3, 4, 5, 6]
49
-
},
50
-
width: 800,
51
-
height: 400
40
+
nodes: [
41
+
{x: 0, y: 0.6, group: 0, label: 0},
42
+
{x: -0.4, y: 0, group: 1, label: 1},
43
+
{x: 0.4, y: 0, group: 1, label: 2},
44
+
{x: -0.6, y: -0.6, group: 2, label: 3},
45
+
{x: -0.2, y: -0.6, group: 2, label: 4},
46
+
{x: 0.2, y: -0.6, group: 2, label: 5},
47
+
{x: 0.6, y: -0.6, group: 2, label: 6}
48
+
],
49
+
edges: [
50
+
{from: 0, to: 1},
51
+
{from: 0, to: 2},
52
+
{from: 1, to: 3},
53
+
{from: 1, to: 4},
54
+
{from: 2, to: 5},
55
+
{from: 2, to: 6}
56
+
],
57
+
width: 500,
58
+
height: 500
52
59
}
53
60
});
54
61
```
55
62
56
63
*```container``` - DOM element that will contain the El Grapho graph.
57
64
58
-
*```model.nodes``` - object that defines the nodes in the graph (graphs are made up of nodes and edges). Each node is defined by a position (x and y), and also a color. El Grapho x and y ranges are between -1 and 1. If x is -1, then the node position is on the very left of the viewport. If x is 0 it is in the center. And if x is 1 it is on the very right of the viewport. Colors are integer values between 0 and 7. These integer values map to the El Grapho color palette.
65
+
*```model.nodes``` - object that defines the nodes in the graph. Each node is defined by a position (x and y), and also a group. El Grapho x and y ranges are between -1 and 1. If x is -1, then the node position is on the very left of the viewport. If x is 0 it is in the center, and if x is 1 it is on the very right of the viewport. Groups are integer values, and El Grapho automatically assigns colors to each unique grouping. To add labels, simply add a ```label``` key and value pair to each node.
59
66
60
67
*```model.edges``` - object that defines the edges between nodes based on their indices. Each edge is defined by a from-node-index and a to-node-index. In the example above, the first edge begins at node ```0``` and ends at node ```1```. For non directed graphs, or bi-directional graphs, ```from``` and ```to``` are interchangeable.
61
68
@@ -67,111 +74,186 @@ let graph = new ElGrapho({
67
74
68
75
*```debug``` - boolean that can be used to enable debug mode. Debug mode will show the node and edge count in the bottom right corner of the visualization. The default is false.
69
76
70
-
*```arrows``` - boolean that enables or disables edge arrows. For non directed or bi-directional graphs, you should set ```arrows``` to ```false```. The default is true.
71
-
72
-
*```labels``` - array of strings used to define labels for each node. If your visualization has 100 nodes, there should be 100 strings in the ```labels``` array. The default is an empty array which results in no labels.
77
+
*```arrows``` - boolean that enables or disables edge arrows. The default is false. For non directed or bi-directional graphs, you should keep ```arrows``` as ```false```.
73
78
74
79
### Models
75
80
76
-
Determining the positions of the nodes for your graph can be alot of work! While it's nice to have the power to construct custom graph shapes, most El Grapho users will want to leverage the provided El Grapho models which will generate node positions for you. Currently, ElGrapho supports ```Tree```, ```Ring```, ```Cluster```, and ```ForceDirectedGraph```
81
+
Determining the positions of the nodes for your graph can be alot of work! While it's nice to have the power to construct custom graph layouts, most El Grapho users will want to leverage the provided El Grapho models which will generate node positions for you. Currently, ElGrapho supports ```ForceDirected```, ```Tree```, ```Web```, ```Cluster```, and ```Ring```
82
+
83
+
#### ForceDirected Model
84
+
85
+
```
86
+
let model = {
87
+
nodes: [
88
+
{group: 0},
89
+
{group: 1},
90
+
{group: 1},
91
+
{group: 2},
92
+
{group: 2},
93
+
{group: 3}
94
+
],
95
+
edges: [
96
+
{from: 0, to: 1},
97
+
{from: 0, to: 2},
98
+
{from: 1, to: 3},
99
+
{from: 1, to: 4},
100
+
{from: 2, to: 5},
101
+
],
102
+
width: 500,
103
+
height: 500,
104
+
steps: 30
105
+
};
106
+
107
+
graph = new ElGrapho({
108
+
container: document.getElementById('container'),
109
+
model: ElGrapho.models.ForceDirected(model)
110
+
});
111
+
```
112
+
113
+
The ```ForceDirected``` model uses Webcola to reduce edge crossing and optimize node spacing. Be warned that force directed graphs take O(n^2) time, which means they may not be appropriate for generating models on the client with lots of nodes. If it's possible to build your models in advance, it's a good idea to build the force directed graph model on the server and then cache it. If you require your models to be constructed at execution time, and the number of nodes is very high, you may consider using an O(n) model substitude such as ```Web``` or ```Cluster```
114
+
115
+
The ```ForceDirected``` model accepts a ```steps``` property from the model config which can be used to define the accuracy of the result. This is because force directed graphs require multiple passes to obtain the final result. The default is 30. Lowering this number will result in faster model construction but less accurate results. Increasing this number will result in slower model construction but more accurate results.
77
116
78
117
#### Tree Model
79
118
80
119
```
81
-
let modelConfig = {
82
-
nodes: {
83
-
colors: [0, 1, 1, 2, 2, 3, 3]
84
-
},
85
-
edges: {
86
-
from: [0, 0, 1, 1, 2, 2],
87
-
to: [1, 2, 3, 4, 5, 6]
88
-
},
89
-
width: 800,
90
-
height: 400
120
+
let model = {
121
+
nodes: [
122
+
{group: 0},
123
+
{group: 1},
124
+
{group: 1},
125
+
{group: 2},
126
+
{group: 2},
127
+
{group: 3},
128
+
{group: 3}
129
+
],
130
+
edges: [
131
+
{from: 0, to: 1},
132
+
{from: 0, to: 2},
133
+
{from: 1, to: 3},
134
+
{from: 1, to: 4},
135
+
{from: 2, to: 5},
136
+
{from: 2, to: 6}
137
+
],
138
+
width: 500,
139
+
height: 500
91
140
};
92
141
93
142
let graph = new ElGrapho({
94
143
container: document.getElementById('container'),
95
-
model: ElGrapho.models.Tree(modelConfig)
144
+
model: ElGrapho.models.Tree(model),
145
+
arrows: true
96
146
});
97
147
```
98
148
99
-
#### Ring Model
149
+
#### Web Model
100
150
101
151
```
102
-
let modelConfig = {
103
-
nodes: {
104
-
colors: [0, 1, 1, 2, 2, 3, 3]
105
-
},
106
-
edges: {
107
-
from: [0, 0, 1, 1, 2, 2],
108
-
to: [1, 2, 3, 4, 5, 6]
109
-
},
110
-
width: 800,
111
-
height: 400
152
+
let model = {
153
+
nodes: [
154
+
{group: 0},
155
+
{group: 1},
156
+
{group: 1},
157
+
{group: 2},
158
+
{group: 2},
159
+
{group: 3},
160
+
{group: 3}
161
+
],
162
+
edges: [
163
+
{from: 0, to: 1},
164
+
{from: 0, to: 2},
165
+
{from: 1, to: 3},
166
+
{from: 1, to: 4},
167
+
{from: 2, to: 5},
168
+
{from: 2, to: 6}
169
+
],
170
+
width: 500,
171
+
height: 500
112
172
};
113
173
114
174
let graph = new ElGrapho({
115
175
container: document.getElementById('container'),
116
-
model: ElGrapho.models.Ring(modelConfig)
176
+
model: ElGrapho.models.Web(model),
177
+
arrows: true
117
178
});
118
179
```
119
180
181
+
Web begin by positioning all of the nodes in a ring, and then iteratively move nodes closer together that share an edge. This essentially moves nodes with lots of edges towards the center, and pushes nodes with few or no edges to the outside. Often times, Web models looks fairly similar to ForceDirected models, but Web models run in O(n) time compared to ForceDirected models, which run in O(n^2) time, which makes them great alternatives for large numbers of nodes and edges.
182
+
120
183
#### Cluster Model
121
184
122
185
```
123
-
let modelConfig = {
124
-
nodes: {
125
-
colors: [0, 1, 1, 2, 2, 2, 2, 2]
126
-
},
127
-
edges: {
128
-
from: [0, 0, 0, 0, 0, 0, 0, 0],
129
-
to: [1, 2, 3, 4, 5, 6, 7, 8]
130
-
},
131
-
width: 800,
132
-
height: 400
186
+
let model = {
187
+
nodes: [
188
+
{group: 0},
189
+
{group: 1},
190
+
{group: 1},
191
+
{group: 2},
192
+
{group: 2},
193
+
{group: 3},
194
+
{group: 3}
195
+
],
196
+
edges: [
197
+
{from: 0, to: 1},
198
+
{from: 0, to: 2},
199
+
{from: 1, to: 3},
200
+
{from: 1, to: 4},
201
+
{from: 2, to: 5},
202
+
{from: 2, to: 6}
203
+
],
204
+
width: 500,
205
+
height: 500
133
206
};
134
207
135
208
let graph = new ElGrapho({
136
209
container: document.getElementById('container'),
137
-
model: ElGrapho.models.Cluster(modelConfig)
210
+
model: ElGrapho.models.Cluster(model),
211
+
arrows: true
138
212
});
139
213
```
140
214
141
-
The Cluster model clusters nodes by color. If a single color is used for all of the nodes, ElGrapho will generate a single centered cluster. If there are several colors used, ElGrapho will render distinct clusters. Because Cluster models can be generated in ```O(n)``` time, i.e. linear time, they are very fast to construct compared to other models such as force directed graphs which are polynomial in time.
215
+
The Cluster model clusters nodes by group. If a single group is used for all of the nodes, ElGrapho will generate a single centered cluster. If there are several groups used, ElGrapho will render distinct clusters. Because Cluster models can be generated in ```O(n)``` time, i.e. linear time, they are very fast to construct compared to other models such as force directed graphs which are polynomial in time.
The ```ForceDirectedGraph``` uses a physics simulator to repel and attract nodes in order to generate natural layouts. Be warned that force directed graphs take O(n^2) time, which means they may not be appropriate for generating models on the client with lots of nodes. If it's possible to build your models in advance, it's a good idea to build the force directed graph model on the server and then cache it. If you require your models to be constructed at execution time, and the number of nodes is very high, you may consider using an O(n) model such as ```Cluster```
165
-
166
-
The ```ForceDirectedGraph``` model accepts a ```steps``` property from the modelConfig which can be used to define the accuracy of the result. This is because force directed graphs require multiple passes to obtain the final result. The default is 10. Lowering this number will result in faster model construction but less accurate results. Increasing this number will result in slower model construction but more accurate results.
167
249
168
250
## Model Polymorphism
169
251
170
-
You may have noticed that the model config schema is identical for all models. As a result, El Grapho visualizations are polymorphic, meaning you can pass the same data structure into different models and get different graph visualizations. Pretty cool!
252
+
You may have noticed that the model config schema is identical for all models. As a result, El Grapho visualizations are polymorphic, meaning you can pass the same data structure into different models and get different graph layouts. Pretty cool!
171
253
172
254
## Server Side Model Generation
173
255
174
-
Because the El Grapho models are fully decoupled from the rendering engine itself, they can be executed on the client or on the server, depending on your needs. For really complex models, it may be best to build the model on the server side and then deliver the output over http to the browser, and passed directly into the El Grapho config.
256
+
Because the El Grapho models are fully decoupled from the rendering engine itself, they can be executed on the client or on the server, depending on your needs. For really complex models, it may be best to build the model on the server, deliver the output over http to the browser, and pass it directly into the El Grapho config.
175
257
176
258
## Controls
177
259
@@ -189,7 +271,7 @@ And there are three action buttons:
189
271
190
272
## Tooltips
191
273
192
-
El Grapho ships with a default template and default content. It is assumed however that you will be providing your own tooltip content (at the end of the day, most people want something custom anyways). To set the tooltip template, simple do the following:
274
+
El Grapho ships with a default template and default content. It is assumed however that you will be providing your own tooltip content (at the end of the day, most people want something custom anyways). To set the tooltip template, simply do the following:
0 commit comments