Map To KML (Conversion)

Summary

Converts a map containing feature or raster layers to KML format (.kmz file). The output KML will contain a translation of Esri feature geometries, raster cells, layer symbology, and other properties.

Learn more about KML support in ArcGIS

Usage

• The output .kmz file is an archive or .zip file containing a .kml file and other supplemental files. A .kmz file can be read by many applications including ArcGIS Earth and Google Earth.

• You can control the appearance of KML in the following two ways:

  • By default, the pop-up display is composed of all visible fields from the layer. Pop-up displays can also be set using the layer's customized pop-ups. If the layer pop-ups have not been customized, the values in the feature layer's PopupInfo field are shown in the pop-up when a KML feature is clicked. These values can be numeric or text attributes as well as HTML code stored in a text field.
  • When the layer properties are not set and the feature class contains certain attributes (fields), the field properties are used in creating the KML layers that were originally created using the KML To Layer tool including attributes that define how KML is created. See KML conversion for more information about creating KML from attributes.

• If the input has scale-dependent display properties, reduce the size of the output .kmz file by providing an appropriate Map Output Scale parameter value.

• The input map's layers will be projected to WGS84, as all .kmz files must use that coordinate system. To ensure that the projection locates features and raster cells accurately, you may need to specify the geographic transformation environment. Alternatively, use the Project tool to re-project the map's layers to WGS84 with a valid transformation before to converting to KML.

• The Map Output Scale and Size of Returned Image (Pixels) parameters are used together to create tiled output. For example, for an image with a size of 7000 by 5000 pixels, and a Size of Returned Image (Pixels) parameter value of 1000 pixels, the output image will be composed of 7 x 5, or 35, subimages. If the Map Output Scale parameter value is 1, each subimage will be 1000 by 1000 pixels. If the Map Output Scale parameter value is 10, each subimage will be 100 by 100 pixels.

• To include a legend in the output KML as a screen overlay, specify a value for the Legend Layout Source parameter. You must have a legend element in a layout in the map.

  Only legend elements will become screen overlays in KML. Each legend will become a subfolder under the main KML folder when viewing the KML data.

Parameters

Dialog

Label	Explanation	Data Type
Input Map	The map, scene, or basemap that will be converted to KML.	Map
Output File (KMZ)	The output KML file, which is compressed and has a .kmz extension.	File
Map Output Scale (Optional)	The scale at which each layer in the map will be exported. This parameter is important with any scale dependency, such as layer visibility or scale-dependent rendering. If the layer is not visible at the output scale, it is not included in the output KML. Any value, such as 1, can be used if there are no scale dependencies. For raster layers, a value of 0 can be used to create one untiled output image. If a value greater than or equal to 1 is used, it determines the output resolution of the raster. This parameter has no effect on layers that are not raster layers. Only numeric characters are accepted; for example, enter 20000 as the scale, not 1:20000. In languages that use commas as the decimal point, 20,000 is also acceptable. If you're exporting a layer that is to be displayed as 3D vectors and the Return single composite image parameter is checked, you can set this parameter to any value as long as the features do not have any scale-dependent rendering.	Double
Return single composite image (Optional)	Specifies whether the output KML will contain a single composite image or separate layers. Checked—The output KML will contain a single image that composites all the features in the map into a single raster image. The raster is draped over the terrain as a KML GroundOverlay. This option reduces the size of the output KML. Individual features and layers in the KML are not selectable. Unchecked—The output KML will contain separate, individual layers. This is the default. Whether the layers are returned as rasters or as a combination of vectors and rasters is determined by the Convert features to images parameter value.	Boolean
Convert features to images (Optional)	Specifies whether each feature layer in the map will be converted to a separate raster image or preserved as features. This parameter is not used if the Return single composite image parameter is checked. Checked—Feature layers will be converted to a separate raster image in the KML output. Normal raster layers are also added to the KML output. Each output KML raster layer is selectable, and its transparency can be adjusted in certain KML viewer applications. Unchecked—Features will be preserved in the output KML as feature geometries. This is the default.	Boolean
Extent (Optional)	The geographic extent of the layer to be converted. Only features or raster cells in this extent will be included in the output KML. 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 the 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. Clipboard —The extent can be copied to and pasted from the clipboard. Copy Extent —Copies the extent coordinates and coordinate system to the clipboard. Use 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
Size of Returned Image (Pixels) (Optional)	The size of the tiles for raster layers if the Map Output Scale parameter value is greater than or equal to 1. This parameter no effect on layers that are not raster layers.	Long
Output Image DPI (Optional)	The device resolution for any rasters in the output KML document. Typical screen resolution is 96 dpi. If the data in the map supports a high resolution and the KML requires it, consider increasing the value. Use this parameter with the Size of Returned Image (Pixels) parameter to control output image resolution. The default value is 96.	Long
Clamp features to ground (Optional)	Specifies whether the z-values of the input features will be ignored and all features will be located, or clamped, at the ground elevation. Checked—The z-values of the input features will be ignored and all features will be located, or clamped, at the ground elevation. If the input features do not have z-values, they will always be clamped to the ground. This is the default. Unchecked—The z-values of the features will be maintained in the output KML. The features will be drawn in KML clients relative to sea level.	Boolean
Legend Layout Source (Optional)	The name of the layout that contains legend elements that will be included in the KML output as screen overlays.	String

