y.layout.labeling
Class AbstractLabelingAlgorithm

java.lang.Object
  y.layout.AbstractLayoutStage
      y.layout.labeling.AbstractLabelingAlgorithm

All Implemented Interfaces:

Layouter, LayoutStage

Direct Known Subclasses:

MISLabelingAlgorithm

public abstract class AbstractLabelingAlgorithm
extends AbstractLayoutStage

This class is an abstract base class for labeling algorithms. A labeling algorithm places a set of labels.

Field Summary

protected static double	EPS
static Object	LABEL_MODEL_DPKEY DataProvider key to specify for each EdgeLabelLayouts and each NodeLabelLayout a replacement EdgeLabelModel or NodeLabelModel, respectively, that is used by the labeling algorithm instead of the original label model.
protected boolean	setCustomizedProfitModel

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

protected

AbstractLabelingAlgorithm() Creates a new instance of this class.

Method Summary

boolean	canLayout(LayoutGraph graph) Returns true.
protected void	checkGroupNodeSize(GraphLayout layout, Object node) This method throws an IllegalArgumentException if the width/height of the given group node object is zero.
protected void	checkNodeSize(GraphLayout layout, Object node) This method throws an IllegalArgumentException if the width/height of the given node object is zero.
void	doLayout(LayoutGraph graph) Place the labels in the graph.
boolean	getPlaceEdgeLabels() Returns whether labels assigned to edges in a graph should be placed or ignored.
boolean	getPlaceNodeLabels() Returns whether labels assigned to nodes in a graph should be placed or ignored.
double	getProfit(LabelCandidate l) Returns the profit model that is used to rank the available positions for each label.
ProfitModel	getProfitModel()
YList	getRects() Returns the set of all generated candidate rectangles.
boolean	getRemoveEdgeOverlaps() Returns how label candidates which overlap with edges are handled.
boolean	getRemoveNodeOverlaps() Returns how label candidates which overlap with nodes are handled.
Object	getSelectionKey() Returns the labeling selection DataProvider key.
boolean	isApplyPostprocessing() Returns true if the postprocessing step is applied.
boolean	isAutoFlippingEnabled() Determines whether or not edge labels associated with a "free" label model (see, e.g., SmartEdgeLabelModel) should be automatically flipped if they would be upside-down.
boolean	isEdgeGroupOverlapAllowed() Returns whether edge labels may overlap with edges belonging to the same edge group.
boolean	isMoveInternalNodeLabels() Returns true if the labeling algorithm is allowed to move internal node labels.
boolean	isStoreRects() Returns whether the candidate rectangles should be stored to be retrieved.
boolean	isUseAlternativeSideHandling() Deprecated. use PreferredPlacementDescriptor.getSideReference() instead
void	label(LayoutGraph gl) Place the labels in the graph.
void	label(LayoutGraph gl, Object key) Place a subset of the labels.
void	label(LayoutGraph gl, YList nodeLabels, YList edgeLabels) Place some labels in the graph.
void	setApplyPostprocessing(boolean applyPostprocessing) Sets if the postprocessing step should be applied.
void	setAutoFlippingEnabled(boolean enabled) Specifies whether or not edge labels associated with a "free" label model (see, e.g., SmartEdgeLabelModel) should be automatically flipped if they would be upside-down.
void	setEdgeGroupOverlapAllowed(boolean edgeGroupOverlapAllowed) Sets the policy for edge groups.
void	setMoveInternalNodeLabels(boolean moveInternalNodeLabels) Sets if the labeling algorithm is allowed to move internal node labels.
void	setPlaceEdgeLabels(boolean enable) Specifies whether labels assigned to edges in a graph should be placed or ignored.
void	setPlaceNodeLabels(boolean enable) Specifies whether labels assigned to nodes in a graph should be placed or ignored.
void	setProfitModel(ProfitModel model) Sets the profit model that is used to rank the available positions for each label.
void	setRemoveEdgeOverlaps(boolean flag) Specifies how label candidates which overlap with edges are handled.
void	setRemoveNodeOverlaps(boolean flag) Specifies how label candidates which overlap with nodes are handled.
void	setSelection(Object key) Sets the DataProvider key, under which the labeling selection can be retrieved.
void	setStoreRects(boolean s) Sets whether the candidate rectangles should be stored to be retrieved.
void	setUseAlternativeSideHandling(boolean useAlternativeSideHandling) Deprecated. use PreferredPlacementDescriptor.setSideReference(byte) with PreferredPlacementDescriptor.SIDE_IS_ABSOLUTE_WITH_LEFT_IN_NORTH or PreferredPlacementDescriptor.SIDE_IS_ABSOLUTE_WITH_RIGHT_IN_NORTH as argument instead

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

