Summary
Calculates the three-dimensional distance from each input feature to the nearest feature that resides in one or more near feature classes.
Usage
All input features must have Z values, and all geometry types are supported. The input features can also be specified as the near features to determine the closest features within the same feature class.
The following fields may be added to the input feature's attribute table:
- NEAR_FID—The FID of the nearest feature. A value of -1 indicates no match was found within the specified search radius
- NEAR_DIST—The 2D distance (horizontal distance) between the nearest point on an input feature and the nearest point on the nearest feature.
- NEAR_DIST3—The 3D distance (slope distance) between the nearest point on an input feature and the nearest point on the nearest feature.
- NEAR_DELTX—The distance along the X axis from the nearest point on the input feature to the nearest point on the nearest feature.
- NEAR_DELTY—The distance along the Y axis from the nearest point on the input feature to the nearest point on the nearest feature.
- NEAR_DELTZ—The distance along the Z axis from the nearest point on the input feature to the nearest point on the nearest feature.
- NEAR_FROMX—The X coordinate of the nearest point on the input feature to the nearest feature.
- NEAR_FROMY—The Y coordinate of the nearest point on the input feature to the nearest feature.
- NEAR_FROMZ—The Z coordinate of the nearest point on the input feature to the nearest feature.
- NEAR_X—The X coordinate of the nearest point on the nearest feature.
- NEAR_Y—The Y coordinate of the nearest point on the nearest feature.
- NEAR_Z—The Z coordinate of the nearest point on the nearest feature.
- NEAR_ANG_H—The horizontal arithmetic angle to the nearest point expressed in degrees.
- NEAR_ANG_V—The angle of elevation to the nearest point expressed in degrees. Horizontal is zero, straight up is 90, straight down is -90.
- NEAR_FC—The path of the feature class containing the nearest feature. This field is only added when multiple Near Features are specified.
Note:
If the aforementioned fields already exist, their values will be updated.
Syntax
arcpy.3d.Near3D(in_features, near_features, {search_radius}, {location}, {angle}, {delta})
Parameter | Explanation | Data Type |
in_features | The input feature class whose features will be attributed with information about the nearest feature. | Feature Layer |
near_features [near_features,...] | The one or more features whose proximity to the input features will be calculated. If multiple feature classes are specified, an additional field named NEAR_FC will be added to the input feature class to identify which near feature class contained the closest feature. | Feature Layer |
search_radius (Optional) | The maximum distance for which the nearest features from a given input will be determined. If no value is specified, the nearest feature at any distance will be determined. | Linear Unit |
location (Optional) | Determines whether the coordinates of the nearest point in the input and near feature will be added to the input's attribute table.
| Boolean |
angle (Optional) | Determines whether the horizontal arithmetic angle and vertical angle between the input feature and the nearest feature will be added to the input attribute table.
| Boolean |
delta (Optional) | Determines whether the distances along the X, Y, and Z axes between the input feature and the nearest feature will be added to the input attribute table.
| Boolean |
Derived Output
Name | Explanation | Data Type |
out_feature_class | The updated input features. | Feature Layer |
Code sample
The following sample demonstrates the use of this tool in the Python window.
arcpy.env.workspace = "C:/data"
arcpy.Near3D_3d("points_3D.shp", "buildings_multipatch.shp", "30", "LOCATION", "ANGLE", "DELTA")
The following sample demonstrates the use of this tool in a stand-alone Python script.
'''****************************************************************************
Name: Near 3D Example
Description: This script demonstrates how to use
the Near 3D tool to identify the nearest z-aware features
that satisfy the results from a queried feature.
****************************************************************************'''
# Import system modules
import arcpy
# Set environment settings
arcpy.env.workspace = 'C:/data'
# Set Local Variables
inFC = 'homes.shp'
nearFC = 'radiotowers.shp'
# See the 'Building an SQL expression' topic for more information
# Query the field 'MATERIAL' for the string 'Reinforced Concrete'
SQL_Expression = "'"'MATERIAL'"' = 'Reinforced Concrete'"
#Execute Make Feature Layer
arcpy.MakeFeatureLayer_management(nearFC, 'Near Layer', SQL_Expression)
result = arcpy.GetCount_management('Near Layer')
if int(result.getOutput(0)) == 0:
arcpy.AddMessage('{0} has no features that satisfy the query: {1}'\
.format(nearFC, SQL_Expression))
else:
#Execute Near3D
arcpy.Near3D_3d(inFC, 'nearLayer', '', 'LOCATION', 'ANGLE')
Environments
Licensing information
- Basic: Requires 3D Analyst
- Standard: Requires 3D Analyst
- Advanced: Requires 3D Analyst