com.yworks.yfiles.layout.labeling

Class AbstractLabeling

java.lang.Object

com.yworks.yfiles.layout.AbstractLayoutStage

com.yworks.yfiles.layout.labeling.AbstractLabeling

All Implemented Interfaces:

ILayoutAlgorithm, ILayoutStage

Direct Known Subclasses:

AbstractMISLabeling

public abstract class AbstractLabeling
extends AbstractLayoutStage

An abstract base class for generic labeling algorithms which place labels of graphs.

Labeling algorithms compute positions for labels in a given graph. The main goal is to place labels such that they do not overlap with other graph elements. Labeling algorithms do not modify positions of nodes and edges.

Concept

Generic labeling algorithms use the model associated with a label (i.e. node label model for nodes and edge label model for edges). The models are necessary to compute a set of LabelCandidates, i.e., candidate positions for a label. Then, one best matching candidate from the set will be selected. This selection depends on several preferences, e.g., if overlaps with nodes are not allowed, candidates encoding overlapping positions will be ignored.

After one LabelCandidate has been chosen, the label model's parameter is used for encoding the label position. Therefore, the result of a generic labeling algorithm is one model parameter per label. The parameter is stored with the label and expresses the label position with respect to the underlying label model.

Features

This class provides a general frame, offering functionality which can be shared by other generic labeling algorithms.

To only place labels or a subset of labels, the main labeling methods label(LayoutGraph, Object), label(LayoutGraph, Object) and label(LayoutGraph, YList, YList) are offered.

As this class represents an AbstractLayoutStage, it allows usage as a generic labeling stage. By combining it with a core layouter, the labeling will take place after the core layouter was executed (applyLayout(LayoutGraph)). This is especially useful if the core layouter does not support label handling.

Field Summary

Fields

Modifier and Type	Field and Description
static ILabelLayoutDpKey<Object>	LABEL_MODEL_DPKEY A DataProvider key for mapping models to edge/node labels The INodeLabelLayoutModels and IEdgeLabelLayoutModels linked to INodeLabelLayouts and IEdgeLabelLayouts by this IDataProvider are taken as replacement models.

Constructor Summary

Constructors

Constructor and Description
AbstractLabeling() Creates a new AbstractLabeling instance with default settings.

Method Summary

Modifier and Type	Method and Description
void	applyLayout(LayoutGraph graph) Places the labels in the graph after first executing the core layouter.
Object	getAffectedLabelsDpKey() Gets the IDataProvider key to mark labels as selected for placement.
double	getProfit(LabelCandidate candidate) Returns the profit for placing a LabelCandidate with respect to the current profit model.
IProfitModel	getProfitModel() Gets the IProfitModel for ranking the LabelCandidates for labels.
boolean	isAutoFlippingEnabled() Gets whether or not edge labels are automatically flipped if otherwise they would be upside-down.
boolean	isEdgeGroupOverlapAllowed() Gets whether or not edge labels may overlap with edges belonging to the same edge group as the label's edge.
boolean	isEdgeLabelPlacementEnabled() Gets whether or not labels assigned to edges are placed.
boolean	isEdgeOverlapsRemovalEnabled() Gets whether or not label candidates that overlap with edges are removed.
boolean	isInternalNodeLabelMovingEnabled() Gets whether or not internal node labels are allowed to move.
boolean	isLabelOverlapsReducingEnabled() Gets whether or not a post-processing step to reduce the number of label overlaps is applied.
boolean	isNodeLabelPlacementEnabled() Gets whether or not labels assigned to nodes are placed.
boolean	isNodeOverlapsRemovalEnabled() Gets whether or not label candidates that overlap with nodes are removed.
void	label(LayoutGraph graph) Places the labels of the input graph using a IDataProvider registered to the input graph with the given key for determining which labels to place.
void	label(LayoutGraph graph, Object key) Places the labels of the input graph using a IDataProvider registered to the input graph with the given key for determining which labels to place.
void	label(LayoutGraph graph, YList nodeLabels, YList edgeLabels) Places the labels of the input graph restricting the placement to labels contained in the given lists.
void	setAffectedLabelsDpKey(Object value) Sets the IDataProvider key to mark labels as selected for placement.
void	setAutoFlippingEnabled(boolean value) Sets whether or not edge labels are automatically flipped if otherwise they would be upside-down.
void	setEdgeGroupOverlapAllowed(boolean value) Sets whether or not edge labels may overlap with edges belonging to the same edge group as the label's edge.
void	setEdgeLabelPlacementEnabled(boolean value) Sets whether or not labels assigned to edges are placed.
void	setEdgeOverlapsRemovalEnabled(boolean value) Sets whether or not label candidates that overlap with edges are removed.
void	setInternalNodeLabelMovingEnabled(boolean value) Sets whether or not internal node labels are allowed to move.
void	setLabelOverlapsReducingEnabled(boolean value) Sets whether or not a post-processing step to reduce the number of label overlaps is applied.
void	setNodeLabelPlacementEnabled(boolean value) Sets whether or not labels assigned to nodes are placed.
void	setNodeOverlapsRemovalEnabled(boolean value) Sets whether or not label candidates that overlap with nodes are removed.
void	setProfitModel(IProfitModel value) Sets the IProfitModel for ranking the LabelCandidates for labels.

