Label | Explanation | Data Type |
Input Features
| The polygons that represent the building footprints to be regularized. | Feature Layer |
Output Feature Class | The feature class that will be produced. | Feature Class |
Method
| Specifies the regularization method that will be used in processing the input features.
| String |
Tolerance
| For most methods, this value represents the maximum distance that the regularized footprint can deviate from the boundary of its originating feature. The specified value will be based on the linear units of the input feature's coordinate system. When using the Circle method, this option can also be interpreted as a ratio of the difference between the original feature and its regularized result against the area of the regularized result based on the selection that is made in the Tolerance Type parameter. | Double |
Densification
| The sampling interval that will be used to evaluate whether the regularized feature will be straight or bent. The densification must be equal to or less than the tolerance value. This parameter is only used with methods that support right angle identification. | Double |
Precision
| The precision of the spatial grid that will be used in the regularization process. Valid values range from 0.05 to 0.25. | Double |
Diagonal Penalty
| When the Right Angles and Diagonals method is used, this value identifies the likelihood of constructing right angles or diagonal edges between two adjoining segments. When the Any Angles method is used, this value identifies the likelihood of constructing diagonal edges that do not conform to the preferred edges determined by the tool's algorithm. If the penalty value is set to 0, the preferred edges will not be used, resulting in the production of a simplified irregular polygon. Generally, the higher the value, the less likely a diagonal edge will be constructed. | Double |
Minimum Radius
| The smallest radius allowed for a regularized circle. A value of 0 implies that there is no minimum size limit. This option is only available with the Circle method. | Double |
Maximum Radius
| The largest radius allowed for a regularized circle. This option is only available with the Circle method. | Double |
Alignment Feature
(Optional) | The line feature that will be used to align the orientation of the regularized polygons. Each polygon will only be aligned to one line feature. | Feature Layer |
Alignment Tolerance
(Optional) | The maximum distance threshold that will be used for finding the nearest alignment feature. For example, a value of 20 meters means the nearest line that is within 20 meters will be used to align the regularized polygon. | Linear Unit |
Tolerance Type
(Optional) | Specifies how tolerance will be applied when the Method parameter is set to Circle.
| String |
Summary
Normalizes the footprint of building polygons by eliminating undesirable artifacts in their geometry.
Illustration
Usage
This tool uses a polyline compression algorithm to correct distortions in building footprint polygons created through feature extraction workflows that may produce undesirable artifacts.
If your building footprints contain circular structures, process those features first. A compactness ratio can be used to identify circular buildings. To calculate this value, do the following:
- Add a field of type double.
- Use the field calculator to compute the following formula:
(4 * 3.14159265358979 * !shape.area!) / !shape.length! ** 2
- A perfect circle will have a value of 1. However, since the polygons processed with this tool will have some irregularities, values close to 1 are likely to have a circular shape. Check the results to identify the minimum value of a circular building. Then select values greater than or equal to this value before executing this tool with the Method parameter set to Circle.
Set the Method parameter to Any Angles if the building footprints represent geometries with edges that form a combination of angles that include, but are not limited to, 45° and 90° bends. Start by selecting a subset of features containing irregular edges and evaluate which diagonal penalty value yields the desired result. If the result does not adequately capture diagonal edges, modify the tolerance value to constrain the regularization zone and incrementally lower the diagonal penalty. If the output contains undesirable edges with acute interior angles, iteratively run the tool while incrementally increasing the diagonal penalty until the desired output is attained. Then use this value to process the entire dataset.
When the Any Angles option is used on a computer with an NVIDIA graphics card that supports CUDA and has more than 2 GB of memory, the tool will use the GPU to perform its operation. You can modify this behavior using the Processor Type environment. If multiple GPUs are present, the specific GPU can be set using the GPU ID environment.
When the tool cannot produce a regularized solution for a given input, the original feature is copied to the output. The value specified in the STATUS field will indicate whether the feature was regularized as follows:
- 0—Regularized feature
- 1—Original feature
When using the Circles method with geometries that have a large variation in size, using the Area Ratio option for the Tolerance Type parameter may yield better results than the Distance option since the construction of the output features will be constrained by the size of the original geometry as opposed to a fixed size that may work for a limited subset of the original features.
Parameters
arcpy.ddd.RegularizeBuildingFootprint(in_features, out_feature_class, method, tolerance, densification, precision, diagonal_penalty, min_radius, max_radius, {alignment_feature}, {alignment_tolerance}, {tolerance_type})
Name | Explanation | Data Type |
in_features | The polygons that represent the building footprints to be regularized. | Feature Layer |
out_feature_class | The feature class that will be produced. | Feature Class |
method | Specifies the regularization method that will be used in processing the input features.
| String |
tolerance | For most methods, this value represents the maximum distance that the regularized footprint can deviate from the boundary of its originating feature. The specified value will be based on the linear units of the input feature's coordinate system. When using the CIRCLE method, this option can also be interpreted as a ratio of the difference between the original feature and its regularized result against the area of the regularized result based on the selection that is made in the tolerance_type parameter. | Double |
densification | The sampling interval that will be used to evaluate whether the regularized feature will be straight or bent. The densification must be equal to or less than the tolerance value. This parameter is only used with methods that support right angle identification. | Double |
precision | The precision of the spatial grid that will be used in the regularization process. Valid values range from 0.05 to 0.25. | Double |
diagonal_penalty | When the RIGHT_ANGLES_AND_DIAGONALS method is used, this value identifies the likelihood of constructing right angles or diagonal edges between two adjoining segments. When the ANY_ANGLES method is used, this value identifies the likelihood of constructing diagonal edges that do not conform to the preferred edges determined by the tool's algorithm. Generally, the higher the value, the less likely a diagonal edge will be constructed. | Double |
min_radius | The smallest radius allowed for a regularized circle. A value of 0 implies that there is no minimum size limit. This option is only available with the CIRCLE method. | Double |
max_radius | The largest radius allowed for a regularized circle. This option is only available with the CIRCLE method. | Double |
alignment_feature (Optional) | The line feature that will be used to align the orientation of the regularized polygons. Each polygon will only be aligned to one line feature. | Feature Layer |
alignment_tolerance (Optional) | The maximum distance threshold that will be used for finding the nearest alignment feature. For example, a value of 20 meters means the nearest line that is within 20 meters will be used to align the regularized polygon. | Linear Unit |
tolerance_type (Optional) | Specifies how tolerance will be applied when the method parameter is set to CIRCLE.
| String |
Code sample
The following sample demonstrates the use of this tool in the Python window.
arcpy.env.workspace = 'c:/data'
arcpy.ddd.RegularizeBuildingFootprint('rough_footprints.shp',
'regularized_footprints.shp',
method='Circle', tolerance=1.5, min_radius=10,
max_radius=20)
The following sample demonstrates the use of this tool in a stand-alone Python script.
'''****************************************************************************
Name: Extract Building Footprints
Description: Extract footprint from lidar points classified as buildings,
regularize its geometry, and calculate the building height.
****************************************************************************'''
import arcpy
lasd = arcpy.GetParameterAsText(0)
footprint = arcpy.GetParameterAsText(1)
try:
lasd_layer = 'building points'
arcpy.management.MakeLasDatasetLayer(lasd, lasd_layer, class_code=6)
temp_raster = 'in_memory/bldg_raster'
arcpy.management.LasPointStatsAsRaster(lasd_layer, temp_raster,
'PREDOMINANT_CLASS', 'CELLSIZE', 2.5)
temp_footprint = 'in_memory/footprint'
arcpy.conversion.RasterToPolygon(temp_raster, temp_footprint)
arcpy.ddd.RegularizeBuildingFootprint(temp_footprint, footprint,
method='RIGHT_ANGLES')
arcpy.ddd.LasPointStatsByArea(lasd_layer, footprint, ['MIN_Z', 'MAX_Z'])
arcpy.management.AddField(footprint, 'Height', 'Double')
arcpy.management.CalculateField(footprint, 'Height',
"round('!Z_Max! - !Z_Min!', 2)",
'PYTHON_9.3')
except arcpy.ExecuteError:
print(arcpy.GetMessages())