y.layout.organic
Class InteractiveOrganicLayouter

java.lang.Object
  y.layout.organic.InteractiveOrganicLayouter

All Implemented Interfaces:

Layouter

public class InteractiveOrganicLayouter
extends java.lang.Object
implements Layouter

This algorithm arranges graphs in an organic fashion and offers special functionality to interact with the graph while the algorithm is running.

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.

Organic layout obtained using this algorithm

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.

InteractiveOrganicLayouter is designed to run in a thread on its own. This allows for creating interactive user interfaces where the layout algorithm runs while users interact with the graph. The algorithm can then react to changes by immediately adapting the layout.
However, the algorithm can also be executed in a single-threaded mode using startLayoutSingleThreaded(LayoutGraph). A Context instance provides the necessary methods to control the layout calculation.

Features

Several update methods allow to indicate lightweight changes on the graph, for example, setCenter(Node, double, double) 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.

If a CopiedLayoutGraph is being laid out, structural changes (e.g. creation or removal of nodes and edges) in the original graph can be automatically scheduled and applied to the CopiedLayoutGraph instance. Enable automatic structure updates for this feature.
Method addStructureUpdate(Runnable) allows to schedule a custom Runnable 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 in its own thread using startLayout(LayoutGraph). 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(Node, double, double)). 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.

For the mere use case of generating an organic layout of a graph without the need for special interaction, it is recommended to use SmartOrganicLayouter instead of this class.

Nested Class Summary

static interface

InteractiveOrganicLayouter.SingleThreadContext A InteractiveOrganicLayouter.SingleThreadContext provides control over the layout calculation in the case of single-threaded algorithm execution.

Field Summary

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

InteractiveOrganicLayouter()
Creates a new instance of the InteractiveOrganicLayouter with default settings.

Method Summary

void	addStructureUpdate(java.lang.Runnable runnable) 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.
boolean	canLayout(LayoutGraph graph) Accepts all general non-empty graphs.
void	commitPositions() Writes calculated intermediate locations of nodes and edges to the actual graph.
double	commitPositionsSmoothly(double maxMovement, double factor) Writes calculated intermediate locations of nodes and edges to the actual graph and returns the largest movement value.
void	doLayout(LayoutGraph graph) Calculates an organic layout for the given input graph, however, the layout is not automatically applied to the graph.
void	enableOnlyCore() Disables all predefined LayoutStages so that upon doLayout(y.layout.LayoutGraph) only the internal organic layout algorithm will be executed.
YPoint	getCenter(Node node) Polls the current coordinates of the center of the given node.
double	getCenterX(Node node) Polls the current x-coordinate of the center location of the given node.
double	getCenterY(Node node) Polls the current y-coordinate of the center location of the given node.
double	getCompactness() Returns the compactness factor for the layout algorithm.
long	getLastWakeupTime() Returns the time when the last wake-up, that is, call to wakeUp(), occurred.
long	getMaxTime() Specifies the maximum duration in milliseconds that this algorithm is allowed to run.
OutputRestriction	getOutputRestriction() Returns an OutputRestriction which restricts the area for the layout result of this algorithm.
double	getPreferredEdgeLength() Returns the default preferred edge length.
double	getPreferredNodeDistance() Returns the preferred distance between nodes.
double	getQuality() Returns the ratio of layout quality versus running time.
double	getStress(Node node) Polls the current stress value of a given node.
double	getWorkingRatio() Returns the working ratio which defines the amount of processor time this algorithm tries to get.
boolean	isAutomaticStructureUpdateEnabled() Returns whether or not this algorithm performs automatic structure updates on the graph copy if the original graph changes.
boolean	isRunning() Determines whether or not this layout algorithm is currently running.
boolean	isSleeping() Determines whether or not this layout algorithm is currently sleeping.
boolean	isStopped() Determines whether or not this layout algorithm has stopped.
void	setAutomaticStructureUpdateEnabled(boolean automaticStructureUpdateEnabled) Specifies whether or not this algorithm performs automatic structure updates on the graph copy if the original graph changes.
void	setCenter(Node node, double x, double y) Schedules an update for the center location of the given node.
void	setCenterX(Node node, double x) Schedules an update for the center location's x-coordinate of the given node.
void	setCenterY(Node node, double y) Schedules an update for the center location's y-coordinate of the given node.
void	setCompactness(double compactness) Specifies the compactness factor for the layout algorithm.
void	setInertia(Node node, double inertia) Schedules an update for the inertia of the given node.
void	setMaxTime(long maxTime) Specifies the maximum duration in milliseconds that this algorithm is allowed to run.
void	setOutputRestriction(OutputRestriction restriction) Specifies an OutputRestriction which restricts the area for the layout result of this algorithm.
void	setPreferredEdgeLength(double preferredEdgeLength) Specifies the default preferred edge length.
void	setPreferredEdgeLength(Edge edge, double newEdgeLength) Schedules an update for the preferred length of the given edge.
void	setPreferredNodeDistance(double preferredNodeDistance) Specifies the preferred distance between nodes.
void	setQuality(double quality) Specifies the ratio of layout quality versus running time.
void	setRadius(Node node, double radius) Schedules an update for the radius of the given node.
void	setStress(Node node, double stress) Schedules an update for the stress value of the given node.
void	setWorkingRatio(double workingRatio) Specifies the working ratio which defines the amount of processor time this algorithm tries to get.
java.lang.Thread	startLayout(LayoutGraph graph) Starts the layout process calculating an organic layout for the input graph in a new, separate Thread.
InteractiveOrganicLayouter.SingleThreadContext	startLayoutSingleThreaded(LayoutGraph graph) Creates a context object that provides methods to continue and stop the layout calculation for running this layout algorithm in a single-threaded environment.
void	stop() Stops the layout algorithm.
void	stopAndWait() Stops a previously started algorithm and then blocks until the current layout calculation is completed.
void	syncStructure() Synchronizes the structure of the graph copy with the original graph.
void	wakeUp() Wakes up the algorithm with the effect that it will restart/continue the layout calculation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InteractiveOrganicLayouter

