Calculate Color Theorem Field (Cartography)

Summary

Populates an integer field to use for symbolizing polygons with a small number of colors and ensuring no two adjacent polygons are the same color.

Values are assigned to each polygon based on the theorem that only a small number of colors, often four or five, are needed to ensure no two adjacent polygons in a 2-dimensional map are the same color. Overlapping and multipart polygons can increase the number of colors required. The assigned values will be integers ranging from 1 to the number of unique values assigned.

Illustration

Integer values are assigned to each feature and are used to symbolize the layer so that no two adjacent polygons are the same color.

Usage

• This tool does not create new output. It modifies the input by assigning integer values in a new or existing field that can be used in unique values symbology to symbolize the features.

• Polygons will be considered adjacent if any of the following are true:

  • The polygons share a border segment comprised of at least two vertices.
  • The polygons overlap.
  • The polygons are separated by a small amount of empty space (such as nearby islands).

• Polygons that touch at only a single vertex may be assigned the same value.

• Polygons that are separated by a small amount of empty space but do not touch may still be assigned the same value depending on their shape and proximity.

• Multipart features can only be assigned one value, so all parts of a multipart feature will be the same color when symbolized. You can convert multipart features to individual features to allow each part to receive a different value if needed. Conversely, you can combine individual features into multipart features to guarantee they receive the same value if needed.

• The tool will attempt to equalize the number of instances of each unique value. A spatially even distribution of unique values is not guaranteed.

Parameters

Dialog

Label	Explanation	Data Type
Input Features	The input polygons that will use the tool results to symbolize features.	Feature Layer
Field Name (Existing or New)	The field that will store the tool results. Each feature will be assigned an integer between 1 and the number of unique values created to ensure no two adjacent polygons have the same value. If the field does not exist, it will be created with the short integer data type. If an existing field is specified, it must be of short, long, or big integer data type. Existing values will be overwritten with the tool results.	Field

Derived Output

Label	Explanation	Data Type
Output features	The updated input features.	Feature Layer

Python

arcpy.cartography.CalculateColorTheoremField(in_features, field_name)

Name	Explanation	Data Type
in_features	The input polygons that will use the tool results to symbolize features.	Feature Layer
field_name	The field that will store the tool results. Each feature will be assigned an integer between 1 and the number of unique values created to ensure no two adjacent polygons have the same value. If the field does not exist, it will be created with the short integer data type. If an existing field is specified, it must be of short, long, or big integer data type. Existing values will be overwritten with the tool results.	Field

Derived Output

Name	Explanation	Data Type
out_features	The updated input features.	Feature Layer

Code sample

CalculateColorTheoremField example (Python window)

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

import arcpy
arcpy.env.workspace = "C:/data"
arcpy.cartography.CalculateColorTheoremField("countries", "color_index")

CalculateColorTheoremField example 2 (stand-alone script)

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

# Name: CalculateColorTheorem_standalone_script.py
# Description: Populates a number field to use for symbolizing 
# polygons with a small number of colors and ensuring no two adjacent 
# polygons are the same color.

# Import system modules
import arcpy

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

# Set local variables
inPolygonFeatures = "countries"
fieldName = "color_index"

# Execute Calculate Color Theorem Field
arcpy.cartography.CalculateColorTheoremField(inPolygonFeatures, 
                                             fieldName)

Environments

This tool does not use any geoprocessing environments.

Licensing information

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