Convert Labels To Annotation (Cartography)

Summary

Converts labels to annotation for a single layer or the entire map. Both standard annotation and feature-linked annotation can be created.

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 map 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 Labeling tab in ArcGIS Pro.

• Annotation feature classes will not be overwritten if an existing suffix is specified. In this case, a number will be added to the annotation feature class suffix (for example, CitiesAnno, CitiesAnno_1, and so on). The complete format for naming is as follows:

  <layer name> <duplicate feature class count> <anno suffix> <running number>

• If you are producing annotation at a variety of reference scales, design the map for each of those scales and avoid setting a reference scale in the map. You can then convert the labels to annotation for each scale and name them appropriately, for example, CitiesAnno_1000, CitiesAnno_100000, and so on.

• One output of this tool is a group layer. When working in the Catalog pane, the Python window, or a stand-alone Python script, you can use the Save To Layer File tool to write the output group layer to a layer file. When using ArcGIS Pro, the tool adds the group layer to the display. The group layer that is created is temporary and will not persist after the session ends unless the project is saved.

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

• 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.

• Feature-linked annotation is associated with a specific feature in another feature class in the geodatabase. If the Create feature-linked annotation parameter is checked, a relationship class will be automatically generated when you create the output annotation feature class.

• 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 display on the map because there is no room. To convert these labels, check the Convert unplaced labels to unplaced annotation parameter. This saves the unplaced labels in the annotation feature class, allowing you to position them later in an ArcGIS Pro edit session.

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

• This tool honors the Annotation Text String Field Length environment. When set, it will override the default field length on the TextString field in any annotation feature classes created in a database.

Parameters

Dialog

