This algorithm arranges graphs in an organic fashion and offers special functionality to interact with the graph while the algorithm is running.
Remarks
Besides the organic graph arrangement, this algorithm enables to immediately visualize changes made to a graph. Changes can be committed and the layout will be locally updated. That way, live interactions with an adapting graph layout are possible. Another advantage is that it is not necessary to compute a completely new layout if only small changes were made.
Layout Style
This algorithm supports the organic layout style which is characterized by a natural distribution of nodes. It is well suited to exhibit clusters and symmetric properties of a graph. Nodes are placed in a space-saving manner and distances between neighbors are highly uniform. Edges maintain uniform lengths too and are routed with straight-line segments without bends.
Organic diagrams are well suited for visualizing relations in large networks, for example, in bioinformatics, enterprise networking, social networks visualization, mesh visualization or system management.
Concept
The internal basis for computing actual layouts is a force-directed approach placing the nodes of the input graph. The graph is modeled as a physical system with appropriate forces acting on it. Nodes are considered as electrically charged particles with mutually repulsive forces. Edges are modeled as forces that attract adjacent nodes. A good diagram is obtained from an equilibrium state of the system, i.e., the nodes are rearranged based on the physical forces until the system reaches a (local) minimum of the sum of the forces.
Features
Several update methods allow to indicate lightweight changes on the graph, for example, setCenter for node location updates. These updates will be scheduled and executed at a specific point within the life-cycle of the layout algorithm. They are ideally suited for usage in interactive scenarios, where users, for example, change node positions via mouse-dragging.
Method addStructureUpdate allows to schedule a custom event handler instance that is executed in a synchronized context and can safely update the structure of the graph.
Usage Hints
It is easiest to start the algorithm using startLayout. Furthermore, it is strongly recommended to start it by passing a copy of the original graph (i.e. a CopiedLayoutGraph instance) as parameter to the mentioned method.
Importantly, changes will not be automatically applied to the input graph. Updates can be scheduled via various methods (e.g. setCenter). The whole layout will then internally be adjusted accordingly and changes are stored as intermediate results. Such intermediate results can be committed in order to apply them to the actual graph.
Default Values of Properties
| compactnessFactor | 0.4 | |
| outputRestriction | NONE | No area restriction is imposed. |
| preferredEdgeLength | 50 | |
| preferredNodeDistance | 50 | |
| qualityTimeRatio | 1 |
Type Details
- yfiles module
- layout-organic
- yfiles-umd modules
- layout-multipage, layout-organic, layout
- Legacy UMD name
- yfiles.organic.InteractiveOrganicLayout
See Also
Constructors
Creates a new instance of the InteractiveOrganicLayout with default settings.
Parameters
A map of options to pass to the method.
- compactnessFactor - number
The compactness factor for the layout algorithm. This option sets the compactnessFactor property on the created object.
- preferredEdgeLength - number
The default preferred edge length. This option sets the preferredEdgeLength property on the created object.
- preferredNodeDistance - number
The preferred distance between nodes. This option sets the preferredNodeDistance property on the created object.
- maximumDuration - number
The maximum duration in milliseconds that this algorithm is allowed to run. This option sets the maximumDuration property on the created object.
- qualityTimeRatio - number
The ratio of layout quality versus running time. This option sets the qualityTimeRatio property on the created object.
- outputRestriction - OutputRestriction
An OutputRestriction which restricts the area for the layout result of this algorithm. This option sets the outputRestriction property on the created object.
Properties
Gets or sets the compactness factor for the layout algorithm.
Remarks
Smaller values result in less compact drawings, greater values result in more compact drawings.
The compactness value needs to lie in [0,1].
Default Value
0.4.Throws
- Exception({ name: 'ArgumentError' })
- if the specified value is outside the interval
[0,1]
Sample Graphs
0.4 may lead to components drifting away from each other.Gets the time when the last wake-up, that is, call to wakeUp, occurred.
Remarks
Gets or sets the maximum duration in milliseconds that this algorithm is allowed to run.
Remarks
Default Value
<code>0x7FFFFFFF</code>.No time restriction is imposed.
Throws
- Exception({ name: 'ArgumentError' })
- if the specified maximum duration has a negative value
See Also
0 will be interpreted as 0x7FFFFFFF which roughly means that no time limit is specified and the algorithm may run as long as necessary.Gets or sets an OutputRestriction which restricts the area for the layout result of this algorithm.
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if the given restriction is
null
See Also
Sample Graphs
Gets or sets the default preferred edge length.
Remarks
This length does not define the actual absolute length of edges, but the layout algorithm considers the specified preference where possible.
The preferred edge length needs to be non-negative.
Default Value
50.Throws
- Exception({ name: 'ArgumentError' })
- if the specified edge length is negative
See Also
Sample Graphs
Gets or sets the preferred distance between nodes.
Remarks
Default Value
50.Throws
- Exception({ name: 'ArgumentError' })
- if the specified minimum node distance is negative
See Also
Sample Graphs
Gets or sets the ratio of layout quality versus running time.
Remarks
The larger the ratio, the better the quality of the resulting layout but the longer it may take to perform the layout calculation.
The value needs to lie within [0,1].
Default Value
1.Throws
- Exception({ name: 'ArgumentError' })
- if the specified ratio is outside the interval
[0,1]
See Also
Gets whether or not this layout algorithm is currently sleeping.
Remarks
See Also
Methods
Schedules an update for the structure of the graph, which will automatically be executed at a later point in the life-cycle of this algorithm.
Remarks
Parameters
A map of options to pass to the method.
- handler - function(Object, EventArgs):void
- The handler delegate that will be invoked using
nullas the sender andevtas the event arguments - evt - EventArgs
- The event argument that will be piped to the
handlerinvocation.
Calculates an organic layout for the given input graph, however, the layout is not automatically applied to the graph.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Implements
Writes calculated intermediate locations of nodes and edges to the actual graph.
Remarks
See Also
Writes calculated intermediate locations of nodes and edges to the actual graph and returns the largest movement value.
Remarks
Update methods like setCenter schedule changes which cause that the whole layout will internally be adjusted. All adjustments are stored as intermediate results. This method smoothly transfers all these intermediate results to the actual input graph.
Positions are, however, not transferred directly (use commitPositions if that is intended). Instead, the nodes are moved towards the calculated position. The movement is restricted to the given maximum distance.
The movement will be calculated as (movement) = (factor) * (distance between calculated and actual location)
The returned largest movement can be used for estimating the difference between calculated layout and actual positions. If the return value is 0, the calculated layout was completely transferred.
Parameters
A map of options to pass to the method.
- maxMovement - number
- the maximum distance a node will be moved
- factor - number
- a factor that determines the node movement
Returns
- ↪number
- the largest movement value or
0, if the calculated layout has been transferred completely
See Also
25 times a second, suitable parameter values are 50 for the maximum movement and 0.15 for the factor.Disables all predefined ILayoutStages so that upon applyLayout only the internal organic layout algorithm will be executed.
Remarks
See Also
Polls the current coordinates of the center of the given node.
Remarks
Parameters
A map of options to pass to the method.
- node - YNode
- the node for which the center should be polled
Returns
- ↪YPoint
- the YPoint representing the center location of the given node, or
nullif nothing about the node is known
See Also
Polls the current x-coordinate of the center location of the given node.
Remarks
Parameters
A map of options to pass to the method.
- node - YNode
- the node for which the x-coordinate should be polled
Returns
- ↪number
- the x-coordinate of the center location of the given node
See Also
Polls the current y-coordinate of the center location of the given node.
Remarks
Parameters
A map of options to pass to the method.
- node - YNode
- the node for which the y-coordinate should be polled
Returns
- ↪number
- the y-coordinate of the center location of the given node
See Also
Polls the current stress value of a given node.
Remarks
The stress value indicates how far a node will possibly move. The higher the stress of a node is, the farther it may move.
The stress value is defined to be a value from the interval [0,1].
Parameters
A map of options to pass to the method.
- node - YNode
- the node for which the stress value should be polled
Returns
- ↪number
- the stress value of the given node
See Also
Schedules an update for the center location of the given node.
Remarks
Parameters
A map of options to pass to the method.
- node - YNode
- the node that should be updated
- x - number
- the desired x-coordinate of the given node
- y - number
- the desired y-coordinate of the given node
See Also
Schedules an update for the center location's x-coordinate of the given node.
Remarks
Parameters
A map of options to pass to the method.
- node - YNode
- the node that should be updated
- x - number
- the desired x-coordinate of the given node
See Also
Schedules an update for the center location's y-coordinate of the given node.
Remarks
Parameters
A map of options to pass to the method.
- node - YNode
- the node that should be updated
- y - number
- the desired y-coordinate of the given node
See Also
Schedules an update for the inertia of the given node.
Remarks
The inertia is defined to be a value from the interval [0,1].
1.0: The node will not move.0.5: The node will only move half as far as it would with an inertia of0.0.0.0: The node will move as fast as possible.
This method can be used while layout calculation is in progress (e.g. for interactive layout scenarios). However, the change will not directly be applied to the graph itself but only stored internally as an intermediate result. Scheduled updates can be committed to the graph while the algorithm is running using methods commitPositions or commitPositionsSmoothly.
Parameters
A map of options to pass to the method.
- node - YNode
- the node whose inertia to set
- inertia - number
- an inertia value between
0and1
Throws
- Exception({ name: 'ArgumentError' })
- if the given inertia value is negative or greater than
1
See Also
Schedules an update for the preferred length of the given edge.
Remarks
Parameters
A map of options to pass to the method.
- edge - Edge
- the edge whose preferred length should be updated
- newEdgeLength - number
- the new preferred edge length
See Also
Schedules an update for the radius of the given node.
Remarks
Parameters
A map of options to pass to the method.
- node - YNode
- the node whose radius should be updated
- radius - number
- the desired radius for the given node
See Also
Schedules an update for the stress value of the given node.
Remarks
The stress value indicates how far a node will possibly move. The higher the stress of a node is, the farther it may move.
This method can be used while layout calculation is in progress (e.g. for interactive layout scenarios). However, the change will not directly be applied to the graph itself but only stored internally as an intermediate result. Scheduled updates can be committed to the graph while the algorithm is running using methods commitPositions or commitPositionsSmoothly.
The stress value is defined to be a value from the interval [0,1].
Parameters
A map of options to pass to the method.
- node - YNode
- the node whose stress value should be updated
- stress - number
- a stress value from the interval
[0,1]
Throws
- Exception({ name: 'ArgumentError' })
- if the given stress value is negative or greater than
1
Creates a context object that provides methods to continue and stop the layout calculation for running this layout algorithm in a single-threaded environment.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
Returns
- ↪InteractiveOrganicLayoutExecutionContext
- a context instance to control layout calculation
See Also
Stops the layout algorithm.
Remarks
See Also
Stops a previously started algorithm and then blocks until the current layout calculation is completed.
Synchronizes the structure of the graph copy with the original graph.
Throws
- Exception({ name: 'InvalidOperationError' })
- if the currently handled graph is not of type CopiedLayoutGraph
Wakes up the algorithm with the effect that it will restart/continue the layout calculation.