Tiled Labels To Annotation (Cartography)

Summary

Converts labels to annotation for layers in a map based on a polygon index layer.

The tool divides a map into tiles and creates annotation for each tile in turn. This is useful for converting a large number of labels to annotation. The polygon index layer can be generated by the Map Server Cache Tiling Scheme To Polygons or Grid Index Features tool or any other polygon feature class that covers the area where you want to create annotation.

Usage

• Labels can be converted to annotation for a single layer or the entire map. If the single layer option is chosen, the layer must be specified, and it must be in the map.

• Label class scale ranges are respected. When the tool generates annotation for a specific reference scale, it will only convert label classes that are turned on and visible at that scale.

  Note:

  Label class scale ranges are set on the layer's properties in ArcGIS Pro. Once you have configured your label properties, save the project before running this tool.

• If you select tiles prior to running the tool, annotation will only be created for the selected tiles.

• To update annotation for only some tiles in the polygon index layer, first select the annotation features with that specific TileID value and delete them. Then select the polygon features and run the tool again.

• One output of this tool is a series of group layers. One group layer will contain a group layer for each reference scale for which annotation was created.

• When working in the Catalog pane or ModelBuilder, you can use the Save To Layer File tool to write the output group layer to a layer file.

• An existing group layer will be overwritten if the same layer name is specified and if you explicitly state that overwriting outputs is allowed.

• If duplicate feature class names are found in the map, a number will be added to the annotation following the feature class name (for example, Cities01Anno10000, Cities02Anno10000, and so on).

• Annotation feature classes will not be overwritten if a suffix is specified that already exists. In this case, a number will be added to the annotation feature class suffix (for example, CitiesAnno10000, CitiesAnno10000_1, and so on).

• The reference scale for the annotation feature classes can be specified in one of the following two ways:

  • The first option is to use a field from the polygon index layer to determine the reference scale of the output annotation feature classes. Use this option if you will create annotation for a variety of scale levels.
  • The second option is to explicitly state a reference scale value. All annotation feature classes will use this reference scale. If a reference scale is set in the map, this will be the default value input into the tool. If no reference scale is set in the map, the current scale will provide the default value.

• If you are using a polygon index layer that was created by the Map Server Cache Tiling Scheme To Polygons tool, use the Tile_Scale field for the Reference Scale Field parameter. A new annotation feature class will be created for each layer-Tile_Scale combination.

• If you are producing annotation at a variety of reference scales, design your map for each of those scales and avoid setting a reference scale.

• If a coordinate system field from the polygon index layer is provided, the annotation for each tile will be projected into that coordinate system for the purpose of drawing and placement.

• If the Create feature-linked annotation parameter is not checked, the Convert labels from all layers to a single output feature class parameter can be used to create a single annotation feature class for the entire map.

  When creating a single annotation feature class for the map, label classes with similar properties can be merged into one annotation class using the Merge similar label classes parameter.

• Annotation that is feature linked is associated with a specific feature in another feature class in the geodatabase. If checked, when you create the output annotation feature class, a relationship class will be automatically generated as well.

• When creating feature-linked annotation, the output workspace must be the same as that of the feature classes to which they are linked.

• Some labels may not currently display on the map because there is no room for them. To convert these labels, check the Generate Unplaced Annotation check box. This saves the unplaced labels in the annotation feature class, allowing you to position them later in an edit session.

• Memory and in_memory workspaces do not support feature-linked annotation.

Syntax

arcpy.cartography.TiledLabelsToAnnotation(input_map, polygon_index_layer, out_geodatabase, out_layer, anno_suffix, {reference_scale_value}, {reference_scale_field}, {tile_id_field}, {coordinate_sys_field}, {map_rotation_field}, {feature_linked}, {generate_unplaced_annotation}, {which_layers}, {single_layer}, {require_symbol_id}, {auto_create}, {update_on_shape_change}, {multiple_feature_classes}, {merge_label_classes})

