Disponible avec une licence Spatial Analyst.
Disponible avec une licence Image Analyst.
Résumé
Crée une table ou une classe d’entités ponctuelles indiquant les valeurs de cellule d’un raster ou d’un jeu de rasters, pour des emplacements définis. Les emplacements sont définis par des cellules raster, des points, des polylignes ou des polygones.
Pour en savoir plus sur le Fonctionnement de l'outil Echantillon
Utilisation
Les valeurs de cellule sont extraites de tous les rasters en entrée (in_rasters dans Python) pour chaque emplacement. Une table ou une classe d’entités ponctuelles est créée avec des champs contenant les valeurs de cellule de chaque raster en entrée.
Les éventuels attributs supplémentaires de la table raster en entrée ne seront pas inclus dans la table en sortie.
Vous pouvez spécifier n’importe quelle combinaison de rasters (monocanal ou multicanal) pour les rasters en entrée. La structure de la table en sortie change automatiquement lorsque les rasters en entrée sont multidimensionnels.
Lorsqu’un raster multicanal est spécifié comme l’un des rasters en entrée, tous les canaux de cette entrée sont utilisés.
Les éléments suivants peuvent être utilisés comme valeurs du paramètre Input location raster or features (Raster d’emplacement ou entités en entrée) (in_location_data dans Python) :
- Raster : les cellules contenant des valeurs valides (différentes de NoData) sont utilisées pour extraire les valeurs de cellule de tous les rasters en entrée, et le centre de la cellule est utilisé comme emplacement des points.
- Point : les valeurs sont échantillonnées à chaque emplacement de point.
- Polyligne ou polygone : la valeur moyenne de toutes les cellules qui intersectent chaque polyligne ou polygone est calculée si l’entrée est un raster à deux dimensions, ou plusieurs rasters. D’autres types de statistiques peuvent être spécifiés si l’entrée est un raster multidimensionnel et qu’elle est traitée comme telle.
Les emplacements qui extraient des valeurs des cellules NoData dans le raster en entrée se voient attribuer la valeur <null> dans la table en sortie. Les champs null n’étant pas pris en charge pour les fichiers de forme, les cellules NoData sont représentées dans la table par la valeur -9999.
Les rasters en entrée sont échantillonnés avec leur référence spatiale et leur résolution natives. S’il existe plusieurs rasters en entrée avec des références spatiales différentes, les emplacements en entrée sont d’abord projetés dans la référence spatiale de chaque raster individuel, puis les valeurs sont extraites. Ainsi, bien que les rasters en entrée ne respectent pas les paramètres d’environnement d’analyse, les environnements appropriés sont appliqués aux emplacements en entrée.
Par défaut, la référence spatiale des coordonnées x,y du paramètre Output table or feature class (Table ou classe d’entités en sortie) (out_table dans Python) est la même que celle des valeurs du paramètre Input location raster or features (Raster d’emplacement ou entités en entrée), sauf si une valeur différente est spécifiée pour le paramètre d’environnement Système de coordonnées en sortie. Si la référence spatiale des données d’emplacements en entrée est inconnue, la référence spatiale des coordonnées x,y est également inconnue.
La référence spatiale des coordonnées x,y est indiquée à la fin de l’exécution de l’outil sous forme de message de géotraitement.
Si le champ Input location raster or features (Raster d’emplacement ou entités en entrée) est une classe d’entités ponctuelles sans index spatial, un avertissement est émis. Pour améliorer les performances de l’outil pour une entrée comportant de nombreux points, créez un index spatial. Reportez-vous à la rubrique Ajouter un index spatial pour plus d’informations.
L’outil ne peut pas être exécuté avec les entités multi-points. Pour effectuer l’analyse avec des entités multi-points, convertissez-les en entités ponctuelles uniques avant de les utiliser dans l’outil d’extraction. Reportez-vous à la rubrique Traitement des données multi-points pour plus d'informations.
Lorsque la valeur du paramètre Resampling technique (Technique de rééchantillonnage) est Nearest (Le plus proche) (resampling_type = "NEAREST" dans Python), le type de champ de la table en sortie correspond à celui du type de raster. Lorsque l’option de rééchantillonnage est Bilinear (Bilinéaire) ou Cubic (Cubique), le type de champ est toujours à virgule flottante afin de préserver la précision des valeurs interpolées.
Un champ est ajouté à la table en sortie pour stocker les valeurs spécifiées dans le paramètre Unique ID field (Champ d’identifiant unique) (unique_id_field dans Python). Par défaut, le nom du champ est identique à celui du jeu de données d’emplacement en entrée. Il est recommandé d’utiliser un champ contenant des valeurs uniques pour identifier chaque emplacement pour une analyse approfondie.
Si le paramètre Process as multidimensional (Traiter comme multidimensionnel) n’est pas activé (process_as_multidimensional = "CURRENT_SLICE" dans Python), les conditions suivantes s’appliquent :
- Si l’entrée est un raster multidimensionnel, seule la tranche actuelle est échantillonnée.
- Si l’entrée est un raster multivarié, seule la variable actuelle est échantillonnée.
Si le paramètre Process as multidimensional (Traiter comme multidimensionnel) est activé (process_as_multidimensional = "ALL_SLICES" dans Python), les conditions suivantes s’appliquent :
- Si l’entrée est un raster multidimensionnel, toutes les tranches sont échantillonnées.
- Si l’entrée est un raster multivarié, toutes les variables sont échantillonnées.
- Si l’entrée est un raster multidimensionnel à plusieurs variables, toutes les tranches de toutes les variables sont échantillonnées. Les variables doivent avoir les mêmes dimensions.
Si le paramètre Process as multidimensional (Traiter comme multidimensionnel) est activé (process_as_multidimensional = "ALL_SLICES" dans Python), le scénario approprié parmi les suivants s’applique :
Le paramètre Acquisition information of location data (Informations d’acquisition des données d’emplacement) (acquisition_definition dans Python) est utilisé pour spécifier le sous-ensemble du raster en entrée à utiliser pour l’échantillonnage.
Lorsque la dimension, la valeur de départ et la valeur de fin sont spécifiées, les tranches comprises entre les valeurs de départ et de fin sont traitées. La valeur de fin par défaut est la valeur de dimension maximale. Pour une dimension temporelle, spécifiez la valeur au format standard. Pour les autres dimensions, spécifiez la valeur dans la même unité que celle du raster en entrée.
Lorsque la dimension, le champ de départ et le champ de fin sont spécifiés (les champs de départ et de fin proviennent des données d’emplacement), les valeurs de ces champs sont utilisées pour spécifier un sous-ensemble du raster en entrée lors de l’échantillonnage des valeurs pour cet emplacement.
Les valeurs des paramètres Relative value or days before (Valeur relative ou jours avant) et Relative value or days after (Valeur relative ou jours après) peuvent être utilisées pour spécifier un sous-ensemble relatif à la valeur de départ, dans lequel la valeur before (avant) indique le début du sous-ensemble et la valeur after (après), la fin du sous-ensemble. Les valeurs de temps sont spécifiées en jours et les valeurs des autres dimensions, dans la même unité que celle du raster en entrée.
Le paramètre Statistic type (Type de statistique) (statistics_type dans Python) cumule les valeurs du paramètre Input raster (Raster en entrée) comme indiqué par le sous-ensemble du paramètre Acquisition information of location data (Informations d’acquisition des données d’emplacement).
Si le paramètre Column-wise layout (Mise en page en colonnes) est désactivé (layout = "ROW_WISE" dans Python), les valeurs extraites sont stockées dans un champ portant le même nom que la variable. Des champs supplémentaires sont créés pour stocker les valeurs de dimensions non spatiales portant le même nom que la dimension.
Si le paramètre Column-wise layout (Mise en page en colonnes) est activé (layout = "COLUMN_WISE" dans Python), les valeurs extraites sont stockées dans des champs dont les noms suivent la convention <variable_name>_<dimension_name>_<dimension_value>. Notez que le paramètre Column-wise layout (Mise en page en colonnes) est pris en charge lorsque le raster multidimensionnel contient une seule variable, que la variable n’a qu’une dimension et que chaque tranche est monocanale. Dans le cas contraire, un message d’erreur est généré.
Si le raster multidimensionnel contient plusieurs canaux, un champ supplémentaire est créé pour chaque canal, dans lequel est stockée la valeur extraite de ce canal.
La valeur NoData du raster multidimensionnel en entrée est attribuée aux emplacements qui extraient des valeurs des cellules NoData.
Un raster multidimensionnel peut être une couche raster netCDF, une couche raster multidimensionnelle, un jeu de données mosaïque multidimensionnel, un fichier CRF multidimensionnel, un service d’imagerie multidimensionnel ou un fichier netCDF. Vous ne pouvez pas accéder à un fichier netCDF à partir de la boîte de dialogue de l’outil, mais vous pouvez spécifier le chemin du fichier.
Si le paramètre Generate Feature Class (Générer une classe d’entités) est activé (generate_feature_class = "FEATURE_CLASS" dans Python), la sortie est une classe d’entités ponctuelles comportant les valeurs échantillonnées dans sa table attributaire. Les types d’emplacements possibles, ainsi qu’une description du mode d’échantillonnage des valeurs, sont décrits ci-dessous.
- Raster : les points sont créés à partir de l’emplacement du centre de la cellule.
- Point : un point est créé à chaque emplacement de point.
- Polyligne ou polygone : un point est créé à chaque centroïde de polygone ou de polyligne.
La référence spatiale de la classe d’entités en sortie est identique à celle du paramètre Input location raster or features (Raster d’emplacement ou entités en entrée), sauf si elle est spécifiée dans le paramètre d’environnement Système de coordonnées en sortie.
L’environnement Parallel Processing Factor (Facteur de traitement parallèle) est seulement pris en charge si le paramètre Process as multidimensional (Traiter comme multidimensionnel) est activé.
Si une entité est spécifiée dans l’environnement de masque, un raster interne est créé en utilisant la taille de cellule minimum des rasters en entrée. Lors de l’extraction, le raster de masque interne est à nouveau ré-échantillonné sur la taille de cellule de chaque raster en entrée.
Pour plus d’informations sur les environnements de géotraitement qui s’appliquent à cet outil, reportez-vous à la rubrique Environnements d’analyse et Spatial Analyst.
Syntaxe
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})| Paramètre | Explication | Type de données |
in_rasters [in_raster,...] | Rasters dont les valeurs sont échantillonnées en fonction des données d’emplacement en entrée. Le paramètre process_as_multidimensional est uniquement pris en charge lorsque l’entrée est un raster multidimensionnel unique. | Raster Layer |
in_location_data | Données identifiant les positions où un échantillon sera prélevé. L’entrée peut être un raster ou une classe d’entités. | Raster Layer; Feature Layer |
out_table | Table ou classe d’entités en sortie contenant les valeurs de cellule échantillonnées. Le format de sortie est déterminé par l’emplacement et le chemin d’accès en sortie. Par défaut, la sortie est une table de géodatabase ou une classe d’entités de géodatabase dans un espace de travail de géodatabase, ou une table dBASE ou une classe d’entités de shapefile dans un espace de travail de dossier. Le type de données en sortie pour la génération d’une table ou d’une classe d’entités est contrôlé par le paramètre generate_feature_class. | Table; Point feature class |
resampling_type (Facultatif) | Algorithme de rééchantillonnage à utiliser pour échantillonner un raster afin de déterminer comment obtenir les valeurs de celui-ci.
| String |
unique_id_field (Facultatif) | Champ qui contient une valeur différente pour chaque emplacement ou entité du raster d’emplacement ou des entités en entrée. | Field |
process_as_multidimensional (Facultatif) | Indique comment les rasters en entrée sont traités. Ce paramètre est uniquement disponible lorsque l’entrée est un raster multidimensionnel unique.
| Boolean |
acquisition_definition [acquisition_definition,...] (Facultatif) | Spécifie l’heure, la profondeur ou les autres données d’acquisition liées aux entités d’emplacement. Seules les associations suivantes sont prises en charge :
Relative value or days before et Relative value or days after ne prennent en charge que les valeurs non négatives. Les statistiques sont calculées à l’aide du paramètre statistics_type pour les variables situées dans cette plage de dimensions. | Value Table |
statistics_type (Facultatif) | Spécifie le type de statistique à calculer.
| String |
percentile_value (Facultatif) | Pourcentage à calculer lorsque le paramètre Statistics Type (Type de statistique) est défini sur Percentile (Pourcentage). Centile à calculer lorsque le paramètre statistics_type est défini sur PERCENTILE. Cette valeur peut être comprise entre 0 et 100. La valeur par défaut est 90. | Double |
buffer_distance (Facultatif) | Distance autour des entités de données d’emplacement. La distance de la zone tampon est exprimée dans l’unité linéaire de la référence spatiale de l’entité d’emplacement. Si l’entité utilise une référence géographique, l’unité utilisée est le degré. Les statistiques sont calculées dans cette zone tampon. | Double; Field |
layout (Facultatif) | Indique si les valeurs échantillonnées apparaissent en lignes ou en colonnes dans la table en sortie.
| Boolean |
generate_feature_class (Facultatif) | Spécifie si une classe d’entités ponctuelles comportant les valeurs échantillonnées dans sa table attributaire ou une table comportant les valeurs échantillonnées, sera créée.
| Boolean |
Exemple de code
Extraire les valeurs de cellule de plusieurs rasters vers une table, en fonction de localisations en entrée.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
Sample(["elevation", "costraster"], "observers.shp",
"c:/sapyexamples/output/samptable.dbf")Extraire les valeurs de cellule de plusieurs rasters vers une table, en fonction de localisations en entrée.
# 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)Extraire les valeurs de cellule de plusieurs rasters vers une table, en fonction de localisations en entrée.
# Name: Sample_Ex_03.py
# Description: Creates a table that shows the temperature values from
# a multidimensional raster, for defined locations.
# Each temperature has a unique OBSERVATION_ID
# 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 = "temperature_1990_2019.nc"
locations = "observers.shp"
outTable = "C:/sapyexamples/output/samptable_03.dbf"
sampMethod = "BILINEAR"
uniqueIDField = "OBSERVATION_ID"
process_as_multidimensional = True
# 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)Extraire les valeurs de cellule de plusieurs rasters vers une table, en fonction de localisations en entrée.
# 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)Environnements
Informations de licence
- Basic: Requiert Spatial Analyst ou Image Analyst
- Standard: Requiert Spatial Analyst ou Image Analyst
- Advanced: Requiert Spatial Analyst ou Image Analyst
Rubriques connexes
Vous avez un commentaire à formuler concernant cette rubrique ?