Search this API

y.layout
Class LabelCandidate

java.lang.Object
  extended by y.layout.LabelCandidate
All Implemented Interfaces:
PlaneObject
Direct Known Subclasses:
EdgeLabelCandidate, NodeLabelCandidate

public class LabelCandidate
extends java.lang.Object
implements PlaneObject

A LabelCandidate describes one valid placement for a label considering the label model.

Generic labeling algorithms place labels according to their label model. To get valid locations for the label, the label model generates various LabelCandidates. One of these candidates will be chosen to provide the actual placement of the label.

See Also:
NodeLabelModel, EdgeLabelModel, SALabeling, GreedyMISLabeling
 

Constructor Summary
LabelCandidate(OrientedRectangle labelBox, java.lang.Object param, LabelLayout owner)
          Creates a new instance of LabelCandidate described by its box and model parameter.
LabelCandidate(OrientedRectangle labelBox, java.lang.Object param, LabelLayout owner, boolean internal)
          Creates a new instance of LabelCandidate described by its box, model parameter and internal flag.
LabelCandidate(YPoint pos, YDimension size, java.lang.Object param, LabelLayout owner)
          Creates a new instance of LabelCandidate described by location, size and model parameter.
LabelCandidate(YPoint pos, YDimension size, java.lang.Object param, LabelLayout owner, boolean internal)
          Creates a new instance of LabelCandidate described by location, size, model parameter and internal flag.
 
Method Summary
 YRectangle getBoundingBox()
          Returns the bounding box of this candidate.
 OrientedRectangle getBox()
          Returns the oriented box of this candidate.
 double getCustomProfit()
          Returns the custom profit for this candidate.
 double getEdgeOverlapPenalty()
          Returns a penalty for a candidate position that overlaps the path of an edge.
 double getHeight()
          Returns the height of the candidate's bounding box.
 YPoint getLocation()
          Returns the coordinates of the upper-left corner of the candidate's bounds.
 java.lang.Object getModelParameter()
          Returns the model parameter that was used by the underlying model to generate this label candidate.
 double getNodeOverlapPenalty()
          Returns a penalty for a candidate position that overlaps the box of a node.
 double getOverlapPenalty()
          Returns the sum of node overlap penalty and edge overlap penalty.
 LabelLayout getOwner()
          Returns the LabelLayout for which this candidate was created.
 java.lang.Object getParameter()
          Returns the model parameter that was used by the underlying model to generate this label candidate.
 YDimension getSize()
          Returns the width and height of the candidate's bounds.
 double getWidth()
          Returns the width of the candidate's bounds.
 double getX()
          Returns the minimum x-coordinate of the candidate's bounds.
 double getY()
          Returns the minimum y-coordinate of the candidate's bounds.
 boolean isInternal()
          Returns whether or not this candidate describes an internal label.
 boolean isPropagated()
          Returns whether or not this candidate's box had already been chosen by the labeling algorithm.
 void propagate()
          Replaces the model parameter and box of the owner with the model parameter and box of this candidate.
 void setCustomProfit(double customProfit)
          Specifies the custom profit for this candidate.
 void setEdgeOverlapPenalty(double penalty)
          Specifies a penalty for a candidate position that overlaps the path of an edge.
 void setNodeOverlapPenalty(double penalty)
          Specifies a penalty for a candidate position that overlaps the box of a node.
 java.lang.String toString()
          Returns a String representation of this LabelCandidate.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

LabelCandidate

public LabelCandidate(YPoint pos,
                      YDimension size,
                      java.lang.Object param,
                      LabelLayout owner)
Creates a new instance of LabelCandidate described by location, size and model parameter.

Parameters:
pos - the location of the upper left corner of the candidate
size - the size of the candidate
param - the parameters of the label model associated with this candidate
owner - the label associated with the candidate

LabelCandidate

public LabelCandidate(YPoint pos,
                      YDimension size,
                      java.lang.Object param,
                      LabelLayout owner,
                      boolean internal)
Creates a new instance of LabelCandidate described by location, size, model parameter and internal flag.

Parameters:
pos - the location of the upper left corner of the candidate
size - the size of the candidate
param - the parameters of the label model associated with this candidate
owner - the label associated with the candidate
internal - true if the candidate is allowed to overlap with its owner, false otherwise

LabelCandidate

public LabelCandidate(OrientedRectangle labelBox,
                      java.lang.Object param,
                      LabelLayout owner,
                      boolean internal)
Creates a new instance of LabelCandidate described by its box, model parameter and internal flag.

Parameters:
labelBox - the box that specifies the candidate's size and position
param - the parameters of the label model associated with this candidate
owner - the label associated with the candidate
internal - true if the candidate is allowed to overlap with its owner, false otherwise

LabelCandidate

public LabelCandidate(OrientedRectangle labelBox,
                      java.lang.Object param,
                      LabelLayout owner)
Creates a new instance of LabelCandidate described by its box and model parameter.

Parameters:
labelBox - the box that specifies the candidate's size and position
param - the parameters of the label model associated with this candidate
owner - the label associated with the candidate
Method Detail

getCustomProfit

public double getCustomProfit()
Returns the custom profit for this candidate. The profit describes the priority of this candidate with respect to other candidates. Labeling algorithms will use the profit to decide which candidate to choose.

The value is restricted to the interval [0,1], where 1 specifies the highest possible profit.

 
The value is only considered if the labeling algorithm uses an optimization strategy.
Returns:
the custom profit for this candidate
See Also:
setCustomProfit(double)

setCustomProfit

public void setCustomProfit(double customProfit)
Specifies the custom profit for this candidate. The profit describes the priority of this candidate with respect to other candidates. Labeling algorithms will use the profit to decide which candidate to choose.

