Pairwise Buffer (Analysis)

Summary

Creates buffer polygons around input features to a specified distance using a parallel processing approach.

Alternate tools are available for buffer operations. See the Buffer and Graphic Buffer tool documentation for details.

Illustration

Pairwise Buffer illustration

Usage

  • This tool honors the Parallel Processing Factor environment. If the environment is not set (the default) or is set to 100, full parallel processing will be enabled and the tool will attempt to distribute the work to all the logical cores on the machine. Setting the environment to 0 will disable parallel processing. Specifying a factor between 1 and 99 will cause the tool to identify the percentage of logical cores to use by applying the formula (Parallel Processing Factor / 100 * Logical Cores) rounded up to the nearest integer. If the result of this formula is 0 or 1, parallel processing will not be enabled.

  • This tool relies on the input features having a spatial index. Use the Add Spatial Index tool to create an index (particularly for shapefiles) or rebuild an existing index if there is any doubt about it being correct.

  • As described in How Buffer works, an important feature of the Buffer tool is the Method parameter, which determines how buffers are constructed. The two basic methods for constructing buffers, Euclidean and geodesic, are described as follows:

    • Euclidean buffers measure distance in a two-dimensional Cartesian plane, where straight-line or Euclidean distances are calculated between two points on a flat surface (the Cartesian plane). Euclidean buffers are the more common type of buffer and are appropriate when you're analyzing distances around features in a projected coordinate system that are concentrated in a relatively small area (such as one UTM zone).
    • Geodesic buffers account for the actual shape of the earth (an ellipsoid, or more properly, a geoid). Distances are calculated between two points on a curved surface (the geoid) as opposed to two points on a flat surface (the Cartesian plane). You should always consider creating geodesic in the following circumstances:
      • Your input features are dispersed (cover multiple UTM zones, large regions, or even the entire globe).
      • The spatial reference (map projection) of your input features distorts distances to preserve other properties such as area.
      Geodesic buffers may appear unusual on a flat map. When displayed on a globe, however, these buffers will look correct (you can also use a 3D scene or ArcGIS Earth to view geographic data on a three-dimensional globe). For more information, see How Buffer works.

    The Method parameter determines how buffers are created.

    • Planar (method = "PLANAR" in Python) is the default option. This option will automatically determine which method to use based on the coordinate system of the input.
      • If the input features have a projected coordinate system, Euclidean buffers will be created.
      • If the input features have a geographic coordinate system and you specify a Buffer Distance value in linear units (meters, feet, and so forth, as opposed to angular units such as degrees), geodesic buffers will be created.
      • This option produces the same result as the Buffer tool prior to ArcGIS 10.3.
    • Geodesic (method = "GEODESIC" in Python) creates a shape-preserving geodesic buffer regardless of the input coordinate system. The shape-preserving geodesic buffer densifies the input features prior to creating the output geodesic buffers to create buffers that more closely represent the input features' shape. If you are concerned about the shape of your buffers and how closely their shape matches the original input features, it is recommended that you investigate using this option, particularly when your input data is in a geographic coordinate system. In some cases, this may take more time than the geodesic buffer created using the Planar option, but the result is a buffer that more accurately matches the shape of the input feature.

    Note:

    You can change the coordinate system of a feature class using the Project tool, or you can set the Output Coordinate System geoprocessing environment before executing the Buffer tool, and this coordinate system will be used when creating buffers.

    When using the Planar method, you can improve the accuracy of buffers created with projected inputs using a projection that minimizes distance distortion, such as an Equidistant Conic or an Azimuthal Equidistant projection, and is geographically appropriate for your input.

  • When buffering features in a projected coordinate system with output to a geodatabase feature class, the geometries created may contain circular arc segments (when buffering points, the output will always be circular arcs). If buffers containing circular arcs are reprojected to a different coordinate system, the location and size of the original buffers will be transformed, but the shape of the buffers will not change, causing the reprojected buffers to no longer accurately represent the area covered by the original buffer. If you reproject buffers containing circular arcs, first use the Densify tool to convert circular arc segments to straight lines, Then reproject the densified buffers.

  • The output feature class will include a BUFF_DIST field that contains the buffer distance used to buffer each feature in the linear unit of the input's coordinate system. When using the Geodesic method to create buffers, the buffer distance entered will be converted to meters in all cases.

    If a field named BUFF_DIST exists in the input, its values will be overwritten in the output. If a Dissolve Type of All or List (ALL or LIST in Python) is used, the output will not include this field.

  • The output feature class will include a ORIG_FID field that contains the feature ID of the input feature for which the buffer was created. If a field named ORIG_FID exists in the input, its values will be overwritten in the output. If a Dissolve Type of All or List is used, the output will not include this field.

  • When buffering polygon features, negative buffer distances can be used to create buffers inside the polygon features. Using a negative buffer distance will reduce the polygons' boundaries by the distance specified.

    Caution:

    If the negative buffer distance is large enough to collapse the polygon to nothing, a null geometry will be generated. A warning message will appear, and no null geometry features will be written to the output feature class.

  • If a field from the input is used to obtain buffer distances, the field's values can be either a number (5, for example) or a number with a valid linear unit (5 Kilometers, for example). If a field value is a number, it is assumed that the distance is in the linear unit of the input's spatial reference (unless the input is in a geographic coordinate system, in which case, the value is assumed to be in meters). If the linear unit specified in the field values is invalid or not recognized, the linear unit of the input's spatial reference will be used by default.

    Using a buffer field for buffer distances
  • The Add Field button in the Dissolve Field(s) parameter is used only in ModelBuilder. In ModelBuilder, when the preceding tool has not been run or its derived data does not exist, the Dissolve Field(s) parameter may not be populated with field names. The Add Field button allows you to add expected fields to the Dissolve Field(s) list to complete the Buffer tool dialog box.

  • Buffer operations do not support the transfer of z-values from the input to the output buffer features.

  • Buffer operations do not support the transfer of m-values from the input to the output buffer features.

