Contour Annotation (Cartography)

Summary

Creates annotation for contour features.

The tool creates an annotation feature class with corresponding mask polygons based on input contour features.

Usage

• The contours are labeled using the Contour placement style and the Centered straight placement position in the Maplex Label Engine.

  Learn more about labeling contours

• The output of this tool is a group layer. The group layer will contain the input contour features, the annotation layer, and the mask polygons.

• An existing group layer will be overwritten if the same layer name is specified and if you explicitly state that overwriting outputs is allowed.

• When working in the Catalog pane or in ModelBuilder, you can use the Save To Layer File tool to write the output group layer to a layer file.

• Annotation feature classes will not be overwritten if the tool is run multiple times on a single contour feature class. In this case, a number will be added to the annotation feature class name (for example, ContourAnno, ContourAnno_1, and so on).

• Each mask will be created with a two-point margin around the annotation feature and a mask type of exact simplified, meaning that the mask will be a generalized polygon representing the exact shape of the annotation.

• There are three choices for the color of the contour layer and output annotation: black, brown, and blue.

• Contours that have been created using the Contour With Barriers tool contain a Type field. The Type field contains one or more of the following values:

  • 1—Contours
  • 2—Indexed contours
  • 3—Explicit contours

  This Type field can be used as input to the Contour Type Field parameter. A separate annotation class will be created for annotation of each type.

• This tool honors the Annotation Text String Field Length environment. When set, it will override the default field length on the TextString field in any annotation feature classes created in a database.

Parameters

Dialog

Label	Explanation	Data Type
Input Features	The contour line feature class for which the annotation will be created.	Feature Layer
Output Geodatabase	The workspace where the output feature classes will be saved. The workspace can be an existing geodatabase or an existing feature dataset.	Workspace; Feature Dataset
Contour Label Field	The field in the input layer attribute table on which the annotation text will be based.	Field
Reference Scale	The scale that will be used as a reference for the annotation. This sets the scale on which all symbol and text sizes in the annotation will be based.	Double
Output Layer Name	The group layer that will contain the contour layer, the annotation, and the mask layer. 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, the tool adds the group layer to the display if the Add output datasets to an open map option is checked on the Geoprocessing tab on the Options dialog box. The group layer that is created is temporary and will not persist after the session ends unless the document is saved.	Group Layer
Contour and Label Color	Specifies the color of the output contour layer and annotation features. Black—The output contour layer and annotation features will be drawn in black. This is the default. Brown—The output contour layer and annotation features will be drawn in brown. Blue—The output contour layer and annotation features will be drawn in blue.	String
Contour Type Field (Optional)	The field in the input layer attribute table containing a value for the type of contour feature. An annotation class will be created for each type value.	Field
Contour Alignment (Optional)	Specifies how the annotation will be aligned to contour elevations. The annotation can be aligned to the contour elevations so that the top of the text is always placed uphill or downhill. These options allow the annotation to be placed upside down. The contour annotation can also be aligned to the page, ensuring that the text is never placed upside down. Align top of text to top of page— The annotation will be aligned to the page, ensuring that the text is never placed upside down. This is the default. Align top of text uphill—The annotation will be aligned to the contour elevations so that the top of the text is always placed uphill. This option allows the annotation to be placed upside down. Align top of text downhill—The annotation will be aligned to the contour elevations so that the top of the text is always placed downhill. This option allows the annotation to be placed upside down.	String
Enable Laddering (Optional)	Specifies whether annotation will be placed in ladders. Placing annotation in ladders will place the text so it appears to step up and step down the contours in a straight path. These ladders will run from the top of a hill to the bottom, will not cross each other, will belong to a single slope, and will not cross any other slope. Checked—Annotation will step up and down the contours in a straight path. Unchecked—Annotation will not be placed up and down the contours in a straight path. This is the default.	Boolean

Derived Output

Label	Explanation	Data Type
Output Workspace	The workspace where the output feature classes are saved.	Workspace; Feature Dataset

Python

arcpy.cartography.ContourAnnotation(in_features, out_geodatabase, contour_label_field, reference_scale_value, out_layer, contour_color, {contour_type_field}, {contour_alignment}, {enable_laddering})

