Raster To Multipoint (3D Analyst)

Summary

Converts raster cell centers to 3D multipoint features with z-values that reflect the raster cell value.

Usage

• Consider using this tool if you have raster elevation data and require access to the functional capabilities provided by a triangulated surface, as multipoint features can be loaded into a TIN or terrain dataset.

• When the Input Raster parameter value is very large in size, consider using the Thinning Method parameter to reduce the number of cells that are exported to the multipoint feature class. The options are as follows:

  • Z Tolerance—Thin cells while preserving vertical accuracy.
  • Kernel—Thin cells while controlling the horizontal sample distance.
  • VIP—Use this option if the resulting multipoints will be primarily applied for visualization applications. This method is relatively fast, outputs a predictable number of points, and identifies local peaks and pits. However, it is sensitive to noise and may ignore topographic features that span an extent that is larger than the 3 cell by 3 cell area.
  • VIP Histogram—Use this option as an initial step to apply the VIP option, as it produces a histogram of the significance scores reflecting the number of points that will be selected with each incrementing percentile value.

Parameters

Dialog

Label	Explanation	Data Type
Input Raster	The raster that will be processed.	Raster Layer; Mosaic Layer
Output Feature Class	The feature class that will be produced.	Feature Class
Output VIP table (Optional)	The histogram table that will be created when VIP Histogram is specified for the Thinning Method parameter. The histogram table that will be created when VIP_HISTOGRAM is specified for the method parameter.	Table
Thinning Method (Optional)	Specifies the thinning method that will be applied to the input raster to select a subset of cells that will be exported to the multipoint feature class. No Thinning—No thinning will be applied. This is the default. Z Tolerance—Only the cells that are required for maintaining a surface within a specified z-range of the input raster will be exported. Kernel—The raster will be divided into equal-sized tiles based on the Thinning Value parameter value, and one or two cells that meet the Kernel Method parameter value will be exported. VIP—A roving 3-cell-by-3-cell window will be used to create a three-dimensional best fit plane. Each cell is given a significance score based on its absolute deviation from this plane. A histogram of these scores is then used to determine the cells that will be exported based on the Thinning Value parameter value. VIP Histogram—A table will be created containing the significance values and the corresponding number of points associated with those values.	String
Kernel Method (Optional)	Specifies the selection method that will be used in each kernel neighborhood when kernel thinning is applied on the input raster. Minimum—A point will be created at the cell with the smallest elevation value found in the kernel neighborhood. This is the default. Maximum—A point will be created at the cell with the largest elevation value found in the kernel neighborhood. Minimum and Maximum—Two points will be created at the cells with the smallest and largest z-values found in the kernel neighborhood. Closest to Mean—A point will be created at the cell whose elevation value is closest to the average of the cells in the kernel neighborhood.	String
Z Factor (Optional)	The factor by which z-values will be multiplied. This is typically used to convert z linear units to match x,y linear units. The default is 1, which leaves elevation values unchanged. This parameter is not available if the spatial reference of the input surface has a z-datum with a specified linear unit.	Double
Thinning Value (Optional)	The thinning value associated with the Thinning Method parameter value. Z Tolerance—The maximum allowable difference in z-units between the input raster and the surface created from the output multipoint feature class. The default value is one-tenth of the z-range of the input raster. Kernel—The number of raster cells along the edge of each tile. The default value is 3, which means that the raster will be divided into 3-cell-by-3-cell windows. VIP—The percentile rank of the histogram of significance scores. The default value is 5.0, which means that the cells with scores within the top 5 percent of the histogram will be exported.	Double

Python

arcpy.ddd.RasterToMultipoint(in_raster, out_feature_class, {out_vip_table}, {method}, {kernel_method}, {z_factor}, {thinning_value})

