采样 (空间分析)

需要 Spatial Analyst 许可。

获得 Image Analyst 许可后可用。

摘要

创建一个表或点要素类,其中显示从一个栅格或一组栅格提取的已定义位置的像元值。 该位置由栅格像元、点、折线或面进行定义。

了解有关“采样”工作原理的详细信息

使用情况

  • 系统将从每个位置的所有输入栅格(Python 中的 in_rasters)中提取像元值。 系统将使用包含每个输入栅格像元值的字段创建一个表格或点要素类。

  • 输入栅格表中的其他属性(若有的话)将不会包含在输出表中。

  • 可以为输入栅格指定任意栅格(单波段或多波段)组合。 如果输入栅格是多维的,输出表的结构会自动发生更改。

    将多波段栅格指定为输入栅格之一时,将使用该输入中的所有波段。

  • 以下各项可以用作输入位置栅格或要素(Python 中的 in_location_data)参数值:

    • 栅格 - 包含有效值(非 NoData)的像元将用于从所有输入栅格中提取像元值,且像元的中心将用作点位置。
    • 点 - 将在每个点位置对值进行采样。
    • 折线或面 - 如果输入是二维栅格或多个栅格,则将计算与每个折线或面相交的所有像元的平均值。 如果输入为多维栅格并作为多维进行处理,则可以指定其他统计类型。

  • 从输入栅格的 NoData 像元中提取值的位置将在输出表中被赋予 <空> 值。 对于 shapefile,由于不支持空字段,因此 NoData 像元在表中以值 -9999 表示。

  • 系统将以输入栅格的原有空间参考和分辨率对其进行采样。 如果存在多个具有不同空间参考的输入栅格,则系统会先将输入位置分别投影到每个栅格的空间参考,然后提取值。 这意味着尽管输入栅格将不支持任何分析环境设置,但会将适当的环境应用于输入位置。

  • 默认情况下,输出表或要素类中的 x,y 坐标的空间参考(Python 中的 out_table)参数将与输入位置栅格或要素参数值相同,除非在“输出坐标系”环境中指定了其他值。 如果输入位置数据的空间参考未知,则 x,y 坐标的空间参考也将是未知的。

    x,y 坐标的空间参考在工具执行结束时被报告为地理处理消息。

  • 如果输入位置栅格或要素为点要素类且不包含空间索引,将发出一则警告。 要提升具有大量点的输入的工具性能,请创建空间索引。 有关详细信息,请参阅添加空间索引

  • 该工具无法使用多点要素执行。 要使用多点要素执行分析,请将其转换为单点要素,然后在提取工具中使用。 有关详细信息,请参阅处理多点数据

  • 如果将重采样技术参数设置为最邻近(Python 中的 resampling_type = "NEAREST"),则输出表中的字段类型将与栅格类型的字段类型相匹配。 为了保持内插值的精度,如果重采样选项为双线性三次卷积,则字段类型将始终为浮点型。

  • 一个字段将被添加到输出表中,以存储唯一 ID 字段参数(Python 中的 unique_id_field)中指定的值。 默认情况下,该字段的名称与输入位置数据集的名称相同。 建议使用包含唯一值的字段作为每个位置的标识符以供进一步分析。

  • 如果未选中以多维方式处理参数(Python 中的 process_as_multidimensional = "CURRENT_SLICE"),将适用于以下条件:

    • 如果输入是多维栅格,则仅对当前切片进行采样。
    • 如果输入是多元栅格,则仅对当前变量进行采样。

  • 如果选中以多维方式处理参数(Python 中的 process_as_multidimensional = "ALL_SLICES"),将适用于以下条件:

    • 如果输入是多维栅格,则将对所有切片进行采样。
    • 如果输入是多元栅格,则将对所有变量进行采样。
    • 如果输入是具有多个变量的多维栅格,则将对所有变量的所有切片进行采样。 变量必须具有相同的维度。

  • 如果选中以多维方式处理参数(Python 中的 process_as_multidimensional = "ALL_SLICES"),则会适用于来自下列内容的适当情景:

    • 位置数据采集信息参数(Python 中的 acquisition_definition)将用来指定用于采样的输入栅格的子集。

      • 指定维度、开始值和结束值时,将处理开始值和结束值内的切片。 默认的结束值是最大维度值。 对于时间维度,请以标准格式指定值。 对于其他维度,请以与输入栅格相同的单位指定值。

      • 指定维度、开始字段和结束字段(开始字段和结束字段来自位置数据)时,这些字段中的值用于在该位置采样值时指定输入栅格的子集。

      • 相对值或之前的天数相对值或之后的天数值可用于指定相对于开始值的子集,其中前值指定子集的开始,后值指定子集的结束。 时间值是以天为单位进行指定,而其他维度值则以与输入栅格相同的单位加以指定。

    • 统计数据类型参数(Python 中的 statistics_type)聚合由位置数据采集信息参数中的子集指定的输入栅格参数的值。

    • 如果未选中列式布局参数(Python 中的 layout = "ROW_WISE"),则提取的值将存储在与变量同名的字段中。 将创建附加字段,以存储与维度的名称相同的非空间维度值。

    • 如果选中列式布局参数(Python 中的 layout = "COLUMN_WISE"),则提取的值将存储在名称遵循 <variable_name>_<dimension_name>_<dimension_value> 约定的字段中。 请注意,当多维栅格仅包含一个变量,变量仅具有一个维度并且每个剖切具有单个波段时,将支持列式布局参数。 否则,将生成错误消息。

    • 如果多维栅格具有多个波段,则将为每个波段创建一个附加字段,用于存储从该波段提取的值。

    • 系统将为从 NoData 像元提取值的位置分配来自输入多维栅格的 NoData 值。

  • 多维栅格可以是 netCDF 栅格图层多维栅格图层多维镶嵌数据集、多维 CRF、多维影像服务或 netCDF 文件。 您不能从工具对话框浏览到 netCDF 文件,但可以指定文件的路径。

  • 如果选中生成要素类参数(Python 中的 generate_feature_class = "FEATURE_CLASS"),输出将是在属性表中包含采样值的点要素类。 以下是可能的位置类型,并说明了如何对值采样:

    • 栅格 - 将使用像元中心的位置创建点。
    • 点 - 将在每个点位置创建点。
    • 折线或面 - 将在每个面或折线质心处创建点。

  • 除非在输出坐标系环境中已指定输出要素类的空间参考,否则该空间参考将与输入位置栅格或要素的空间参考相同。

  • 仅当选中以多维方式处理参数时,才支持并行处理因子环境。

  • 如果在掩膜环境中指定了要素,则将使用输入栅格的最小像元大小来创建内部栅格。 在提取期间,内部掩膜栅格再次被重新采样为每个输入栅格的像元大小。

  • 有关适用于此工具的地理处理环境的详细信息,请参阅分析环境和 Spatial Analyst

