Regularize Building Footprint (3D Analyst)

Summary

Normalizes the footprint of building polygons by eliminating undesirable artifacts in their geometry.

Illustration

Regularize Building Footprint tool 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:

    1. Add a field of type double.
    2. Use the field calculator to compute the following formula:
      (4 * 3.14159265358979 * !shape.area!) / !shape.length! ** 2
    3. 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

LabelExplanationData 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.

  • RIGHT_ANGLESShapes composed of 90° angles between adjoining edges will be constructed.
  • RIGHT_ANGLES_AND_DIAGONALSShapes composed of 45° and 90° angles between adjoining edges will be constructed.
  • ANY_ANGLEShapes that form any angles between adjoining edges will be constructed.
  • CIRCLEThe best fitting circle around the input features will be constructed.
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.

  • DistanceThe tolerance will represent the maximum distance from the boundary of the feature being processed. This is the default.
  • Area RatioThe tolerance will represent the maximum limit for the ratio between the area of the original feature that differs from the regularized circle and the area of the regularized circle.
String

arcpy.ddd.RegularizeBuildingFootprint(in_features, out_feature_class, method, tolerance, densification, precision, diagonal_penalty, min_radius, max_radius, {alignment_feature}, {alignment_tolerance}, {tolerance_type})
NameExplanationData 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.

  • RIGHT_ANGLESShapes composed of 90° angles between adjoining edges will be constructed.
  • RIGHT_ANGLES_AND_DIAGONALSShapes composed of 45° and 90° angles between adjoining edges will be constructed.
  • ANY_ANGLEShapes that form any angles between adjoining edges will be constructed.
  • CIRCLEThe best fitting circle around the input features will be constructed.
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.

  • DISTANCEThe tolerance will represent the maximum distance from the boundary of the feature being processed. This is the default.
  • AREA_RATIOThe tolerance will represent the maximum limit for the ratio between the area of the original feature that differs from the regularized circle and the area of the regularized circle.
String

Code sample

RegularizeBuildingFootprint example 1 (Python window)

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)
RegularizeBuildingFootprint example 2 (stand-alone script)

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())

Related topics