Collapse Hydro Polygon (Cartography)

Summary

Collapses or partially collapses hydro polygons to a centerline based on a collapse width.

Illustration

Usage

• This tool is optimized to collapse features that would be appropriate to represent as lines at small scales. Consider running this tool more than once with different collapse widths to create output suitable for different scales. Compact input polygon features may produce unexpected centerlines unless they are intersected by input connecting hydro line features.

• Tool performance depends on the cleanliness of the data. Overlapping input polygon features or disconnections in the hydro network between the input lines and polygons may cause unexpected results.

• Holes or islands in the input polygons will result in output centerlines that branch around the holes. To avoid this, remove holes from the input polygons using the Eliminate Polygon Part tool before running this tool.

• Processing large hydro datasets may exceed memory limitations. In this case, process the 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, are processed sequentially.

  After all partitions are processed, line and polygon feature class outputs are generated simultaneously. These feature classes will appear seamless and will not be split at partition edges.

  See Generalizing large datasets using partitions for more information.

• Large individual input polygon features can take a long time to process; avoid dissolving input polygons before running this tool. If the polygons must be dissolved first, check the Merge Adjacent Input Polygons parameter. Using this parameter, the tool will merge the input polygons without creating large polygons while maintaining correct connectivity in the hydro network. The output lines will be split at the original input polygon boundaries.

  To avoid long processing times, it may be necessary to split input polygons into smaller features using the Dice tool if they are very large. Use the Simplify Polygon tool to reduce the number of vertices to improve performance.

• An output polygon feature class must be specified when the collapse width value is set to a distance greater than 0. The output polygons will contain polygons that are wider than the collapse width. Polygons may be partially collapsed if only part of the polygon is smaller than the collapse width value. Output lines are created for all input polygons including those that are larger than the collapse width value. A collapse width value of 0 will result in all input polygons being fully collapsed, and no output polygon feature class will be created.

• The output line feature class will include a field named COLLAPSED. This field will contain a value of 0 to correspond to polygons that were not collapsed and a value of 1 for polygons that were collapsed.

• When the collapse width value is set to a distance greater than 0, use the Collapse Width Tolerance (%) and Minimum Length parameters to avoid oscillations in the partially collapsed polygons. Oscillations occur when a polygon river is partially collapsed on and off along its length, resulting in a string of small polygon lakes connected by single line rivers. Sections of partially collapsed polygons that are within the collapse width tolerance percentage value will be analyzed and the surrounding context will be considered when determining whether to collapse that part of the polygon feature. If the portion of the polygon being analyzed is shorter than the minimum length value, the collapse width may be ignored to prevent oscillation. The minimum length is based on the length of the centerline created for the polygon.

• Partially collapsed polygons will be tapered at the connection points with output lines to create a smooth transition between collapsed polygons and those that are not collapsed. The length of each taper is controlled by the Taper Length Percentage parameter, which sets the taper length to a percentage of the width of the partially collapsed polygon at the location of the taper. A taper length percentage value of 0 prevents all tapering.

• The output line feature class will have attribute fields populated with IDs from the features used to create them. Use these values to join output features to their corresponding input as needed.

  • InPoly_ID—A number representing the input order of the polygon feature class containing the polygon used to create the output line feature. A table named <out_line_feature_class>_InPoly_DecodeID will be saved in the output location linking the InPoly_ID values to the names of the input feature classes. If the output location is specified in a feature dataset, the table will be created one level higher, at the geodatabase level.
  • InPoly_FID—The OBJECTID of the input polygon feature used to create the output line.
  • InLine_ID—A number representing the input order of the input connecting hydro line feature class containing the feature connected to the output line feature. A table named <out_line_feature_class>_InLine_DecodeID will be saved in the output location linking the InLine_ID values to the names of the input feature classes. If the output location is specified in a feature dataset, the table will be created one level higher, at the geodatabase level.
  • InLine_FID—The OBJECTID of the input connecting hydro line feature connected to the output line feature. This will be set to a value of -1 if no connecting hydro line features are connected to the output line feature.

  The output polygons will also include the InPoly_ID and InPolyFID attributes populated with the IDs of the feature classes and features used to create them. Only one ID number will be recorded in each attribute if multiple input connecting lines are used to create a single output feature.