参数

标注说明数据类型
输入栅格

将根据输入位置数据对栅格值进行采样。

仅当输入为单个多维栅格时,以多维方式处理参数才可用。

Raster Layer
输入位置栅格数据或要素

标识将要进行采样的位置的数据。

输入可以是栅格或要素类。

Raster Layer; Feature Layer
输出表或要素类。

包含采样像元值的输出表或要素类。

输出格式由输出位置和路径确定。 默认情况下,输出将是地理数据库工作空间中的地理数据库表或地理数据库要素类,或者文件夹工作空间中的 dBASE 表或 shapefile 要素类。

生成表或要素类的输出数据类型由 生成要素类参数控制。

Table; Point feature class
重采样技术
(可选)

此重采样算法将用于对栅格进行采样,以确定如何从栅格中获取值。

  • 最邻近将使用最邻近分配法。 这是默认设置。
  • 双线性将使用双线性插值法。
  • 三次卷积将使用三次卷积插值法。
String
唯一 ID 字段
(可选)

包含输入位置栅格或要素中每个位置或要素不同值的字段。

Field
以多维方式处理
(可选)

指定如何处理输入栅格。

仅当输入为单个多维栅格时,该参数才可用。

  • 未选中 - 将处理来自多维数据集的当前剖切片的样本。 这是默认设置。
  • 选中 - 将处理来自多维数据集的所有维度(如时间或深度)的样本。
Boolean
位置数据采集信息
(可选)

指定与位置要素关联的时间、深度或其他采集数据。

仅支持以下组合:

  • 维度 + 开始字段或值
  • 维度 + 开始字段或值 + 结束字段或值
  • 维度 + 开始字段或值 + 相对值或之前的天数 + 相对值或之后的天数

相对值或之前的天数相对值或之后的天数仅支持非负值。

