LabelOrganizingSettings Class
Specifies settings that controls the behavior of a LabelOrganizingLayer.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECore assembly)
Syntax
public class LabelOrganizingSettings : EngineObjectRemarks
The LabelOrganizingSettings class is used to control the automatic label placement of individual labels in a LabelOrganizingLayer.
To control a specific label, the visualization generated by a single PointVisualizer, add a LabelOrganizingSettings object with the options you want to the PointVisualizer.LabelOrganizingSettings property .
Visualization generated by PointVisualizer objects that do not have a LabelOrganizingSettings are ignored when a LabelOrganizingLayer organizes labels but they are still drawn as if by a normal layer.
Configuring label placement in 2D
Labels around points
Label candidates around a point, including visualizations generated at the center of very small polygons (see the section A label inside a polygon), are generated and tested in a deterministic order as demonstrated in the following picture.
 |
As can be seen in the picture candidates are generated in rings of eight around the default position, the filled black circle in the center, starting near the default position and going outwards. If Count is not evenly divisible by eight then the outermost ring will not be full.
The Dx and Dy properties determine the maximum distance, in pixels, from the default position to the candidates in the outermost ring.
Also note that the candidates are not generated in a strictly clock-wise order, instead candidates nearer the default position are generated and tested before candidates farther away.
Labels along lines
A PointVisualizer that is applied to a line feature can operate in two different ways:
It can generate a single label at one position along the line. This occurs when the PointVisualizer.Repeat property is set to No.
Or it can repeat a label along the line which happens when the PointVisualizer.Repeat property differs from No.
This is the normal operation of a PointVisualizer but the label placement algorithm will handle both of these cases differently as described in the following sections.
Both these sections are also relevant for text labels that follow a line, when TextVisualizer.FollowLine is True, but for clarity we use a simple horizontal line in the following examples.
A single label somewhere along a line
The label placement algorithm will take a visualization generated by a visualizer with the PointVisualizer.Repeat property is set to No to mean that it should attempt to place the label once somewhere along the line.
 |
One candidate, considered to be the original position, will be generated at the midpoint of the line. This candidate is shown in black in the image above. If Count is greater than zero then additional candidates will be generated evenly spread out along the line (shown in a lighter gray).
The label placement algorithm first attempts to place the label at the original position and if that fails it will try the other candidates starting with the ones near the original position and then farther and farther away. This makes the algorithm prefer positions near the midpoint of the line.
A label that is repeated along a line
When a PointVisualizer repeats a visualization along a line then the label placement algorithm will generate Count candidates around each original position.
 |
The image above shows a line where the label HWY 1 has been been repeated. The original positions, as determined by the values of the PointVisualizer.Repeat and PointVisualizer.At properties, are shown in black. If Count is greater than zero then additional candidates are generated around each original position (shown in a lighter gray). The distance, in pixels, between the additional candidates around one of the original positions is specified by the Dx property.
The label placement algorithm first attempts to place the labels at the original positions and if that fails it will try the other candidates surrounding each original position starting with the ones near the original position and then farther and farther away.
A label inside a polygon
For labels at the center of polygons, when PointVisualizer.AtCenter is True, up to Count candidates will be distributed inside the polygon. The following example shows how 16 candidate positions are generated for the Swedish island of Gotland, located in the Baltic Sea.
 |
As can be seen in the image above the candidates are generated in rings of eight around the default position, the filled black circle inside the polygon (the center position of the polygon). If Count is not evenly divisible by eight then the outer most ring will not be full.
The candidate positions are generated as follows:
Find up to eight positions at equal distances from each other along the polygon outline (the filled blue circles in the polygon outline above).
Shoot a ray from the center of the polygon to each position along the outline (the gray lines between the center and the outline).
Distribute the candidates evenly along the rays generated by the previous step (the filled gray circles).
Throw away any candidates located outside the polygon outline (this can happen due to the shape of the polygon). For example, in the example above candidate 10 will be thrown away.
Note that the Dx and Dy properties are not used when calculating candidate positions inside a polygon. However, if the size of the polygon on screen is very small and Dx or Dy are greater than zero, then candidates will be generated in the same manner as for a point feature which can result in candidate positions outside the polygon. If you want to ensure that only candidate positions inside the polygon are used when placing labels set both Dx and Dy to zero.
Removing labels that do not fit
The RemoveNonFitting property determines whether a label that is too long to fit along a line, or inside a polygon, is removed from the result. The tests are for performance reasons done against the geometries and not the visualization.
Avoiding other visualization
The automatic label placement will for performance reasons ignore overlap between labels and other visualization (although RemoveNonFitting can in many cases be used to good effect with a minimal performance hit). However, it is possible to make the label placement algorithm aware of other visualization and take it into consideration when placing labels.
 |
