Aggregate Polygons (Cartography)

Summary

Combines polygons that are within a specified distance of each other into new polygons.

Illustration

Aggregate Polygons tool illustration
Orthogonal or nonorthogonal features can be aggregated.

Usage

  • This tool is intended for moderate scale reduction and aggregation when input features can no longer be represented individually due to the limited map space or the required data resolution. Aggregation will only occur when two polygon boundaries are within the specified aggregation distance of each other. There will be no self-aggregation, meaning no aggregation within an input polygon feature itself along its boundary, and no aggregation between any parts of a multipart polygon feature.

  • Using the orthogonal option will construct orthogonally shaped output features. This option is best suited for use with input features that have predominantly orthogonal edges. In some cases, less aggregation will occur to accommodate this. For example, two square buildings situated diagonally apart within the aggregation distance may not be aggregated because there is no clear connection that can be made while preserving orthogonality. The nonorthogonal option will produce more organically shaped results.

  • Use barrier features to prevent aggregation from occurring across boundaries. Examples include preventing land cover from aggregating across rivers or buildings aggregating across streets. Barriers can be either lines or polygons, and multiple barrier feature classes can be used simultaneously.

  • When the Aggregate Field parameter is defined, the attribute field and its values are copied to the output feature class. The aggregate field must be of data type text, date, or integer. If the aggregate field has domains and subtypes, they are copied to the output feature class when the Transfer Geodatabase Field Properties environment setting is checked.

  • Overlapping polygon features will be aggregated. Unexpected results may occur if the Aggregate Field parameter is defined and overlapping features have different aggregate field values.

  • The output feature class will not contain any geographic attributes from the input features. A one-to-many relationship table can be created to link the aggregated polygons to their source polygons. This link can become incorrect when any of the input or output features are modified.

  • If the input features contain z-values, the z-values can be preserved if they're specified in the environment settings. If the output vertices do not change, the input z-values will be carried over to the output vertices; otherwise, a z-value will be derived for new vertices, either from existing z-values or through interpolation.

  • Processing a large input dataset may exceed memory limitations. In this case, consider processing input data by partition by identifying a relevant polygon feature class in the Cartographic Partitions environment setting. Portions of the data, defined by partition boundaries, will be processed sequentially. The resulting output feature class will be consistent at partition edges, but output features that cross partitions will be split at the partition line. An IS_SPLIT field in the output feature class will have a value of 1 in this instance.

Parameters

LabelExplanationData Type
Input Features

The polygon features to be aggregated. If this is a layer referencing a representation and shape overrides are present on the input features, the overridden shapes, not the feature shapes, will be considered in aggregation processing.

Feature Layer
Output Feature Class

The output feature class to be created.

Feature Class
Aggregation Distance

The distance to be satisfied between polygon boundaries for aggregation to occur. A distance must be specified, and it must be greater than zero. You can choose a preferred unit; the default is the feature unit.

Linear Unit
Minimum Area
(Optional)

The minimum area for an aggregated polygon to be retained. The default value is zero, that is, to keep all polygons. You can specify a preferred unit; the default is the feature unit.

Areal Unit
Minimum Hole Size
(Optional)

The minimum size of a polygon hole to be retained. The default value is zero, that is, to keep all polygon holes. You can specify a preferred unit; the default is the feature unit.

Areal Unit
Preserve orthogonal shape
(Optional)

Specifies the characteristic of the output features when constructing the aggregated boundaries.

  • Unchecked--Organically shaped output features will be created. This is suitable for natural features, such as vegetation or soil polygons. This is the default.
  • Checked--Orthogonally shaped output features will be created. This is suitable for preserving the geometric characteristic of anthropogenic input features, such as building footprints.
Boolean
Barrier Features
(Optional)

The layers containing the line or polygon features that are aggregation barriers for input features. Features will not be aggregated across barrier features. Barrier features that are in geometric conflict with input features will be ignored.

Feature Layer
Output Table
(Optional)

A one-to-many relationship table that links the aggregated polygons to their source polygon features. This table contains two fields, OUTPUT_FID and INPUT_FID, that store the aggregated feature IDs and their source feature IDs, respectively. Use this table to derive necessary attributes for the output features from their source features. The default name for this table is the name of the output feature class, appended with _tbl. The default path is the same as the output feature class. If the output features location is specified in a feature dataset, this table will be created one level higher, at the geodatabase level. No table is created when this parameter is left blank.

Table
Aggregate Field
(Optional)

The field that contains attributes for aggregation. Features must share the same attribute value to be considered for aggregation. For example, use a building classification field as the aggregate field to prevent commercial buildings from aggregating with residential buildings.

Field

arcpy.cartography.AggregatePolygons(in_features, out_feature_class, aggregation_distance, {minimum_area}, {minimum_hole_size}, {orthogonality_option}, {barrier_features}, {out_table}, {aggregate_field})
NameExplanationData Type
in_features

