Nearest Neighbor 3D (Geostatistical Analyst)

Available with Geostatistical Analyst license.

Summary

Creates a voxel layer source file (netCDF) from categorical 3D points by assigning each voxel the categories of the nearest neighbor in 3D.

Learn more about voxel layers

Illustration

A voxel layer displays the soil and rock classes of the closest 3D point.

Usage

• If the tool is run in a local scene with the same horizontal and vertical coordinate systems as the input features, a voxel layer will be added to the scene allowing you to interactively explore the results. You can also add the output netCDF file as a voxel layer using the Make Multidimensional Voxel Layer tool or the Add Multidimensional Voxel Layer dialog box.

  You can convert the output netCDF file to a multidimensional raster using the Copy Raster tool. You can also add it to a map as a feature or raster layer using the Make NetCDF Feature Layer tool or Make NetCDF Raster Layer tool, respectively.

• The input features must be 3D points with elevations stored in the Shape.Z geometry attribute. You can convert 2D point features with an elevation field into 3D point features using the Feature To 3D By Attribute tool.

  It is recommended that the input features have a vertical coordinate system that accurately defines their z-coordinates. You can assign a vertical coordinate system to the points using the Define Projection tool.

• If multiple fields are specified in the Category fields parameter, the output netCDF file will contain a separate variable for each field. Each variable will have the same name as the category field. You can choose the variable to display in a scene when adding the voxel layer to a scene.

  For example, you can provide a field of soil classes (shale, sand, clay, and so on) and a second field of soil color, and each voxel in the output netCDF file will contain the soil class and soil color of the nearest neighbor.

• The Input study area polygons, Minimum elevation clipping raster, and Maximum elevation clipping raster parameters can be used to limit the analysis within a specific study area and between two elevation surfaces. Any voxels outside these bounds will have no value and will not display. For example, if the points are located within a marine preserve, you can create a voxel layer that displays only within a polygon of the preserve (study area), above the ocean floor (minimum elevation raster), and below the thermocline (maximum elevation raster).

  There are various considerations for using elevation surfaces as minimum or maximum elevation rasters. Image services, web elevation layers, and web imagery layers will have the slowest performance and errors may occur for large numbers of queries. Rasters saved as local files on disk will have the fastest performance and are recommended when creating high-resolution voxel layers over large spatial extents.

• The count and percent of the number of voxels of each category will be returned as geoprocessing messages. Voxels with null values (such as voxels outside the input study area polygons) will not be included in the counts or percentages. If multiple category fields are provided, separate messages will be returned for each field.

• The input features and the minimum and maximum elevation clipping rasters must be in a projected coordinate system. If the points or rasters have a geographic coordinate system with latitude and longitude coordinates, they must be projected to a projected coordinate system using the Project or Project Raster tool.

• For each category field, each unique value will be saved in the output netCDF file as an integer. After sorting (ascending) the unique values, the first category is assigned the integer 0, the next category is assigned the integer 1, and so on. When added to a scene as a discrete voxel layer, unique value symbology applies the original values of the category field as labels to the integers.

  When the values of a category field are integers, the integers representing the categories in the netCDF file will generally be different than the original integers in the category field. The symbology labels of the voxel layer can be used to determine the original integer categories.

• When laying out the 3D grid of points that will represent the voxels, the first point is created at the minimum x-, minimum y-, and minimum z-coordinate of the output extent (by default, the extent of the input features). The remaining points are created by iterating the X spacing, Y spacing, and Elevation spacing parameter distances through the dimensions of the output extent. If any of the spacing distances do not evenly divide the corresponding dimension of the output extent, one row or column of points will be created beyond the output extent. For example, if the output extent for x is specified as 0 through 10 and the X spacing parameter is specified as 3, the output will have five rows in the x-extent: 0, 3, 6, 9, and 12. Similarly, an additional row or column of points will be created if the spacing distances do not evenly divide the y- or z-extents.

• If input study area polygons are provided, the extent of the study area will be used as the default output extent, and the X spacing and Y spacing parameter values will recalculate based on this extent. This ensures that the output will fill the entirety of the study area by default.

• If the input features contain coincident points (points with the same x-, y-, and z-coordinate) that have different values of the category field, the first alphanumeric category will be used at the location.

• If the input features have a selection, the values of the X spacing, Y spacing, and Elevation spacing parameters will recalculate while the tool is running based on the extent of the selected features. The recalculated values will print as warning messages when the tool completes. If you manually provide a value for a spacing parameter (or provide an output extent), the value will not recalculate.