LABEL_MODEL_DPKEY

public static final Object LABEL_MODEL_DPKEY

DataProvider key to specify for each EdgeLabelLayouts and each NodeLabelLayout a replacement EdgeLabelModel or NodeLabelModel, respectively, that is used by the labeling algorithm instead of the original label model. If this key is not defined or if a label has no mapping, the original model is used as normal. Otherwise, a model parameter that fits the calculated position of the replacement model best is set for the original model.

This feature is especially useful to restrict a free model. For example, to place a label upon its associated edge, a centered RotatedSliderEdgeLabelModel can be used a replacement model.

setCustomizedProfitModel

protected boolean setCustomizedProfitModel

EPS

protected static final double EPS

See Also:

Constant Field Values

Constructor Detail

AbstractLabelingAlgorithm

protected AbstractLabelingAlgorithm()

Creates a new instance of this class.

Method Detail

getProfitModel

public ProfitModel getProfitModel()

isMoveInternalNodeLabels

public boolean isMoveInternalNodeLabels()

Returns true if the labeling algorithm is allowed to move internal node labels. A node label is deemed internal if the label's bounds are completely within the node bounds.

setMoveInternalNodeLabels

public void setMoveInternalNodeLabels(boolean moveInternalNodeLabels)

Sets if the labeling algorithm is allowed to move internal node labels. A node label is deemed internal if the label's bounds are completely within the node bounds.

isApplyPostprocessing

public boolean isApplyPostprocessing()

Returns true if the postprocessing step is applied. The postprocessing step tries to further reduce the number of overlaps.

setApplyPostprocessing

public void setApplyPostprocessing(boolean applyPostprocessing)

Sets if the postprocessing step should be applied. The postprocessing step tries to further reduce the number of overlaps.

Note: the postprocessing step is only applied to edge labels whose edge label model is FreeEdgeLabelModel and node labels whose node label model is FreeNodeLabelModel.

isUseAlternativeSideHandling

public boolean isUseAlternativeSideHandling()

Deprecated. use PreferredPlacementDescriptor.getSideReference() instead

Returns true if the preference on which side of an edge a corresponding label should be placed is interpreted by human perception instead of always following the edge from source to target.

setUseAlternativeSideHandling

public void setUseAlternativeSideHandling(boolean useAlternativeSideHandling)

Deprecated. use PreferredPlacementDescriptor.setSideReference(byte) with PreferredPlacementDescriptor.SIDE_IS_ABSOLUTE_WITH_LEFT_IN_NORTH or PreferredPlacementDescriptor.SIDE_IS_ABSOLUTE_WITH_RIGHT_IN_NORTH as argument instead

Specifies whether the preference on which side of an edge a corresponding label should be placed is interpreted by human perception instead of always following the edge from source to target.

Note: the alternative side handling is only applied to edge labels whose edge label model is FreeEdgeLabelModel.

Parameters:

useAlternativeSideHandling - if true, the preferred side for an edge label is interpreted according to human perception.

setRemoveNodeOverlaps

public void setRemoveNodeOverlaps(boolean flag)

Specifies how label candidates which overlap with nodes are handled. If true these candidates are not considered, if false these candidates are considered, but a penalty is assigned to them.

setRemoveEdgeOverlaps

public void setRemoveEdgeOverlaps(boolean flag)

Specifies how label candidates which overlap with edges are handled. If true these candidates are not considered, if false these candidates are considered, but a penalty is assigned to them.

getRemoveNodeOverlaps

public boolean getRemoveNodeOverlaps()

Returns how label candidates which overlap with nodes are handled. If true these candidates are not considered, if false these candidates are considered, but a penalty is assigned to them.

getRemoveEdgeOverlaps

public boolean getRemoveEdgeOverlaps()

Returns how label candidates which overlap with edges are handled. If true these candidates are not considered, if false these candidates are considered, but a penalty is assigned to them.

setPlaceNodeLabels

public void setPlaceNodeLabels(boolean enable)

Specifies whether labels assigned to nodes in a graph should be placed or ignored. This method has higher priority than a specified selection, that means that all selected node labels are ignored by this algorithm if this property is set to false.

Parameters:

enable - whether labels assigned to nodes should be placed or ignored.

See Also:

getPlaceNodeLabels(), setSelection(Object)

setPlaceEdgeLabels

public void setPlaceEdgeLabels(boolean enable)

Specifies whether labels assigned to edges in a graph should be placed or ignored. This method has higher priority than a specified selection, that means that all selected edge labels are ignored by this algorithm if this property is set to false.

