public class Force
extends com.google.gwt.core.client.JavaScriptObject
A force-directed layout with the default settings: size 1×1, link strength 1,
friction 0.9, distance 20, charge strength -30, gravity strength 0.1, and
theta parameter 0.8. The default nodes and links are the empty array, and
when the layout is started, the internal alpha cooling parameter is set to
0.1. The general pattern for constructing force-directed layouts is to set
all the configuration properties, and then call start:
var force = d3.layout.force() .nodes(nodes) .links(links) .size([w, h]) .start();
Note that, like D3's other layouts, the force-directed layout doesn't mandate a particular visual representation. Most commonly, nodes are mapped to SVG circle elements, and links are mapped to SVG line elements. But you might also display nodes as symbols or images.
| Modifier and Type | Class and Description |
|---|---|
static class |
Force.Node
A node in d3j's force layout, see d3 docs on
node.
|
| Modifier | Constructor and Description |
|---|---|
protected |
Force() |
| Modifier and Type | Method and Description |
|---|---|
double |
alpha() |
Force |
alpha(double x)
Sets the force layout's cooling parameter, alpha to the constant value
specified.
|
double |
charge() |
Force |
charge(DatumFunction<?> callback)
Sets sets the charge strength per node.
|
Force |
charge(double x)
Sets the charge strength to the specified constant value for all nodes.
|
double |
chargeDistance() |
Force |
chargeDistance(double x)
Sets the maximum distance over which charge forces are applied to the
constant specified value.
|
Drag |
drag()
Bind a behavior to nodes to allow interactive dragging, either using the
mouse or touch.
|
double |
friction() |
Force |
friction(double friction)
Sets the friction coefficient to the specified value.
|
double |
gravity() |
Force |
gravity(double x)
Sets the gravitational strength to the specified value.
|
double |
linkDistance() |
Force |
linkDistance(DatumFunction<?> callback)
Sets the target distance between linked nodes. if distance is a function,
then the function is evaluated for each link (in order), being passed the
link and its index, with the this context as the force layout; the
function's return value is then used to set each link's distance.
|
Force |
linkDistance(double distance)
Sets the target distance between linked nodes to the specified constant
value.
|
Array<? extends Link> |
links() |
Force |
links(Array<? extends Link> links)
Sets the layout's associated links to the specified array.
|
double |
linkStrength() |
Force |
linkStrength(DatumFunction<?> callback)
Sets the strength (rigidity) of links in the range [0,1].
|
Force |
linkStrength(double strength)
Sets the strength (rigidity) of all links to the specified constant value
in the range [0,1].
|
Array<? extends Force.Node> |
nodes() |
Force |
nodes(Array<? extends Force.Node> nodes)
Sets the layout's associated nodes to the specified array.
|
Selection |
on(String name,
DatumFunction<?> callback)
Registers the specified listener to receive events of the specified type
from the force layout.
|
Force |
resume()
Equivalent to:
force.alpha(.1); Sets the cooling parameter alpha to 0.1. |
Array<Short> |
size() |
Force |
size(Array<Short> size)
If size is specified, sets the available layout size to the specified
two-element array of numbers representing x and y.
|
Force |
start()
Starts the simulation; this method must be called when the layout is
first created, after assigning the nodes and links.
|
Force |
stop()
Equivalent to:
force.alpha(0); Terminates the simulation, setting the cooling parameter alpha to zero. |
double |
theta() |
Force |
theta(double x)
Sets the Barnes–Hut approximation criterion to the specified value.
|
void |
tick()
Runs the force layout simulation one step.
|
public final Force size(Array<Short> size)
size - to setpublic final double linkDistance()
public final Force linkDistance(double distance)
distance - to setpublic final Force linkDistance(DatumFunction<?> callback)
callback - function that returns link distance for each link in the
documentpublic final double linkStrength()
public final Force linkStrength(double strength)
public final Force linkStrength(DatumFunction<?> callback)
public final double friction()
public final Force friction(double friction)
public final double charge()
public final Force charge(double x)
A negative value results in node repulsion, while a positive value results in node attraction. For graph layout, negative values should be used; for n-body simulation, positive values can be used. All nodes are assumed to be infinitesimal points with equal charge and mass. Charge forces are implemented efficiently via the Barnes–Hut algorithm, computing a quadtree for each tick. Setting the charge force to zero disables computation of the quadtree, which can noticeably improve performance if you do not need n-body forces.
public final Force charge(DatumFunction<?> callback)
A negative value results in node repulsion, while a positive value results in node attraction. For graph layout, negative values should be used; for n-body simulation, positive values can be used. All nodes are assumed to be infinitesimal points with equal charge and mass. Charge forces are implemented efficiently via the Barnes–Hut algorithm, computing a quadtree for each tick. Setting the charge force to zero disables computation of the quadtree, which can noticeably improve performance if you do not need n-body forces.
public final double chargeDistance()
public final Force chargeDistance(double x)
public final double theta()
public final Force theta(double x)
To avoid quadratic performance slowdown for large graphs, the force layout uses the Barnes–Hut approximation which takes O(n log n) per tick. For each tick, a quadtree is created to store the current node positions; then for each node, the sum charge force of all other nodes on the given node are computed. For clusters of nodes that are far away, the charge force is approximated by treating the distance cluster of nodes as a single, larger node. Theta determines the accuracy of the computation: if the ratio of the area of a quadrant in the quadtree to the distance between a node to the quadrant's center of mass is less than theta, all nodes in the given quadrant are treated as a single, larger node rather than computed individually.
public final double gravity()
public final Force gravity(double x)
Gravity can be disabled by setting the gravitational strength to zero. If you disable gravity, it is recommended that you implement some other geometric constraint to prevent nodes from escaping the layout, such as constraining them within the layout's bounds.
public final Array<? extends Force.Node> nodes()
public final Force nodes(Array<? extends Force.Node> nodes)
Force.Node node within the
nodes array.These attributes do not need to be set before passing the nodes to the layout; if they are not set, suitable defaults will be initialized by the layout when start is called. However, be aware that if you are storing other data on your nodes, your data attributes should not conflict with the above properties used by the layout.
public final Array<? extends Link> links()
public final Force links(Array<? extends Link> links)
Force.Node node (an element in nodes).Force.Node node (an element in nodes).Note: the values of the source and target attributes may be initially specified as indexes into the nodes array; these will be replaced by references after the call to start. Link objects may have additional fields that you specify; this data can be used to compute link strength and distance on a per-link basis using an accessor function.
public final Force start()
On start, the layout initializes various attributes on the associated
nodes. The index of each node is computed by iterating over the array,
starting at zero. The initial x and y coordinates, if not already set
externally to a valid number, are computed by examining neighboring
nodes: if a linked node already has an initial position in x or y, the
corresponding coordinates are applied to the new node. This increases the
stability of the graph layout when new nodes are added, rather than using
the default which is to initialize the position randomly within the
layout's size. The previous px and py position is set to the initial
position, if not already set, giving new nodes an initial velocity of
zero. Finally, the fixed boolean defaults to false.
The layout also initializes the source and target attributes on the associated links: for convenience, these attributes may be specified as a numeric index rather than a direct link, such that the nodes and links can be read-in from a JSON file or other static description that may not allow circular linking. The source and target attributes on incoming links are only replaced with the corresponding entries in nodes if these attributes are numbers; thus, these attributes on existing links are unaffected when the layout is restarted. The link distances and strengths are also computed on start.
public final double alpha()
public final Force alpha(double x)
public final Force resume()
force.alpha(.1);
Sets the cooling parameter alpha to 0.1. This method sets the internal alpha parameter to 0.1, and then restarts the timer. Typically, you don't need to call this method directly; it is called automatically by start. It is also called automatically by drag during a drag gesture.
public final Force stop()
force.alpha(0);
Terminates the simulation, setting the cooling parameter alpha to zero. This can be used to stop the simulation explicitly, for example, if you want to show animation or allow other interaction. If you do not stop the layout explicitly, it will still stop automatically after the layout's cooling parameter decays below some threshold.
public final void tick()
force.start();
for (var i = 0; i < n; ++i)
force.tick();
force.stop();
The number of iterations depends on the graph size and complexity. The
choice of initial positions can also have a dramatic impact on how
quickly the graph converges on a good solution. For example, here the
nodes are arranged along the diagonal:
var n = nodes.length;
nodes.forEach(function(d, i) {
d.x = d.y = width / n * i;
});
If you do not initialize the positions manually, the force layout will initialize them randomly, resulting in somewhat unpredictable behavior.
public final Selection on(String name, DatumFunction<?> callback)
var link = vis.selectAll("line").data(links).enter().append("line");
var node = vis.selectAll("circle").data(nodes).enter().append("circle")
.attr("r", 5);
You can set their positions on tick:
force.on("tick", function() {
link.attr("x1", function(d) { return d.source.x; })
.attr("y1", function(d) { return d.source.y; })
.attr("x2", function(d) { return d.target.x; })
.attr("y2", function(d) { return d.target.y; });
node.attr("cx", function(d) { return d.x; })
.attr("cy", function(d) { return d.y; });
});
In this case, we've stored the selections node and link on
initialization, so that we don't need to reselect the nodes on every
tick. If you prefer, you can display nodes and links differently; for
example, you might use symbols rather than circles.
The "end" event is dispatched when the simulations internal alpha cooling parameter reaches zero.
name - callback - public final Drag drag()
Implementation note: the mousemove and mouseup event listeners are
registered on the current window, such that when the user starts dragging
a node, they can continue to drag the node even if the mouse leaves the
window. Each event listener uses the "force" namespace, so as to avoid
collision with other event listeners you may wish to bind to nodes or to
the window. If a node is moved by the drag behavior, the subsequent click
event that would be triggered by the final mouseup is captured and the
default behavior prevented. If you register a click event listener, you
can ignore these clicks on drag by seeing if the default behavior was
prevented:
selection.on("click", function(d) {
if (d3.event.defaultPrevented) return; // ignore drag
otherwiseDoAwesomeThing();
});
See the collapsible force layout and divergent forces for examples.
Copyright © 2015 gwt-d3. All rights reserved.