Parameter	Explanation	Data Type
input_map	The map that contains the labels to convert to annotation.	Map
polygon_index_layer	The polygon layer that contains tile features.	Table View
out_geodatabase	The workspace where the output feature classes will be saved. The workspace can be an existing geodatabase or an existing feature dataset.	Workspace; Feature Dataset
out_layer	The group layer that will contain the generated annotation. You can use the Save To Layer File tool to write the output group layer to a layer file.	Group Layer
anno_suffix	The suffix that will be added to each new annotation feature class. This suffix will be appended to the name of the source feature class for each new annotation feature class. The reference scale for the annotation will follow this suffix.	String
reference_scale_value (Optional)	The scale value that will be used as a reference for the annotation. This is the scale on which all symbol and text sizes in the annotation will be based.	Double
reference_scale_field (Optional)	The field in the polygon index layer that will determine the reference scale of the annotation. This is the scale on which all symbol and text sizes in the annotation will be based.	Field
tile_id_field (Optional)	A field in the polygon index layer that uniquely identifies the tiled area. These values will populate the TileID field in the annotation feature class attribute table.	Field
coordinate_sys_field (Optional)	A field in the polygon index layer that contains the coordinate system information for each tile. Due to the length required for a field to store coordinate system information, a polygon index layer that contains a coordinate system field must be a geodatabase feature class.	Field
map_rotation_field (Optional)	A field in the polygon index layer that contains an angle by which the data frame is to be rotated.	Field
feature_linked (Optional)	License: This parameter is only available with ArcGIS Desktop Standard and ArcGIS Desktop Advanced licenses. Specifies whether the output annotation feature class will be linked to the features in another feature class. STANDARD — The output annotation feature class will not be linked to the features in another feature class. This is the default. FEATURE_LINKED —The output annotation feature class will be linked to the features in another feature class.	Boolean
generate_unplaced_annotation (Optional)	Specifies whether unplaced annotation will be created from unplaced labels. NOT_GENERATE_UNPLACED_ANNOTATION —Annotation will only be created for features that are currently labeled. This is the default. GENERATE_UNPLACED_ANNOTATION —Unplaced annotation is stored in the annotation feature class. The status field for these annotation is set to Unplaced.	Boolean
which_layers (Optional)	Specifies whether annotation will be created for all layers in the map or for a single layer. The single layer must be specified. ALL_LAYERS —Labels will be converted to annotation for the entire map. This is the default. SINGLE_LAYER —Labels will be converted to annotation for a single layer. The layer must be specified.	String
single_layer (Optional)	The layer that will be converted when the which_layers parameter is set to SINGLE_LAYER. This layer must be in the map.	Feature Layer
require_symbol_id (Optional)	Specifies whether all text symbol properties can be edited. NO_REQUIRE_ID —All text symbol properties can be edited. This is the default. REQUIRE_ID —Only symbol properties that enable annotation features to maintain reference to their associated text symbol in the collection can be edited.	Boolean
auto_create (Optional)	Specifies whether annotation will be created when new features are added to the linked feature class if the feature_linked parameter is set to FEATURE_LINKED. AUTO_CREATE —Feature-linked annotation will be created when new features are added to the linked feature class. This is the default. NO_AUTO_CREATE —Feature-linked annotation will not be created when new features are added to the linked feature class.	Boolean
update_on_shape_change (Optional)	Specifies whether the position of annotation will be updated when the shape of the linked feature is updated if the feature_linked parameter is set to FEATURE_LINKED. SHAPE_UPDATE —The position of the annotation will be updated when the shape of the linked feature is modified. This is the default. NO_SHAPE_UPDATE —The position of the annotation will not be updated when the shape of the linked feature is modified.	Boolean
multiple_feature_classes (Optional)	Specifies whether labels will be converted to individual annotation feature classes or a single annotation feature class. If converting to a single annotation feature class, the annotation cannot be feature-linked. SINGLE_FEATURE_CLASS —Labels from all layers will be converted to a single annotation feature class. FEATURE_CLASS_PER_FEATURE_LAYER —Labels will be converted to individual annotation feature classes that correspond to their layers. This is the default.	Boolean
merge_label_classes (Optional)	Specifies whether similar label classes will be merged if the multiple_feature_classes parameter is set to SINGLE_FEATURE_CLASS. MERGE_LABEL_CLASS —Label classes with similar properties will be merged when creating a single feature class. NO_MERGE_LABEL_CLASS —Label classes will not be merged. This is the default.	Boolean

