ForceDirectedLayout class

Force-directed layout treats the graph as if it were a system of physical bodies with repulsive electrical, attractional gravitational, and spring forces acting on them and between them.

Electrical forces come both from the field at the vertex's location as well as from neighboring vertexes and are quadratic by distance. Gravitational forces come from the field at the vertex's location and are constant. Spring forces are only exerted between two different vertexes that are connected by an edge and are linear by distance.

The electrical forces on a vertex are the sum of the electrical charge times the electrical field at that location (#electricalCharge, #electricalFieldX, #electricalFieldY) and the electrical forces of all nearby vertexes divided by the square of the distance between them. You can easily assign the electrical charge for all vertexes by assigning #defaultElectricalCharge. By default there is no electrical field, so all forces are due to nearby charged vertexes. For efficiency, #infinityDistance determines a cut-off distance between vertexes for which to consider any influence.

The gravitational forces on a vertex are the sum of the gravitational mass times the gravitational field at that location (#gravitationalMass, #gravitationalFieldX, #gravitationalFieldY). You can easily assign the gravitational mass for all vertexes by assigning #defaultGravitationalMass. By default there is no gravitational field.

The spring forces on a vertex are only exerted by the edges connecting it with other vertexes. The force along an edge is the stiffness of the spring times the difference of the distance between the vertexes and the nominal length of the spring (#springStiffness, #springLength) divided by the distance between the vertexes. When the distance is less than the nominal length, the force pushes the vertexes apart; when the distance is greater, the force pulls them together. You can easily assign the spring length and stiffness for all edges by assigning #defaultSpringLength and #defaultSpringStiffness.

When the distance between two vertexes is less than one unit, this uses a random number generator to decide which direction the forces should go. For layouts that start with all of the vertexes at the same location, this results in potentially dramatically different results. Set #randomNumberGenerator to null in order to produce reproducible results given the same initial vertex locations.

The algorithm seeks a configuration of the bodies with locally minimal energy, i.e. vertex positions such that the sum of the forces on each vertex is zero. This is achieved by repeatedly computing the forces on each vertex, moving them, and repeating. Computations stop when no vertex moves more than #epsilonDistance or when #maxIterations have happened.

The layout cannot guarantee that it provides optimal positioning of nodes. Nodes will normally not overlap each other, but when there is a dense interconnectivity overlaps might not be avoidable.

If you want to experiment interactively with most of the properties, try the Force Directed Layout sample. See samples that make use of ForceDirectedLayout in the samples index.

This layout makes use of a LayoutNetwork of ForceDirectedVertexes and ForceDirectedEdges that normally correspond to the Nodes and Links of the Diagram.

Implemented types

• Layout

Available extensions

• ForceDirectedLayout$Typings
• Layout$Typings

Annotations

• @JS()
• @staticInterop

Constructors

ForceDirectedLayout([dynamic init])

factory

Properties

arrangementOrigin ↔ Point

Available on Layout, provided by the Layout$Typings extension

Gets or sets the top-left point for where the graph should be positioned when laid out. The default value for this property is the Point(0, 0). Setting this property to a new value invalidates this layout. This property is likely to be set by many Layouts that belong to a Group when the layout is performed.

getter/setter pair

arrangementSpacing ↔ Size

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets the space between which the layout will position the connected graphs that together compose the network. This defaults to Size(100, 100). These distances are used during a clustered layout; afterwards the normal force-directed layout will likely cause the size of any space between connected graphs to change, perhaps considerably.

getter/setter pair

arrangesToOrigin ↔ bool

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets whether #commitNodes should move all of the nodes so that the nodes all fit with the top-left corner at the Layout#arrangementOrigin. By default this is false -- the Layout#arrangementOrigin is ignored. When this is true, nodes are moved even though #isFixed was true.

getter/setter pair

boundsComputation ↔ Rect Function(Part, Layout, Rect)?

Available on Layout, provided by the Layout$Typings extension

Gets or sets a function that determines the initial size and position in document coordinates of a LayoutVertex corresponding to a Node. This function is called by #getLayoutBounds. The default value for this property is null, in which case the GraphObject#actualBounds of the Node is used. Setting this property to a new value invalidates this layout.

getter/setter pair

comments ↔ bool

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets whether this layout should find all Nodes whose category is "Comment" and whose anchors are nodes represented in the network, and add ForceDirectedVertexes representing those balloon comments as nodes in the network. The default value is false.

getter/setter pair

currentIteration ↔ num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

This read-only property returns the current iteration count, valid during a call to #doLayout.

getter/setter pair

defaultCommentElectricalCharge ↔ num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets the default value computed by #electricalCharge. The initial value is 5.

getter/setter pair

defaultCommentSpringLength ↔ num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets the default value computed by #springLength. The initial value is 10.

getter/setter pair

defaultElectricalCharge ↔ num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets the default value computed by #electricalCharge. The initial value is 150.

getter/setter pair

defaultGravitationalMass ↔ num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets the default value computed by #gravitationalMass. The initial value is zero.

getter/setter pair

defaultSpringLength ↔ num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets the default value computed by #springLength. The initial value is 50.

getter/setter pair

defaultSpringStiffness ↔ num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets the default value computed by #springStiffness. The initial value is 0.05.

getter/setter pair

diagram ↔ Diagram?

Available on Layout, provided by the Layout$Typings extension

Gets the Diagram that owns this layout, if it is the value of Diagram#layout.

getter/setter pair

epsilonDistance ↔ num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets approximately how far a node must move in order for the iterations to continue. The default value is 1. The value must be larger than zero.

getter/setter pair

group ↔ Group?

Available on Layout, provided by the Layout$Typings extension

Gets the Group that uses this layout, if it is the value of a group's Group#layout.

getter/setter pair

hashCode → int

The hash code for this object.

no setter, inherited

infinityDistance ↔ num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets a threshold for the distance beyond which the electrical charge forces may be ignored. The default value is 1000. The value must be larger than 1.

getter/setter pair

isInitial ↔ bool

Available on Layout, provided by the Layout$Typings extension

Gets or sets whether this layout is performed on an initial layout. The default value is true. Setting this property to false causes #isValidLayout to be set to true so that the diagram does not perform this layout.

getter/setter pair

isOngoing ↔ bool

Available on Layout, provided by the Layout$Typings extension

Gets or sets whether this layout can be invalidated by #invalidateLayout. Set this to false to prevent actions such as adding or removing Parts from invalidating this layout. The default value is true. Setting this property does not invalidate this layout.

getter/setter pair

isRealtime ↔ bool?

Available on Layout, provided by the Layout$Typings extension

Gets or sets whether this layout be performed in real-time, before the end of a transaction. All layouts that are invalidated will be performed at the end of a transaction. The default value is null. A null value is treated as true for a Diagram#layout but false for a Group#layout. Setting this property does not invalidate this layout.

getter/setter pair

isRouting ↔ bool

Available on Layout, provided by the Layout$Typings extension

Gets or sets whether this layout routes Links. The default value is true. When false, this layout will not explicitly set the Link#points, and the default routing of each individual Link will take place after the Nodes are moved by #commitLayout. Setting this property does not invalidate this layout.

getter/setter pair

isValidLayout ↔ bool

Available on Layout, provided by the Layout$Typings extension

Gets or sets whether this layout needs to be performed again (if false). Instead of setting this property directly, it is normal to set it to false by calling #invalidateLayout, since that also requests performing a layout in the near future.

getter/setter pair

isViewportSized ↔ bool

Available on Layout, provided by the Layout$Typings extension

Gets or sets whether this layout depends on the Diagram#viewportBounds's size. If set to true, the layout will invalidate when the Diagram's viewport changes size. This only applies to diagram layouts, not to group layouts, and only when Diagram#autoScale is set to Diagram.None.

getter/setter pair

maxIterations ↔ num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets the maximum number of iterations to perform when doing the force-directed auto layout. The value must be non-negative. The default value is 100.

getter/setter pair

moveLimit ↔ num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets how far a vertex may be moved in an iteration. The default value is 10. The value must be larger than 1.

getter/setter pair

network ↔ LayoutNetwork?

Available on Layout, provided by the Layout$Typings extension

Gets or sets the LayoutNetwork used by this Layout, if any. The default value is null. Setting this property does not invalidate this layout. Not all kinds of layout make use of a LayoutNetwork. Call #createNetwork or #makeNetwork to create a network.

getter/setter pair

randomNumberGenerator ↔ dynamic

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets a random number generator. The default value is Math, which results in calling Math.random(). Change this to null in order to use an instance of an internal repeatable pseudo-random number generator, which will become the new value of this property.

getter/setter pair

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

setsPortSpots ↔ bool

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Gets or sets whether the fromSpot and the toSpot of every Link should be set to Spot.Default. The default value is true.

getter/setter pair

Methods

addComments(ForceDirectedVertex v) → void

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Find any associated objects to be positioned along with the LayoutVertex#node.

cloneProtected(Layout copy) → void

Available on Layout, provided by the Layout$Typings extension

Copies properties from this object to the given object, which is of the same class. This is called by #copy and should be overridden for each class that adds properties. There are examples of such overrides in the samples. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

collectParts(Object coll) → Set<Part>

Available on Layout, provided by the Layout$Typings extension

A convenient way of converting the Diagram|Group|Iterable argument to doLayout to an actual collection of eligible Parts. The resulting Set will not include any Nodes or Links for which Part#canLayout is false. If the argument includes a Group for which Group#layout is null, the resulting Set will include the member parts of that group rather than that group itself. You will not need to call collectParts if you call #makeNetwork, because that method does effectively the same thing when building the LayoutNetwork.

commitLayout() → void

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Set the fromSpot and toSpot on each Link, position each Node according to the vertex position, and then position/route the Links.

commitLayout() → void

Available on Layout, provided by the Layout$Typings extension

When using a LayoutNetwork, commit changes to the diagram by setting Node positions and by routing the Links. This is called by #updateParts within a transaction.

commitLinks() → void

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Routes the links.

commitNodes() → void

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Commit the position of all nodes.

copy() → Layout

Available on Layout, provided by the Layout$Typings extension

Creates a copy of this Layout and returns it. When a Group is copied that has a Group#layout, the Layout must also be copied. This calls #cloneProtected on a newly constructed Layout. @expose @return {Layout}

createNetwork() → ForceDirectedNetwork

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Create a new LayoutNetwork of ForceDirectedVertexes and ForceDirectedEdges. @return {ForceDirectedNetwork} a new LayoutNetwork.

createNetwork() → LayoutNetwork

Available on Layout, provided by the Layout$Typings extension

Create a new LayoutNetwork of LayoutVertexes and LayoutEdges. This may be overridden in Layout subclasses to create instances of subclasses of LayoutNetwork. Please read the Introduction page on Extensions for how to override methods and how to call this base method. @expose @return {LayoutNetwork} a new LayoutNetwork.

doLayout(Object coll) → void

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Perform the force-directed layout.

doLayout(Object coll) → void

Available on Layout, provided by the Layout$Typings extension

Position all of the nodes that do not have an assigned Part#location in the manner of a simple rectangular array. The default implementation ignores all Groups and Links; many subclasses of Layout ignore all instances of Parts that are not Nodes or Links.

electricalCharge(ForceDirectedVertex v) → num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Returns the charge of the vertex, the value of ForceDirectedVertex#charge if it's a number, or else the value of #defaultElectricalCharge.

electricalFieldX(num x, num y) → num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Returns the electrical field in the X direction acting on a vertex at the given point. By default there is no electrical field at any location.

electricalFieldY(num x, num y) → num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Returns the electrical field in the Y direction acting on a vertex at the given point. By default there is no electrical field at any location.

getLayoutBounds(Part part, [Rect? rect]) → Rect

Available on Layout, provided by the Layout$Typings extension

This method is called by layouts to determine the size and initial position of the nodes that it is laying out. Normally this just returns the part's GraphObject#actualBounds. However, if #boundsComputation has been set to a function, that function will be called in order to return the bounds of the given Part in document coordinates that the layout should pretend it has. @param {Part} part the Part being laid out @param {Rect=} rect an optional Rect that will be modified and returned @return {Rect} a Rect in document coordinates @since 2.0

gravitationalFieldX(num x, num y) → num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

This returns the gravitational field in the X direction acting on a vertex at the given point. By default there is no gravitational field at any location.

gravitationalFieldY(num x, num y) → num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

This returns the gravitational field in the Y direction acting on a vertex at the given point. By default there is no gravitational field at any location.

gravitationalMass(ForceDirectedVertex v) → num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Returns the mass of the vertex, the value of ForceDirectedVertex#mass if it's a number, or else the value of #defaultGravitationalMass. Please read the Introduction page on Extensions for how to override methods and how to call this base method. @expose @param {ForceDirectedVertex} v @return {number}

initialOrigin(Point origin) → Point

Available on Layout, provided by the Layout$Typings extension

Compute the desired value of #arrangementOrigin if this Layout is being performed for a Group. This is typically called near the beginning of the implementation of #doLayout: this.arrangementOrigin = this.initialOrigin(this.arrangementOrigin); if the layout wants to respect the pre-layout location of the Group when deciding where to position its member nodes.

invalidateLayout() → void

Available on Layout, provided by the Layout$Typings extension

If #isOngoing is true and if an initial layout has not yet been performed, set the #isValidLayout property to false, and ask to perform another layout in the near future. If #isInitial is true, this layout is invalidated only when the Diagram#model is replaced, not under the normal circumstances such as when parts are added or removed or due to other calls to Layout#invalidateLayout.

isFixed(ForceDirectedVertex v) → bool

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

This predicate returns true if the vertex should not be moved by the layout algorithm but still have an effect on nearby and connected vertexes. The default implementation returns ForceDirectedVertex#isFixed. Please read the Introduction page on Extensions for how to override methods and how to call this base method. @expose @param {ForceDirectedVertex} v @return {boolean} returns true if the node should not be moved by the layout algorithm.

makeNetwork(Object coll) → LayoutNetwork

Available on Layout, provided by the Layout$Typings extension

Create and initialize a LayoutNetwork with the given nodes and links. This should be called by #doLayout when this layout uses a #network. This method calls #createNetwork to allocate the network. This may be overridden in Layout subclasses to customize the initialization. Please read the Introduction page on Extensions for how to override methods and how to call this base method. @expose @param {Diagram|Group|Iterable.

moveFixedVertex(ForceDirectedVertex v) → void

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Maybe move a vertex that #isFixed. This is called each iteration on each such vertex. By default this does nothing. @expose @param {ForceDirectedVertex} v

moveVertex(ForceDirectedVertex v) → num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

(undocumented) Move the vertex by its ForceDirectedVertex.forceX and ForceDirectedVertex.forceY. Return the square of the distance moved. This can be overridden in order to constrain the vertex's actual movement. @expose @param {ForceDirectedVertex} v @return {number} square of distance moved

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

springLength(ForceDirectedEdge e) → num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Returns the length of the spring representing an edge. The two vertexes connected by the edge E are acted upon by a force of proportional to springStiffness(E) * (getNodeDistance(E.fromVertex, E.toVertex) - springLength(E)) divided by the distance between the vertexes. Please read the Introduction page on Extensions for how to override methods and how to call this base method. @expose @param {ForceDirectedEdge} e @return {number} Returns the length of the edge representing a link, the value of ForceDirectedEdge#length if it's a number, or else the value of #defaultSpringLength.

springStiffness(ForceDirectedEdge e) → num

Available on ForceDirectedLayout, provided by the ForceDirectedLayout$Typings extension

Returns the stiffness of the spring representing an edge.

toString() → String

A string representation of this object.

inherited

updateParts() → void

Available on Layout, provided by the Layout$Typings extension

When using a LayoutNetwork, update the "physical" node positionings and link routings. This should be called by #doLayout when this layout uses a #network. This calls #commitLayout to actually set Node positions and route Links. This performs the changes within a transaction. Please read the Introduction page on Extensions for how to override methods and how to call this base method. @expose

Operators

operator ==(Object other) → bool

The equality operator.

inherited