Near 3D (3D Analyst)

License Level:BasicStandardAdvanced

Summary

Calculates the three-dimensional distance from each input feature to the nearest feature that resides in one or more near feature classes.

Usage

Syntax

Near3D_3d (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

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.

  • NO_LOCATIONThe X,Y, and Z coordinates are not saved. This is the default.
  • LOCATIONThe X,Y, and Z coordinates are saved. Six additional attribute fields are added to each input field.
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.

  • NO_ANGLEThe angle will not be saved. This is the default.
  • ANGLEThe angles will be added to the result, and the fields will be created if they don't already exist.
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.

  • NO_DELTANo deltas will be calculated. This is the default.
  • DELTADeltas will be calculated. Three additional fields (NEAR_DELTX, NEAR_DELTY, and NEAR_DELTZ) will be added to the result.
Boolean

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

Related Topics

Licensing Information

ArcGIS for Desktop Basic: Requires 3D Analyst
ArcGIS for Desktop Standard: Requires 3D Analyst
ArcGIS for Desktop Advanced: Requires 3D Analyst
3/7/2014