y.layout
Class EdgeLabelOrientationSupport

java.lang.Object
  y.layout.EdgeLabelOrientationSupport

public class EdgeLabelOrientationSupport
extends java.lang.Object

EdgeLabelOrientationSupport provides orientation and mirroring support for layout algorithms with integrated edge labeling.

To calculate the position and orientation of edge labels whose placements are defined with the PreferredPlacementDescriptor, the OrientationLayouter would need the direction of the associated edge. Since this direction is not available to the OrientationLayouter, because it is a wrapper, the calculation must be done in the core layout algorithm itself with the help of the EdgeLabelOrientationSupport.

Important: Since layout algorithms with integrated edge labeling cannot deal with ambiguous preferred placement descriptors (combinations of the same setting, e.g., source or target for the PreferredPlacementDescriptor.getPlaceAlongEdge()), preProcessLabel(Graph, LabelLayoutData, Direction) removes combinations and replaces the original descriptor with a non-ambiguous one that is used during the layout calculation.

Constructor Summary

EdgeLabelOrientationSupport()
Creates a new EdgeLabelOrientationSupport instance.

Method Summary

protected PreferredPlacementDescriptor	createNonAmbiguous(PreferredPlacementDescriptor ambiguous) Creates and returns a non-ambiguous PreferredPlacementDescriptor of the given potentially ambiguous one.
static YVector	getEdgeLabelUpVector(PreferredPlacementDescriptor descriptor, Direction segmentDirection) Calculates the up vector of an edge label considering the preferred placement of the label as well as the direction of the edge segment the label is attached to.
static YVector	getLabelUpVector(double rightVectorAngle) Calculates the up vector for a label whose right vector is rotated clockwise by the given angle.
static Direction	getOrientedDirection(Direction direction, byte orientation, int mirrorMask) Transforms a direction of the layout to the oriented layout direction.
static boolean	isOrientationMirrored(byte orientation, int mirrorMask) Returns whether or not the orientation is mirrored.
void	markPortLabelForFallbackPlacement(LabelLayoutData portLabel) Marks the given port label for a non-port placement (fallback).
void	postProcessLabel(Graph graph, LabelLayoutData label) Restores the original preferred placement and updates the label rotation according to the layout orientation.
void	preProcessLabel(Graph graph, LabelLayoutData label, Direction segmentDirection) Prepares the label for the core layout algorithm.
void	replaceAmbiguousLabelDescriptors(Graph graph) Replaces the PreferredPlacementDescriptors of all edge labels in the given graph with non-ambiguous descriptors.
void	resetAmbiguousLabelDescriptors(Graph graph) Restores the PreferredPlacementDescriptors of all edge labels in the given graph with their original descriptors.
static void	updateLabelOrientation(LabelLayoutData label, Direction segmentDirection) Calculates and sets the up vector of an edge label considering the preferred placement of the label as well as the direction of the edge segment the label is attached to.

Methods inherited from class java.lang.Object

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

Constructor Detail

EdgeLabelOrientationSupport

public EdgeLabelOrientationSupport()

Creates a new EdgeLabelOrientationSupport instance.

Since this class handles the orientation of the edge labels, the core layout algorithm should disable the edge label calculation in its OrientationLayouter.

See Also:

OrientationLayouter.setConsiderEdgeLabelsEnabled(boolean)

Method Detail

replaceAmbiguousLabelDescriptors

public void replaceAmbiguousLabelDescriptors(Graph graph)

Replaces the PreferredPlacementDescriptors of all edge labels in the given graph with non-ambiguous descriptors.

The non-ambiguous descriptors are retrieved from the original descriptors. They describe only one of the possible placements.

This method should be called by a layout algorithm at the beginning of the layout calculation to assure that the label's placement is handled consistently.

Parameters:

graph - the input graph

resetAmbiguousLabelDescriptors

public void resetAmbiguousLabelDescriptors(Graph graph)

Restores the PreferredPlacementDescriptors of all edge labels in the given graph with their original descriptors.

This method should be called by a layout algorithm at the end of the layout calculation to assure that the original state of the graph is not corrupted.

Parameters:

graph - the input graph

preProcessLabel

public void preProcessLabel(Graph graph,
                            LabelLayoutData label,
                            Direction segmentDirection)

Prepares the label for the core layout algorithm.

First, the preferred placement of the edge label is replaced by a non-ambiguous PreferredPlacementDescriptor that has only relative references. This descriptor is orientation independent and can be used in the core layout algorithm. Second, the method rotates the label box in respect of its PreferredPlacementDescriptor and the direction of the segment to which it belongs. After that call, the core layout algorithm can use the geometry (LabelLayoutData.getWidth() and LabelLayoutData.getHeight()) of the label to calculate its location.

