Organic Layouts

The organic layout style is based on the force-directed layout paradigm. When calculating a layout, the nodes are considered to be physical objects with mutually repulsive forces, like, e.g., protons or electrons. The connections between nodes also follow the physical analogy and are considered to be springs attached to the pair of nodes. These springs produce repulsive or attractive forces between their end points if they are too short or too long. The layout algorithm simulates these physical forces and rearranges the positions of the nodes in such a way that the sum of the forces emitted by the nodes and the edges reaches a (local) minimum.

Resulting layouts often expose the inherent symmetric and clustered structure of a graph, they show a well-balanced distribution of nodes and have few edge crossings.

This layout style is well suited for the visualization of highly connected backbone regions with attached peripheral ring or star structures. These structurally different regions of a network can be easily identified by looking at a drawing produced by organic layout algorithms.

Application Areas

The organic layout style presents a multi-purpose layout for undirected graphs. It produces clear representations of complex networks and is especially fit for application areas such as:

Bioinformatics
Enterprise networking
Knowledge representation
System management
WWW visualization
Mesh visualization

Relevant Classes

Relevant classes for this style lists the relevant classes for the organic layout style.

Relevant classes for this style
Class Name	Description
OrganicLayout	Main algorithm. See the description below.
InteractiveOrganicLayout	This class provides organic layout in an interactive environment where a user directly manipulates a diagram and updates to the diagram’s layout are calculated continuously. See the description of this class in Interactive Organic Layout.

Besides OrganicLayout (OL), the yFiles diagramming library includes a legacy layout algorithm for the organic layout style, class ClassicOrganicLayout. OL supersedes this class and adds features to prevent node (label) overlaps and to keep minimum distances between the nodes. See also Related Layout Algorithms.

Class OrganicLayout is an organic layout provider that supports both complete re-layout of a given diagram as well as incremental layout where only a subset of a diagram should be rearranged.

One of the strengths of OrganicLayout is its ability to control the ratio of quality versus running time, as well as its ability to produce organic layouts while guaranteeing the absence of node overlaps. Additionally, OrganicLayout also prevents node label overlaps and keeps minimum distances between nodes.

OrganicLayout provides a set of options that influence the layout behavior.

Basic Options

Preferred Edge Length
preferredEdgeLength: Allows to specify the general preferred length of all edges. The layout algorithm tries to arrange the nodes in such a way that the edges have the desired edge length. If "Node Size Aware" is checked, then the edge length is measured from node border to node border. Otherwise, the edge length is measured from node center to node center.To specify the preferred edge length for each edge individually, provide supplemental layout data, for example using the property OrganicLayoutData.preferredEdgeLengths Note that in the absence of an individual preferred edge length the general preferred edge length will be used.
Node Size Aware
considerNodeSizes: Whether or not to obey the size of the nodes when calculating the layout. The distance between two nodes is calculated with respect to the node sizes, i.e., for equal preferred edge lengths, activating this feature will lead to bigger layouts. Note that enabling "Consider Node Labels" also enables this property.
Consider Node Labels
considerNodeLabels: Enables node label-aware layout calculation. Note that enabling this option also enables the "Node Size Aware" property.
Node Overlaps Allowed
nodeOverlapsAllowed: Whether or not nodes are allowed to overlap. If this feature is disabled, the "Minimal Node Distance" will be used to arrange the nodes in such a way that the given distance will be obeyed.
Minimal Node Distance
minimumNodeDistance: The minimal node distance which will be used if "Node Overlaps Allowed" is disabled.

Using property "Node Overlaps Allowed," organic layout can be configured to guarantee the absence of node overlaps even for very dense graphs. Further improvements can be achieved using the "Consider Node Labels" property, which prevents that node label overlap with graph elements.

Additionally, using property "Minimal Node Distance," it is possible to specify a minimal node distance, i.e., it can be guaranteed that there will be a certain amount of space around each node, which is not occupied by other nodes.