Name	Explanation	Data Type
in_raster	The raster that will be processed.	Raster Layer; Mosaic Layer
out_feature_class	The feature class that will be produced.	Feature Class
out_vip_table (Optional)	The histogram table that will be created when VIP Histogram is specified for the Thinning Method parameter. The histogram table that will be created when VIP_HISTOGRAM is specified for the method parameter.	Table
method (Optional)	Specifies the thinning method that will be applied to the input raster to select a subset of cells that will be exported to the multipoint feature class. NO_THIN—No thinning will be applied. This is the default. ZTOLERANCE—Only the cells that are required for maintaining a surface within a specified z-range of the input raster will be exported. KERNEL—The raster will be divided into equal-sized tiles based on the Thinning Value parameter value, and one or two cells that meet the Kernel Method parameter value will be exported. VIP—A roving 3-cell-by-3-cell window will be used to create a three-dimensional best fit plane. Each cell is given a significance score based on its absolute deviation from this plane. A histogram of these scores is then used to determine the cells that will be exported based on the Thinning Value parameter value. VIP_HISTOGRAM—A table will be created containing the significance values and the corresponding number of points associated with those values.	String
kernel_method (Optional)	Specifies the selection method that will be used in each kernel neighborhood when kernel thinning is applied on the input raster. MIN—A point will be created at the cell with the smallest elevation value found in the kernel neighborhood. This is the default. MAX—A point will be created at the cell with the largest elevation value found in the kernel neighborhood. MINMAX—Two points will be created at the cells with the smallest and largest z-values found in the kernel neighborhood. MEAN—A point will be created at the cell whose elevation value is closest to the average of the cells in the kernel neighborhood.	String
z_factor (Optional)	The factor by which z-values will be multiplied. This is typically used to convert z linear units to match x,y linear units. The default is 1, which leaves elevation values unchanged. This parameter is not available if the spatial reference of the input surface has a z-datum with a specified linear unit.	Double
thinning_value (Optional)	The thinning value associated with the method parameter value. ZTolerance—The maximum allowable difference in z-units between the input raster and the surface created from the output multipoint feature class. The default value is one-tenth of the z-range of the input raster. KERNEL—The number of raster cells along the edge of each tile. The default value is 3, which means that the raster will be divided into 3-cell-by-3-cell windows. VIP—The percentile rank of the histogram of significance scores. The default value is 5.0, which means that the cells with scores within the top 5 percent of the histogram will be exported.	Double

Code sample

RasterToMultipoint example 1 (Python window)

The following sample demonstrates the use of this tool in the Python window:

arcpy.env.workspace = "C:/data"
arcpy.ddd.RasterToMultipoint("elevation.tif", out_vip_table="elev_VIP.dbf", 
                            method="VIP_HISTOGRAM", z_factor=1)

RasterToMultipoint example 2 (stand-alone script)

The following sample demonstrates the use of this tool in a stand-alone Python script:

'''*********************************************************************
Name: RasterToMultipoint Example
Description: This script demonstrates how to use
             the RasterToMultipoint tool to create multipoint datasets
             fot all IMG rasters in a target workspace.
**********************************************************************'''
# Import system modules
import arcpy

# Set default workspace
arcpy.env.workspace = "C:/data"
# Create the list of IMG rasters
rasterList = arcpy.ListRasters("*", "IMG")
# Loop the process for each raster
if rasterList:
    for raster in rasterList:
        # Set Local Variables
        # [:-4] strips the last 4 characters (.img) from the raster name
        outTbl = "VIP_" + raster[:-4] + ".dbf"
        method = "VIP_HISTOGRAM"
        zfactor = 1
        #Execute RasterToMultipoint
        arcpy.ddd.RasterToMultipoint(raster, "",outTbl, method, "", zfactor)
else:
    print("There are no IMG rasters in the " + env.workspace + " directory.")

Environments

Current Workspace, Output Coordinate System, Extent, Geographic Transformations, XY Resolution, XY Tolerance, Z Resolution, Z Tolerance, Output XY Domain, Output Z Domain, Output CONFIG Keyword, Auto Commit