This method is called by the core layout algorithm with the integrated edge labeling for each edge label before the layout algorithm uses the geometry of labels. It should be called as soon as the direction of the segment the label belongs to is determined.

Parameters:

graph - the graph to get the orientation information from

label - the information about the edge label whose segment direction is determined

segmentDirection - the direction of the segment the edge label belongs to

createNonAmbiguous

protected PreferredPlacementDescriptor createNonAmbiguous(PreferredPlacementDescriptor ambiguous)

Creates and returns a non-ambiguous PreferredPlacementDescriptor of the given potentially ambiguous one.

The created descriptor will be one without any combinations of settings, e.g., source or target for the PreferredPlacementDescriptor.getPlaceAlongEdge().

Parameters:

ambiguous - an ambiguous PreferredPlacementDescriptor

Returns:

a non-ambiguous version of the given ambiguous PreferredPlacementDescriptor

postProcessLabel

public void postProcessLabel(Graph graph,
                             LabelLayoutData label)

Restores the original preferred placement and updates the label rotation according to the layout orientation.

The original LabelLayoutData.getPreferredPlacementDescriptor() that has been replaced in preProcessLabel(Graph, LabelLayoutData, Direction) gets restored. Then it moves and rotates the label box in respect of the orientation.

This method is called by the core layout algorithm with the integrated edge labeling for each edge label after the location of the label is determined.

Parameters:

graph - the graph to get the orientation information from

label - the information about the edge label whose location is determined

getOrientedDirection

public static Direction getOrientedDirection(Direction direction,
                                             byte orientation,
                                             int mirrorMask)

Transforms a direction of the layout to the oriented layout direction.

Parameters:

direction - direction in the layout

orientation - the orientation of the layout

mirrorMask - the mask to determine whether or not the orientation is mirrored

Returns:

the direction in the oriented layout

isOrientationMirrored

public static boolean isOrientationMirrored(byte orientation,
                                            int mirrorMask)

Returns whether or not the orientation is mirrored.

Parameters:

orientation - the orientation of the layout

mirrorMask - the mask to determine whether or not the orientation is mirrored

Returns:

true if the orientation is mirrored, false otherwise

updateLabelOrientation

public static void updateLabelOrientation(LabelLayoutData label,
                                          Direction segmentDirection)

Calculates and sets the up vector of an edge label considering the preferred placement of the label as well as the direction of the edge segment the label is attached to.

Parameters:

label - the data that describes the label orientation and is used for setting the new up vector

segmentDirection - the direction the edge segment is pointing to

See Also:

getEdgeLabelUpVector(PreferredPlacementDescriptor, Direction)

getEdgeLabelUpVector

public static YVector getEdgeLabelUpVector(PreferredPlacementDescriptor descriptor,
                                           Direction segmentDirection)

Calculates the up vector of an edge label considering the preferred placement of the label as well as the direction of the edge segment the label is attached to.

Parameters:

descriptor - the data describing the preferred label orientation

segmentDirection - the direction the edge segment is pointing to

Returns:

the up vector for the edge label that considers the preferred placement of the label as well as the direction of the edge segment the label is attached to

getLabelUpVector

public static YVector getLabelUpVector(double rightVectorAngle)

Calculates the up vector for a label whose right vector is rotated clockwise by the given angle.

The up vector starts in the lower-left corner of the label and points up. If the label is paraxial it is (0, -1). The right vector starts at the same point and points right. In a paraxial label it is (1, 0).

Parameters:

rightVectorAngle - the angle in radians the right vector is rotated by

Returns:

the up vector for a label whose right vector is rotated clockwise by the given angle

markPortLabelForFallbackPlacement

public void markPortLabelForFallbackPlacement(LabelLayoutData portLabel)

Marks the given port label for a non-port placement (fallback).

The given edge label's PreferredPlacementDescriptor will internally be changed such that its placement along edge is either LabelLayoutConstants.PLACE_AT_SOURCE or LabelLayoutConstants.PLACE_AT_TARGET.

Algorithms that are executed after this call and before resetAmbiguousLabelDescriptors(y.base.Graph) will handle port labels like normal source or target labels.

This method may only be called for labels that were also processed by an earlier call to replaceAmbiguousLabelDescriptors(y.base.Graph).

Parameters:

portLabel - an edge label that had a LabelLayoutConstants.PLACE_AT_SOURCE_PORT or LabelLayoutConstants.PLACE_AT_TARGET_PORT placement preference

Throws:

java.lang.IllegalStateException - if replaceAmbiguousLabelDescriptors(y.base.Graph) was never called for the graph containing the given label.

See Also:

LabelLayoutConstants.PLACE_AT_SOURCE_PORT, LabelLayoutConstants.PLACE_AT_TARGET_PORT