Chain Recognition
chainRecognition: If this property is enabled, the OrganicLayout adaptively straightens chains, i.e., it straightens path of degree-2 nodes. More precisely, if the nodes of a chain lie almost on one common straight line after applying the physical forces, the positions of these nodes are adapted such they are aligned on a straight line. The orientation of the line as well as the order and distances of the nodes is determined automatically.
Circle Recognition
circleRecognition: If this property is enabled, the OrganicLayout detects cycles in the graph whose nodes almost lie on a geometric circle, respectively. For each of these cycles the layout algorithm rearranges the nodes such that they exactly lie on a geometric circle. The radius is automatically detected. Currently, only cycles are supported, that are connected to the remaining graph by at most one edge and that do not have any chord edges.
Compactness
compactnessFactor: Adjusting this value can lead to a variety of differing layouts. For small values, the resulting layout will use a lot of space and nodes tend to be far away from each other. Values around 0.5 lead to evenly distributed nodes, whereas values near 1.0 produce highly compact layouts.

Layout results when using different compactness settings shows the results of layout calculations using different compactness values.

Output Restriction
outputRestriction: Allows to impose so-called "output restrictions" on the result of the layout calculation. More precisely, the layout result can be specified to fit into a (simple) geometric shape, like, e.g., a rectangle or a circle. Also, the layout result can be restricted to a specified aspect ratio.Class OutputRestriction serves as a factory to create predefined output restrictions that can be used in conjunction with this property.

Organic layout can choose between different strategies, combinations and configurations of a couple of related algorithms to control the running time versus the quality of the layout.

Using small values for property "Quality/Time Ratio," it is possible to produce acceptable layouts for huge graphs (thousands of nodes within seconds), whereas setting this value to greater values leads to high-quality layouts, which may take longer (up to a few minutes for hundreds of nodes).

Quality/Time Ratio
qualityTimeRatio: This setting can be used to adjust the quality versus the running time of the layout algorithm. Small values lead to short running times, while greater values result in better quality. For large graph structures (hundreds and thousands of nodes) it is advisable to begin with smaller values and to gradually increase them.
Maximum Duration
maximumDuration: Sets the maximal duration of the layout process in milliseconds. If this upper bound is hit during the layout process, the quality of the layout may not be optimal. Increasing this values increases the likeliness of an optimal layout.
Deterministic
deterministic: Whether or not the layout process should be deterministic. In deterministic mode the layout algorithm produces identical results for identical input graphs and identical settings.

Labeling

Edge labels can be placed automatically using the generic labeling support as described in Generic Labeling, which is available with all yFiles layout algorithms. Additionally, OrganicLayout can be set up to take node labels into account during layout. Node labels do not need to be placed, but instead their size needs to be considered for the placement of adjacent graph elements. Taking node labels into consideration during layout calculation guarantees that they will not overlap nodes in the diagram.

Node label awareness is enabled using the "Consider Node Labels" property. See the description of the options in Basic Options.

Grouped Graphs

OrganicLayout directly supports layout of grouped graphs. Both position and dimension of group nodes will be calculated by the algorithm.

Minimum size constraints for group nodes, which can be conveniently used in order to accommodate for the size of its label, are handled by the MinimumSizeGroupBoundsCalculator instance that is registered with OrganicLayout. If a data provider is registered with the graph using the look-up key MINIMUM_NODE_SIZE_DP_KEY, any individual minimum size constraints for group nodes held by this data provider are respected by default.

Additional size requirements for group nodes can be handled by registering a custom IGroupBoundsCalculator implementation, replacing the default MinimumSizeGroupBoundsCalculator instance.

groupBoundsCalculator: Setting another IGroupBoundsCalculator implementation.

organic node groups1a — Organic layout of a grouped graph

You can achieve fine-grained control over group node handling during layout calculation by specifying GroupNodeMode for nodes via supplemental layout data. The following constants are available to instruct the algorithm how to treat a specific group node:

NORMAL: The contents of the group node will be processed by the layout algorithm. Also, the group node’s size and position will be determined by the algorithm.
FIX_CONTENTS: Size and position of the group node will be determined by the algorithm. The contents of the group node are not processed by the algorithm, but are moved with the group node.
FIX_BOUNDS: The contents of the group node will be processed by the layout algorithm, however, with respect to the original bounds of the group node which will not change.

Note that in conjunction with partitioned layout, only the first constant is supported.

