ForceDirected

ForceDirected class implements automatic layouts for graphs using a force-directed approach.

To learn more, check out the learn section.

constructor

constructor(options: ForceDirected.Options);

The layout.ForceDirected constructor options parameter has following properties:

charge

[optional] Repulsive force. Bigger the parameter is, bigger the repulsive force. If the charge is set to 0, the repulsive force is not calculated. Default is 10.

deltaT

[optional] Multiplier for the temperature between steps. Default is 0.99.

elementPoint

[optional] Option which specifies point of the element for calculations. The option has following possible values:

• 'center' - the point for calculations is a center of an element's bounding box.
• 'origin' - the point for calculations is a position of an element. Usually it is a top-left corner of an element's bounding box.

Default is center.

graph

dia.Graph or dia.Cell[] to apply layout to.

gravity

[optional] Gravity force. Applied only if gravityCenter is specified. Default is 10.

gravityCenter

[optional] The point the elements tend to move to.

gravityType

[optional] Gravity force type. The option has following possible values:

• 'graph' - all elements are attracted to the gravity center as a whole in a way that distances between elements are preserved.
• 'element' - each element is attracted to the gravity center of the graph separately with a force proportional to the distance.
• 'elementUniform' - each element is attracted to the gravity center of the graph with a same force regardless of the distance.

Default is 'graph'.

height

(deprecated) - use layoutArea instead.

[optional] Height of the layout area.

layoutArea

[optional] The layout area, which restricts the movement of the elements.

linkBias

[optional] Do use bias for link strength calculations depending on the number of the links. This option enables asymmetric application of attractive force to the elements on the ends of the link. This option is better use for graph-like diagrams as it produces more clear and ordered representations. Default is true.

linkDistance

[optional] Specifies targeted link length. Default is 50.

linkStrength

[optional] Attractive force parameter. Bigger the parameter, bigger the attractive force. Default is 200.

radialForceStrength

[optional] Strength of a radial force. Radial force prevents the elements from overlapping by applying force if the elements` circular representation overlaps. By default the radius is a radius of an outer circle of a bbox. It can be specified for the particular element using radius attribute. Default is 0.

randomize

[optional] Randomize initial positions of the elements in the randomizeArea. If randomizeArea is not presented, layoutArea is used instead. Default is false.

randomizeArea

[optional] The area where the elements are randomized.

theta

[optional] Barnes-Hut quadtree approximation parameter. Default is 0.7.

timeQuantum

[optional] Time quantum for the force integration for each step. Default is 0.03.

tMin

[optional] Minimal temperature. Default is 0.001.

tTarget

[optional] Target temperature. If the tTarget is larger then tMin the simulation will be calculated at the tTarget temperature level. It is useful for the use cases where constant changes occur. Default is 0.

velocityDecay

[optional] Velocity decay parameter, which is used to limit the velocity of the elements. The value should be in the (0, 1) interval. Default is 0.6.

weightDistribution

[optional] The weight distribution of the elements. The option has following possible values:

• 'linkCount' - the default weight of a element is calculated based on the number of links connected to it.
• 'uniform' - the default weight is the same for all elements (1).

Default is linkCount.

width

(deprecated) - use layoutArea instead.

[optional] Width of the layout area.

x

(deprecated) - use layoutArea instead.

[optional] X coordinate of the top-left corner of the layout area. Default is 0.

y

(deprecated) - use layoutArea instead.

[optional] Y coordinate of the top-left corner of the layout area. Default is 0.

Methods

addElement()

forceDirected.addElement(element: dia.Element): void

Adds new element to the layout.

addLink()

forceDirected.addLink(link: dia.Link): void

Adds new link to the layout.

changeLinkData()

forceDirected.changeLinkData(id: dia.Cell.ID, data: Partial<ForceDirected.LinkData>): void

Changes current data associated with the link.

changeElementData()

forceDirected.changeElementData(id: dia.Cell.ID, data: Partial<ForceDirected.ElementData>): void

Changes current data associated with the element.

finalize()

forceDirected.finalize(): void

Calculates all required steps to reach tMin or tTarget whichever is higher and applies final positions to the graph. It continues calculation from the current state of the simulation (i.e. you can finalize if you want to fast-forward already started simulation).

getLinkData()

forceDirected.getLinkData(id: dia.Cell.ID): ForceDirected.LinkData

Returns the link data object by link's id. The changes to the object are reflected in the layout.

getElement()

forceDirected.getElement(id: dia.Cell.ID): ForceDirected.ElementData

Returns the element data object by element's id. The changes to the object are reflected in the layout.

removeElement()

forceDirected.removeElement(id: dia.Cell.ID): void

Removes the element from the layout.

removeLink()

forceDirected.removeLink(id: dia.Cell.ID): void

Removes the link from the layout.

restart()

forceDirected.restart(t: number): void

Restarts the layout process with the given temperature.

start()

forceDirected.start(): void

Initiates the layout process.

step()

forceDirected.step(dt: number): void

Updates the position of shapes for the current step. The dt parameter is the time quantum for the force integration for the step. The default value is timeQuantum option.

Cell attributes

The force directed layout also reads some cell attributes allowing for a fine control of the layout engine. The attributes are located in the special attribute object specified in the attributesName static property (by default under forceDirectedAttributes object). For example:

element.prop('forceDirectedAttributes/radius', 10);

layout.addElement(element);

note

The attributes are read only once at the time of adding element to the layout. If you want to change the attributes during the layout process, you have to call the changeElementData() or changeLinkData() method.

Element attributes

Attribute	Description
weight	Sets the weight of the element
fixed	Makes the position of the element fixed in place
radius	Sets the radius for the element

Link attributes

Attribute	Description
strength	Sets the strength of the link
distance	Sets the target distance of the link

Static properties

attributesName

Name of the special attribute which contains all options for the layout on the cell level. Default is 'forceDirectedAttributes'. if you want to change this path, so the algorithm reads the attributes from different object, you can change the attributesName static property like this:

layout.ForceDirected.attributesName = 'customAttributesObject';

And then you can set the attributes using customAttributesObject and the algorithm will read them:

element.prop('customAttributesObject/radius', 10);

Types

ElementData

Element data object type

interface ElementData {
    weight: number;
    weightCoeff: number;
    p: dia.Point;
    v: dia.Point;
    force: dia.Point;
    absoluteForce: dia.Point;
    element: dia.Element;
    fixed: boolean;
    restrictX: boolean;
    restrictY: boolean;
    alignX: dia.Cell.ID;
    alignY: dia.Cell.ID;
    radius?: number;
}

LinkData

Link data object type

interface LinkData {
    source: ElementData;
    target: ElementData;
    strength: number;
    distance: number;
    link: dia.Link;
    bias: number;
}

Options

Constructor options parameter type

interface Options {
    graph: dia.Graph | dia.Cell[];
    layoutArea?: dia.BBox;
    weightDistribution?: WeightDistribution;
    linkDistance?: number;
    linkStrength?: number;
    randomize?: boolean;
    randomizeArea?: dia.BBox;
    gravityCenter?: dia.Point;
    gravity?: number;
    charge?: number;
    linkBias?: boolean;
    theta?: number;
    deltaT?: number;
    velocityDecay?: number;
    tMin?: number;
    tTarget?: number;
    timeQuantum?: number;
    elementPoint?: ElementPoint;
    x?: number;
    y?: number;
    width?: number;
    height?: number;
    radialForceStrength?: number;
    gravityType?: GravityType;
}