public InteractiveOrganicLayouter()

Creates a new instance of the InteractiveOrganicLayouter with default settings.

Method Detail

enableOnlyCore

public void enableOnlyCore()

Disables all predefined LayoutStages so that upon doLayout(y.layout.LayoutGraph) only the internal organic layout algorithm will be executed.

This method is called upon construction of this class so that by default additional LayoutStages are deactivated. This method may be overridden if the additional stages should stay active (e.g. override the method and return silently).

This algorithm internally uses a CanonicMultiStageLayouter to compute the organic layout and this method delegates to CanonicMultiStageLayouter.enableOnlyCore().

See Also:

CanonicMultiStageLayouter.enableOnlyCore()

isAutomaticStructureUpdateEnabled

public boolean isAutomaticStructureUpdateEnabled()

Returns whether or not this algorithm performs automatic structure updates on the graph copy if the original graph changes.

If this feature is enabled, a listener will be registered with the original input graph. This listener will automatically transfer structural changes on the original graph to the graph copy and update its internal data structures.

This feature will take effect only when running this algorithm on a copy of the original graph.

Returns:

true if automatic structure updates on the graph copy are enabled, false otherwise

See Also:

setAutomaticStructureUpdateEnabled(boolean)

setAutomaticStructureUpdateEnabled

public void setAutomaticStructureUpdateEnabled(boolean automaticStructureUpdateEnabled)

Specifies whether or not this algorithm performs automatic structure updates on the graph copy if the original graph changes.

If this feature is enabled, a listener will be registered with the original input graph. This listener will automatically transfer structural changes on the original graph to the graph copy and update its internal data structures.

This feature will take effect only when running this algorithm on a copy of the original graph.

Default Value:

The default value is false. Structure updates need to be scheduled manually.

Parameters:

automaticStructureUpdateEnabled - true if automatic structure updates on the graph copy should be enabled, false otherwise

getCompactness

public double getCompactness()

Returns the compactness factor for the layout algorithm.

Smaller values result in less compact drawings, greater values result in more compact drawings.

The compactness value needs to lie in [0,1].

If the graph consists of multiple components, using values less than 0.4 may lead to components drifting away from each other.

Returns:

the compactness value in [0,1]

See Also:

setCompactness(double)

setCompactness

public void setCompactness(double compactness)

Specifies the compactness factor for the layout algorithm.

Smaller values result in less compact drawings, greater values result in more compact drawings.

The compactness value needs to lie in [0,1].

If the graph consists of multiple components, using values less than 0.4 may lead to components drifting away from each other.

Default Value:

The default value is 0.4.

Parameters:

compactness - the compactness value in [0,1]

Throws:

java.lang.IllegalArgumentException - if the specified value is outside the interval [0,1]

Sample Graphs:

Compactness is set to 0

Compactness is set to 1

canLayout

public boolean canLayout(LayoutGraph graph)

Accepts all general non-empty graphs.

Specified by:

canLayout in interface Layouter

Parameters:

graph - the input graph

Returns:

true if the given graph contains at least one node, false otherwise

See Also:

Layouter.doLayout(LayoutGraph)

doLayout

public void doLayout(LayoutGraph graph)

Calculates an organic layout for the given input graph, however, the layout is not automatically applied to the graph.

Changes have to be committed to update the graph with the actual calculated positions.

The following example shows how to use the InteractiveOrganicLayouter on a CopiedLayoutGraph:

 InteractiveOrganicLayouter layouter = new InteractiveOrganicLayouter();
 Graph2D originalGraph = new Graph2D();

 CopiedLayoutGraph copy = new CopiedLayoutGraph( originalGraph );
 layouter.setAutomaticStructureUpdateEnabled( true );
 layouter.doLayout( copy );
 

Specified by:

doLayout in interface Layouter

If an instance of CopiedLayoutGraph is given as input, the setters and getters with a Node or Edge as parameter may be used with instances from both, the original graph or the copied graph.

It is strongly recommended to use a CopiedLayoutGraph to buffer the original graph. Then, automatic structure updates can be enabled to enforce that changes to the original graph are automatically applied to the copied graph.

Parameters:

graph - the input graph

See Also:

startLayout(LayoutGraph), startLayoutSingleThreaded(LayoutGraph)

startLayout

public java.lang.Thread startLayout(LayoutGraph graph)

Starts the layout process calculating an organic layout for the input graph in a new, separate Thread.

The created thread will be marked as a daemon thread.

Parameters:

graph - the input graph

Returns:

the Thread instance that has been created and started and in which the layout algorithm is running

See Also:

doLayout(LayoutGraph), startLayoutSingleThreaded(LayoutGraph)

startLayoutSingleThreaded

public InteractiveOrganicLayouter.SingleThreadContext startLayoutSingleThreaded(LayoutGraph graph)

Creates a context object that provides methods to continue and stop the layout calculation for running this layout algorithm in a single-threaded environment.

Usage: Call doLayout(long) on the created instance to run the actual layout calculation for some specified period of time, whenever the layout should be recalculated. To actually transfer the changes, commitPositions() should be called subsequently.

Invoking this method will not compute any actual layout. A call to InteractiveOrganicLayouter.SingleThreadContext.doLayout(long) needs to be made to do so.

Parameters:

graph - the input graph

Returns:

a context instance to control layout calculation

See Also:

InteractiveOrganicLayouter.SingleThreadContext, doLayout(LayoutGraph), startLayout(LayoutGraph)

commitPositions

public void commitPositions()

Writes calculated intermediate locations of nodes and edges to the actual graph.

Update methods like setCenter(Node, double, double) schedule changes which cause that the whole layout will internally be adjusted. All adjustments are stored as intermediate results. This method immediately transfers all these intermediate results to the actual input graph.

To realize a user-interaction scenario with this layout algorithm, it is recommended to regularly call this method to make sure that changes are applied to the graph and made visible. A timer running in a separate thread than the algorithm itself can commit calculated positions in constant intervals.

This method only has an effect while the layout algorithm is running.

See Also:

commitPositionsSmoothly(double, double)

commitPositionsSmoothly

public double commitPositionsSmoothly(double maxMovement,
                                      double factor)

Writes calculated intermediate locations of nodes and edges to the actual graph and returns the largest movement value.

Update methods like setCenter(Node, double, double) 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.

To realize a user-interaction scenario with this layout algorithm, this method can be regularly called to make sure changes are applied to the graph and become visible for the user. A timer running in a separate thread than the algorithm itself can commit calculated positions in constant intervals.

Assuming that this method is called about 25 times a second, suitable parameter values are 50 for the maximum movement and 0.15 for the factor.

This method only has an effect while the layout algorithms is running.

Parameters:

maxMovement - the maximum distance a node will be moved

factor - a factor that determines the node movement

Returns:

the largest movement value or 0, if the calculated layout has been transferred completely

See Also:

commitPositions()

wakeUp

public void wakeUp()