Using the FIX_CONTENTS or FIX_BOUNDS constant for group nodes also enables additional incremental layout behavior specifically for group nodes.

In conjunction with the layout for grouped graphs, OrganicLayout recognizes several supplemental layout data such as GROUP_DPKEY, NODE_ID_DPKEY, PARENT_NODE_ID_DPKEY and MINIMUM_NODE_SIZE_DPKEY. Additionally, OrganicLayoutData provides a property for the aforementioned group node modes.

Incremental Layout

OrganicLayout supports different kinds of incremental layout strategies through the Scope feature.

The scope property determines the set of nodes from the graph that should be processed. In conjunction with a specified subset of the nodes of a graph, this property can be used to switch between non-incremental and incremental layout.

By default, OrganicLayout re-computes the entire layout of a given graph, i.e., it performs a non-incremental layout. When only a subset of the graph should be rearranged, i.e., when the scope is changed from its default value, supplemental layout data holding the selection state for each node is queried. The specified subset of nodes is then arranged in an incremental manner.

The following scope constants are available:

ALL: The whole graph will be considered for layout, i.e., a complete re-layout will be calculated. This is the default setting.
MAINLY_SUBSET: The selected nodes will be rearranged. The unselected nodes are only allowed to move to a certain degree.
SUBSET: Only the selected nodes will be rearranged.

Incremental layout of augmented graph shows the resulting diagrams for different Scope settings for the initial (augmented) graph from Initial graph and an augmentation. Only (or mostly) the nodes from the specified subset get arranged by OrganicLayout. The other nodes keep their position.

When only a subset of nodes should be rearranged, the "Node Overlaps Allowed" property should be enabled, otherwise unselected nodes might be moved to resolve node overlaps.

In unconnected graphs, i.e., graphs with multiple components, the following additional option can be used to improve the results of an incremental layout calculation.

smartComponentLayout: When enabled, the ComponentLayout that is used with this MultiStageLayout is configured in such a way that separate components containing nodes which should not be moved will not be rearranged.

You can achieve further incremental layout behavior specifically for group nodes through supplemental layout data, more specifically group node modes. See also the corresponding description for layout data in Grouped Graphs.

Affected nodes are also respected in conjunction with incremental layout.

Tables

OrganicLayout provides support for so-called partitioned layout. This type of layout uses the notion of cells in a table-like grid structure into which nodes are placed. Each normal node of the graph is placed into a single cell and the contents of group nodes belong to the same single cell as the group node itself. The setup for partitioned layout is presented in Layout of Tables and Swimlanes.

Partitioned layout as calculated by OrganicLayout shows a resulting partitioned layout as calculated by OrganicLayout. The visual representation as a table is rendered by a group node that uses the TableNodeStyle node style.

OrganicLayout’s support for partitioned layout covers the configuration options below for normal nodes and group nodes. Depending on the kind of partition cell ID that is associated with a normal node, the layout algorithm will place the normal node:

none: in a suitable partition cell of the partition grid structure
Single cell: in the specified partition cell of the partition grid structure

Depending on the kind of the partition cell ID that is associated with a group node, the layout algorithm will place the group node such that:

none: it encompasses all its contained nodes
Single cell: its boundary corresponds to the bounds of the specified partition cell
Range of cells: its boundary corresponds to the smallest rectangle encompassing the partition cells of the specified range, independent of the cells of its contained nodes

A node contained in a group node can have either no partition cell ID configuration associated with it (none) or a single cell partition cell ID configuration. All nodes with the latter, however, need to use the same partition cell ID configuration.

In conjunction with the group node handling option, partitioned layout calculation does not support group nodes that are associated with group node mode constants other than NORMAL.

To configure a swimlane/partitioned layout with OrganicLayout, use partitionGridData as supplemental layout data.

Layout of Regular Substructures

The organic layout algorithm can identify regular substructures in a graph, like, e.g.,

chains
stars
cycles
parallel structures
trees
groups

and arrange them in an optimized manner depending on the kind of substructure. This makes them easily recognizable in the resulting layout.

For example, the diagram in the following figure has star substructures of different sizes, a chain, a cycle, a parallel substructure, a group substructure and a tree.