Methods inherited from class com.yworks.yfiles.layout.AbstractLayoutStage

applyLayoutCore, getCoreLayout, setCoreLayout

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 ILabelLayoutDpKey<Object> LABEL_MODEL_DPKEY

A DataProvider key for mapping models to edge/node labels

The INodeLabelLayoutModels and IEdgeLabelLayoutModels linked to INodeLabelLayouts and IEdgeLabelLayouts by this IDataProvider are taken as replacement models. This means that the original model is internally replaced by another model when computing valid positions for the label. A model parameter that fits the calculated position of the replacement model best is set for the original label model.

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

If there is no IDataProvider registered with this key, then the original models will be used.

Constructor Detail

AbstractLabeling

public AbstractLabeling()

Creates a new AbstractLabeling instance with default settings.

Method Detail

applyLayout

public void applyLayout(LayoutGraph graph)

Places the labels in the graph after first executing the core layouter.

Specified by:

applyLayout in interface ILayoutAlgorithm

Specified by:

applyLayout in class AbstractLayoutStage

Calls method label(LayoutGraph, Object) to perform the actual labeling.

Parameters:

graph - the input graph

See Also:

label(LayoutGraph, Object)

getAffectedLabelsDpKey

public Object getAffectedLabelsDpKey()

Gets the IDataProvider key to mark labels as selected for placement.

If a IDataProvider is registered with this key, only the selected labels will be placed, while all other labels are considered fixed.

The registered IDataProvider needs to map from ILabelLayout to Boolean where true indicates that a label should be placed and false indicates that a label should be ignored.

The specified selection will be ignored when invoking the algorithm via label(LayoutGraph, Object) or label(LayoutGraph, YList, YList). Furthermore, if node labeling or edge labeling is disabled, the selection does not have any effect on the respective labels.

Default Value:

The default value is null. All labels are considered to be selected.

Returns:

the IDataProvider key for marking labels as selected or null if all labels should be considered selected

See Also:

setAffectedLabelsDpKey(Object)

getProfit

public double getProfit(LabelCandidate candidate)

Returns the profit for placing a LabelCandidate with respect to the current profit model.

Method IProfitModel.getProfit(LabelCandidate) on the current profit model will be invoked to compute the actual profit value.

The higher the profit (rank) of a candidate is, the more likely it will be chosen as actual position by the algorithm.

Parameters:

candidate - a label candidate

Returns:

the profit value between 0 and 1

getProfitModel

public IProfitModel getProfitModel()

Gets the IProfitModel for ranking the LabelCandidates for labels.

The profit model is used when calculating the profit of a candidate.

The higher the profit (rank) of a candidate is, the more likely it will be chosen as actual position by the algorithm.

Default Value:

The default value is SimpleProfitModel

Returns:

a IProfitModel instance for ranking label candidates

See Also:

IProfitModel, SimpleProfitModel, getProfit(LabelCandidate), setProfitModel(IProfitModel)

isAutoFlippingEnabled

public boolean isAutoFlippingEnabled()