Wakes up the algorithm with the effect that it will restart/continue the layout calculation.

This method is useful if the layouter is sleeping but should be notified of changes (e.g. due to user interaction).

It may be convenient to call this method after scheduling changes via the update methods such as setCenter(Node, double, double) or setStress(Node, double).

If the algorithm already terminated (i.e. stopped), it can not be awakened again.

See Also:

isSleeping()

getLastWakeupTime

public long getLastWakeupTime()

Returns the time when the last wake-up, that is, call to wakeUp(), occurred.

The time is defined in terms of the difference between the current time and midnight, January 1, 1970 UTC, measured in milliseconds.

Returns:

the time in milliseconds when the last call to wakeUp() occurred

addStructureUpdate

public void addStructureUpdate(java.lang.Runnable runnable)

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.

The given Runnable will be queued and executed at a specific time. The Runnable can make structural changes (e.g. removal/creation of edges or nodes). They will be synchronized with the rest of the layout algorithm.

This method should only be used for changes to the structure of the graph, because structural changes require the internal data structures to be rebuilt. Therefore, lightweight changes like modifications of the locations of the nodes should be made using the corresponding update methods, e.g., setCenter(Node, double, double).

Structural updates via this method only work if multi-threading is used.

Parameters:

runnable - a Runnable making structural changes on the graph

stop

public void stop()

Stops the layout algorithm.

In contrast to stopAndWait(), the algorithm terminates immediately and will not wait until the ongoing layout calculation is finished.

After calling this method, the algorithm cannot be awakened again via wakeUp().

See Also:

isStopped(), stopAndWait()

isStopped

public boolean isStopped()

Determines whether or not this layout algorithm has stopped.

If the algorithm has stopped, it terminated all its layout calculations. It is not running anymore and can not be restarted/continued by calling wakeUp().

Returns:

true if the layout algorithm has stopped, false otherwise

isSleeping

public boolean isSleeping()

Determines whether or not this layout algorithm is currently sleeping.

Sleeping indicates that the algorithm has not stopped yet but is waiting (i.e. doing nothing). It can be notified to continue its work using wakeUp().

The algorithm may start sleeping if the layout has reached a stable state or if the maximum runtime was exceeded.

Returns:

true if this algorithm is currently sleeping, false otherwise

See Also:

wakeUp()

isRunning

public boolean isRunning()

Determines whether or not this layout algorithm is currently running.

The algorithm is running if the layout process is still active, the algorithm has not stopped yet and is not sleeping.

Returns:

true if this algorithm is currently running, false otherwise

getWorkingRatio

public double getWorkingRatio()

Returns the working ratio which defines the amount of processor time this algorithm tries to get.

A working ratio value of 1 means that the algorithm will try to run as fast as possible. Lower values will lead to small breaks after each internal round.

The ratio needs to be a value in (0,1].

The working ratio is only considered if this algorithm is running in a separate thread.

Returns:

the working ratio value

See Also:

setWorkingRatio(double)

setWorkingRatio

public void setWorkingRatio(double workingRatio)

Specifies the working ratio which defines the amount of processor time this algorithm tries to get.

A working ratio value of 1 means that the algorithm will try to run as fast as possible. Lower values will lead to small breaks after each internal round.

The ratio needs to be a value in (0,1].

The working ratio is only considered if this algorithm is running in a separate thread.

Default Value:

The default value is 0.9.

Parameters:

workingRatio - the working ratio value

Throws:

java.lang.IllegalArgumentException - if the given ratio is not in (0,1].

setPreferredEdgeLength

public void setPreferredEdgeLength(double preferredEdgeLength)

Specifies the default preferred edge length.

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.

Changes to this property are not considered while the layout process is still active. The preferred edge length specified here will only be considered when first starting the layout algorithm. Use setPreferredEdgeLength(Edge, double) instead to schedule updates.

Default Value:

The default value is 50.

Parameters:

preferredEdgeLength - the preferred edge length

Throws:

java.lang.IllegalArgumentException - if the specified edge length is negative

See Also:

setPreferredEdgeLength(Edge, double)

Sample Graphs:

Preferred edge length 40

Preferred edge length 100

getPreferredEdgeLength

public double getPreferredEdgeLength()

Returns the default preferred edge length.

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.

Changes to this property are not considered while the layout process is still active. The preferred edge length specified here will only be considered when first starting the layout algorithm. Use setPreferredEdgeLength(Edge, double) instead to schedule updates.