将使用统计类型参数计算该维度范围内变量的统计数据。

Value Table
统计类型
(可选)

指定要计算的统计数据类型。

  • 最小值将计算指定范围内的最小值。
  • 最大值将计算指定范围内的最大值。
  • 中值将计算指定范围内的中值。
  • 平均值将计算指定范围的平均值。
  • 总和将计算指定范围内变量的总值。
  • 众数将计算出现次数最多的值。
  • 少数将计算出现次数最少的值。
  • 标准差将计算标准差。
  • 百分比数将计算指定范围内定义的百分比。
String
百分比值
(可选)

该值范围可以介于 0 到 100 之间。 默认值为 90。

Double
缓冲距离字段或值
(可选)

位置数据要素周围的距离。 缓冲距离以位置要素空间参考的线性单位指定。 如果要素使用地理参考,则单位将为度。

将在此缓冲区区域内计算统计数据。

Double; Field
列式布局
(可选)

指定采样值将在输出表中以行还是以列显示。

  • 未选中 - 采样值将在输出表中以单独行显示。 这是默认设置。
  • 选中 - 采样值将在输出表中以单独列显示。 仅当输入多维栅格包含一个变量和一个维度并且每个剖切为单波段栅格时,此选项才有效。
Boolean
生成要素类
(可选)

指定将生成在其属性表中具有采样值的点要素类,还是仅会生成具有采样值的表。

  • 未选中 - 将生成具有采样值的表。 这是默认设置。
  • 选中 - 将生成在其属性表中具有采样值的点要素类。
Boolean

Sample(in_rasters, in_location_data, out_table, {resampling_type}, {unique_id_field}, {process_as_multidimensional}, {acquisition_definition}, {statistics_type}, {percentile_value}, {buffer_distance}, {layout}, {generate_feature_class})
名称说明数据类型
in_rasters
[in_raster,...]

将根据输入位置数据对栅格值进行采样。

仅当输入为单个多维栅格时,process_as_multidimensional 参数才受支持。

Raster Layer
in_location_data

标识将要进行采样的位置的数据。

输入可以是栅格或要素类。

Raster Layer; Feature Layer
out_table

包含采样像元值的输出表或要素类。

输出格式由输出位置和路径确定。 默认情况下,输出将是地理数据库工作空间中的地理数据库表或地理数据库要素类,或者文件夹工作空间中的 dBASE 表或 shapefile 要素类。

生成表或要素类的输出数据类型由 generate_feature_class 参数控制。

Table; Point feature class
resampling_type
(可选)

此重采样算法将用于对栅格进行采样,以确定如何从栅格中获取值。

  • NEAREST将使用最邻近分配法。 这是默认设置。
  • BILINEAR将使用双线性插值法。
  • CUBIC将使用三次卷积插值法。
String
unique_id_field
(可选)

包含输入位置栅格或要素中每个位置或要素不同值的字段。

Field
process_as_multidimensional
(可选)

指定如何处理输入栅格。

仅当输入为单个多维栅格时,该参数才可用。

  • ALL_SLICES将处理来自多维数据集的所有维度(如时间或深度)的样本。
  • CURRENT_SLICE将处理来自多维数据集的当前剖切片的样本。 这是默认设置。
Boolean
acquisition_definition
[acquisition_definition,...]
(可选)

指定与位置要素关联的时间、深度或其他采集数据。

仅支持以下组合:

  • 维度 + 开始字段或值
  • 维度 + 开始字段或值 + 结束字段或值
  • 维度 + 开始字段或值 + 相对值或之前的天数 + 相对值或之后的天数

Relative value or days beforeRelative value or days after 仅支持非负值。

将使用 statistics_type 参数计算该维度范围内变量的统计数据。

Value Table
statistics_type
(可选)

指定要计算的统计数据类型。

  • MINIMUM将计算指定范围内的最小值。
  • MAXIMUM将计算指定范围内的最大值。
  • MEDIAN将计算指定范围内的中值。
  • MEAN将计算指定范围的平均值。
  • SUM将计算指定范围内变量的总值。
  • MAJORITY将计算出现次数最多的值。
  • MINORITY将计算出现次数最少的值。
  • STD将计算标准差。
  • PERCENTILE将计算指定范围内定义的百分比。
String
percentile_value
(可选)

统计数据类型参数设置为百分比数时,要计算的百分比数。

