Aggregate Polygons

Summary

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

Illustration

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 happen where two polygon boundaries are within the specified aggregation distance to 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 in order 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.

• If the input feature class is a layer referencing a representation, and there are shape overrides on any of the input features, the shape overrides will be assessed in the aggregation, not the feature geometry.

• The output feature class will not contain any geographic attributes from the input features. A one-to-many relationship table can be optionally 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 specified in the environment settings. Where the output vertices are not changed, 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 consistent at partition edges, but output features crossing partitions, will be split at the partition line. A field called IS_SPLIT in the output feature class will have a value of 1 in this instance.

Syntax

AggregatePolygons_cartography (in_features, out_feature_class, aggregation_distance, {minimum_area}, {minimum_hole_size}, {orthogonality_option}, {barrier_features}, {out_table})

Parameter	Explanation	Data 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 happen. 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_ORTHOGONAL —Organically shaped output features will be created. This is suitable for natural features, such as vegetation or soil polygons. This is the default. ORTHOGONAL —Orthogonally shaped output features will be created. This option 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
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, storing 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. No table is created when this parameter is left blank.	Table

Code Sample

AggregatePolygons tool example 1 (Python window)

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

import arcpy
arcpy.env.cartographicPartitions = "C:/data/county.gdb/zipcodepoly"
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"
arcpy.AggregatePolygons_cartography(buildings, output, "20 Meters", "5 SquareMeters", "0 SquareMeters", "ORTHOGONAL", roads, output_table)

AggregatePolygons tool 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
# Author: ESRI
 
# Import system modules
import arcpy
from arcpy import env
import arcpy.cartography as CA
import arcpy.management as DM
import arcpy.analysis as AN
  
# Set environment settings
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.
CA.AggregatePolygons(inGrassFeatures, aggregatedFeatures, 50, 300, 300, "NON_ORTHOGONAL", "", aggregatedTable)
 
# Join the aggregatedTable with input and
# transfer the COUNT field to aggregatedTable.
DM.JoinField(aggregatedTable, "INPUT_FID", inGrassFeatures, "OBJECTID", "COUNT")
 
# Use Frequency on aggregatedTable and
# obtain sum for COUNT.
AN.Frequency(aggregatedTable, frequencyTable, "OUTPUT_FID", "COUNT")

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

Environments

• Current Workspace
• Default Output Z Value
• Output M Domain
• Output XY Domain
• Output Coordinate System
• Extent
• Output has M values
• Output has Z values
• Scratch Workspace
• XY Tolerance
• Cartographic Partitions

Licensing Information

• ArcGIS for Desktop Basic: No
• ArcGIS for Desktop Standard: No
• ArcGIS for Desktop Advanced: Yes

Feedback on this topic?