Generic Labeling

This chapter describes the major API changes to the GenericLabeling introduced with yFiles for HTML 3.0 and explains how to migrate from the older version.

Renamed, Moved, and Removed Classes and Members

Candidate Positions

yFiles for HTML 3.0 replaces the previous concept of specifying valid label positions using models with the more flexible NodeLabelCandidates and EdgeLabelCandidates. These sets of candidate positions offer convenience methods to create positions corresponding to the previous model implementations, as well as new functionality to add fixed positions. Additionally, weights can be specified for each individual candidate to designate preferred positions.

// specify candidates with different weights (lower weight means that it is less likely chosen by the algorithm)
// creates slider candidates on the left side
const leftSliderCandidates =
  new EdgeLabelCandidates().addSliderCandidates({
    mode: 'single-side',
    distance: 10,
    weight: 1
  })

// adds slider candidates with lower weight on the right side
const candidates = leftSliderCandidates.addSliderCandidates({
  mode: 'single-side',
  distance: -5,
  weight: 0
})

// apply layout
const labeling = new GenericLabeling()
const labelingData = labeling.createLayoutData(graph)
labelingData.edgeLabelCandidates.constant = candidates
labeling.applyLayout(graph)

Instead of specifying the weights when creating the candidates, the nodeLabelCandidateProcessors and edgeLabelCandidateProcessors also offer the option to adjust the weights during the execution of the generic labeling algorithm. This approach is especially helpful when the priorities of label candidates depend on the result of another layout that has not yet run at the time when candidates are specified. Note that, when the delegate is called, the label candidates already contain the weights calculated by the labeling algorithm.

const weightRatio = 0.8
labelingData.edgeLabelCandidateProcessors.constant = (
  candidates,
  label
) => {
  for (const labelCandidate of candidates) {
    const customWeight = calculateCustomWeight(label, labelCandidate)

    // the new weight combines the weight already calculated by the labeling algorithm with a custom weight
    labelCandidate.weight =
      labelCandidate.weight * (1 - weightRatio) +
      customWeight * weightRatio
  }
}

const weightRatio = 0.8
labelingData.edgeLabelCandidateProcessors.constant = (
  candidates: IEnumerable<LabelCandidate>,
  label: LayoutEdgeLabel
) => {
  for (const labelCandidate of candidates) {
    const customWeight = calculateCustomWeight(label, labelCandidate)

    // the new weight combines the weight already calculated by the labeling algorithm with a custom weight
    labelCandidate.weight =
      labelCandidate.weight * (1 - weightRatio) +
      customWeight * weightRatio
  }
}

Scope

The generic labeling algorithm now offers more convenient ways to specify the labels it should handle. While it is still possible to simply restrict the scope to edge labels or node labels using GenericLabeling.scope, the new scope property of the generic labeling data offers the option to select individual labels, either directly or based on their owners.

For more information on the changed scope API, see Scope and Affected Items.

Optimization Strategy

The labeling algorithm’s optimizationStrategy property for prioritizing different layout qualities has been removed. Instead, the optimization strategy can be specified using LabelingCosts and LabelingOptimizationStrategy for each node label or edge label. Each of the old optimization strategies corresponds to a LabelingOptimizationStrategy, which can be used to construct a LabelingCosts instance that replicates the old behavior. Costs applying to all node labels and edge labels respectively can be specified with defaultNodeLabelingCosts and defaultEdgeLabelingCosts. Individual costs that supersede the default may be specified using the nodeLabelingCosts and edgeLabelingCosts properties of the labeling data.

Note that there is also a new cost preset AMBIGUOUS_PLACEMENTS that replaces the old reduceAmbiguity property of the generic labeling algorithm.