Label	Explanation	Data Type
Input Map	The input map.	Map
Conversion Scale	The scale at which labels will be converted. If a reference scale is set on the map, the reference scale will be used for symbol sizing and annotation feature class creation, but conversion will occur at this scale.	Double
Output Geodatabase	The workspace where the output feature classes will be saved. The workspace can be an existing geodatabase or an existing feature dataset. If this is not the same database used by all the layers in the map, the feature-linked option will be disabled.	Workspace; Feature Dataset
Annotation Suffix (Optional)	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.	String
Extent (Optional)	Specifies the extent that contains the labels to convert to annotation. Current Display Extent —The extent will be based on the active map or scene. This option is only available when there is an active map. Draw Extent —The extent will be based on a rectangle drawn on the map or scene. This option will create a feature class in the project geodatabase and add a layer to the map. The feature class will have the same coordinate system as the map. Note: This option is not available in the Environments dialog box. It is only available from a tool parameter with an extent data type or from the Environments tab on a tool dialog box. Note: When the Enable and disable editing from the Edit tab editing option is checked, you must enable editing on the Edit ribbon tab to draw the extent. Extent of a Layer —The extent will be based on an active map layer. Use the drop-down list to choose an available layer or use the Extent of data in all layers option to get the combined extent of all active map layers, excluding the basemap. This option is only available when there is an active map with layers. Each map layer has the following options: All Features —The extent of all features in the layer. Selected Features —The extent of the selected features in the layer. Visible Features —The extent of visible features in the layer. Note: The extents from the Selected Features and Visible Features options are only available for feature layers. Browse —The extent will be based on an existing dataset. Intersection of Inputs —The extent will be based on the minimum or intersecting extent of all inputs. If no inputs overlap, a null extent with all zeros will result. Union of Inputs —The extent will be based on the maximum or combined extent of all inputs. Clipboard —The extent can be copied to and from the clipboard. Copy Extent —Copies the extent coordinates and coordinate system to the clipboard. Paste Extent —Pastes the extent coordinates and, optionally, the coordinate system from the clipboard. If the clipboard values do not include a coordinate system, the extent will use the map’s coordinate system. Note: The extent coordinates are copied to and pasted from the clipboard using the same formatting and order as the ArcPy Extent object: x-min, y-min, x-max, y-max, and the spatial reference. Reset Extent —The extent will be reset to the default value. Manually entered coordinates—The coordinates must be numeric values and in the active map's coordinate system. Caution: The map may use different display units than the entered coordinates. The use of a cardinal direction (N, S, E, W) is not supported. Use a negative value sign for south and west coordinates.	Extent
Convert unplaced labels to unplaced annotation (Optional)	Specifies whether unplaced annotation will be created from unplaced labels. Unchecked—Annotation will only be created for features that are currently labeled. This is the default. Checked—Unplaced annotation will be stored in the annotation feature class. The status field for this annotation is set to Unplaced.	Boolean
Require symbols to be selected from the symbol table (Optional)	Specifies whether all text symbol properties can be edited. Unchecked—All text symbol properties can be edited. This is the default. Checked—Only symbol properties that enable annotation features can be edited to maintain reference to their associated text symbol in the collection.	Boolean
Create feature-linked annotation (Optional)	Specifies whether the output annotation feature class will be linked to the features in another feature class. Unchecked—The output annotation feature class will not be linked to the features in another feature class. This is the default. Checked—The output annotation feature class will be linked to the features in another feature class.	Boolean
Create annotation when new features are added (Optional)	Specifies whether annotation will be created when new features are added to the linked feature class and the Create feature-linked annotation parameter is checked. Checked—Feature-linked annotation will be created when new features are added to the linked feature class. This is the default. Unchecked—Feature-linked annotation will not be created when new features are added to the linked feature class.	Boolean
Update annotation when feature's shape is modified (Optional)	Specifies whether the position of annotation will be updated when the shape of the linked feature is modified and the Create feature-linked annotation parameter is checked. Checked—The position of the annotation will be updated when the shape of the linked feature is modified. This is the default. Unchecked—The position of the annotation will not be updated when the shape of the linked feature is modified.	Boolean
Output Layer (Optional)	The group layer that will contain the generated annotation. When working in the Catalog pane, you can use the Save To Layer File tool to write the output group layer to a layer file. When using ArcGIS Pro with a map open, the tool adds the group layer to the display if this option is checked in the geoprocessing options. The group layer that is created is temporary and will not persist after the session ends unless the project is saved.	Group Layer
Convert (Optional)	Specifies whether annotation will be converted for all layers in the map or for a single layer. The single layer must be specified. All layers in map—Labels will be converted to annotation for all layers in the map. This is the default. Single layer—Labels will be converted to annotation for a single layer. The layer must be specified.	String
Feature Layer (Optional)	The layer with the annotation that will be converted when the Convert parameter is set to Single layer. This layer must be in the map.	Feature Layer
Convert labels from all layers to a single output feature class (Optional)	Specifies whether labels will be converted to individual annotation feature classes or to a single annotation feature class. If converting to a single annotation feature class, the annotation cannot be feature-linked. Checked—Labels from all layers will be converted to a single annotation feature class. Unchecked—Labels will be converted to individual annotation feature classes that correspond to their layers. This is the default.	Boolean
Merge similar label classes (Optional)	Specifies whether similar label classes will be merged when the Convert labels from all layers to a single output feature class parameter is checked. Checked—Label classes with similar properties will be merged when converting to a single feature class. Unchecked—Label classes with similar properties will not be merged. This is the default.	Boolean

Derived Output

Label	Explanation	Data Type
Updated Geodatabase	The workspace where the output feature classes will be saved.	Workspace

Python

arcpy.cartography.ConvertLabelsToAnnotation(input_map, conversion_scale, output_geodatabase, {anno_suffix}, {extent}, {generate_unplaced}, {require_symbol_id}, {feature_linked}, {auto_create}, {update_on_shape_change}, {output_group_layer}, {which_layers}, {single_layer}, {multiple_feature_classes}, {merge_label_classes})

