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 with the Feature Layer parameter.	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. Current Display Extent —The extent will be based on the active map or scene. Draw Extent —The extent will be based on a rectangle drawn on the map or scene. Extent of a Layer —The extent will be based on an active map layer. Choose an available layer or use the Extent of data in all layers option. Each map layer has the following options: All Features —The extent of all features. Selected Features —The extent of the selected features. Visible Features —The extent of visible features. Browse —The extent will be based on a dataset. Intersection of Inputs —The extent will be the intersecting extent of all inputs. Union of Inputs —The extent will be the combined extent of all inputs. Clipboard —The extent can be copied to and from the clipboard. Copy Extent —Copies the extent and coordinate system to the clipboard. Paste Extent —Pastes the extent and coordinate system from the clipboard. If the clipboard does not include a coordinate system, the extent will use the map’s coordinate system. Reset Extent —The extent will be reset to the default value. When coordinates are manually provided, the coordinates must be numeric values and in the active map's coordinate system. The map may use different display units than the provided coordinates. Use a negative value sign for south and west coordinates.	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 with the single_layer parameter.	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