Parameters

Dialog

Label	Explanation	Data Type
Input features	The input points representing locations with known categories in 3D. The points must be in a projected coordinate system, and there must be at least three points.	Feature Layer
Category fields	The fields of the input features containing the categories of each point. For each field, the unique values of the field represent the categories of the field. Each field must be Text, Short, or Long type. For example, you can provide a field of soil classes (shale, sand, clay, and so on) and a second field of the color of the soil (yellow, brown, white, and so on). Each voxel in the output netCDF file will store the nearest soil class and soil color as separate variables.	Field
Output netCDF file	The output netCDF file containing categories in a 3D grid. Each point in the 3D grid is assigned the category of the closest input point. This file can be used as the data source of a voxel layer.	File
X spacing (Optional)	The spacing between each gridded point in the x-dimension. The default value creates 40 points along the output x-extent.	Linear Unit
Y spacing (Optional)	The spacing between each gridded point in the y-dimension. The default value creates 40 points along the output y-extent.	Linear Unit
Elevation spacing (Optional)	The spacing between each gridded point in the elevation (z) dimension. The default value creates 40 points along the output z-extent.	Linear Unit
Elevation inflation factor (Optional)	A constant value that is multiplied to the elevation (z-coordinates) of the input points prior to finding the nearest neighbor. Values larger than 1 will search farther horizontally than vertically to find the nearest neighbor. For example, a value of 10 means that each voxel will search 10 times farther horizontally than vertically to find the closest neighbor. The default is 1, meaning that the elevations are not adjusted. The value must be between 1 and 1,000. Elevation inflation is only used to find the nearest neighbor, and all elevations are returned to the original scale before creating the output netCDF file. Elevation inflation is recommended when the categories of the input points tend to be similar along horizontal strata, such as with soil classes and rock types.	Double
Input study area polygons (Optional)	The polygon features that represent the study area. Only points that are within the study area are saved in the output netCDF file. When visualized as a voxel layer, only voxels within the study area will display in the scene. Points are determined to be inside or outside the study area using only their x- and y-coordinates.	Feature Layer
Minimum elevation clipping raster (Optional)	The elevation raster that will be used to clip the bottom of the voxel layer. Only voxels above this elevation raster will be assigned predictions. For example, if you use a ground elevation raster, the voxel layer will only display above the ground. It can also be used for bedrock surfaces or the bottom of a shale deposit. The raster must be in a projected coordinate system, and the elevation values must be in the same unit as the vertical unit of the raster.	Raster Layer
Maximum elevation clipping raster (Optional)	The elevation raster that will be used to clip the top of the voxel layer. Only voxels below this elevation raster will be assigned predictions. For example, if you use a ground elevation raster, the voxel layer will only display below the ground. It can also be used to clip voxels to the top of a restricted airspace. The raster must be in a projected coordinate system, and the elevation values must be in the same unit as the vertical unit of the raster.	Raster Layer

Derived Output

Label	Explanation	Data Type
Output voxel layer	A voxel layer of the categories.	Voxel Layer

Python

arcpy.ga.NearestNeighbor3D(in_features, category_field, out_netcdf_file, {x_spacing}, {y_spacing}, {elevation_spacing}, {elev_inflation_factor}, {in_study_area}, {min_elev_raster}, {max_elev_raster})