Regular substructures in an organic layout

To enable the support for identifying and arranging regular substructures, the following properties are available.

chainSubstructureStyle
cycleSubstructureStyle
parallelSubstructureStyle
starSubstructureStyle
treeSubstructureStyle
groupSubstructureScope: The properties to enable/disable the logic for finding the respective substructures and to configure the layout style for each kind of substructure.

It is recommended to enable property considerNodeSizes when using substructure styles. Otherwise, the layout quality with substructures may suffer.

To define the minimum number of nodes a substructure must contain to be handled as such, a property regarding each style is available (e.g. for chains chainSubstructureSize).

As an option, the logic to identify the regular substructures can take node types into account. A substructure can only contain nodes of the same type. The types can be specified via the layout data property nodeTypes.

Another option that influences the detection of substructures is the edge directedness. This means that within a substructure all edges need to have the same direction. To enable this option, define supplemental layout data that specifies the directedness for edges, for example by setting the OrganicLayoutData.edgeDirectedness property.

An edge can be marked using one of the following directedness values:

0 denotes a regular, i.e., undirected edge
1 denotes an edge that should be oriented from source to target
-1 denotes an edge that should be oriented from target to source

Carefully observe that this support for edge directedness is only provided by the logic that identifies the regular substructures in a graph and is only taken into account in conjunction with substructure layout. By default, all edges are assumed to have a directedness value of 0.

For the layout of stars (style separated radial only) and parallel substructures, edge groups that are specified for the edge ends at the substructure’s root node or its common end nodes will automatically be observed. Edges that belong to the same group at an end will be routed in a bus-style manner with an additional bend inserted into the edge path.

The following figure shows the resulting layout of a parallel substructure with one edge group at each of the end nodes:

Parallel substructure layout in combination with edge grouping

The general setup for edge groups is described in section Layout with Edge Grouping.

You can configure the substructure layout component of OrganicLayout via supplemental layout data such as edge directedness, source group ids and target group ids.

Nesting of Substructures

Some of the available substructures allow to be nested inside other substructures. This can emphasize how they are inter-connected and may be beneficial for certain use-cases. On the other hand, it can make the overall layout less compact because a nested structure often makes the outer structure much larger in size - this is notable especially if all other members of the outer structure are much smaller (i.e. the sizes are not homogeneous).

Nesting is supported by styles with the respective suffix, that is, CIRCULAR_NESTED, RECTANGULAR_NESTED, STRAIGHT_LINE_NESTED, RADIAL_NESTED and CIRCULAR_NESTED.

Substructures are detected in the following order: groups, cycles, stars, chains, parallel structures, trees. Due to this fixed order it is determined which structures may be nested inside which others. For example, parallel structure cannot be nested at all and stars may be nested inside chains and parallel structures but not inside cycles. As special case groups do not support nesting in either direction, i.e., a group substructure cannot be nested in any other substructure and no other substructure can be nested in a group.

Node Halos

OrganicLayout by default supports node halos as soon as they are declared. It considers any specified additional padding around nodes, however, due to the straight-line routing of the edges, they can cross through these areas in the resulting diagram. Also, node halo overlaps may occur if:

option "Node Overlaps Allowed" is enabled
"Scope" is set to SUBSET or MAINLY_SUBSET

You can specify node halos by means of supplemental layout data.

Edge Orientation

OrganicLayout supports the definition of edge orientations with respect to the specified layout orientation. For an edge a positive orientation means that the edge should have the same orientation as the layout orientation, while a negative orientation means that it should have the opposite orientation. For example, if the orientation of the layout is from left to right, a positive orientation of an edge means that it also should go from left to right.

By default, the orientation of the edges is undefined such that the edges do not have a common flow direction.

You can specify the orientation of edges by means of supplemental layout data. A negative value is interpreted as negative orientation, a positive value is interpreted as positive orientation, and 0 is interpreted as undefined orientation.

Edge Lengths

Apart from the preferred edge length, which should be used as the major parameter for controlling the length of edges, OrganicLayout also supports the definition of minimum lengths of edges. It can be utilized for example for enforcing enough space along an edge such that a label can be placed without overlaps.

You can specify the lengths of edges by means of supplemental layout data.

