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 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})
ParameterExplanationData 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.

  • NO_LOCATIONThe coordinates are not added to the input feature. This is the default.
  • LOCATIONThe coordinates are added to the input feature.
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.

  • NO_ANGLEThe angles will not be added to the input's attribute table. This is the default.
  • ANGLEThe horizontal arithmetic angle and vertical angle will be added to the NEAR_ANG_H and NEAR_ANG_V fields in the input's 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.

  • NO_DELTANo distances will be added to the input attribute table. This is the default.
  • DELTADistances along the X, Y, and Z axes will be calculated in the NEAR_DELTX, NEAR_DELTY, and NEAR_DELTZ fields.
Boolean

Derived Output

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

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

# 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')

Licensing information

  • Basic: Requires 3D Analyst
  • Standard: Requires 3D Analyst
  • Advanced: Requires 3D Analyst

Related topics