Name	Explanation	Data Type
in_features	The input points representing locations with known categories in 3D. The points must be in a projected coordinate system, and there must be at least three points.	Feature Layer
category_field [category_field,...]	The fields of the input features containing the categories of each point. For each field, the unique values of the field represent the categories of the field. Each field must be Text, Short, or Long type. For example, you can provide a field of soil classes (shale, sand, clay, and so on) and a second field of the color of the soil (yellow, brown, white, and so on). Each voxel in the output netCDF file will store the nearest soil class and soil color as separate variables.	Field
out_netcdf_file	The output netCDF file containing categories in a 3D grid. Each point in the 3D grid is assigned the category of the closest input point. This file can be used as the data source of a voxel layer.	File
x_spacing (Optional)	The spacing between each gridded point in the x-dimension. The default value creates 40 points along the output x-extent.	Linear Unit
y_spacing (Optional)	The spacing between each gridded point in the y-dimension. The default value creates 40 points along the output y-extent.	Linear Unit
elevation_spacing (Optional)	The spacing between each gridded point in the elevation (z) dimension. The default value creates 40 points along the output z-extent.	Linear Unit
elev_inflation_factor (Optional)	A constant value that is multiplied to the elevation (z-coordinates) of the input points prior to finding the nearest neighbor. Values larger than 1 will search farther horizontally than vertically to find the nearest neighbor. For example, a value of 10 means that each voxel will search 10 times farther horizontally than vertically to find the closest neighbor. The default is 1, meaning that the elevations are not adjusted. The value must be between 1 and 1,000. Elevation inflation is only used to find the nearest neighbor, and all elevations are returned to the original scale before creating the output netCDF file. Elevation inflation is recommended when the categories of the input points tend to be similar along horizontal strata, such as with soil classes and rock types.	Double
in_study_area (Optional)	The polygon features that represent the study area. Only points that are within the study area are saved in the output netCDF file. When visualized as a voxel layer, only voxels within the study area will display in the scene. Points are determined to be inside or outside the study area using only their x- and y-coordinates.	Feature Layer
min_elev_raster (Optional)	The elevation raster that will be used to clip the bottom of the voxel layer. Only voxels above this elevation raster will be assigned predictions. For example, if you use a ground elevation raster, the voxel layer will only display above the ground. It can also be used for bedrock surfaces or the bottom of a shale deposit. The raster must be in a projected coordinate system, and the elevation values must be in the same unit as the vertical unit of the raster.	Raster Layer
max_elev_raster (Optional)	The elevation raster that will be used to clip the top of the voxel layer. Only voxels below this elevation raster will be assigned predictions. For example, if you use a ground elevation raster, the voxel layer will only display below the ground. It can also be used to clip voxels to the top of a restricted airspace. The raster must be in a projected coordinate system, and the elevation values must be in the same unit as the vertical unit of the raster.	Raster Layer

Derived Output

Name	Explanation	Data Type
out_voxel_layer	A voxel layer of the categories.	Voxel Layer

Code sample

NearestNeighbor3D example 1 (Python window)

The following Python script demonstrates how to use the NearestNeighbor3D function.

# Create a voxel layer source file of 3D soil class points within a field
# and between a bedrock layer and the ground.
arcpy.ga.NearestNeighbor3D("SoilPoints", "SoilClass","outputNCDF.nc",
                           "50 Meters", "50 Meters", "5 Meters", 1,
                           "MyStudyArea", "Bedrock.tif", "WorldElevation3D")

NearestNeighbor3D example 2 (stand-alone script)

The following Python script demonstrates how to use the NearestNeighbor3D function.

# Name: NearestNeighbor3D_Example_02.py
# Description: Creates a voxel layer source file from 3D categorical points.
# Requirements: Geostatistical Analyst Extension
# Author: Esri


# Create a voxel layer source file of 3D soil class points within a field
# and between a bedrock layer and the ground.



# Import system modules
import arcpy

# Allow overwriting output
arcpy.env.overwriteOutput = True

# Define 3D input points with categories
in3DPoints = "C:/gapydata/inputs.gdb/my3DSoilPoints"
categoryField = "SoilClass"
outNetCDF = "C:/gapydata/outputs/SoilClassVoxel.nc"

# Define voxel dimensions and elevation inflation
xSpacing = "50 Meters"
ySpacing = "50 Meters"
elevSpacing = "5 Meters"
elevInflation = 1

# Define study area, bedrock elevation layer, and ground elevation layer
studyArea = "C:/gapydata/inputs.gdb/StudyAreaPolygon"
minElevRaster = "C:/gapydata/inputs.gdb/BedrockDepth"
maxElevRaster = "C:/gapydata/inputs.gdb/WorldElevationDEM"


# Check out the ArcGIS Geostatistical Analyst extension license
arcpy.CheckOutExtension("GeoStats")

# Execute Nearest Neighbor 3D
arcpy.ga.NearestNeighbor3D(in3DPoints, categoryField,outNetCDF,
                           xSpacing, ySpacing, elevSpacing,
                           elevInflation, studyArea, minElevRaster,
                           maxElevRaster)

Environments

Extent, Geographic Transformations, Output Coordinate System, Parallel Processing Factor

Licensing information

• Basic: Requires Geostatistical Analyst
• Standard: Requires Geostatistical Analyst
• Advanced: Requires Geostatistical Analyst