• The line output features include three field attributes that record information about the width of the corresponding input polygon features. Width is measured in the linear units of the spatial reference of the output.

  • MIN_WIDTH—The minimum width of the polygon along the output line
  • MAX_WIDTH—The maximum width of the polygon along the output line
  • AVG_WIDTH—The average width of the polygon along the output line

Parameters

Dialog

Label	Explanation	Data Type
Input Hydro Polygon Features	One or more feature layers containing hydro polygons.	Feature Layer
Output Line Feature Class	The line feature class containing the centerlines of the collapsed polygons. It contains centerlines of all input polygons including those that are not collapsed. This feature class has a COLLAPSED attribute that specifies whether the centerline feature represents a collapsed polygon.	Feature Class
Merge Adjacent Input Polygons (Optional)	Specifies whether adjacent input polygons will be merged before calculating the centerlines. Checked—Input hydro polygons will be merged before calculating the centerlines. This is the default. Unchecked—Centerlines will be calculated from input hydro polygons that are not merged.	Boolean
Connecting Hydro Line Features (Optional)	Input hydro line features that connect to the input hydro polygons to be collapsed. Line features will be created to maintain these connections.	Feature Layer
Collapse Width (Optional)	The threshold width of an input hydro polygon to be considered for collapse. All polygons below the specified width will be collapsed. The default value is 0, which will collapse all features.	Linear Unit
Collapse Width Tolerance (%) (Optional)	A percentage tolerance within which features will be analyzed and the surrounding context will be considered when determining whether to collapse a feature. This is to minimize oscillations within the collapse. The default value is 20 percent. This parameter is applied only when the Collapse Width parameter value is specified.	Double
Minimum Length (Optional)	The minimum length required for a polygon to be retained in the output polygon feature class. The minimum length is based on the length of the centerline created for the polygon. If the centerline of a polygon is longer than the collapse width but shorter than the minimum length, the polygon will not be included in the output polygon feature class. The default value is 0. This parameter is applied only when the Collapse Width parameter value is specified.	Linear Unit
Taper Length Percentage (Optional)	The length that connections between polygons in the output polygon feature class and the output line feature class will be tapered. This parameter specifies the length of the tapering as a percentage of the width at the connection location. A taper length percentage value of 0 will result in no tapering. The default value is 50. This parameter is applied only when the Collapse Width parameter value is specified.	Double
Output Polygon Feature Class (Optional)	The polygon feature class containing the portions of the input hydro polygons that are not collapsed. This parameter is applied only when the Collapse Width parameter value is specified.	Feature Class

Derived Output

Label	Explanation	Data Type
InPoly Decode ID Table	The table linking the InPoly_ID values to the names of the input hydro polygon features. The table will be created in the same location as the Output Line Feature Class value. If the Output Line Feature Class value is specified in a feature dataset, the table will be created one level higher, at the geodatabase level.	Table
InLine Decode ID Table	The table linking the InLine_ID values to the names of the connecting hydro line features. The table will be created in the same location as the Output Line Feature Class value. If the Output Line Feature Class value is specified in a feature dataset, the table will be created one level higher, at the geodatabase level.	Table

Python

arcpy.cartography.CollapseHydroPolygon(in_features, out_line_feature_class, {merge_adjacent_input_polygons}, {connecting_features}, {collapse_width}, {collapse_width_tolerance}, {minimum_length}, {taper_length_percentage}, {out_poly_feature_class})