Gets whether or not edge labels are automatically flipped if otherwise they would be upside-down.

This feature has an effect only if labels have a free model.

Default Value:

The default value is false. Edge labels being upside-down keep their orientation.

Returns:

true, if edge labels automatically flip, false otherwise

See Also:

setAutoFlippingEnabled(boolean)

isEdgeGroupOverlapAllowed

public boolean isEdgeGroupOverlapAllowed()

Gets whether or not edge labels may overlap with edges belonging to the same edge group as the label's edge.

An edge group is a set of edges which share a common bus near the target or source node. They are defined using IDataProviders registered with PortConstraintKeys.SOURCE_GROUP_ID_DPKEY and PortConstraintKeys.TARGET_GROUP_ID_DPKEY.

Default Value:

The default value is false. Edge labels are not allowed to overlap with edges of the same edge group.

Returns:

true if edge labels may overlap with edges of the same edge group, false otherwise

See Also:

PortConstraintKeys.SOURCE_GROUP_ID_DPKEY, PortConstraintKeys.TARGET_GROUP_ID_DPKEY, setEdgeGroupOverlapAllowed(boolean)

isEdgeLabelPlacementEnabled

public boolean isEdgeLabelPlacementEnabled()

Gets whether or not labels assigned to edges are placed.

This setting has higher priority than any custom label selection. If it is disabled, edge labels marked via the selection will still be ignored. If enabled, then the selection may determine whether a label is placed or not.

Default Value:

The default value is true. Edge labels will be placed.

Returns:

true if edge labels should be placed, false otherwise

See Also:

setAffectedLabelsDpKey(Object), setEdgeLabelPlacementEnabled(boolean)

isEdgeOverlapsRemovalEnabled

public boolean isEdgeOverlapsRemovalEnabled()

Gets whether or not label candidates that overlap with edges are removed.

If overlapping candidates are not removed, they will be considered but get a penalty. Therefore, it is still less likely that an overlapping candidate is finally chosen.

The detection and removal of labels that overlap with edges may increase the runtime of this algorithm.

If this feature is enabled and all candidates of a label overlap with some edge, then the label model's default parameter will be used to determine the actual placement (DefaultParameter for node labels and DefaultParameter for edge labels).

Default Value:

The default value is false. Candidates overlapping with edges are allowed.

Returns:

true if candidates overlapping with edges are removed, false otherwise

See Also:

setEdgeOverlapsRemovalEnabled(boolean)

isInternalNodeLabelMovingEnabled

public boolean isInternalNodeLabelMovingEnabled()

Gets whether or not internal node labels are allowed to move.

A node label is internal if the label's boundaries are completely within the node's boundaries.

This setting will only have an effect if node labeling is enabled.

This feature only works in conjunction with INodeLabelLayoutModels that restrict the positioning of labels (i.e. non-free label models).

Default Value:

The default value is false. Internal node labels will not be moved.

Returns:

true if internal node labels may be moved, false otherwise

See Also:

setInternalNodeLabelMovingEnabled(boolean)

isLabelOverlapsReducingEnabled

public boolean isLabelOverlapsReducingEnabled()

Gets whether or not a post-processing step to reduce the number of label overlaps is applied.

The overlap reduction process is only applied to edge labels whose IEdgeLabelLayoutModel is of type FreeEdgeLabelLayoutModel and node labels whose INodeLabelLayoutModel is of type FreeNodeLabelLayoutModel.

Default Value:

The default value is false. Post-processing to reduce overlaps is disabled.

Returns:

true if a post-processing step for reducing the number of label overlaps is applied, false otherwise

See Also:

setLabelOverlapsReducingEnabled(boolean)

isNodeLabelPlacementEnabled

public boolean isNodeLabelPlacementEnabled()

Gets whether or not labels assigned to nodes are placed.

This setting has higher priority than any custom label selection. If it is disabled, node labels marked via the selection will still be ignored. If enabled, then the selection may determine whether a label is placed or not.

Default Value:

The default value is true. Node labels will be placed.

Returns:

true if node labels should be placed, false otherwise

See Also:

setAffectedLabelsDpKey(Object), setNodeLabelPlacementEnabled(boolean)

isNodeOverlapsRemovalEnabled