Name	Explanation	Data Type
input_map	The input map.	Map
conversion_scale	The scale at which labels will be converted. If a reference scale is set on the map, the reference scale will be used for symbol sizing and annotation feature class creation, but conversion will occur at this scale.	Double
output_geodatabase	The workspace where the output feature classes will be saved. The workspace can be an existing geodatabase or an existing feature dataset. If this is not the same database used by all the layers in the map, the feature-linked option will be disabled.	Workspace; Feature Dataset
anno_suffix (Optional)	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.	String
extent (Optional)	Specifies the extent that contains the labels to convert to annotation. MAXOF—The maximum extent of all inputs will be used. MINOF—The minimum area common to all inputs will be used. DISPLAY—The extent is equal to the visible display. Layer name—The extent of the specified layer will be used. Extent object—The extent of the specified object will be used. Space delimited string of coordinates—The extent of the specified string will be used. Coordinates are expressed in the order of x-min, y-min, x-max, y-max. If no extent value is set, the extent will be based on the maximum extent of all participating inputs. This is the default.	Extent
generate_unplaced (Optional)	Specifies whether unplaced annotation will be created from unplaced labels. ONLY_PLACED—Annotation will only be created for features that are currently labeled. This is the default. GENERATE_UNPLACED—Unplaced annotation will be stored in the annotation feature class. The status field for this annotation is set to Unplaced.	Boolean
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 can be edited to maintain reference to their associated text symbol in the collection.	Boolean
feature_linked (Optional)	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
auto_create (Optional)	Specifies whether annotation will be created when new features are added to the linked feature class and 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 modified and 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
output_group_layer (Optional)	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
which_layers (Optional)	Specifies whether annotation will be converted 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 all layers in the 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 with the annotation that will be converted when the which_layers parameter is set to SINGLE_LAYER. This layer must be in the map.	Feature Layer
multiple_feature_classes (Optional)	Specifies whether labels will be converted to individual annotation feature classes or to 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 when the multiple_feature_classes parameter is set to SINGLE_FEATURE_CLASS. MERGE_LABEL_CLASS—Label classes with similar properties will be merged when converting to a single feature class. NO_MERGE_LABEL_CLASS—Label classes with similar properties will not be merged. This is the default.	Boolean

Derived Output

Name	Explanation	Data Type
updated_geodatabase	The workspace where the output feature classes will be saved.	Workspace

Code sample

ConvertLabelsToAnnotation example (Python window)

This Python sample for the ConvertLabelsToAnnotation function converts labels to annotation for a single layer in the map.

import arcpy
arcpy.cartography.ConvertLabelsToAnnotation(
    'Map1', 10000, 'D:/data/Cobourg.gdb', 'Anno', 'MAXOF', 'ONLY_PLACED', 
    'REQUIRE_ID', 'STANDARD', '', '', 'AnnoLayer', 'SINGLE_LAYER', 'Schools')

ConvertLabelsToAnnotation example 2 (stand-alone script)

This stand-alone script converts labels to annotation for the map using the ConvertLabelsToAnnotation function. The annotation will be converted to a single annotation feature class and similar label classes will be merged.

# Name: ConvertLabelsToAnnotation.py
# Description: Find all the maps in the project and
#              convert labels to annotation for each map

# import system modules

import arcpy

# Loop through the project, find all the maps, and
#   convert labels to annotation for each map,
#   using the name of the map as part of the annotation suffix 
project = arcpy.mp.ArcGISProject("D:\\data\\myproject.aprx")
for mp in project.listMaps():
    print("Converting labels to annotation for: " + mp.name)
    arcpy.cartography.ConvertLabelsToAnnotation(
            mp, 10000, 'D:/data/Cobourg.gdb', 'Anno_' + mp.name, 'MAXOF', 
            'ONLY_PLACED', 'REQUIRE_ID', 'STANDARD', '', '', 
            'AnnoLayers_' + mp.name, 'ALL_LAYERS', '', 'SINGLE_FEATURE_CLASS', 
            'MERGE_LABEL_CLASS')

Environments

Output CONFIG Keyword, Annotation Text String Field Length

Licensing information

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