Constraints

OrganicLayout supports different types of constraints that restrict the placement of the graph’s nodes. They can be specified by means of supplemental layout data. The OrganicLayout enforces the specified constraints, when it applies the physical forces on the nodes.

Example 1 - Alignment of nodes. This type of constraint enforces that the specified nodes lie on a common line. The user can specify whether this line should be horizontal or vertical. This constraint particularly can be used to emphasize paths in layouts. The first of the above figures shows a graph layout without any constraints, while the second figure shows the same layout, but this time the blue nodes have been forced to lie on a horizontal line geometrically emphasizing that they lie on a path.
Example 2 - Geometric shapes. This type of constraints enforces that the specified nodes lie on a common axis-aligned rectangle or ellipse. The third figure shows an example in which multiple subsets of nodes are forced to be placed on rectangles and ellipses. Apart from the nodes, the user can also specify the aspect ratio of the geometric shapes, e.g., defining an aspect ratio of 1 leads to a square or rectangle. Similar to constraints aligning nodes, this type of constraint can be used to emphasize cycles in the graph layout.

When specifying constraints, one needs to keep in mind that these constraints easily oppose the physical forces applied on the nodes. It is therefore recommended using the constraints to visually emphasize structures that are also respected by the physical forces. For example, if nodes almost lie on a circle when using the OrganicLayout without constraints, forcing them on a circle oppose the physical forces only little. Hence, the constrained placement of these nodes will blend in with the remaining layout seamlessly.

The constraints have the following technical restrictions.

Graphs with groups. Currently, only constraints for nodes that lie in the same group are supported. In case that two nodes of the affected nodes lie in different groups, the entire constraint is ignored.
Contradicting Constraints. When defining constraints for nodes, it is recommended that the constraints do not contradict each other. Otherwise, the OrganicLayout ignores some of the constraints such that the remaining constraints do not contradict each other. It is not further defined which of the constraints are ignored, but OrganicLayout is free to do this arbitrarily.

Layout Data

When using class OrganicLayout, supplemental layout data for a graph’s elements can be specified either by using class OrganicLayoutData or by registering data providers with the graph using given look-up keys. Supplemental layout data lists all properties of OrganicLayoutData and the corresponding look-up keys that OrganicLayout tests during the layout process in order to query supplemental data.

Providing supplemental layout data is described in detail in Layout Data.

Supplemental layout data

