T
- the type of datum of each nodepublic class Force<T>
extends com.google.gwt.core.client.JavaScriptObject
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.ForceEventType
Type of force event for
on(ForceEventType, DatumFunction) method. |
static class |
Force.Link<T>
Each link has the following attributes:
source - the source node (an element in nodes).
|
static class |
Force.Node<T>
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<T> |
alpha(double x)
Sets the force layout's cooling parameter, alpha to the constant value
specified.
|
double |
charge() |
Force<T> |
charge(DatumFunction<Double> callback)
Sets sets the charge strength per node.
|
Force<T> |
charge(double x)
Sets the charge strength to the specified constant value for all nodes.
|
double |
chargeDistance() |
Force<T> |
chargeDistance(double x)
Sets the maximum distance over which charge forces are applied to nodes.
|
Drag |
drag()
Bind a behavior to nodes to allow interactive dragging, either using the
mouse or touch.
|
double |
friction() |
Force<T> |
friction(double friction)
Sets the friction coefficient to the specified value.
|
double |
gravity() |
Force<T> |
gravity(double x)
Sets the gravitational strength to the specified value.
|
double |
linkDistance() |
Force<T> |
linkDistance(DatumFunction<Double> callback)
Sets the target distance between linked nodes.
|
Force<T> |
linkDistance(double distance)
Sets the target distance between linked nodes to the specified constant
value.
|
Array<Force.Link<T>> |
links() |
Force<T> |
links(Array<Force.Link<T>> links)
Sets the layout's associated links to the specified array.
|
double |
linkStrength() |
Force<T> |
linkStrength(DatumFunction<Double> callback)
Sets the strength (rigidity) of links in the range [0,1].
|
Force<T> |
linkStrength(double strength)
Sets the strength (rigidity) of all links to the specified constant value
in the range [0,1].
|
Array<Force.Node<T>> |
nodes() |
Force<T> |
nodes(Array<Force.Node<T>> nodes)
Sets the layout's associated nodes to the specified array.
|
Force<T> |
nodes(List<Force.Node<T>> nodes)
Sets the layout's associated nodes to the specified array.
|
Selection |
on(Force.ForceEventType type,
DatumFunction<?> callback)
Registers the specified listener to receive events of the specified type
from the force layout.
|
Force<T> |
resume()
Equivalent to:
|
Array<Short> |
size() |
Force<T> |
size(Array<Double> size)
Sets the available layout size.
|
Force<T> |
size(double width,
double height)
Sets the available layout size.
|
Force<T> |
start()
Starts the simulation; this method must be called when the layout is
first created, after assigning the nodes and links.
|
Force<T> |
stop()
Equivalent to:
|
double |
theta() |
Force<T> |
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<T> size(Array<Double> size)
The size affects two aspects of the force-directed layout: the gravitational center, and the initial random position. The center of gravity is simply [ width / 2, height / 2 ]. When nodes are added to the force layout, if they do not have x and y attributes already set, then these attributes are initialized using a uniform random distribution in the range [0, width] and [0, height], respectively.
size
- to setpublic final Force<T> size(double width, double height)
The size affects two aspects of the force-directed layout: the gravitational center, and the initial random position. The center of gravity is simply [ width / 2, height / 2 ]. When nodes are added to the force layout, if they do not have x and y attributes already set, then these attributes are initialized using a uniform random distribution in the range [0, width] and [0, height], respectively.
width
- height
- public final double linkDistance()
public final Force<T> linkDistance(double distance)
distance
- to setpublic final Force<T> linkDistance(DatumFunction<Double> callback)
The given function is evaluated for each link (in order), being passed the link and its index, with the context
as the force layout; the function's return value is then used to set each link's distance. The function is
evaluated whenever the layout start()
s.
callback
- function that returns link distance for each link in the
documentpublic final double linkStrength()
public final Force<T> linkStrength(double strength)
public final Force<T> linkStrength(DatumFunction<Double> callback)
The given 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 strength. The function
is evaluated whenever the layout start()
s.
public final double friction()
public final Force<T> friction(double friction)
public final double charge()
public final Force<T> 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<T> charge(DatumFunction<Double> callback)
The given function is evaluated for each node (in order), being passed the node and its index, with the this
context as the force layout; the function's return value is then used to set each node's charge. The function is
evaluated whenever the start()
s.
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<T> chargeDistance(double x)
Specifying a finite charge distance improves the performance of the force layout and produces a more localized layout; distance-limited charge forces are especially useful in conjunction with custom gravity.
public final double theta()
public final Force<T> 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<T> 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<Force.Node<T>> nodes()
public final Force<T> nodes(List<Force.Node<T>> nodes)
Nodes 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 Force<T> nodes(Array<Force.Node<T>> nodes)
Nodes 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<Force.Link<T>> links()
public final Force<T> links(Array<Force.Link<T>> links)
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<T> start()
resume()
or by restarting; this happens
automatically when using the drag()
behavior.
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
linkDistance()
and linkStrength()
are also computed on start.
public final double alpha()
public final Force<T> alpha(double x)
Force.ForceEventType.START
event
and enabling the tick timer. If value is nonpositive, and the force
layout is running, this method stops the force layout on the next tick
and dispatches an Force.ForceEventType.END
event.public final Force<T> 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<T> 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()
start()
and stop()
to compute a static layout. For example:
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(Force.ForceEventType type, 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.
type
- the type of event to listen tocallback
- public final Drag drag()
resume()
of the force layout, reheating
the simulation. If you want dragged nodes to remain fixed after dragging,
set the fixed attribute to true on dragstart, as in the sticky force
layout example.
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 © 2017 gwt-d3. All rights reserved.