statistics_type 参数设置为 PERCENTILE 时,要计算的百分比数。

该值范围可以介于 0 到 100 之间。 默认值为 90。

Double
buffer_distance
(可选)

位置数据要素周围的距离。 缓冲距离以位置要素空间参考的线性单位指定。 如果要素使用地理参考,则单位将为度。

将在此缓冲区区域内计算统计数据。

Double; Field
layout
(可选)

指定采样值将在输出表中以行还是以列显示。

  • ROW_WISE采样值将在输出表中以单独行显示。 这是默认设置。
  • COLUMN_WISE采样值将在输出表中以单独列显示。 仅当输入多维栅格包含一个变量和一个维度并且每个剖切为单波段栅格时,此选项才有效。
Boolean
generate_feature_class
(可选)

指定将生成在其属性表中具有采样值的点要素类,还是仅会生成具有采样值的表。

  • TABLE将生成具有采样值的表。 这是默认设置。
  • FEATURE_CLASS将生成在其属性表中具有采样值的点要素类。
Boolean

代码示例

采样示例 1(Python 窗口)

将多个栅格的像元值提取到基于输入位置的表中。

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
Sample(["elevation", "costraster"], "observers.shp",
       "c:/sapyexamples/output/samptable","NEAREST")
采样示例 2(独立脚本)

将多个栅格的像元值提取到基于输入位置的表中。

# Name: Sample_Ex_02.py
# Description: Creates a feature class that shows the values of cells from 
#              rasters, for defined locations. 
#              The locations are defined by a set of points.
#              Sampling method is Bilinear.
# Requirements: Spatial Analyst Extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *

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

# Set the analysis environments
env.workspace = "C:/sapyexamples/data"

# Set local variables
inRasters = ["elevation",
             "costraster"]
locations = "observers.shp"
outFeatureClass = "c:/sapyexamples/output/samptable02.shp"
sampMethod = "BILINEAR"
generate_feature_class = "FEATURE_CLASS"

# Execute Sample
Sample(inRasters, locations, outFeatureClass, sampMethod, "", "", "", "", "", "", "", generate_feature_class)
采样示例 3(独立脚本)

将多个栅格的像元值提取到基于输入位置的表中。

# Name: Sample_Ex_03.py
# Description: Creates a table that shows the temperature values from 
#              a multidimensional raster, for defined locations. 
#              The locations are defined by a set 
#              of points.
# Requirements: Spatial Analyst Extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *

# Set environment settings
env.workspace = "C:/sapyexamples/data"

# Set local variables
inRasters = "temperature_1990_2019.nc"
locations = "observers.shp"
outTable = "C:/sapyexamples/output/samptable_03"
sampMethod = ""
uniqueIDField = "FID"
process_as_multidimensional = True

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

# Execute Sample
# the temperature value at each slice in temperature_1990_2019.nc will be extracted for each point
Sample(inRasters, locations, outTable, sampMethod, uniqueIDField, process_as_multidimensional)
采样示例 4(独立脚本)

将多个栅格的像元值提取到基于输入位置的表中。

# Name: Sample_Ex_04.py
# Description: Creates a table that shows, for each polygon, the maximum temperature value within the period [1999-01-01T00:00:00 , 2019-01-01-T00:00:00]
# Requirements: Spatial Analyst Extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *

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

# Set environment settings
env.workspace = "C:/sapyexamples/data"

# Set local variables
inRasters = "temperature_1990_2019.nc"
locations = "observers_polygons.shp"
outTable = "C:/sapyexamples/output/samptable_04.dbf"
sampMethod = "BILINEAR"
uniqueIDField = "OBSERVATIONID"
process_as_multidimensional = True
# StdTime in acquisition_definition is the name of the dimension in inRasters that are related with time
# 1999-01-01T00:00:00 in acquisition_definition is the start time of the period
# 2019-01-01-T00:00:00 in acquisition_definition is the end time of the period
acquisition_definition = "StdTime 1999-01-01T00:00:00 2019-01-01-T00:00:00"
statistic_method = "MAXIMUM"

# Execute Sample
# for each polygon in locations, the maximum temperature value within the period [1999-01-01T00:00:00 , 2019-01-01-T00:00:00] will be extracted
Sample(inRasters, locations, outTable, sampMethod, uniqueIDField, process_as_multidimensional, acquisition_definition, statistic_method)