Near 3D (3D Analyst)
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 geometry types are supported, and all input feature classes must have Z values.
The Near Features can include one or more feature classes of different shape types.
The Near Features can be the same dataset as the Input Features. When an input feature's nearest Near Feature is itself (distance is 0), this feature is ignored and the next nearest feature is found.
The basic difference between the Near tool and the Near 3D tool is that the Near 3D tool works with 3D features instead of 2D features. Furthermore, the distances that are compared by the Near 3D tool are the 3D (slope) distances, rather than the horizontal distances. A number of additional fields can be output as well.
The angle fields will only be created and populated if the Angle option is enabled.
The following fields are appended to the input feature's attribute table:
- NEAR_FID—The FID of the nearest Near feature.
- NEAR_DIST—The 2D distance (horizontal distance) between the nearest point on an input feature and the nearest point on the nearest Near feature.
- NEAR_DIST3—The 3D distance (slope distance) between the nearest point on an input feature and the nearest point on the nearest Near feature.
- NEAR_DELTX—The distance along the X axis from the nearest point on the input feature to the nearest point on the nearest Near feature.
- NEAR_DELTY—The distance along the Y axis from the nearest point on the input feature to the nearest point on the nearest Near feature.
- NEAR_DELTZ—The distance along the Z axis from the nearest point on the input feature to the nearest point on the nearest Near feature.
- NEAR_FROMX—The X coordinate of the nearest point on the input feature nearest to the nearest point on the nearest Near feature.
- NEAR_FROMY—The Y coordinate of the nearest point on the input feature nearest to the nearest point on the nearest Near feature.
- NEAR_FROMZ—The Z coordinate of the nearest point on the input feature nearest to the nearest point on the nearest Near feature.
- NEAR_X—The X coordinate of the nearest point on the nearest Near feature, or of the nearest imaginary point along the nearest Near feature.
- NEAR_Y—The Y coordinate of the nearest point on the nearest Near feature, or of the nearest imaginary point along the nearest Near feature.
- NEAR_Z—The Z coordinate of the nearest point on the nearest Near feature, or of the nearest imaginary point along the nearest Near feature.
- NEAR_ANG_H—The horizontal geographic angle (north azimuth), in degrees, between the nearest point on the input feature and the nearest point on the nearest Near feature. It is the same system as used by the older Near tool; it is not an azimuth or a bearing. Due east is zero, northeast is 45, due north is 90, due south is -90, and due west is 180 or -180. This value disregards elevation.
- NEAR_ANG_V—The vertical angle (aka the elevation angle, or angle of elevation), in degrees, from the nearest point on the input feature to the nearest point on the nearest Near feature. Horizontal is zero, straight up is 90, straight down is -90, up at 10 degrees above horizontal is 10.
- NEAR_FC—The path of the feature class containing the nearest Near feature. This field is only added when multiple Near Features are specified.
If the aforementioned fields already exist, their value gets updated.
The values for NEAR_FID, NEAR_DIST, and NEAR_DIST3 will be -1 if no match is found within the Search Radius.
The NEAR_DELTX, NEAR_DELTY, and NEAR_DELTZ fields will only be created and populated if the Delta option is enabled.
The NEAR_FROMX, NEAR_FROMY, NEAR_FROMZ, NEAR_X, NEAR_Y, and NEAR_Z fields will only be created and populated if the Location check box is checked.
This tool is a 3D set operator that provides analytical functions on 3D features. See Working with 3D set operators for more information on what set operators are and how to use them.
Syntax
| 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 |
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 between Input Features and Near Features for which distance and FID will be determined. If no Search Radius is specified, all Near Features will be used. | Linear Unit |
location (Optional) |
Determines whether six coordinate fields (two sets of XYZ values) are added to each input feature. The values are the three coordinates of the input feature (NEAR_FROMX, NEAR_FROMY, NEAR_FROMZ), and the three coordinates of the nearest feature (NEAR_X, NEAR_Y, NEAR_Z). The fields NEAR_FID and NEAR_DIST are always added, regardless of the Location option.
| Boolean |
angle (Optional) |
Determines whether the angles between the input feature and the nearest near feature will be calculated and stored into the NEAR_ANG_H and NEAR_ANG_V fields. Both angle values are in degrees, where one degree represents 1/360 of a circle, and fractions of a degree are represented as decimal points. Horizontal angles are measured from 180° to -180°; 0° to the east, 90° to the north, 180° (-180°) to the west, and -90° to the south. Vertical angles are zero for horizontal, 90° for straight up, and -90° for straight down.
| Boolean |
delta (Optional) |
Determines whether the distances along the primary axes between the input feature and the nearest near feature will be calculated and stored into the NEAR_DELTX, NEAR_DELTY, and NEAR_DELTZ fields.
| Boolean |
Code Sample
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")
The following sample demonstrates how to use 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)