Returns:

the preferred edge length

See Also:

setPreferredEdgeLength(double)

setPreferredNodeDistance

public void setPreferredNodeDistance(double preferredNodeDistance)

Specifies the preferred distance between nodes.

The minimum node distance needs to be non-negative.

It is not encouraged to change the node distance while the algorithm is running. Unlike other update methods, no update scheduling is implemented for this setting, so that synchronization problems may occur.

Default Value:

The default value is 50.

Parameters:

preferredNodeDistance - the non-negative preferred distance between nodes

Throws:

java.lang.IllegalArgumentException - if the specified minimum node distance is negative

Sample Graphs:

Preferred node distance 40

Preferred node distance 100

getPreferredNodeDistance

public double getPreferredNodeDistance()

Returns the preferred distance between nodes.

The minimum node distance needs to be non-negative.

It is not encouraged to change the node distance while the algorithm is running. Unlike other update methods, no update scheduling is implemented for this setting, so that synchronization problems may occur.

Returns:

the non-negative preferred distance between nodes

See Also:

setPreferredNodeDistance(double)

setPreferredEdgeLength

public void setPreferredEdgeLength(Edge edge,
                                   double newEdgeLength)

Schedules an update for the preferred length of the given edge.

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(double, double).

To make sure that the layout algorithm is active, it can be woken up after scheduling this update.

Parameters:

edge - the edge whose preferred length should be updated

newEdgeLength - the new preferred edge length

setInertia

public void setInertia(Node node,
                       double inertia)

Schedules an update for the inertia of the given node.

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 of 0.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(double, double).

To make sure that the layout algorithm is active, it can be woken up after scheduling this update.

Parameters:

node - the node whose inertia to set

inertia - an inertia value between 0 and 1

Throws:

java.lang.IllegalArgumentException - if the given inertia value is negative or greater than 1

setCenter

public void setCenter(Node node,
                      double x,
                      double y)

Schedules an update for the center location of the given node.

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(double, double).

This method may be used for updating node positions due to user interaction (e.g. dragging). To make sure that the layout algorithm is active, it can be woken up after scheduling this update.

Parameters:

node - the node that should be updated

x - the desired x-coordinate of the given node

y - the desired y-coordinate of the given node

setRadius

public void setRadius(Node node,
                      double radius)

Schedules an update for the radius of the given node.

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(double, double).

To make sure that the layout algorithm is active, it can be woken up after scheduling this update.

Parameters:

node - the node whose radius should be updated

radius - the desired radius for the given node

setStress

public void setStress(Node node,
                      double stress)

Schedules an update for the stress value of the given node.

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(double, double).

The stress value is defined to be a value from the interval [0,1].

To make sure that the layout algorithm is active, it can be woken up after scheduling this update.

Parameters:

node - the node whose stress value should be updated

stress - a stress value from the interval [0,1]

Throws:

java.lang.IllegalArgumentException - if the given stress value is negative or greater than 1

getStress

public double getStress(Node node)

Polls the current stress value of a given node.

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].

If a certain stress value for a node was set earlier using setStress(Node, double), this method will not necessarily return that same value for the same node. The reason is that the algorithm may be sleeping and did therefore not notice the change yet.

Parameters:

node - the node for which the stress value should be polled

Returns:

the stress value of the given node

See Also:

setStress(Node, double)

setCenterX

public void setCenterX(Node node,
                       double x)

Schedules an update for the center location's x-coordinate of the given node.

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(double, double).

This method may be used for updating node positions due to user interaction (e.g. horizontal dragging). To make sure that the layout algorithm is active, it can be woken up after scheduling this update.

Parameters:

node - the node that should be updated

x - the desired x-coordinate of the given node

See Also:

setCenterY(Node, double), setCenter(Node, double, double)

setCenterY

public void setCenterY(Node node,
                       double y)

Schedules an update for the center location's y-coordinate of the given node.

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(double, double).

This method may be used for updating node positions due to user interaction (e.g. vertical dragging). To make sure that the layout algorithm is active, it can be woken up after scheduling this update.

Parameters:

node - the node that should be updated

y - the desired y-coordinate of the given node

See Also:

setCenterX(Node, double), setCenter(Node, double, double)

getCenter

public YPoint getCenter(Node node)

Polls the current coordinates of the center of the given node.

