y.layout
Class LabelCandidate

java.lang.Object
  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()