Syntax

arcpy.analysis.PairwiseBuffer(in_features, out_feature_class, buffer_distance_or_field, {dissolve_option}, {dissolve_field}, {method}, {max_deviation})
ParameterExplanationData Type
in_features

The input point, line, or polygon features to be buffered.

Feature Layer
out_feature_class

The feature class containing the output buffers.

Feature Class
buffer_distance_or_field

The distance around the input features that will be buffered. Distances can be provided as either a value representing a linear distance or as a field from the input features that contains the distance to buffer each feature.

If linear units are not specified or are entered as Unknown, the linear unit of the input features' spatial reference is used.

When specifying a distance, if the desired linear unit has two words, such as Decimal Degrees, combine the two words into one (for example, 20 DecimalDegrees).

Linear Unit; Field
dissolve_option
(Optional)

Specifies the type of dissolve operation to be performed to remove buffer overlap.

  • NONEAn individual buffer for each feature will be maintained, regardless of overlap. This is the default.
  • ALLAll buffers will be dissolved together into a single feature, removing any overlap.
  • LISTAny buffers sharing attribute values in the listed fields (carried over from the input features) will be dissolved.
String
dissolve_field
[dissolve_field,...]
(Optional)

The list of fields from the input features on which the output buffers will be dissolved. Any buffers sharing attribute values in the listed fields (carried over from the input features) will be dissolved.

Field
method
(Optional)

Specifies the method to use, planar or geodesic, to create the buffer.

  • PLANARIf the input features are in a projected coordinate system, Euclidean buffers will be created. If the input features are in a geographic coordinate system and the buffer distance is in linear units (meters, feet, and so forth, as opposed to angular units such as degrees), geodesic buffers will be created. This is the default. You can use the Output Coordinate System environment setting to specify the coordinate system to use. For example, if your input features are in a projected coordinate system, you can set the environment to a geographic coordinate system to create geodesic buffers.
  • GEODESICAll buffers will be created using a shape-preserving geodesic buffer method, regardless of the input coordinate system.
String
max_deviation
(Optional)

The maximum distance the resulting output buffer polygon boundary will deviate from the true buffer boundary.

The true buffer boundary is a curve. However, the resulting polygon boundary is a densified polyline. Using this parameter, you can control how the output polygon boundary approximates the true buffer boundary.

If this parameter is not set or is set to 0, the tool will identify the maximum deviation. It is recommended that you use the default value. Performance degradation (in the tool and in subsequent analyses) may result from using a maximum offset deviation that is too small.

See the max_deviation parameter information in the Densify tool documentation for details.

Linear Unit

Code sample

PairwiseBuffer example 1 (Python window)

The following Python window script demonstrates how to use the PairwiseBuffer function.

import arcpy
arcpy.env.workspace = "C:/data"
arcpy.PairwiseBuffer_analysis("roads", "C:/output/majorrdsBuffered", "100 Feet", 
                              "LIST", "Distance")
PairwiseBuffer example 2 (stand-alone script)

Find areas of suitable vegetation that exclude areas heavily impacted by major roads.

# Name: PairwiseBuffer.py
# Description: Find areas of suitable vegetation that exclude areas heavily 
#              impacted by major roads.

# Import system modules 
import arcpy

# Set environment settings
arcpy.env.workspace = "C:/data/Habitat_Analysis.gdb"

# Select suitable vegetation patches from all vegetation
veg = "vegtype"
suitableVeg = "C:/output/Output.gdb/suitable_vegetation"
whereClause = "HABITAT = 1" 
arcpy.Select_analysis(veg, suitableVeg, whereClause)

# Buffer areas of impact around major roads
roads = "majorrds"
roadsBuffer = "C:/output/Output.gdb/buffer_output"
distanceField = "Distance"
dissolveType = "LIST"
dissolveField = "Distance"
arcpy.PairwiseBuffer_analysis(roads, roadsBuffer, distanceField, dissolveType, 
                              dissolveField)

# Erase areas of impact around major roads from the suitable vegetation patches
eraseOutput = "C:/output/Output.gdb/suitable_vegetation_minus_roads"
xyTol = "1 Meters"
arcpy.Erase_analysis(suitableVeg, roadsBuffer, eraseOutput, xyTol)

Licensing information

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

Related topics