When vector tiles are created, any labels enabled on the map layers are included in the tiles. However, the labeling capabilities of vector tiles include only a subset of those available in ArcGIS Pro. Labeling properties in ArcGIS Pro are converted where possible into corresponding properties in the vector tile specification. ArcGIS Pro supports two labeling engines, but the Maplex Label Engine results in more properties converted, as specified below.
Label classes
One or more label classes can be converted to vector tiles. The placement capabilities of vector tile clients are limited compared to the label engines in ArcGIS Pro. For instance, if two label classes for a point layer place labels with a preferred position at the upper right of the label, the label engines of ArcGIS Pro move the labels so they both appear.
For vector tiles, clients place only the label from the highest priority class in the specified position and drop the other because it conflicts. Therefore, it is recommended that features with more than one label class have distinct label positions to avoid conflicts and minimize dropped labels. In many cases, stacked text can also meet the needs of more than one label class. See the label stacking section below for more information.
Text symbol
The text symbol is converted to corresponding symbol properties in the vector tile specification. Font sizes are converted from points to pixels. Fonts are converted to optimized representations in the vector tile resources, and callouts are converted to sprites. For text symbols using scale-based label sizing, stops are created for the "text-size" property. If the size of the labels is limited to a size range, the "text-size" property will be applied with stops to get variations in size based on the values.
The following is an example for text symbols: "layout": {
"text-font": ["Tahoma Bold"],
"text-size": {
"stops": [[5, 13.3333], [15, 48]]
}
}
The Halo Symbol Color and Halo Size text symbol properties are converted to "text-halo-color" and "text-halo-size". The Halo Symbol Outline Width and Halo Symbol Outline Color text symbol properties are not supported in the vector tile specification and are ignored.
Text case specified as lowercase or all caps is applied to the feature's label text. Letter spacing is converted to "text-letter-spacing" with units converted to ems. Leader lines are not supported in vector tiles. Callout types with leader lines have only the background symbol represented. For instance, a balloon callout has the color and outline specified, but no leader line.
Vertical text specified as right-to-left with the Block Progression property is converted to text-writing mode with vertical as its value. This property is used for vertical placement of Asian text. Only labels containing at least one character from a range that supports vertical writing (for example, CJK characters) may be placed vertically.
The following text symbol properties are not supported in vector tile creation:
- Text symbol properties such as outline color, outline width, underline, strikethrough, text case for small caps, position adjustment, horizontal alignment, vertical alignment, and shadow
- Text symbol formatting properties such as word spacing, letter width, line spacing, flip angle, ligatures, kerning, draw glyphs as geometry, extrapolate baselines, glyph hinting, and compatibility mode
- Text symbol paragraph properties such as soft hyphens, indent first line, indent before, and indent after
- Text symbol internationalization properties such as text direction, glyph orientation, region language, and font encoding
Label expressions
Simple single-line or advanced label expressions in Arcade, VBScript, JScript, and Python languages are supported in vector tiles. SQL queries used to label a subset of features based on a field value are also supported. Label expressions are processed and stored as a property value in vector tiles with the property name of "_name". If more than one label class is being labeled, the property name will contain a number corresponding to label class order "_name1", "_name2", and so on.
Label formatting tags are not supported and are removed from the label text in the vector tiles.
Label stacking
Maplex labels can be configured to stack dynamically based on characters present in the label and space available on the map. Alternatively, Maplex labels can be configured to force stacking based on the presence of specified characters. Vector tiles do not support dynamic stacking but do support forced stacking. The vector tile creation process applies forced stacking to the text written to the name property of the feature being labeled.
Label abbreviation
Maplex labels can be configured to abbreviate dynamically based on text in the label and space available on the map. Alternatively, Maplex abbreviation dictionary entries using the Translate option are applied regardless of space. Vector tiles do not support dynamic abbreviations but do support translate abbreviations. The vector tile creation process applies translate abbreviations to the text written to the name property of the feature being labeled.
Label placement
The following label placement options are available:
Point placement
Vector tile creation sets the label position, "text-anchor", based on the default position specified in the label placement properties. If using a fixed placement style in Maplex or the Standard Label Engine, placement is matched. If using a "Best Position" style placement, the highest ranked position is specified as the location in vector tiles. The label is offset from the feature using the "text-offset" property, which considers symbol size and specified offset in label placement. If rotation is applied to the text, the rotation value is set for the "text-rotate" property. If the text is rotated using a rotation field or expression, the rotation field plus any additional rotation is set for the "text-rotate" property. If the label settings of the map are configured to rotate labels when the map is rotated, this setting is honored for point labels using the "text-rotation-alignment" property set to "map", and the "text-keep-upright" property set to false.
The following is an example demonstrating a point layer's
labeling properties for text placed directly on top of a point
(anchor at the bottom):"id": "U.S. Cities",
"type": "symbol",
"source": "esri",
"source-layer": "U.S. Cities",
"layout": {
"icon-image": "U.S. Cities",
"icon-allow-overlap": true,
"text-font": ["Tahoma Regular"],
"text-size": 13.3333,
"text-anchor": "bottom",
"text-offset": [0, 0.065],
"text-field": "{_name}",
"text-optional": true
}
Line placement
Only regular curved placement and centered horizontal placement are possible for line labels in vector tiles. All other line placement styles are converted to regular curved placement. Offset label placements on lines are converted to vector tiles if the offset is constrained to a single side of the line. An offset value is applied to move the text to the correct side. Note that curved labels are typically placed as straight text if the segment is straight. The vector tile creation process creates secondary line geometries to smooth curved placement. Secondary point geometries are created for centered horizontal placement.
The following is an example of line placement on the line:"id": "U.S. National Transportation Atlas Interstate Highways/label/Class 1",
"type": "symbol",
"source": "esri",
"source-layer": "U.S. National Transportation Atlas Interstate Highways/label",
"layout": {
"symbol-placement": "line",
"symbol-spacing": 1000,
"text-font": ["Tahoma Regular"],
"text-size": 13.3333,
"text-field": "{_name}",
"text-optional": true
}
Polygon placement
Curved, horizontal, straight, and river placements are supported. River placement results in the same placement as curved placement. The vector tile creation process creates secondary geometries to label, if necessary, to match the placement style requested. For example, label placement options such as Straight in polygon and Curved in polygon result in point or line geometry being created to locate and orient labels properly within each polygon. If the label settings of the map are configured to rotate labels when the map is rotated, this setting is honored for polygon labels with the "text-rotation-alignment" style property set to "map", and the "text-keep-upright" property set to false.
For basic placement in the center of a polygon, no position properties are specified, as in the example below:"id": "U.S. Counties (Generalized)/label/Class 1",
"type": "symbol",
"source": "esri",
"source-layer": "U.S. Counties (Generalized)/label",
"layout": {
"text-font": ["Tahoma Regular"],
"text-size": 13.3333,
"text-field": "{_name}",
"text-optional": true
}
Conflict resolution
Maplex label placement has a variety of conflict resolution settings, but only two are supported for vector tiles.
For line labels, Repeat > Minimum interval is converted to the "symbol-spacing" property with units in pixels. Unplaced labels > Never remove, which allows overlapping labels when enabled, is converted to the "text-allow-overlap" property with a value of true.