GROUP_DP_KEY: For each node a boolean value indicating whether it is a group node or not.
Data Provider Key: GROUP_DP_KEY
Maps from node to boolean
NODE_ID_DP_KEY: For each node an Object that serves as a unique ID.
Data Provider Key: NODE_ID_DP_KEY
Maps from node to Object
PARENT_NODE_ID_DP_KEY: For each node an Object indicating the group node it belongs to. The Object matches the unique ID of a group node that is in the same graph.
Data Provider Key: PARENT_NODE_ID_DP_KEY
Maps from node to Object
groupNodeModes: For each group node an Object indicating how to proceed with it during the layout process.
Data Provider Key: GROUP_NODE_MODE_DP_KEY
Maps from node to Object
affectedNodes: For each node a boolean value indicating whether it should be treated as selected or not.
Data Provider Key: AFFECTED_NODES_DP_KEY
Maps from node to boolean
preferredEdgeLengths: For each edge a floating point value that indicates its preferred length.
Data Provider Key: PREFERRED_EDGE_LENGTH_DP_KEY
Maps from edge to double
minimumEdgeLengths: For each edge a floating point value that indicates its minimum length.
Data Provider Key: MINIMUM_EDGE_LENGTH_DP_KEY
Maps from edge to number
MINIMUM_NODE_SIZE_DP_KEY: For each group node a YDimension object that specifies the group node’s minimum size constraint.
Data Provider Key: MINIMUM_NODE_SIZE_DP_KEY
Maps from node to YDimension
nodeHalos: A NodeHalo object that specifies the halo sizes at each side of a node.
Data Provider Key: NODE_HALO_DP_KEY
Maps from node to NodeHalo
abortHandler: An AbortHandler instance that will be queried by the layout algorithm to determine whether layout calculation shall be terminated.
Data Provider Key: ABORT_HANDLER_DP_KEY
Maps from graph to AbortHandler
edgeDirectedness: For each edge a floating point value that indicates the directedness of the edge. Note that the directedness is only taken into account in conjunction with substructures.
Data Provider Key: EDGE_DIRECTEDNESS_DP_KEY
Maps from edge to number
edgeOrientations: For each edge a floating point value that indicates the orientation of the edge in the layout.
Data Provider Key: EDGE_ORIENTATION_DP_KEY
Maps from edge to number
zCoordinates: The algorithm writes the center z-coordinate for each non-group node.
Data Provider Key: Z_COORDINATE_DP_KEY
Maps from node to double
nodeInertia: The inertia value (from 0 to 1) of a non-group node which influences how fast a node moves.
Data Provider Key: NODE_INERTIA_DP_KEY
Maps from node to double
nodeStress: The stress value (from 0 to 1) of a non-group node which influences how far a node possibly moves.
Data Provider Key: NODE_STRESS_DP_KEY
Maps from node to double
nodeTypes: For each node an arbitrary Object indicating the node’s type, see Layout with Custom Node Types for more details.
Data Provider Key: NODE_TYPE_DP_KEY
Maps from node to Object
SOURCE_GROUP_ID_DP_KEY: For each edge an arbitrary object indicating the group its source end is affiliated with. Note that edge groups are only observed in conjunction with substructure layout.
Data Provider Key: SOURCE_GROUP_ID_DP_KEY
Maps from edge to object
TARGET_GROUP_ID_DP_KEY: For each edge an arbitrary Object indicating the group its target end is affiliated with. Note that edge groups are only observed in conjunction with substructure layout.
Data Provider Key: TARGET_GROUP_ID_DP_KEY
Maps from edge to object
minimumNodeDistances: For each edge an arbitrary Object indicating the group its target end is affiliated with. Note that edge groups are only observed in conjunction with substructure layout.
Data Provider Key: MINIMUM_DISTANCE_DP_KEY
Maps from edge to object
overlappingNodes: For each node a boolean value indicating whether it can overlap with other nodes. Note that this property is only considered if nodes overlaps are not allowed in general.
Data Provider Key: OVERLAPPING_NODES_DP_KEY
Maps from node to boolean
partitionGridData: Specifies a PartitionGrid for the organic layout.
PartitionGridData.grid: Specifies the partition grid structure for the graph. Can also be defined using the rowIndices and columnIndices properties.
Data Provider Key: PARTITION_GRID_DP_KEY
Maps from graph to PartitionGrid
PartitionGridData.cellIds: Specifies the partition cell id for a node. Alternatively, cell indices for a node can be specified using the rowIndices and columnIndices properties.
Data Provider Key: PARTITION_CELL_ID_DP_KEY
Maps from node to PartitionCellId
constraints: Specifies constraints that restrict the node placement.

Setup of a grouped graph’s hierarchy of nodes (using GROUP_DPKEY, NODE_ID_DPKEY, and PARENT_NODE_ID_DPKEY) is done transparently by the IGraph-related adapter mechanisms. See also Layout of Grouped Graphs and Applying an Automatic Layout.

Interactive Organic Layout

Class InteractiveOrganicLayout provides organic layout for use in interactive environments. Its strength is its capability to generate continuous updates to the layout of a graph during calculation. Furthermore, it also allows a user to seemingly simultaneously perform arbitrary modifications to a graph, which are subsequently accounted for in the layout calculation.

In contrast to the majority of yFiles for HTML layout algorithms, class InteractiveOrganicLayout does not inherit from MultiStageLayout, but is instead provided as an implementation of the ILayoutAlgorithm interface.

Due to the interactive nature of this layout algorithm, the IGraph-related adapter mechanisms to run a layout algorithm are not applicable.

Among other things, this means that there is no special support for routing of either self-loops or parallel edges, for example. In particular, when a graph contains parallel edges, they will be routed using overlapping edge paths.

Basic Options

Interactive organic layout provides a set of options that affect its behavior. These options can be set using the properties of class InteractiveOrganicLayout.