Derived Output

Name	Explanation	Data Type
out_workspace	The workspace where the output feature classes will be saved.	Workspace; Feature Dataset

Code sample

TiledLabelsToAnnotation example (Python window)

Python sample for TiledLabelsToAnnotation that converts labels to annotation for a single layer in a map based on a polygon index layer.

import arcpy
arcpy.env.workspace = "C:/data/data.gdb"
arcpy.TiledLabelsToAnnotation_cartography("Map1", "Tiles", "data.gdb", 
                                          "GroupAnno", "Anno", "", "Tile_Scale",  
                                          "OID", "", "", "FEATURE_LINKED", 
                                          "GENERATE_UNPLACED_ANNOTATION", 
                                          "SINGLE_LAYER", "Towns", 
																																										"REQUIRE_ID", "AUTO_CREATE", 
                                          "SHAPE_UPDATE", "", "")

TiledLabelsToAnnotation example 2 (workflow script)

The following script demonstrates a workflow using the MapServerCacheTilingSchemeToPolygons and TiledLabelsToAnnotation functions.

# Name: TiledLabelsToAnnotation_Example2.py
# Description: Create a tile feature class and use those tiles to create annotation.
# Requirements: ArcGIS Desktop Advanced license

# Import system modules
import arcpy
import os

# Set environment settings
arcpy.env.workspace = "C:/data/data.gdb"

# Set local variables
aprx = arcpy.mp.ArcGISProject(r"C:/data/Annotation.aprx")
inMap = aprx.listMaps("Map")[0]
inTilingScheme = os.path.join(
    arcpy.GetInstallInfo()['InstallDir'], 
    'Resources\\TilingSchemes\\ArcGIS_Online_Bing_Maps_Google_Maps.xml')
outFeatureClass = "C:/data/data.gdb/Tiles"
inTileExtent = "USE_MAP_EXTENT"
inClipping = "CLIP_TO_HORIZON"
inAntialiasing = "NONE"
inScales = ""

# Execute MapServerCacheTilingSchemeToPolygons
arcpy.MapServerCacheTilingSchemeToPolygons_cartography(
    inMap, inTilingScheme, outFeatureClass, inTileExtent, inClipping, 
    inAntialiasing, inScales)

# Set local variables
inPolygonIndexLayer = "Tiles"
inOutGeodatabase = "C:/data/data.gdb"
outOutLayer = "GroupAnno"
inAnnoSuffix = "Anno"
inRefScaleValue = ""
inRefScaleField = "Tile_Scale"
inTileIDField = "OID"
inCoordSysField = ""
inMapRotationField = ""
inFeatureLinked = "STANDARD"
inGenerateUnplaced = "GENERATE_UNPLACED_ANNOTATION"
inWhichLayers = "ALL_LAYERS"
inSingleLayer = ""
inRequireSymbolID = ""
inAutoCreate = ""
inUpdateOnShapeChange = ""
inMultipleFeatureClasses = "SINGLE_FEATURE_CLASS"
inMergeFeatureClasses = "MERGE_LABEL_CLASS"
 
# Execute TiledLabelsToAnnotation
arcpy.TiledLabelsToAnnotation_cartography(
    inMap, inPolygonIndexLayer, inOutGeodatabase, outOutLayer, inAnnoSuffix, 
    inRefScaleValue, inRefScaleField, inTileIDField, inCoordSysField, 
    inMapRotationField, inFeatureLinked, inGenerateUnplaced, inWhichLayers, 
    inSingleLayer, inRequireSymbolID, inAutoCreate, inUpdateOnShapeChange, 
    inMultipleFeatureClasses, inMergeFeatureClasses)

Environments

Reference Scale

Licensing information

• Basic: Yes
• Standard: Yes
• Advanced: Yes