y.layout
Class CurveFittingLayoutStage

java.lang.Object
  y.layout.AbstractLayoutStage
      y.layout.CurveFittingLayoutStage

All Implemented Interfaces:

Layouter, LayoutStage

public class CurveFittingLayoutStage
extends AbstractLayoutStage

CurveFittingLayoutStage fits a piecewise cubic bezier curve to given arbitrary edge paths.

Concept

The path of an edge, i.e., its start and end point as well as the intermediate control points, are interpreted as the set of input points. A cubic bezier curve is then fitted to these points.

After the fitting, the points of the processed edges can be interpreted as cubic bezier control points. Each four consecutive points form a bezier curve, where the first and last of the four points represent the start and end of the curve and the second and third point are the control points defining how the curve looks. The second and third point do not necessarily lie on the actual curve.

There are two exceptions to the stated rules:

• If an input edge only consists of a source and a target point, it will be ignored by this stage.
• Self-loop edges with only one intermediate control point are also ignored. Note that self-loops with more control points are, however, handled by this stage.

Features

The maximum allowed error for the fitting process can be selected to control how high the precision should be. A high allowed error means that the approximation process has a lot of freedom. Curves are only loosely bound to the original edge path. If this is not desired, e.g., because no new intersection with other graph elements should be introduced, then a rather low error value should be specified. The lower the error value, the larger the number of bend points of an approximated edge will be.

It is possible to define the set of edges that should be processed by this layout stage. Therefore, only paths of a sub-set of edges can be changed. Use a DataProvider registered with the specified selection key to mark edges which should be part of the considered sub-set.

The application of CurveFittingLayoutStage is useful if curved edge paths were modeled using a large number of bends which are then connected by straight lines - as, for example, produced by RadialLayouter. Applying this stage can drastically reduce the number of necessary bends in such cases.

If more than three consecutive points of an edge path are collinear, the stage always fits a bezier piece configured such that it represents a straight line to the collinear points (without the first and last point of the collinear part).

Field Summary

static java.lang.Object

FITTING_SELECTION_DPKEY A DataProvider key for selecting edges for curve fitting

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

CurveFittingLayoutStage()
Creates a new CurveFittingLayoutStage with default settings.

CurveFittingLayoutStage(Layouter core)
Creates a new CurveFittingLayoutStage with the given algorithm as core layout algorithm.

Method Summary

boolean	canLayout(LayoutGraph graph) Accepts all graphs that can be handled by the core layout algorithm.
void	doLayout(LayoutGraph graph) Changes the edge paths of selected edges of the given graph such that they represent piecewise cubic bezier curves which approximate the original points of the path.
double	getMaximumError() Returns the maximum allowed error for the fitting process.
java.lang.Object	getSelectedEdgesDpKey() Returns the DataProvider key to look up the selection state of the edges that defines whether or not an edge's path should be approximated by a bezier curve.
double	getStraightControlPointRatio() Returns the ratio that defines the distance between the intermediate control points and the end points of a cubic segment which actually represents a straight line, i.e., in case the four points are collinear.
void	setMaximumError(double maximumError) Specifies the maximum allowed error for the fitting process.
void	setSelectedEdgesDpKey(java.lang.Object selectedEdgesDpKey) Specifies the DataProvider key to look up the selection state of the edges that defines whether or not an edge's path should be approximated by a bezier curve.
void	setStraightControlPointRatio(double straightControlPointRatio) Specifies the ratio that defines the distance between the intermediate control points and the end points of a cubic segment which actually represents a straight line, i.e., in case the four points are collinear.

Methods inherited from class y.layout.AbstractLayoutStage

canLayoutCore, doLayoutCore, getCoreLayouter, setCoreLayouter

Methods inherited from class java.lang.Object

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

Field Detail

FITTING_SELECTION_DPKEY

public static final java.lang.Object FITTING_SELECTION_DPKEY

A DataProvider key for selecting edges for curve fitting

If there is no DataProvider registered with this key, a curve is fitted to all edges.

Constructor Detail

CurveFittingLayoutStage

public CurveFittingLayoutStage()

Creates a new CurveFittingLayoutStage with default settings.

CurveFittingLayoutStage

public CurveFittingLayoutStage(Layouter core)

