LabelOrganizingLayer Class
Represents a Layer that organizes visualizations generated by PointVisualizer instances so that they do not overlap.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECore assembly)
Syntax
public class LabelOrganizingLayer : LayerSetRemarks
A LabelOrganizingLayer attempts to organize/place a set of labels in a 2D View or 3D GlobeView to avoid overlap and, optionally, removes any conflicts that can not be resolved.
 |
In 2D a LabelOrganizingLayer can also place texts along lines, for example roads, while avoiding overlap with other labels. This can be used to make maps that look similar to printed cartographic maps.
 |
Which set of labels the layer attempts to organize and exactly how they are moved around is controlled by configuring and setting a LabelOrganizingSettings object on the visualizer that generates the visualization. Any other visualization will be drawn as if by a normal layer.
The term label is used in Carmenta Engine for historical reasons and refers to visualization generated by a SymbolVisualizer, TextVisualizer or PointVisualizerSet that have been configured with a LabelOrganizingSettings object.
More details can be found the article Automatic Label Placement and in the documentation for the LabelOrganizingSettings class.
A note about performance
Most labels that are organized in a LabelOrganizingLayer are static texts whose geographic location do not change. For example, names of cities, buildings and roads. To avoid unnecessary work when a user pans or zooms, or moves the camera in 3D, add a TileLayer (or GlobeTileLayer in 3D) as a child layer under a LabelOrganizingLayer, but not vice versa, and the labels will be organized incrementally as the tile layer loads data.
 |
A 3D GlobeView also adds a small hysteresis when the camera is moved before a reorganization is triggered. This is necessary to avoid reorganizing the whole screen for very small camera movements (any camera movement in 3D affects the whole screen while labels will remain still relative each other when panning a 2D map). This means that labels sometimes overlap by couple of pixels before the camera is moved far enough for a new reorganization to remove the conflicts. It is hard to detect because it usually only affects a small number of labels on the screen but it can be avoided altogether by adding a small amount of invisible background padding around the labels.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
Layer
LayerSet
LabelOrganizingLayer
Platforms
Windows, Linux, Android
LabelOrganizingLayer Members
The LabelOrganizingLayer type has the following members.
Constructors
| Name | Description |
|---|---|
| LabelOrganizingLayer | Initializes a new instance of the LabelOrganizingLayer class. |
Properties
| Name | Description |
|---|---|
| BlendMode | Gets or sets the blend mode that determines how the layer is combined with previously rendered layers. Inherited from Layer |
| Buffered | Gets or sets a value that determines whether the presentation between updates is buffered. |
| ClipPolygon | Gets or sets a MultiPolygonGeometry that all labels will be placed inside. |
| Condition | Gets or sets the Condition that determines whether the LabelOrganizingLayer is drawn or not. Inherited from Layer |
| CoverageHint | Gets or sets a value that can assert that the visualization is fully opaque within the data extent. Inherited from Layer |
| Description | Gets or sets a short description of the layer. Inherited from Layer |
| DisableOnError | Gets or sets a value specifying if an error within the layer should automatically disable the layer, or throw an exception. Inherited from Layer |
| DisplayName | Gets or sets a display name for the layer. Inherited from Layer |
| Effects | List of effects Inherited from Layer |
| Enabled | Determines whether the LabelOrganizingLayer is enabled or not. Inherited from Layer |
| EnabledDuringQuickUpdates | Determines whether the LabelOrganizingLayer is temporarily turned off during mouse interactions. Inherited from Layer |
| IsDisposed | Gets a value that tells whether the current LabelOrganizingLayer has been disposed. Inherited from EngineObject |
| IsoMetadataDocument | Gets or sets the path or URL to an ISO 19139 metadata document for the layer. Inherited from Layer |
| Layers | Gets the child layers of this LabelOrganizingLayer. Inherited from LayerSet |
| Legend | Gets or sets a map legend associated with this layer. Inherited from Layer |
| MaxScale | Gets or sets the highest inverted nominal scale in a 2D view, or the furthest distance in a 3D globe view, at which objects from this LabelOrganizingLayer should be drawn. Inherited from Layer |
| MinimumDuplicateDistance | Gets or sets the minimum distance between duplicate labels. |
| MinScale | Gets or sets the lowest inverted nominal scale this LabelOrganizingLayer should be drawn at. Inherited from Layer |
| Name | Gets or sets the name of the layer. Inherited from Layer |
| NamedStyles | Gets the list of named styles that can be enabled for the layer. Inherited from Layer |
| NativeHandle | Gets the native Carmenta Engine kernel object the current LabelOrganizingLayer represents. Inherited from EngineObject |
| Opacity | Gets or sets a value that specifies the opacity of the layer. Inherited from Layer |
| Organize | Gets or sets a value that determines whether the layer should organize labels. |
| Selectable | Gets or sets a value that determines whether features in this LabelOrganizingLayer can be selected. Inherited from Layer |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
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 |
| EnableStyle | Enables or disables a named style for the layer. Inherited from Layer |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |
| FindChildObject | Overloaded. Finds the child object with the specified name. Inherited from Layer |
| FlushCache | Marks the layer as flushed which will release cached resources during the next update. Inherited from Layer |
| GetChildObjects | Overloaded. Gets the child objects of the current object. Inherited from Layer |
| GetDataBounds | Calculates the bounds of all dataset coverages in the layer. Inherited from Layer |
| GetFeatureAttributes | Gets information about all attributes that may be present on features in this layer. Inherited from Layer |
| GetFeatures | Overloaded. Gets features from the layer and any child layers. Inherited from Layer |
| GetLastError | Gets the error message for the last error that occurred within the layer. Inherited from Layer |
| GetLocalizedDescription | Gets a localized version of the layer description in a specific language. Inherited from Layer |
| GetLocalizedDisplayName | Gets a localized version of the layer display name in a specific language. Inherited from Layer |
| GetLocalizedIsoMetadataDocument | Gets the path to an ISO 19139 metadata document for a specific language. Inherited from Layer |
| HasLocalizedDescription | Checks if a localized version of the layer description is available in a specific language. Inherited from Layer |
| HasLocalizedDisplayName | Checks if a localized version of the layer display name is available in a specific language. Inherited from Layer |
| HasLocalizedIsoMetadataDocument | Checks if an ISO 19139 metadata document is available for a specific language. Inherited from Layer |
| IsStyleEnabled | Checks if a certain style is enabled for the layer or not. Inherited from Layer |
| MoveLayer | Moves a child layer to a new position. Inherited from LayerSet |
| SetLocalizedDescription | Sets a layer description in a specific language. Inherited from Layer |
| SetLocalizedDisplayName | Sets a layer display name in a specific language. Inherited from Layer |
| SetLocalizedIsoMetadataDocument | Sets the path to an ISO 19139 metadata document for the layer, for a specific language. Inherited from Layer |
Events
| Name | Description |
|---|---|
| EnabledChanged | Occurs when the value of the Enabled property has changed. Inherited from Layer |