The value is restricted to the interval [0,1], where 1 specifies the highest possible profit.

 
The value is only considered if the labeling algorithm uses an optimization strategy.
Default Value:
The default value is 0.
Parameters:
customProfit - the custom profit for this candidate
Throws:
java.lang.IllegalArgumentException - if the specified value lies outside of [0,1]

getModelParameter

public java.lang.Object getModelParameter()
Returns the model parameter that was used by the underlying model to generate this label candidate.

Returns:
the model parameter

getLocation

public YPoint getLocation()
Returns the coordinates of the upper-left corner of the candidate's bounds.

The bounds are the smallest paraxial box that contains the candidate.

Returns:
the coordinates of the upper-left corner
See Also:
getBoundingBox()

getSize

public YDimension getSize()
Returns the width and height of the candidate's bounds.

The bounds are the smallest paraxial box that contains the candidate.

Returns:
the size of the candidate's bounds
See Also:
getBoundingBox()

getX

public double getX()
Returns the minimum x-coordinate of the candidate's bounds.

The bounds are the smallest paraxial box that contains the candidate.

Returns:
the x-coordinate of the candidate's bounds
See Also:
getLocation(), getBoundingBox()

getY

public double getY()
Returns the minimum y-coordinate of the candidate's bounds.

The bounds are the smallest paraxial box that contains the candidate.

Returns:
the y-coordinate of the candidate's bounds
See Also:
getLocation(), getBoundingBox()

getWidth

public double getWidth()
Returns the width of the candidate's bounds.

The bounds are the smallest paraxial box that contains the candidate.

Returns:
the width of the candidate's bounds
See Also:
getSize(), getBoundingBox()

getHeight

public double getHeight()
Returns the height of the candidate's bounding box.

The bounding box is the smallest paraxial box that contains the candidate.

Returns:
the height of the candidate's bounding box
See Also:
getSize(), getBoundingBox()

getBoundingBox

public YRectangle getBoundingBox()
Returns the bounding box of this candidate.

The bounding box describes the smallest paraxial box that contains the candidate.

Specified by:
getBoundingBox in interface PlaneObject
Returns:
the bounding box

getBox

public OrientedRectangle getBox()
Returns the oriented box of this candidate.

If the label is rotated, this box will be oriented accordingly.

Returns:
the size, location and orientation of the candidate

getOwner

public LabelLayout getOwner()
Returns the LabelLayout for which this candidate was created.

Returns:
the actual label to which the candidate belongs

isInternal

public boolean isInternal()
Returns whether or not this candidate describes an internal label. Internal labels reside inside the boundaries of a node.

Returns:
true if the candidate represents an internal label, false otherwise

propagate

public void propagate()
Replaces the model parameter and box of the owner with the model parameter and box of this candidate.

When this candidate is chosen to provide the placement of the label, this method transfers the model parameter and the candidate box to the LabelLayout.

See Also:
getOwner(), getModelParameter(), getBox()

setNodeOverlapPenalty

public void setNodeOverlapPenalty(double penalty)
Specifies a penalty for a candidate position that overlaps the box of a node.

The penalty should be a factor between 0 and 1, where 0 means that an overlap is considered unimportant and 1 means that an overlap is considered severe.

Default Value:
The default value is 1.
Parameters:
penalty - the penalty for overlaps with nodes
Throws:
java.lang.IllegalArgumentException - if the specified penalty is outside [0,1]

setEdgeOverlapPenalty

public void setEdgeOverlapPenalty(double penalty)
Specifies a penalty for a candidate position that overlaps the path of an edge.

The penalty should be a factor between 0 and 1, where 0 means that an overlap is considered unimportant and 1 means that an overlap is considered severe.

Default Value:
The default value is 1.
Parameters:
penalty - the penalty for overlaps with edges
Throws:
java.lang.IllegalArgumentException - if the specified penalty is outside [0,1]

getNodeOverlapPenalty

public double getNodeOverlapPenalty()
Returns a penalty for a candidate position that overlaps the box of a node.

The penalty should be a factor between 0 and 1, where 0 means that an overlap is considered unimportant and 1 means that an overlap is considered severe.

Returns:
the penalty for overlaps with nodes
See Also:
setNodeOverlapPenalty(double)

getEdgeOverlapPenalty

public double getEdgeOverlapPenalty()
Returns a penalty for a candidate position that overlaps the path of an edge.

The penalty should be a factor between 0 and 1, where 0 means that an overlap is considered unimportant and 1 means that an overlap is considered severe.

Returns:
the penalty for overlaps with edges
See Also:
setEdgeOverlapPenalty(double)

getOverlapPenalty

public double getOverlapPenalty()
Returns the sum of node overlap penalty and edge overlap penalty.

Returns:
the added penalty for edge overlaps and node overlaps
See Also:
getEdgeOverlapPenalty(), getNodeOverlapPenalty()

getParameter

public java.lang.Object getParameter()
Returns the model parameter that was used by the underlying model to generate this label candidate.

Returns:
the model parameter

isPropagated

public boolean isPropagated()
Returns whether or not this candidate's box had already been chosen by the labeling algorithm.

If this candidate is propagated, its model parameter and box were transferred to the label.

Returns:
true if this candidate was chosen, false otherwise
See Also:
propagate()

toString

public java.lang.String toString()
Returns a String representation of this LabelCandidate. The String contains the owning label and the coordinates of the candidate's bounds.

Overrides:
toString in class java.lang.Object
Returns:
a representation of the candidate
See Also:
getOwner(), getLocation()

© Copyright 2000-2021,
yWorks GmbH.
All rights reserved.