Convert Labels To Graphics (Cartography)

Summary

Converts labels to graphics for a single layer or an entire map.

Usage

• Labels can be converted to graphics 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 graphics 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.

• The format for the naming of the graphics layers is <layer name><graphics layer suffix>.

  Duplicate graphics layer names will not be overwritten.

• One output of this tool is a group layer. You can use the Save To Layer File tool to write the output group layer to a layer file. When using the tool in 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 the Allow geoprocessing tools to overwrite existing datasets option is checked in the geoprocessing options.

• The Convert labels from all layers to a single output graphics layer parameter can be used to create a single graphics layer for the entire map.

• Some labels may not display on the map because there is no room. Check the Convert unplaced labels to graphics parameter check box to save the unplaced labels in the graphics layer, allowing you to make them visible and position them later.

Parameters

Dialog

Label	Explanation	Data Type
Input Map	The input map name.	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 graphics layer creation, but conversion will happen at this scale.	Double
Convert (Optional)	Specifies whether to convert graphics for all layers in the map or for a single layer. All layers in map —Labels will be converted to graphics for all layers in the map. This is the default. Single layer —Labels will be converted to graphics for a single layer. The layer must be specified in the Feature Layer parameter (single_layer in Python).	String
Feature Layer (Optional)	The layer with the labels to convert when the Convert parameter is set to Single layer. This layer must be in the map.	Feature Layer
Graphics Layer Suffix (Optional)	The suffix that will be added to each new graphics layer. This suffix will be appended to the name of the source feature class for each new graphics layer.	String
Extent (Optional)	Specifies the extent that contains the labels to convert to graphics. Default—The extent will be based on the maximum extent of all participating inputs. This is the default. Union of Inputs—The extent will be based on the maximum extent of all inputs. Intersection of Inputs—The extent will be based on the minimum area common to all inputs. Current Display Extent—The extent is equal to the visible display. The option is not available when there is no active map. As Specified Below—The extent will be based on the minimum and maximum extent values specified. Browse—The extent will be based on an existing dataset.	Extent
Convert labels from all layers to a single output graphics layer (Optional)	Specifies whether labels will be converted to individual graphics layers or to a single graphics layer. Checked—Labels from all layers will be converted to a single graphics layer. Unchecked—Labels will be converted to individual graphics layers that correspond to their layers. This is the default.	Boolean
Convert unplaced labels to graphics (Optional)	Specifies whether graphics will be created from unplaced labels. Unchecked—Graphics will only be created for features that are currently labeled. This is the default. Checked—Unplaced graphics are stored in the graphics layer with their visibility is turned off.	Boolean
Output Layer (Optional)	The group layer that will contain the generated graphics. 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 the Add output dataset to an open map 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

Python

arcpy.cartography.ConvertLabelsToGraphics(input_map, conversion_scale, {which_layers}, {single_layer}, {graphics_suffix}, {extent}, {multiple_graphics_layers}, {generate_unplaced}, {output_group_layer})

Name	Explanation	Data Type
input_map	The input map object.	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 graphics layer creation, but conversion will happen at this scale.	Double
which_layers (Optional)	Specifies whether to convert graphics for all layers in the map or for a single layer. ALL_LAYERS —Labels will be converted to graphics for all layers in the map. This is the default. SINGLE_LAYER —Labels will be converted to graphics for a single layer. The layer must be specified in the Feature Layer parameter (single_layer in Python).	String
single_layer (Optional)	The layer with the labels to convert when the which_layers parameter is set to SINGLE_LAYER. This layer must be in the map.	Feature Layer
graphics_suffix (Optional)	The suffix that will be added to each new graphics layer. This suffix will be appended to the name of the source feature class for each new graphics layer.	String
extent (Optional)	Specifies the extent that contains the labels to convert to graphics. 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.	Extent
multiple_graphics_layers (Optional)	Specifies whether labels will be converted to individual graphics layers or to a single graphics layer. SINGLE_GRAPHICS_LAYER —Labels from all layers will be converted to a single graphics layer. GRAPHICS_LAYER_PER_FEATURE_LAYER —Labels will be converted to individual graphics layers that correspond to their layers. This is the default.	Boolean
generate_unplaced (Optional)	Specifies whether graphics will be created from unplaced labels. ONLY_PLACED —Graphics will only be created for features that are currently labeled. This is the default. GENERATE_UNPLACED —Unplaced graphics are stored in the graphics layer with their visibility is turned off.	Boolean
output_group_layer (Optional)	The group layer that will contain the generated graphics. You can use the Save To Layer File tool to write the output group layer to a layer file.	Group Layer

Code sample

ConvertLabelsToGraphics example (Python window)

Python sample for the ConvertLabelsToGraphics function that converts labels to graphics for a single layer in the map.

import arcpy
arcpy.cartography.ConvertLabelsToGraphics(
    'Map1', 10000, 'SINGLE_LAYER', 'Schools', 'Graphics', 'MAXOF', 
    'GRAPHICS_LAYER_PER_FEATURE_LAYER', 'ONLY_PLACED', 'GroupGraphics')

ConvertLabelsToGraphics example 2 (stand-alone script)

Stand-alone script that converts labels to graphics for the map using the ConvertLabelsToGraphics function.

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

# import system modules

import arcpy

# Loop through the project, find all the maps, and
#   convert labels to graphics for each map,
#   using the name of the map as part of the graphics layer suffix 
project = arcpy.mp.ArcGISProject("D:\\data\\myproject.aprx")
for mp in project.listMaps():
    print("Converting labels to graphics for: " + mp.name)
    arcpy.cartography.ConvertLabelsToGraphics(
            mp, 10000, 'ALL_LAYERS', '', 'Graphics_' + mp.name, 'MAXOF', 
            'GRAPHICS_LAYER_PER_FEATURE_LAYER', 'ONLY_PLACED',  
            'GraphicsLayers_' + mp.name)

Environments

This tool does not use any geoprocessing environments.

Licensing information

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