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.
Syntax
arcpy.ddd.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
Near3D example 1 (Python window)
The following sample demonstrates the use of this tool in the Python window.
import arcpy
from arcpy import env
arcpy.CheckOutExtension("3D")
env.workspace = "C:/data"
arcpy.Near3D_3d("points_3D.shp", "buildings_multipatch.shp", "30", "LOCATION", "ANGLE", "DELTA")
Near3D example 2 (stand-alone script)
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
import exceptions, sys, traceback
from arcpy import env
try:
# Obtain a license for the ArcGIS 3D Analyst extension
arcpy.CheckOutExtension('3D')
# Set environment settings
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')
except arcpy.ExecuteError:
print arcpy.GetMessages()
except:
# Get the traceback object
tb = sys.exc_info()[2]
tbinfo = traceback.format_tb(tb)[0]
# Concatenate error information into message string
pymsg = 'PYTHON ERRORS:\nTraceback info:\n{0}\nError Info:\n{1}'\
.format(tbinfo, str(sys.exc_info()[1]))
msgs = 'ArcPy ERRORS:\n {0}\n'.format(arcpy.GetMessages(2))
# Return python error messages for script tool or Python Window
arcpy.AddError(pymsg)
arcpy.AddError(msgs)
Environments
Licensing information
- Basic: Requires 3D Analyst
- Standard: Requires 3D Analyst
- Advanced: Requires 3D Analyst