Python

arcpy.conversion.MapToKML(in_map, out_kmz_file, {map_output_scale}, {is_composite}, {is_vector_to_raster}, {extent_to_export}, {image_size}, {dpi_of_client}, {ignore_zvalue}, {layout})

Name	Explanation	Data Type
in_map	The map, scene, or basemap that will be converted to KML.	Map
out_kmz_file	The output KML file, which is compressed and has a .kmz extension.	File
map_output_scale (Optional)	The scale at which each layer in the map will be exported. This parameter is important with any scale dependency, such as layer visibility or scale-dependent rendering. If the layer is not visible at the output scale, it is not included in the output KML. Any value, such as 1, can be used if there are no scale dependencies. For raster layers, a value of 0 can be used to create one untiled output image. If a value greater than or equal to 1 is used, it determines the output resolution of the raster. This parameter has no effect on layers that are not raster layers. Only numeric characters are accepted; for example, enter 20000 as the scale, not 1:20000. In languages that use commas as the decimal point, 20,000 is also acceptable. If you're exporting a layer that is to be displayed as 3D vectors and the is_composite parameter is set to NO_COMPOSITE, you can set this parameter to any value as long as the features do not have any scale-dependent rendering.	Double
is_composite (Optional)	Specifies whether the output KML will contain a single composite image or separate layers. COMPOSITE—The output KML will contain a single image that composites all the features in the map into a single raster image. The raster is draped over the terrain as a KML GroundOverlay. This option reduces the size of the output KML. Individual features and layers in the KML are not selectable. NO_COMPOSITE—The output KML will contain separate, individual layers. This is the default. Whether the layers are returned as rasters or as a combination of vectors and rasters is determined by the is_vector_to_raster parameter value.	Boolean
is_vector_to_raster (Optional)	Specifies whether each feature layer in the map will be converted to a separate raster image or preserved as features. This parameter is not used if the is_composite parameter is set to COMPOSITE. VECTOR_TO_IMAGE—Feature layers will be converted to a separate raster image in the KML output. Normal raster layers are also added to the KML output. Each output KML raster layer is selectable, and its transparency can be adjusted in certain KML viewer applications. VECTOR_TO_VECTOR—Features will be preserved in the output KML as feature geometries. This is the default.	Boolean
extent_to_export (Optional)	The geographic extent of the layer to be converted. Only features or raster cells in this extent will be included in the output KML. The extent can be specified using the following options: 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
image_size (Optional)	The size of the tiles for raster layers if the map_output_scale parameter value is greater than or equal to 1. This parameter has no effect on layers that are not raster layers.	Long
dpi_of_client (Optional)	The device resolution for any rasters in the output KML document. Typical screen resolution is 96 dpi. If the data in the map supports a high resolution and the KML requires it, consider increasing the value. Use this parameter with the image_size parameter to control output image resolution. The default value is 96.	Long
ignore_zvalue (Optional)	Specifies whether the z-values of the input features will be ignored and all features will be located, or clamped, at the ground elevation. ABSOLUTE—The z-values of the features will be maintained in the output KML. The features will be drawn in KML clients relative to sea level. CLAMPED_TO_GROUND—The z-values of the input features will be ignored and all features will be located, or clamped, at the ground elevation. If the input features do not have z-values, they will always be clamped to the ground. This is the default.	Boolean
layout (Optional)	The name of the layout that contains legend elements that will be included in the KML output as screen overlays.	String

Code sample

MapToKML example 1 (Python window)

The following Python window script demonstrates how to use the MapToKML function in immediate mode.

import arcpy
arcpy.conversion.MapToKML("C:/Maps/Cities.mapx", "C:/OutputMaps/Cities.kmz")

MapToKML example 2 (stand-alone script)

The following Python script demonstrates how to use the MapToKML function in a stand-alone script.

# Import system modules
import arcpy

# Set environment settings
arcpy.env.workspace = "C:/data"

# Use ListFiles to identify all map files in workspace
files = arcpy.ListFiles('*.mapx') 
if len(files) > 0:
    for map_file in files:
        # Set Local Variables
        composite = 'NO_COMPOSITE'
        vector = 'VECTOR_TO_VECTOR'
        pixels = 2048
        dpi = 96
        clamped = 'ABSOLUTE'
        for scale in range(10000, 20000, 30000):
            # Strips the '.mapx' part of the name and appends '.kmz'
            outKML = map_file[:-5]+'.kmz'

            # Run MapToKML	
            arcpy.conversion.MapToKML(map_file, outKML, scale, composite, 
                                      vector, '', pixels, dpi, clamped)
else:
    arcpy.AddMessage('There are no map files (*.mapx) in {}.'.format(arcpy.env.workspace))

Environments

Current Workspace, Extent, Scratch Workspace, Maintain Attachments, Geographic Transformations

Licensing information

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