The returned coordinates do not necessarily correspond to the actual location of the node in the input graph. They may only be intermediate results stored in the algorithm. This will be the case if scheduled updates were not yet completely committed to the actual graph.

Even if a certain location was set earlier, it will not necessarily be the result of this method. Reasons can be that changes need to be committed first, or the algorithm is sleeping.

Parameters:

node - the node for which the center should be polled

Returns:

the YPoint representing the center location of the given node, or null if nothing about the node is known

See Also:

setCenter(Node, double, double)

getCenterX

public double getCenterX(Node node)

Polls the current x-coordinate of the center location of the given node.

The returned coordinate is not necessarily the actual x-coordinate of the node in the input graph but only an intermediate result stored in the algorithm. This will be the case if scheduled updates were not yet completely committed to the actual graph.

Even if a certain location was set earlier, it will not necessarily be the result of this method. Reasons can be that changes need to be committed first, or the algorithm is sleeping.

Parameters:

node - the node for which the x-coordinate should be polled

Returns:

the x-coordinate of the center location of the given node

See Also:

setCenterX(Node, double)

getCenterY

public double getCenterY(Node node)

Polls the current y-coordinate of the center location of the given node.

The returned coordinate is not necessarily the actual y-coordinate of the node in the input graph but only an intermediate result stored in the algorithm. This will be the case if scheduled updates were not yet completely committed to the actual graph.

Even if a certain location was set earlier, it will not necessarily be the result of this method. Reasons can be that changes need to be committed first, or the algorithm is sleeping.

Parameters:

node - the node for which the y-coordinate should be polled

Returns:

the y-coordinate of the center location of the given node

See Also:

setCenterY(Node, double)

setMaxTime

public void setMaxTime(long maxTime)

Specifies the maximum duration in milliseconds that this algorithm is allowed to run.

The duration needs to be non-negative.

If the maximum duration is exceeded, the algorithm will start to sleep.

Default Value:

The default value is Long.MAX_VALUE. No time restriction is imposed.

Parameters:

maxTime - the maximum duration in milliseconds

Throws:

java.lang.IllegalArgumentException - if the specified maximum duration has a negative value

setQuality

public void setQuality(double quality)

Specifies the ratio of layout quality versus running time.

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:

The default value is 1.

Parameters:

quality - a value between 0.0 (low quality, fast) and 1.0 (high quality, slow)

Throws:

java.lang.IllegalArgumentException - if the specified ratio is outside the interval [0,1]

getMaxTime

public long getMaxTime()

Specifies the maximum duration in milliseconds that this algorithm is allowed to run.

The duration needs to be non-negative.

If the maximum duration is exceeded, the algorithm will start to sleep.

Returns:

the maximum duration in milliseconds

See Also:

setMaxTime(long)

getQuality

public double getQuality()

Returns the ratio of layout quality versus running time.

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].

Returns:

a value between 0.0 (low quality, fast) and 1.0 (high quality, slow)

syncStructure

public void syncStructure()

Synchronizes the structure of the graph copy with the original graph.

A call to this method will have no effect if the algorithm is currently not running.

This method may be used only if the layout algorithm was previously started with a CopiedLayoutGraph instance as parameter to methods startLayout(LayoutGraph), doLayout(LayoutGraph) or startLayoutSingleThreaded(LayoutGraph).

Throws:

java.lang.IllegalStateException - if the currently handled graph is not of type CopiedLayoutGraph

setOutputRestriction

public void setOutputRestriction(OutputRestriction restriction)

Specifies an OutputRestriction which restricts the area for the layout result of this algorithm.

Default Value:

The default value is OutputRestriction.NONE. No area restriction is imposed.

Parameters:

restriction - the OutputRestriction instance for restricting the area of the layout

Throws:

java.lang.IllegalArgumentException - if the given restriction is null

See Also:

OutputRestriction

Sample Graphs:

No restriction

Circular restriction

Elliptical restriction

Rectangular restriction

getOutputRestriction

public OutputRestriction getOutputRestriction()

Returns an OutputRestriction which restricts the area for the layout result of this algorithm.

Returns:

the OutputRestriction instance for restricting the area of the layout

See Also:

setOutputRestriction(OutputRestriction)

stopAndWait

public void stopAndWait()

Stops a previously started algorithm and then blocks until the current layout calculation is completed.

See Also:

isStopped(), stop()