maximumDuration: Sets the maximal duration of the layout process in milliseconds. If this upper bound is hit during the layout process, the quality of the layout may not be optimal. Increasing the value increases the likeliness of an optimal layout.

After the layout process has finished or the time specified using maximumDuration is spent, InteractiveOrganicLayout will sleep, i.e., it has to be awakened before another layout process can be invoked (see also the description of running/sleeping state of InteractiveOrganicLayout).

preferredNodeDistance: The preferred node distance which will be used to calculate the layout. The layout algorithm tries to arrange the nodes in such a way that the desired distance is complied with.

The following methods allow to specify both the general preferred length for all edges as well as individual preferred edge lengths. The layout algorithm tries to arrange the nodes in such a way that the edges have the desired edge length. Note that the edge length is measured from node border to node border.

preferredEdgeLength: number
setPreferredEdgeLength(edge: Edge, newEdgeLength: number): void: Property and setter method for both general preferred edge lengths as well as individual preferred edge lengths.

Alternatively, to specify the preferred edge length for each edge individually, a data provider holding such supplemental layout data can be bound to the graph. The data provider is expected to be registered with the graph using key PREFERRED_EDGE_LENGTH_DP_KEY. Note that in the absence of an individual preferred edge length the general preferred edge length will be used.

Although the data provider look-up key defined in class ClassicOrganicLayout is used to specify individual preferred edge lengths, the actual type of data provided are double values.

qualityTimeRatio: This setting can be used to adjust the quality of the layout calculated by the layout algorithm. Small values lead to short running times, while greater values result in better quality. For large graph structures (hundreds and thousands of nodes) it is advisable to begin with smaller values and to gradually increase them.

Class InteractiveOrganicLayout allows to impose so-called "output restrictions" on the result of the layout calculcation. More precisely, the layout result can be determined to fit into a specified region, e.g., a rectangle or a circle. Also, the layout result can be restricted to a specified aspect ratio, too.

outputRestriction: Class OutputRestriction serves as a factory to create predefined output restrictions that can be used in conjunction with this property.

General Usage

In the single-threaded JavaScript execution environment, InteractiveOrganicLayout is designed to be used in a cooperative setup where the layout algorithm does its calculations in defined time slices after which it yields back control to the application. This enables an application that presents a graphical user interface (GUI) to the user to remain nearly fully interactive while the layout algorithm, at least perceived simultaneously, performs its calculations. This setup also enables modifications to the graph seemingly simultaneous to the layout calculation.

Setup

If the graph that is to be processed by InteractiveOrganicLayout is intended to allow structural modifications by a user, then it is strongly recommended to use an instance of CopiedLayoutGraph instead of a simple LayoutGraph. Doing so helps avoiding race conditions and synchronization problems that occur when nodes and/or edges can be added to or removed from the graph while the layout algorithm performs its calculations.

Creation of a layout using a copy of the original graph is shown in Using the copied layout graph.

Using the copied layout graph

// Create a copy of the given graph. Using an instance of CopiedLayoutGraph
// helps avoiding race conditions with graph *structure* modifications from a user.
// Note that the graph is of type IGraph
const adapter = new LayoutGraphAdapter(graph, null)
const layoutGraph = adapter.createCopiedLayoutGraph()
const organicLayout = new InteractiveOrganicLayout()
const layoutContext = organicLayout.startLayout(layoutGraph)

Life Cycle

Interactive organic layout algorithm can be in either of three states: running, sleeping, or stopped. When running, the algorithm lives on the allowed maximal runtime and continuously calculates "intermediate" layouts for the given graph. When sleeping, the algorithm does nothing, but is still "alive." In contrast, when stopped, the algorithm is terminated. State diagram for InteractiveOrganicLayout depicts the states and the possible state transitions of InteractiveOrganicLayout.

State diagram for InteractiveOrganicLayout

The following properties can be used to query the current state of an InteractiveOrganicLayout instance, change its state, and set the maximal runtime. Note that when an instance is changed from "sleeping" to "running" state, the maximal runtime is again fully available.

running
sleeping
stopped: Properties to query the algorithm’s current state.
wakeUp(): void
stop(): void
stopAndWait(): void: Methods to change the current state.
maximumDuration: Determines the maximal runtime when in "running" state.

