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