Skip To Content

Convert Labels To Annotation

Summary

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

Usage

  • 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 a suffix is specified that already exists. 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 your 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 appropriately, for example, CitiesAnno_1000, CitiesAnno_100000.

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

  • Annotation that is feature-linked is associated with a specific feature in another feature class in the geodatabase. If the Create feature-linked annotation option is 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. To convert these labels, check the Convert unplaced labels to unplaced annotation check box. This saves the unplaced labels in the annotation feature class, allowing you to position them later in an ArcGIS Pro edit session.

Syntax

ConvertLabelsToAnnotation_cartography (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})
ParameterExplanationData Type
input_map

The input map.

Map
conversion_scale

The scale at which to convert labels. 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 happen 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 as 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)

The extent that contains the labels to convert to annotation. It can be the extent of the map, union of input layers, intersection of input layers, current display extent, same as specified layer extent, or it can be specified by value.

  • MAXOF—Union of inputs
  • MINOF—Intersection of inputs
  • DISPLAY—Same extent as current display
  • <Layer>—Same extent as specified layer
Extent
generate_unplaced
(Optional)

Choose whether to create unplaced annotation from unplaced labels.

  • ONLY_PLACEDAnnotation will only be created for features that are currently labeled. This is the default.
  • GENERATE_UNPLACEDUnplaced annotation are stored in the annotation feature class. The status field for these annotation is set to Unplaced.
Boolean
require_symbol_id
(Optional)

Choose whether to place a restriction on what text symbol properties can be edited.

  • NO_REQUIRE_IDAllow any text symbol property to be edited. This is the default.
  • REQUIRE_IDOnly allow edits to symbol properties that enable annotation features to maintain reference to their associated text symbol in the collection.
Boolean
feature_linked
(Optional)
License:

This parameter is only available with ArcGIS Desktop Standard and ArcGIS Desktop Advanced licenses.

Choose whether the output annotation feature class will be linked to the features in another feature class.

  • STANDARDThe output annotation feature class will not be linked to the features in another feature class. This is the default.
  • FEATURE_LINKEDThe output annotation feature class will be linked to the features in another feature class.
Boolean
auto_create
(Optional)

Choose whether to create annotation when new features are added to the linked feature class if the feature_linked parameter is set to FEATURE_LINKED.

  • AUTO_CREATEFeature-linked annotation will be created when new features are added to the linked feature class. This is the default.
  • NO_AUTO_CREATEFeature-linked annotation will not be created when new features are added to the linked feature class.
Boolean
update_on_shape_change
(Optional)

Choose whether to update the position of annotation when the shape of the linked feature is updated if the feature_linked parameter is set to FEATURE_LINKED.

  • SHAPE_UPDATEUpdate the position of the annotation when the shape of the linked feature is modified. This is the default.
  • NO_SHAPE_UPDATEAnnotation stays in its original position 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

Code sample

ConvertLabelsToAnnotation example (Python window)

Python sample for ConvertLabelsToAnnotation that converts labels to annotation for the map.

import arcpy
arcpy.cartography.ConvertLabelsToAnnotation('Map1', 10000, 'D:/data/Cobourg.gdb', 
                                            'Anno','MAXOF', 'ONLY_PLACED', 'REQUIRE_ID', 
                                            'STANDARD', '', '', 'AnnoLayers')
ConvertLabelsToAnnotation example 2 (stand-alone script)

Stand-alone script that converts labels to annotation for the map using the ConvertLabelsToAnnotation function.

# 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)

Licensing information

  • ArcGIS Desktop Basic: Yes
  • ArcGIS Desktop Standard: Yes
  • ArcGIS Desktop Advanced: Yes

Related topics