Name	Explanation	Data Type
in_features	The contour line feature class for which the annotation will be created.	Feature Layer
out_geodatabase	The workspace where the output feature classes will be saved. The workspace can be an existing geodatabase or an existing feature dataset.	Workspace; Feature Dataset
contour_label_field	The field in the input layer attribute table on which the annotation text will be based.	Field
reference_scale_value	The scale that will be used as a reference for the annotation. This sets the scale on which all symbol and text sizes in the annotation will be based.	Double
out_layer	The group layer that will contain the contour layer, the annotation, and the mask layer. 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, the tool adds the group layer to the display if the Add output datasets to an open map option is checked on the Geoprocessing tab on the Options dialog box. The group layer that is created is temporary and will not persist after the session ends unless the document is saved.	Group Layer
contour_color	Specifies the color of the output contour layer and annotation features. BLACK—The output contour layer and annotation features will be drawn in black. This is the default. BROWN—The output contour layer and annotation features will be drawn in brown. BLUE—The output contour layer and annotation features will be drawn in blue.	String
contour_type_field (Optional)	The field in the input layer attribute table containing a value for the type of contour feature. An annotation class will be created for each type value.	Field
contour_alignment (Optional)	Specifies how the annotation will be aligned to contour elevations. The annotation can be aligned to the contour elevations so that the top of the text is always placed uphill or downhill. These options allow the annotation to be placed upside down. The contour annotation can also be aligned to the page, ensuring that the text is never placed upside down. PAGE— The annotation will be aligned to the page, ensuring that the text is never placed upside down. This is the default. UPHILL—The annotation will be aligned to the contour elevations so that the top of the text is always placed uphill. This option allows the annotation to be placed upside down. DOWNHILL—The annotation will be aligned to the contour elevations so that the top of the text is always placed downhill. This option allows the annotation to be placed upside down.	String
enable_laddering (Optional)	Specifies whether annotation will be placed in ladders. Placing annotation in ladders will place the text so it appears to step up and step down the contours in a straight path. These ladders will run from the top of a hill to the bottom, will not cross each other, will belong to a single slope, and will not cross any other slope. ENABLE_LADDERING—Annotation will step up and down the contours in a straight path. NOT_ENABLE_LADDERING—Annotation will not be placed up and down the contours in a straight path. This is the default.	Boolean

Derived Output

Name	Explanation	Data Type
out_geodatabase2	The workspace where the output feature classes are saved.	Workspace; Feature Dataset

Code sample

ContourAnnotation example (Python window)

The following stand-alone script demonstrates how to use the ContourAnnotation function.

import arcpy
arcpy.env.workspace = "C:/data/data.gdb"
arcpy.cartography.ContourAnnotation("Contours", "C:/data/data.gdb", "Contour", 
                                    50000, "ContourGroupLayer", "BLACK", "", 
                                    "PAGE")

ContourAnnotation example 2 (stand-alone script)

This sample runs the ContourWithBarriers function and uses the output from that tool as input to the ContourAnnotation function.

# Description: Create a contour with barriers feature class and then create 
#              annotation for the contours.
# Requirements: ArcGIS Spatial Analyst extension 

# Import system modules
import arcpy

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

# Set local variables
inRaster = "elevation"
inBarrier = "ridges"
inTextFile = ""
explicitValues = "NO_EXPLICIT_VALUES_ONLY"
contourInterval = 200
indexInterval = 1000
contourList = [1500, 3000]
baseContour = 0
outContours = "C:/data/data.gdb/outcontourwithbarriers"

# Check out the ArcGIS ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")

# Run ContourWithBarriers
arcpy.sa.ContourWithBarriers(inRaster, outContours, inBarrier, "POLYLINES", 
                             inTextFile, explicitValues, baseContour, 
                             contourInterval, indexInterval, contourList)

# Set local variables
inFeatures = "C:/data/data.gdb/outcontourwithbarriers"
inWorkspace = "C:/data/data.gdb"
LabelField = "Contour"
RefScaleValue = 50000
outLayer = "Contours"
Color = "BROWN"
TypeField = "Type"
Alignment = "PAGE"
Laddering = "NOT_ENABLE_LADDERING"

# Run ContourAnnotation
arcpy.cartography.ContourAnnotation(inFeatures, inWorkspace, LabelField, 
                                    RefScaleValue, outLayer, Color, TypeField, 
                                    Alignment, Laddering)

Environments

Reference Scale, Output Coordinate System, Annotation Text String Field Length

Licensing information

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