Polling for Results

The concurrent setup as used with InteractiveOrganicLayout means that the layout process does not return a single result by itself, but instead continuously generates "intermediate" results as long as it is in "running" state. These results are in the layout algorithm’s data structures only, but can be polled by a user at any time and be used as continuous updates to the layout of a graph.

The following methods allow to easily poll either the current coordinates of single nodes or commit all current positions of nodes to the original graph at once:

getCenterX(node: Node): number
getCenterY(node: Node): number
getCenter(node: Node): YPoint: Retrieve the current center coordinate(s) of a single node from InteractiveOrganicLayout’s data structures.
commitPositions(): void
commitPositionsSmoothly(maxMovement: number, factor: number): number: Updates all node locations with the coordinates from InteractiveOrganicLayout’s data structures.

Typically, to assign the "intermediate" results in a continuous fashion to the original graph, a technique similar to that outlined in Callback setup to repeatedly calculate and assign node positions can be used. The current positions of all nodes are repeatedly polled by means of a Animator.

In tutorial demo application Interactive Organic Layout the "intermediate" results are repeatedly calculated and assigned to the original graph in a continuous fashion by means of a callback function in an animation:

Callback setup to repeatedly calculate and assign node positions

// Create and start an infinite animation. Each animation step will
// continue the layout calculation and poll the given organic layout
// to update the node positions in the original graph.
const animator = new Animator(graphComponent)
animator.autoInvalidation = false
animator.allowUserInteraction = true

animator.animate(() => {
  layoutContext.continueLayout(100)
  if (organicLayout.commitPositionsSmoothly(50, 0.05) > 0) {
    graphComponent.updateVisual()
  }
}, TimeSpan.fromSeconds(Number.POSITIVE_INFINITY))

Interaction

The interactive organic layout algorithm allows a user to seemingly simultaneously modify node positions and also node-related parameters while layout calculation takes place. The following methods can be used to update InteractiveOrganicLayout’s data structures with new node positions, and also to specify further node-related parameters that determine, e.g., the size of a node or its inertia:

setCenterX(node: Node, x: number): void
setCenterY(node: Node, y: number): void
setCenter(node: Node, x: number, y: number): void: Set the current center coordinate(s) of a single node in InteractiveOrganicLayout’s data structures.
setInertia(node: Node, inertia: number): void
setRadius(node: Node, radius: number): void: Further node-related parameters used by InteractiveOrganicLayout.

In addition, InteractiveOrganicLayout optionally also supports modifications to the original graph’s structure, i.e., nodes and/or edges can be added to or removed from the graph and the layout calculation subsequently properly accounts for these changes.

To avoid race conditions and synchronization problems when structural changes to the graph are allowed, it is strongly recommended to provide InteractiveOrganicLayout a copy of the original graph using an instance of CopiedLayoutGraph. See also Setup.

To properly support arbitrary structural modifications to the original graph, interactive organic layout relies on proper notification of structural changes to the graph. To this end, the structure of the original graph can be synchronized using code similar to that shown in Performing explicit structure updates.

Performing explicit structure updates

const organicLayout = this.getMyInteractiveOrganicLayout()

// Here: perform the actual graph structure modifications on the original graph.
// For example, remove some nodes and edges...
this.modifyOriginalGraphStructureHere()

// After the changes have been done:
// synchronize the structure of the original graph with that of the copy given
// to InteractiveOrganicLayout.
organicLayout.syncStructure()

Layout Data

Class InteractiveOrganicLayout retrieves supplemental layout data for the preferred length of edges. The data is bound to the graph by means of a data provider, which is registered using a given look-up key.

Binding supplemental layout data to a graph is described in Layout Data.

Data provider look-up keys
Data Provider Key	Element Type	Value Type	Description
PREFERRED_EDGE_LENGTH_DP_KEY	Edge	double	For each edge a double value that indicates its preferred length.

Tutorial Demo Code

Tutorial demo application Interactive Organic Layout shows how to use the layout functionality of class InteractiveOrganicLayout in an interactive environment where the user can "live"-drag nodes and freely modify the graph structure.

Hierarchical Layout Tree Layouts