public boolean isNodeOverlapsRemovalEnabled()

Gets whether or not label candidates that overlap with nodes are removed.

If overlapping candidates are not removed, they will be considered but get a penalty. Therefore, it is still less likely that an overlapping candidate is finally chosen.

The detection and removal of labels that overlap with nodes may increase the runtime of this algorithm.

If this feature is enabled and all candidates of a label overlap with some node, then the label model's default parameter will be used to determine the actual placement (DefaultParameter for node labels and DefaultParameter for edge labels).

Default Value:

The default value is false. Candidates overlapping with nodes are allowed.

Returns:

true if candidates overlapping with nodes are removed, false otherwise

See Also:

setNodeOverlapsRemovalEnabled(boolean)

label

public final void label(LayoutGraph graph)

Places the labels of the input graph using a IDataProvider registered to the input graph with the given key for determining which labels to place.

Instead of considering the current selection key, the IDataProvider registered with the given key will be used for selecting labels. Invoking this method has the same effect as first specifying the key as selection key and then invoking label(LayoutGraph, Object).

Parameters:

graph - the input graph

label

public void label(LayoutGraph graph,
                  Object key)

Places the labels of the input graph using a IDataProvider registered to the input graph with the given key for determining which labels to place.

Instead of considering the current selection key, the IDataProvider registered with the given key will be used for selecting labels. Invoking this method has the same effect as first specifying the key as selection key and then invoking label(LayoutGraph, Object).

Parameters:

graph - the input graph

key - the IDataProvider key for label selection

label

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

Places the labels of the input graph restricting the placement to labels contained in the given lists.

The selection will not be considered; the given lists will define the selection of labels that are to be placed.

If node labeling or edge labeling is disabled, then the labels of the respective given list will not be placed.

Parameters:

graph - the input graph

nodeLabels - a list of INodeLabelLayouts defining the set of node labels that will be placed

edgeLabels - a list of IEdgeLabelLayouts defining the set of edge labels that will be placed

setAffectedLabelsDpKey

public void setAffectedLabelsDpKey(Object value)

Sets the IDataProvider key to mark labels as selected for placement.

If a IDataProvider is registered with this key, only the selected labels will be placed, while all other labels are considered fixed.

The registered IDataProvider needs to map from ILabelLayout to Boolean where true indicates that a label should be placed and false indicates that a label should be ignored.

The specified selection will be ignored when invoking the algorithm via label(LayoutGraph, Object) or label(LayoutGraph, YList, YList). Furthermore, if node labeling or edge labeling is disabled, the selection does not have any effect on the respective labels.

Default Value:

The default value is null. All labels are considered to be selected.

Parameters:

value - the IDataProvider key for marking labels as selected or null if all labels should be considered selected

See Also:

getAffectedLabelsDpKey()

setAutoFlippingEnabled

public void setAutoFlippingEnabled(boolean value)

Sets whether or not edge labels are automatically flipped if otherwise they would be upside-down.

This feature has an effect only if labels have a free model.

Default Value:

The default value is false. Edge labels being upside-down keep their orientation.

Parameters:

value - true, if edge labels automatically flip, false otherwise

See Also:

isAutoFlippingEnabled()

setEdgeGroupOverlapAllowed

public void setEdgeGroupOverlapAllowed(boolean value)

Sets whether or not edge labels may overlap with edges belonging to the same edge group as the label's edge.

An edge group is a set of edges which share a common bus near the target or source node. They are defined using IDataProviders registered with PortConstraintKeys.SOURCE_GROUP_ID_DPKEY and PortConstraintKeys.TARGET_GROUP_ID_DPKEY.

Default Value:

The default value is false. Edge labels are not allowed to overlap with edges of the same edge group.

Parameters:

value - true if edge labels may overlap with edges of the same edge group, false otherwise

See Also:

PortConstraintKeys.SOURCE_GROUP_ID_DPKEY, PortConstraintKeys.TARGET_GROUP_ID_DPKEY, isEdgeGroupOverlapAllowed()

setEdgeLabelPlacementEnabled

public void setEdgeLabelPlacementEnabled(boolean value)

Sets whether or not labels assigned to edges are placed.