Name	Explanation	Data Type
in_features [in_features,...]	One or more feature layers containing hydro polygons.	Feature Layer
out_line_feature_class	The line feature class containing the centerlines of the collapsed polygons. It contains centerlines of all input polygons including those that are not collapsed. This feature class has a COLLAPSED attribute that specifies whether the centerline feature represents a collapsed polygon.	Feature Class
merge_adjacent_input_polygons (Optional)	Specifies whether adjacent input polygons will be merged before calculating the centerlines. MERGE_ADJACENT—Input hydro polygons will be merged before calculating the centerlines. This is the default. NO_MERGE—Centerlines will be calculated from input hydro polygons that are not merged.	Boolean
connecting_features [connecting_features,...] (Optional)	Input hydro line features that connect to the input hydro polygons to be collapsed. Line features will be created to maintain these connections.	Feature Layer
collapse_width (Optional)	The threshold width of an input hydro polygon to be considered for collapse. All polygons below the specified width will be collapsed. The default value is 0, which will collapse all features.	Linear Unit
collapse_width_tolerance (Optional)	A percentage tolerance within which features will be analyzed and the surrounding context will be considered when determining whether to collapse a feature. This is to minimize oscillations within the collapse. The default value is 20 percent. This parameter is applied only when the collapse_width parameter value is specified.	Double
minimum_length (Optional)	The minimum length required for a polygon to be retained in the output polygon feature class. The minimum length is based on the length of the centerline created for the polygon. If the centerline of a polygon is longer than the collapse width but shorter than the minimum length, the polygon will not be included in the output polygon feature class. The default value is 0. This parameter is applied only when the collapse_width parameter value is specified.	Linear Unit
taper_length_percentage (Optional)	The length that connections between polygons in the output polygon feature class and the output line feature class will be tapered. This parameter specifies the length of the tapering as a percentage of the width at the connection location. A taper length percentage value of 0 will result in no tapering. The default value is 50. This parameter is applied only when the collapse_width parameter value is specified.	Double
out_poly_feature_class (Optional)	The polygon feature class containing the portions of the input hydro polygons that are not collapsed. This parameter is applied only when the collapse_width parameter value is specified.	Feature Class

Derived Output

Name	Explanation	Data Type
in_poly_decode_id_table	The table linking the InPoly_ID values to the names of the connecting hydro line features. The table will be created in the same location as the out_line_feature_class value. If the out_line_feature_class value is specified in a feature dataset, the table will be created one level higher, at the geodatabase level.	Table
in_line_decode_id_table	The table linking the InLine_ID values to the names of the connecting hydro line features. The table will be created in the same location as the out_line_feature_class value. If the out_line_feature_class value is specified in a feature dataset, the table will be created one level higher, at the geodatabase level.	Table

Code sample

CollapseHydroPolygon example 1 (stand-alone script)

This example demonstrates how to use the CollapseHydroPolygon function to create a centerline from a polygon feature.

# Name: CollapseHydroPolygon_sample1.py
# Description: Collapse all water polygons to produce centerlines

# Import System Modules
import arcpy
arcpy.env.workspace = r"C:/data/Hydro.gdb"

# Execute Collapse Hydro Polygon
arcpy.cartography.CollapseHydroPolygon('WaterPolygons', 'HydroCenterlinesOut')

CollapseHydroPolygon example 2 (stand-alone script)

This example demonstrates how to use the CollapseHydroPolygon function to create a centerline from a polygon feature that has a width below the collapse width specified. Connecting features are used to maintain connections between centerlines created and the connecting features.

# Name: CollapseHydroPolygon_sample2.py
# Description: Select the rivers and collapse features that are
#               below 6 meters wide to produce centerlines.

# Import System Modules
import arcpy
arcpy.env.workspace = r"C:/data/Hydro.gdb"

# Setting Local Variables
in_features = 'WaterPolygons'
out_line_feature_class = 'HydroCenterlinesOut'
merge_adjacent_input_polygons = False # default is True or "MERGE_ADJACENT"
connection_features = 'WaterLines'
collapse_width = "6 Meters"           # default is '0 Meters'
collapse_width_tolerance = 20         # default is 20
minimum_length = "10 Meters"          # default is '0 Meters' 
taper_length_percentage = 50          # default is 50
out_poly_feature_class =  'HydroPolyOut'

# Select only the Rivers
inputLyr = arcpy.MakeFeatureLayer_management(in_features,
                                             "inputLyr",
                                             "FTYPE = 'rivers'")

# Execute Collapse Hydro Polygon
arcpy.cartography.CollapseHydroPolygon(inputLyr,
                                       out_line_feature_class,
                                       merge_adjacent_input_polygons,
                                       connection_features,
                                       collapse_width,
                                       collapse_width_tolerance,
                                       minimum_length,
                                       taper_length_percentage,
                                       out_poly_feature_class)

Environments

Cartographic Partitions

Licensing information

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