3d-force-graph-vr

3D Force-Directed Graph in VR

A web component to represent a graph data structure in virtual reality using a force-directed iterative layout. Uses A-Frame for VR rendering and d3-force-3d for the layout physics engine.

Check out the examples:

• Basic (source)
• Asynchronous load (source)
• Larger graph (~4k elements) (source)
• Directional links (source)
• Auto-colored nodes/links (source)
• Text as nodes (source)
• Custom node geometries (source)
• Dynamic data changes (source)

See also the WebGL 3D version, and the A-Frame component version (aframe-forcegraph-component).

Quick start

import ForceGraphVR from '3d-force-graph-vr';

or

var ForceGraphVR = require('3d-force-graph-vr');

or even

<script src="//unpkg.com/3d-force-graph-vr"></script>

then

var myGraph = ForceGraphVR();
myGraph(<myDOMElement>)
    .graphData(<myData>);

API reference

Data input

Method	Description	Default
graphData([data])	Getter/setter for graph data structure (see below for syntax details).	{ nodes: [], links: [] }
jsonUrl([url])	URL of JSON file to load graph data directly from, as an alternative to specifying graphData directly.
nodeId([str]) (alias: idField)	Node object accessor attribute for unique node id (used in link objects source/target).	id
linkSource([str]) (alias: linkSourceField)	Link object accessor attribute referring to id of source node.	source
linkTarget([str]) (alias: linkTargetField)	Link object accessor attribute referring to id of target node.	target

Container layout

Method	Description	Default
width([px])	Getter/setter for the canvas width.	<window width>
height([px])	Getter/setter for the canvas height.	<window height>
backgroundColor([str])	Getter/setter for the chart background color.	#000011
showNavInfo([boolean])	Getter/setter for whether to show the navigation controls footer info.	true

Node styling

Method	Description	Default
nodeRelSize([num])	Getter/setter for the ratio of node sphere volume (cubic px) per value unit.	4
nodeVal([num, str or fn]) (alias: valField)	Node object accessor function, attribute or a numeric constant for the node numeric value (affects sphere volume).	val
nodeLabel([str or fn]) (alias: nameField)	Node object accessor function or attribute for name (shown in label).	name
nodeDesc([str or fn])	Node object accessor function or attribute for description (shown under label).	desc
nodeColor([str or fn]) (alias: colorField)	Node object accessor function or attribute for node color (affects sphere color).	color
nodeAutoColorBy([str or fn]) (alias: autoColorBy)	Node object accessor function (fn(node)) or attribute (e.g. 'type') to automatically group colors by. Only affects nodes without a color attribute.
nodeOpacity([num])	Getter/setter for the nodes sphere opacity, between [0,1].	0.75
nodeResolution([num])	Getter/setter for the geometric resolution of each node, expressed in how many slice segments to divide the circumference. Higher values yield smoother spheres.	8
nodeThreeObject([Object3d, str or fn])	Node object accessor function or attribute for generating a custom 3d object to render as graph nodes. Should return an instance of ThreeJS Object3d. If a falsy value is returned, the default 3d object type will be used instead for that node.	default node object is a sphere, sized according to val and styled according to color.

Link styling

Method	Description	Default
linkLabel([str or fn])	Link object accessor function or attribute for name (shown in label).	name
linkDesc([str or fn])	Link object accessor function or attribute for description (shown under label).	desc
linkColor([str or fn]) (alias: linkColorField)	Link object accessor function or attribute for line color.	color
linkAutoColorBy([str or fn])	Link object accessor function (fn(link)) or attribute (e.g. 'type') to automatically group colors by. Only affects links without a color attribute.
linkOpacity([num]) (alias: lineOpacity)	Getter/setter for line opacity of links, between [0,1].	0.2
linkWidth([num, str or fn])	Link object accessor function, attribute or a numeric constant for the link line width. A value of zero will render a ThreeJS Line whose width is constant (1px) regardless of distance. Values are rounded to the nearest decimal for indexing purposes.	0
linkResolution([num])	Getter/setter for the geometric resolution of each link, expressed in how many radial segments to divide the cylinder. Higher values yield smoother cylinders. Applicable only to links with positive width.	6
linkHoverPrecision([int])	Whether to display the link label when gazing the link closely (low value) or from far away (high value).	2
linkDirectionalParticles([num, str or fn])	Link object accessor function, attribute or a numeric constant for the number of particles (small spheres) to display over the link line. The particles are distributed equi-spaced along the line, travel in the direction source > target, and can be used to indicate link directionality.	0
linkDirectionalParticleSpeed([num, str or fn])	Link object accessor function, attribute or a numeric constant for the directional particles speed, expressed as the ratio of the link length to travel per frame. Values above 0.5 are discouraged.	0.01
linkDirectionalParticleWidth([num, str or fn])	Link object accessor function, attribute or a numeric constant for the directional particles width. Values are rounded to the nearest decimal for indexing purposes.	0.5
linkDirectionalParticleColor([str or fn])	Link object accessor function or attribute for the directional particles color.	color
linkDirectionalParticleResolution([num])	Getter/setter for the geometric resolution of each directional particle, expressed in how many slice segments to divide the circumference. Higher values yield smoother particles.	4

Force engine configuration

Method	Description	Default
forceEngine([str])	Getter/setter for which force-simulation engine to use (d3 or ngraph).	d3
numDimensions([int])	Getter/setter for number of dimensions to run the force simulation on (1, 2 or 3).	3
d3AlphaDecay([num])	Getter/setter for the simulation intensity decay parameter, only applicable if using the d3 simulation engine.	0.0228
d3VelocityDecay([num])	Getter/setter for the nodes' velocity decay that simulates the medium resistance, only applicable if using the d3 simulation engine.	0.4
warmupTicks([int])	Getter/setter for number of layout engine cycles to dry-run at ignition before starting to render.	0
cooldownTicks([int])	Getter/setter for how many build-in frames to render before stopping and freezing the layout engine.	Infinity
cooldownTime([num])	Getter/setter for how long (ms) to render for before stopping and freezing the layout engine.	15000

Input JSON syntax

{
    "nodes": [ 
        { 
          "id": "id1",
          "name": "name1",
          "val": 1 
        },
        { 
          "id": "id2",
          "name": "name2",
          "val": 10 
        },
        (...)
    ],
    "links": [
        {
            "source": "id1",
            "target": "id2"
        },
        (...)
    ]
}