Aggregate Polygons (Cartography)
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
| 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.
| 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
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)
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")