The image above demonstrates a line that is avoided by the label underneath and two polygons, one inside the other, where the label of the larger polygon is kept outside the smaller polygon to make it clear which label belongs to which polygon.
To accomplish this you first have to indicate which additional visualization the label placement algorithm should take into consideration when placing labels. This is done by setting LineVisualizer.AvoidableByLabels to True on the visualizers that generate the visualization you want labels to avoid. (It is also possible to avoid visualization generated by a PolygonVisualizer or CompositeLineVisualizer in the same way.)
Then you set the LabelAvoidance for each label to indicate which visualization should be avoided and, in the case of polygon labels, you can also set AvoidOtherPolygons to True to ensure that labels for large polygons are kept outside any smaller polygons.
Configuring label placement in 3D
Label placement in 3D is limited to avoiding overlap between billboard symbols (2D symbols like texts located at a 3D coordinate that are always oriented towards the camera).
Labels around points
In 3D only the default (original) position is considered during label placement. Additional candidate positions are not generated.
Removing labels far from the camera
The RemoveBeyondHorizon property determines whether labels located farther from the camera than the horizon are removed from the result before even checking whether they overlap another label.
Fine tuning label placement
Two other operations that influence the final result are removing conflicts and duplicates from the result. These are orthogonal concepts and can be enabled or disabled individually in both 2D and 3D views.
Removing conflicts
The RemoveConflicts property determines whether a label that cannot be placed without overlapping another label is removed from the result. This property is almost always used together with the Priority property which specifies the order in which labels are placed: a label with a high priority is placed before labels with a low priority and can therefore cause the low-priority labels to be removed from the result.
See also Extra conflict margin and Priority.
Removing duplicates
The RemoveDuplicates property determines whether a label that is a duplicate of a label that has already been placed, and if they lie within a specified minimum distance from each other, should be removed.
See also Removing duplicates.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
LabelOrganizingSettings
Platforms
Windows, Linux, Android
LabelOrganizingSettings Members
The LabelOrganizingSettings type has the following members.
Constructors
| Name | Description |
|---|---|
| LabelOrganizingSettings | Initializes a new instance of the LabelOrganizingSettings class. |
Properties
| Name | Description |
|---|---|
| AvoidOtherPolygons | Gets or sets a value that determines whether labels from large polygons should be placed outside smaller polygons. |
| Count | Gets or sets the number of additional candidate positions to generate for each label. |
| DuplicateAttribute | Gets or sets the attribute that is used to identify duplicate labels. |
| Dx | Gets or sets the number of pixels a label can be moved along the x-axis. |
| Dy | Gets or sets the number of pixels a label can be moved along the y-axis. |
| IsDisposed | Gets a value that tells whether the current LabelOrganizingSettings has been disposed. Inherited from EngineObject |
| LabelAvoidance | Gets or sets a value that indicates which visualization with extended label support the label can overlap. |
| MaximumTextCurvature | Gets or sets a value that influences how texts that follow lines are placed. |
| NativeHandle | Gets the native Carmenta Engine kernel object the current LabelOrganizingSettings represents. Inherited from EngineObject |
| Priority | Gets or sets a priority for the label placement algorithm. |
| RemoveBeyondHorizon | Gets or sets a value that determines whether a label that is located farther away than the horizon in a 3D GlobeView should be removed. |
| RemoveConflicts | Gets or sets a value that determines whether a label that cannot be placed without overlapping another label can be removed. |
| RemoveDuplicates | Gets or sets a value that determines whether a label that is a duplicate of another label should be removed. |
| RemoveNonFitting | Gets or sets a value that determines whether labels that do not fit along a line or inside a polygon should be removed. |
| RemoveOffScreen | Gets or sets a value that determines whether a label that is not entirely inside the view should be removed. |
Methods
| Name | Description |
|---|---|
| Clone | Creates a copy of an object. Inherited from EngineObject |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |