Summary
Combines polygons that are 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 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.
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 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.
Syntax
arcpy.cartography.AggregatePolygons(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 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.
| 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. No table is created when this parameter is left blank. | Table |
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.AggregatePolygons_cartography(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
import arcpy.cartography as CA
import arcpy.management as DM
import arcpy.analysis as AN
# 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.
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
Licensing information
- Basic: No
- Standard: No
- Advanced: Yes
Related topics
- An overview of the Generalization toolset
- Understanding conflict resolution and generalization
- Automating conflict resolution and generalization workflows with geoprocessing
- Simplify Building
- Generalizing large datasets using partitions
- Create Cartographic Partitions
- Cartographic Partitions (Environment setting)