Parameters:

enable - whether labels assigned to edges should be placed or ignored.

See Also:

getPlaceEdgeLabels(), setSelection(Object)

getPlaceNodeLabels

public boolean getPlaceNodeLabels()

Returns whether labels assigned to nodes in a graph should be placed or ignored.

Returns:

true if and only if node labels are placed by this algorithm.

See Also:

setPlaceNodeLabels(boolean)

getPlaceEdgeLabels

public boolean getPlaceEdgeLabels()

Returns whether labels assigned to edges in a graph should be placed or ignored.

Returns:

true if and only if edge labels are placed by this algorithm.

See Also:

setPlaceEdgeLabels(boolean)

setSelection

public void setSelection(Object key)

Sets the DataProvider key, under which the labeling selection can be retrieved. The data provider registered with this key has to return true for labels that should be placed and false for all other labels.

Parameters:

key - The key for a DataProvider.

See Also:

getSelectionKey()

getSelectionKey

public Object getSelectionKey()

Returns the labeling selection DataProvider key.

See Also:

setSelection(Object)

isAutoFlippingEnabled

public boolean isAutoFlippingEnabled()

Determines whether or not edge labels associated with a "free" label model (see, e.g., SmartEdgeLabelModel) should be automatically flipped if they would be upside-down.

By default, this property is set to false.

Returns:

true if edge labels should be automatically flipped and false otherwise.

setAutoFlippingEnabled

public void setAutoFlippingEnabled(boolean enabled)

Specifies whether or not edge labels associated with a "free" label model (see, e.g., SmartEdgeLabelModel) should be automatically flipped if they would be upside-down.

By default, this property is set to false.

Parameters:

enabled - if true, edge labels will be automatically flipped.

canLayout

public boolean canLayout(LayoutGraph graph)

Returns true.

doLayout

public void doLayout(LayoutGraph graph)

Place the labels in the graph. This method is equivalent to the label() method.

Parameters:

graph - The graph to label.

checkNodeSize

protected void checkNodeSize(GraphLayout layout,
                             Object node)
                      throws IllegalArgumentException

This method throws an IllegalArgumentException if the width/height of the given node object is zero. It is called by the label-methods for each node object in the input graph.

Throws:

IllegalArgumentException - thrown if the width/height of the node object is zero.

Parameters:

layout - a graph layout object.

node - the node object to test.

See Also:

checkGroupNodeSize(GraphLayout,Object)

checkGroupNodeSize

protected void checkGroupNodeSize(GraphLayout layout,
                                  Object node)
                           throws IllegalArgumentException

This method throws an IllegalArgumentException if the width/height of the given group node object is zero. It is called by the label-methods for each group node object in the input graph.

Throws:

IllegalArgumentException - thrown if the width/height of the group node object is zero.

Parameters:

layout - a graph layout object.

node - the group node object to test.

See Also:

checkNodeSize(GraphLayout,Object)

label

public void label(LayoutGraph gl)

Place the labels in the graph.

Parameters:

gl - The graph to label.

label

public void label(LayoutGraph gl,
                  Object key)

Place a subset of the labels.

Parameters:

key - The key for a DataProvider in gl. Labels which should be placed return true.

label

public void label(LayoutGraph gl,
                  YList nodeLabels,
                  YList edgeLabels)

Place some labels in the graph. The selection is ignored, if set.

setProfitModel

public void setProfitModel(ProfitModel model)

Sets the profit model that is used to rank the available positions for each label. The higher the rank of a position, the more likely it will be chosen by the algorithm. By default an instance of type LabelRanking is set.

getProfit

public double getProfit(LabelCandidate l)

Returns the profit model that is used to rank the available positions for each label. The higher the rank of a position, the more likely it will be chosen by the algorithm. By default an instance of type LabelRanking is set.

getRects

public YList getRects()

Returns the set of all generated candidate rectangles.

Debug only.

setStoreRects

public void setStoreRects(boolean s)

Sets whether the candidate rectangles should be stored to be retrieved.

Debug only.

isStoreRects

public boolean isStoreRects()

Returns whether the candidate rectangles should be stored to be retrieved.

Debug only.

isEdgeGroupOverlapAllowed

public boolean isEdgeGroupOverlapAllowed()

Returns whether edge labels may overlap with edges belonging to the same edge group.

setEdgeGroupOverlapAllowed

public void setEdgeGroupOverlapAllowed(boolean edgeGroupOverlapAllowed)

Sets the policy for edge groups. If edge labels overlap with other edges of the same group, this flag decides whether these positions are allowed.