C

LabelCandidate

Show Usages
A LabelCandidate describes one valid placement for a label.
ImplementsInheritance Hierarchy

Remarks

The GenericLabeling algorithm places labels according to the positions provided by the associated candidate factory. Therefore, the candidate factory generates various LabelCandidates. One of these candidates will be chosen to provide the actual placement of the label.

Default Values of Properties

NameDefault
weight1.0

See Also

API

GenericLabeling, NodeLabelCandidates, EdgeLabelCandidates

Members

No filters for this type

Constructors

LabelCandidate

(labelBox: IOrientedRectangle, weight?: number)
Creates a new instance of LabelCandidate described by its boundary.

Parameters

labelBox: IOrientedRectangle
The box that specifies the candidate's size and position
weight?: number
The weight associated with the candidate

LabelCandidate

(
pos: Point
size: Size
weight?: number
)
Creates a new instance of LabelCandidate describing a paraxial rectangle with the given location and size.

Parameters

pos: Point
the location of the upper left corner of the candidate
size: Size
the size of the candidate
weight?: number
the weight associated with the candidate

Throws

Exception ({ name: 'ArgumentError' })
if the weight does not lie in the interval [0,1]

Properties

bounds

: Rect
readonly
Gets the bounds of this candidate.
The bounds describes the smallest paraxial box that contains the candidate.
readonlyfinal

intersectsEdge

: boolean
Indicates whether the label candidate intersects an edge that is not the owner of the label candidate.
The value is set at the beginning of the run of GenericLabeling and can be subsequently used for customizing the weight of the candidate; see also nodeLabelCandidateProcessors and edgeLabelCandidateProcessors.
final

Property Value

true if the candidate intersects an edge that is not the owner of the label, false otherwise

Examples

Excluding label candidates based on intersections.
layoutData.nodeLabelCandidateProcessors.constant = (
  candidates: IEnumerable<LabelCandidate>,
  _: ILabel | LayoutNodeLabel,
) => {
  for (const candidate of candidates.filter((c) => c.intersectsEdge)) {
    // candidates that intersect edges should not be selected
    candidate.weight = 0
  }
}

intersectsLayoutGridLine

: boolean
Indicates whether the label candidate intersects a layout grid line.
The value is set at the beginning of the run of GenericLabeling and can be subsequently used for customizing the weight of the candidate; see also nodeLabelCandidateProcessors and nodeLabelCandidateProcessors.
final

Property Value

true if the candidate intersects a layout grid line, false otherwise

Examples

Excluding label candidates based on intersections.
layoutData.nodeLabelCandidateProcessors.constant = (
  candidates: IEnumerable<LabelCandidate>,
  _: ILabel | LayoutNodeLabel,
) => {
  for (const candidate of candidates.filter(
    (c) => c.intersectsLayoutGridLine,
  )) {
    // candidates that intersect a layout grid line should not be selected
    candidate.weight = 0
  }
}

intersectsNode

: boolean
Indicates whether the label candidate intersects a node that is not the owner of the label candidate.
The value is set at the beginning of the run of GenericLabeling and can be subsequently used for customizing the weight of the candidate; see also nodeLabelCandidateProcessors and nodeLabelCandidateProcessors.
final

Property Value

true if the candidate intersects a node that is not the owner of the label, false otherwise

Examples

Excluding label candidates based on intersections.
layoutData.nodeLabelCandidateProcessors.constant = (
  candidates: IEnumerable<LabelCandidate>,
  _: ILabel | LayoutNodeLabel,
) => {
  for (const candidate of candidates.filter((c) => c.intersectsNode)) {
    // candidates that intersect nodes should not be selected
    candidate.weight = 0
  }
}

intersectsOwnEdgeGroup

: boolean
Indicates whether the label candidate intersects with an edge of an edge that is grouped with the label's edge.

The value is set at the beginning of the run of GenericLabeling and can be subsequently used for customizing the weight of the candidate; see also nodeLabelCandidateProcessors and nodeLabelCandidateProcessors.

This property is only relevant for labels of edges. Further, if the label candidate intersects its owner edge, but no other edge of the owner's edge group, this property is false; see also intersectsOwner.

An edge group is a set of edges which share a common bus near the target or source node. They are defined with sourceGroupIds and targetGroupIds.

final

Property Value

true if the label candidate intersects with an edge of an edge that is grouped with the label's edge, false otherwise

Examples

Excluding label candidates based on intersections.
layoutData.edgeLabelCandidateProcessors.constant = (
  candidates: IEnumerable<LabelCandidate>,
  _: ILabel | LayoutEdgeLabel,
) => {
  for (const candidate of candidates.filter(
    (c) => c.intersectsOwnEdgeGroup,
  )) {
    // candidates that intersect an edge of the owner's edge group should not be selected
    candidate.weight = 0
  }
}

Sample Graphs

ShownSetting: true (assume that labels need to be placed left of edges)

intersectsOwner

: boolean
Indicates whether the label candidate intersects the label's owner, i.e., the corresponding node or edge.
The value is set at the beginning of the run of GenericLabeling and can be subsequently used for customizing the weight of the candidate; see also nodeLabelCandidateProcessors and nodeLabelCandidateProcessors.
final

Property Value

true if the candidate intersects the label's owner, false otherwise

Examples

Excluding label candidates based on intersections.
layoutData.nodeLabelCandidateProcessors.constant = (
  candidates: IEnumerable<LabelCandidate>,
  _: ILabel | LayoutNodeLabel,
) => {
  for (const candidate of candidates.filter((c) => c.intersectsOwner)) {
    // candidates that intersect the owner of the label node should not be selected
    candidate.weight = 0
  }
}

layout

: IOrientedRectangle
readonly
Gets the oriented box of this candidate.
If the label is rotated, this box will be oriented accordingly.
readonlyfinal

weight

: number
Gets or sets the weight for this candidate.

The weight describes the priority of this candidate with respect to other candidates. Labeling algorithms will use the weight to decide which candidate to choose. Positions with a higher weight are more likely chosen.

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

The labeling algorithm automatically calculates the weights for each valid label position considering user specified properties like the associated LabelingCosts and EdgeLabelPreferredPlacement. There are also multiple ways to manually specify the weight values, e.g., as a parameter of a predefined candidate set (see addDiscreteCandidates) or by means of property edge label candidate processor and node label candidate processor.

final

Throws

Exception ({ name: 'ArgumentError' })
if the specified value lies outside of [0,1]

Default Value

The default value is: 1.0