The polygon features to be aggregated. If this is a layer referencing a representation and shape overrides are present on the input features, the overridden shapes, not the feature shapes, will be considered in aggregation processing.

Feature Layer
out_feature_class

The output feature class to be created.

Feature Class
aggregation_distance

The distance to be satisfied between polygon boundaries for aggregation to occur. A distance must be specified, and it must be greater than zero. You can choose a preferred unit; the default is the feature unit.

Linear Unit
minimum_area
(Optional)

The minimum area for an aggregated polygon to be retained. The default value is zero, that is, to keep all polygons. You can specify a preferred unit; the default is the feature unit.

Areal Unit
minimum_hole_size
(Optional)

The minimum size of a polygon hole to be retained. The default value is zero, that is, to keep all polygon holes. You can specify a preferred unit; the default is the feature unit.

Areal Unit
orthogonality_option
(Optional)

Specifies the characteristic of the output features when constructing the aggregated boundaries.

  • NON_ORTHOGONALOrganically shaped output features will be created. This is suitable for natural features, such as vegetation or soil polygons. This is the default.
  • ORTHOGONALOrthogonally shaped output features will be created. This is suitable for preserving the geometric characteristic of anthropogenic input features, such as building footprints.
Boolean
barrier_features
[barrier_features,...]
(Optional)

The layers containing the line or polygon features that are aggregation barriers for input features. Features will not be aggregated across barrier features. Barrier features that are in geometric conflict with input features will be ignored.

Feature Layer
out_table
(Optional)

A one-to-many relationship table that links the aggregated polygons to their source polygon features. This table contains two fields, OUTPUT_FID and INPUT_FID, that store the aggregated feature IDs and their source feature IDs, respectively. Use this table to derive necessary attributes for the output features from their source features. The default name for this table is the name of the output feature class, appended with _tbl. The default path is the same as the output feature class. If the output features location is specified in a feature dataset, this table will be created one level higher, at the geodatabase level. No table is created when this parameter is left blank.

Table
aggregate_field
(Optional)

The field that contains attributes for aggregation. Features must share the same attribute value to be considered for aggregation. For example, use a building classification field as the aggregate field to prevent commercial buildings from aggregating with residential buildings.

Field

Code sample

AggregatePolygons example 1 (Python window)

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

This example uses a classification field for aggregating features with the same classification values. An environment setting is used to transfer geodatabase field properties such as domain and subtypes of the aggregate field to the output feature class.

import arcpy
arcpy.env.cartographicPartitions = "C:/data/county.gdb/zipcodepoly"
arcpy.env.transferGDBAttributeProperties = True

buildings = "C:/data/county.gdb/bldgspoly"
roads = "C:/data/county.gdb/roadnetwork"
output = "C:/data/county.gdb/BldgAggBarrierPartition"
output_table = "C:/data/county.gdb/BldgAggBarrierPartition_Tbl"
aggregate_field = "Classification"

arcpy.cartography.AggregatePolygons(buildings, output, "20 Meters", 
                                    "50 SquareMeters", "0 SquareMeters", 
                                    "ORTHOGONAL", roads, output_table, 
                                    aggregate_field)
AggregatePolygons example 2 (stand-alone script)

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

# Name: AggregatePolygons_Example2.py
# Description: Aggregate grass features and then transfer attributes
 
# Import system modules
import arcpy
  
# Set environment settings
arcpy.env.workspace = "C:/data/Portland.gdb/Vegetation"
 
# Set local variables
inGrassFeatures = "grass"
aggregatedFeatures = "C:/data/PortlandOutput.gdb/grassland"
aggregatedTable = "C:/data/PortlandOutput.gdb/grassland_Tbl"
frequencyTable = "C:/data/PortlandOutput.gdb/frequency_Tbl"

# Aggregate grass polygons.
arcpy.cartography.AggregatePolygons(inGrassFeatures, aggregatedFeatures, 50, 
                                    300, 300, "NON_ORTHOGONAL", "", 
                                    aggregatedTable)

# Join the aggregatedTable with input and transfer the COUNT field to 
# aggregatedTable.
arcpy.management.JoinField(aggregatedTable, "INPUT_FID", inGrassFeatures, 
                           "OBJECTID", "COUNT")
 
# Use Frequency on aggregatedTable and obtain sum for COUNT.
arcpy.analysis.Frequency(aggregatedTable, frequencyTable, "OUTPUT_FID", "COUNT")

# Join the aggregatedFeatures with frequencyTable and transfer the COUNT 
# field to aggregatedFeatures.
arcpy.management.JoinField(aggregatedFeatures, "OBJECTID", frequencyTable, 
                           "OUTPUT_FID", "COUNT")

Licensing information

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

Related topics