Creates a new CurveFittingLayoutStage with the given algorithm as core layout algorithm.

Parameters:

core - the core layout algorithm

Method Detail

getMaximumError

public double getMaximumError()

Returns the maximum allowed error for the fitting process.

The error is defined as the minimum distance between an original input control point (i.e. bend) of and edge and the fitted bezier curve.

The maximum error must be greater than or equal to zero.

It is not recommended to set the maximum error to really small values, e.g., zero or one. Doing so produces a high number of bezier pieces and, thus, a high number of control points for each edge.

Returns:

the maximum allowed error for the fitting process

See Also:

setMaximumError(double)

setMaximumError

public void setMaximumError(double maximumError)

Specifies the maximum allowed error for the fitting process.

The error is defined as the minimum distance between an original input control point (i.e. bend) of and edge and the fitted bezier curve.

The maximum error must be greater than or equal to zero.

It is not recommended to set the maximum error to really small values, e.g., zero or one. Doing so produces a high number of bezier pieces and, thus, a high number of control points for each edge.

Default Value:

The default value is 4.0.

Parameters:

maximumError - the maximum allowed error for the fitting process

Throws:

java.lang.IllegalArgumentException - if the specified maximum error is negative

getStraightControlPointRatio

public double getStraightControlPointRatio()

Returns the ratio that defines the distance between the intermediate control points and the end points of a cubic segment which actually represents a straight line, i.e., in case the four points are collinear.

• 0.33 - the second and third control point are equally distributed between te first and fourth point.
• 0.0 - the first and second control point as well as the third and fourth point are equal.
• 0.5 - the second and third control point are equal and exactly the mid-point between the first and fourth point.

The control point ratio is defined to be within the interval [0.0, 0.5].

Returns:

the control point ratio for straight-line path segments

See Also:

setStraightControlPointRatio(double)

setStraightControlPointRatio

public void setStraightControlPointRatio(double straightControlPointRatio)

Specifies the ratio that defines the distance between the intermediate control points and the end points of a cubic segment which actually represents a straight line, i.e., in case the four points are collinear.

• 0.33 - the second and third control point are equally distributed between te first and fourth point.
• 0.0 - the first and second control point as well as the third and fourth point are equal.
• 0.5 - the second and third control point are equal and exactly the mid-point between the first and fourth point.

The control point ratio is defined to be within the interval [0.0, 0.5].

Default Value:

The default value is 0.33.

Parameters:

straightControlPointRatio - the control point ratio for straight-line path segments

Throws:

java.lang.IllegalArgumentException - if the specified ratio is outside the interval [0.0, 0.5]

getSelectedEdgesDpKey

public java.lang.Object getSelectedEdgesDpKey()

Returns the DataProvider key to look up the selection state of the edges that defines whether or not an edge's path should be approximated by a bezier curve.

If there is a DataProvider registered with the input graph with this key, then only marked edges are processed by this layout stage. Otherwise, all edges are processed.

Returns:

the DataProvider key for edge selection

See Also:

setSelectedEdgesDpKey(Object)

setSelectedEdgesDpKey

public void setSelectedEdgesDpKey(java.lang.Object selectedEdgesDpKey)

Specifies the DataProvider key to look up the selection state of the edges that defines whether or not an edge's path should be approximated by a bezier curve.

If there is a DataProvider registered with the input graph with this key, then only marked edges are processed by this layout stage. Otherwise, all edges are processed.

Default Value:

The default value is FITTING_SELECTION_DPKEY

Parameters:

selectedEdgesDpKey - the DataProvider key for edge selection

Throws:

java.lang.IllegalArgumentException - if the specified DataProvider key is null

canLayout

public boolean canLayout(LayoutGraph graph)

Accepts all graphs that can be handled by the core layout algorithm.

If there is no core layout algorithm, all graphs are accepted.

Parameters:

graph - the input graph

Returns:

true if there is no core layout algorithm or the core layout algorithm accepts the graph, false otherwise

See Also:

Layouter.doLayout(LayoutGraph)

doLayout

public void doLayout(LayoutGraph graph)

Changes the edge paths of selected edges of the given graph such that they represent piecewise cubic bezier curves which approximate the original points of the path.

Parameters:

graph - the input graph

See Also:

Layouter.canLayout(LayoutGraph)