This setting has higher priority than any custom label selection. If it is disabled, edge labels marked via the selection will still be ignored. If enabled, then the selection may determine whether a label is placed or not.

Default Value:

The default value is true. Edge labels will be placed.

Parameters:

value - true if edge labels should be placed, false otherwise

See Also:

setAffectedLabelsDpKey(Object), isEdgeLabelPlacementEnabled()

setEdgeOverlapsRemovalEnabled

public void setEdgeOverlapsRemovalEnabled(boolean value)

Sets whether or not label candidates that overlap with edges are removed.

If overlapping candidates are not removed, they will be considered but get a penalty. Therefore, it is still less likely that an overlapping candidate is finally chosen.

The detection and removal of labels that overlap with edges may increase the runtime of this algorithm.

If this feature is enabled and all candidates of a label overlap with some edge, then the label model's default parameter will be used to determine the actual placement (DefaultParameter for node labels and DefaultParameter for edge labels).

Default Value:

The default value is false. Candidates overlapping with edges are allowed.

Parameters:

value - true if candidates overlapping with edges are removed, false otherwise

See Also:

isEdgeOverlapsRemovalEnabled()

setInternalNodeLabelMovingEnabled

public void setInternalNodeLabelMovingEnabled(boolean value)

Sets whether or not internal node labels are allowed to move.

A node label is internal if the label's boundaries are completely within the node's boundaries.

This setting will only have an effect if node labeling is enabled.

This feature only works in conjunction with INodeLabelLayoutModels that restrict the positioning of labels (i.e. non-free label models).

Default Value:

The default value is false. Internal node labels will not be moved.

Parameters:

value - true if internal node labels may be moved, false otherwise

See Also:

isInternalNodeLabelMovingEnabled()

setLabelOverlapsReducingEnabled

public void setLabelOverlapsReducingEnabled(boolean value)

Sets whether or not a post-processing step to reduce the number of label overlaps is applied.

The overlap reduction process is only applied to edge labels whose IEdgeLabelLayoutModel is of type FreeEdgeLabelLayoutModel and node labels whose INodeLabelLayoutModel is of type FreeNodeLabelLayoutModel.

Default Value:

The default value is false. Post-processing to reduce overlaps is disabled.

Parameters:

value - true if a post-processing step for reducing the number of label overlaps is applied, false otherwise

See Also:

isLabelOverlapsReducingEnabled()

setNodeLabelPlacementEnabled

public void setNodeLabelPlacementEnabled(boolean value)

Sets whether or not labels assigned to nodes are placed.

This setting has higher priority than any custom label selection. If it is disabled, node labels marked via the selection will still be ignored. If enabled, then the selection may determine whether a label is placed or not.

Default Value:

The default value is true. Node labels will be placed.

Parameters:

value - true if node labels should be placed, false otherwise

See Also:

setAffectedLabelsDpKey(Object), isNodeLabelPlacementEnabled()

setNodeOverlapsRemovalEnabled

public void setNodeOverlapsRemovalEnabled(boolean value)

Sets whether or not label candidates that overlap with nodes are removed.

If overlapping candidates are not removed, they will be considered but get a penalty. Therefore, it is still less likely that an overlapping candidate is finally chosen.

The detection and removal of labels that overlap with nodes may increase the runtime of this algorithm.

If this feature is enabled and all candidates of a label overlap with some node, then the label model's default parameter will be used to determine the actual placement (DefaultParameter for node labels and DefaultParameter for edge labels).

Default Value:

The default value is false. Candidates overlapping with nodes are allowed.

Parameters:

value - true if candidates overlapping with nodes are removed, false otherwise

See Also:

isNodeOverlapsRemovalEnabled()

setProfitModel

public void setProfitModel(IProfitModel value)

Sets the IProfitModel for ranking the LabelCandidates for labels.

The profit model is used when calculating the profit of a candidate.

The higher the profit (rank) of a candidate is, the more likely it will be chosen as actual position by the algorithm.

Default Value:

The default value is SimpleProfitModel

Parameters:

value - a IProfitModel instance for ranking label candidates

See Also:

IProfitModel, SimpleProfitModel, getProfit(LabelCandidate), getProfitModel()