Utilisation d'outils dans Python

Chaque outil de géotraitement dispose d'un ensemble défini de paramètres qui lui fournissent les informations nécessaires pour son exécution. Les outils contiennent généralement des paramètres en entrée définissant le(s) jeu(x) de données utilisé(s) pour créer les nouvelles données en sortie. Les paramètres possèdent plusieurs propriétés importantes :

Nom	Chaque paramètre de l'outil porte un nom unique.
Type	Type de données attendu, tel que classe d'entités, entier, chaîne ou raster.
Direction	Paramètre définissant les valeurs en entrée ou en sortie.
Requis	Définit si une valeur doit être spécifiée pour un paramètre ou s'il est facultatif.

Lorsqu'un outil est utilisé dans un script, ses valeurs de paramètres doivent être correctement définies pour pouvoir lancer l'outil lorsque le script est exécuté. La documentation de chaque outil définit clairement ses paramètres et ses propriétés. Lorsqu'un ensemble valide de valeurs de paramètres est spécifié, l'outil peut être exécuté.

Les paramètres sont spécifiés sous forme de chaînes ou d'objets. Les chaînes correspondent simplement à un texte identifiant de façon unique une valeur de paramètre telle qu'un chemin vers un jeu de données ou un mot-clé.

La plupart des paramètres d'outil peuvent être spécifiés en tant que chaîne simple. Pour certains paramètres, tels qu'une référence spatiale, vous pouvez utiliser un objet au lieu d'une chaîne. Dans l'exemple de code suivant, les paramètres en entrée et en sortie sont définis pour l'outil Zone tampon. Notez que l'alias de boîte à outils est toujours ajouté au nom d'outil. Dans cet exemple, deux variables de chaîne servent à définir les paramètres en entrée et en sortie afin de faciliter la lecture de l'appel à l'outil.

import arcpy

roads = "c:/St_Johns/data.gdb/roads"
output = "c:/St_Johns/data.gdb/roads_Buffer"

# Run Buffer using the variables set above and pass the remaining parameters
#   in as strings
#
arcpy.Buffer_analysis(roads, output, "distance", "FULL", "ROUND", "NONE")

Dans l'exemple de code ci-dessous, l'outil CreateFeatureClass est exécuté à l'aide d'un objet de référence spatiale pour le paramètre facultatif Coordinate System. L'objet de référence spatiale est créé à l'aide de la classe SpatialReference et ses informations sont chargées à partir d'un fichier de projection.

import arcpy

inputWorkspace = "c:/temp"
outputName =  "rivers.shp"

# Create a spatial reference object
#
spatialRef = arcpy.SpatialReference()

# Use a projection file to define the spatial reference's properties
#
spatialRef.createFromFile("c:/program files/arcgis/Desktop10.0/Coordinate Systems/" + \
                          "Projected Coordinate Systems/Continental/North America/North America Equidistant Conic.prj")

# Run CreateFeatureclass using the spatial reference object
#
arcpy.CreateFeatureclass_management(inputWorkspace, outputName, 
                                    "POLYLINE", "", "", "", spatialRef)

Organisation des outils

Les outils de géotraitement sont organisés de deux manières différentes. Tous les outils sont disponibles en tant que fonctions dans ArcPy mais également dans des modules correspondant au nom d'alias de boîte à outils. Bien que la plupart des exemples dans l'aide présentent des outils organisés en tant que fonctions disponibles à partir d'ArcPy, les deux approches sont également valables. L'approche utilisée dépend des préférences personnelles et des habitudes de codage. Dans l'exemple suivant, l'outil GetCount est présenté avec ces deux approches.

import arcpy

inFeatures = "c:/temp/rivers.shp"

# Tools can be accessed as functions on the arcpy module, and
#  from modules matching the toolbox name.
#
arcpy.GetCount_management(inFeatures)
arcpy.management.GetCount(inFeatures)

Lors de l'utilisation d'outils dans des modules, il peut parfois s'avérer utile d'attirer l'attention sur l'identification d'un module afin de rendre votre script plus lisible. Dans ce cas, vous pouvez utiliser la forme from - import - as.

# Clean up street centerlines that were digitized without having set
#  proper snapping environments
#
import arcpy
from arcpy import edit as EDIT
from arcpy import management as DM

streets = "c:/data/streets.gdb/majorrds"
streetsCopy = "c:/output/Output.gdb/streetsBackup"

DM.CopyFeatures(streets, streetsBackup)
EDIT.TrimLine(streets, "10 Feet", "KEEP_SHORT")
EDIT.ExtendLine(streets, "15 Feet", "EXTENSION")

Licence :

Les outils Spatial Analyst sont gérés différemment pour prendre en charge l'algèbre spatiale et sont uniquement disponibles dans le module arcpy.sa et non en tant que fonctions dans ArcPy.

Obtention de résultats à partir d'un outil

ArcPy retourne les valeurs en sortie d'un outil lorsqu'il est exécuté en tant qu'objet Result. L'objet Result vous permet de conserver les informations relatives à l'exécution d'outils, y compris les messages, paramètres et résultats. Ces résultats peuvent être conservés même après avoir exécuté plusieurs autres outils.

Les exemples suivants indiquent comment obtenir la sortie à partir d'un objet Result après l'exécution d'un outil de géotraitement.

import arcpy

arcpy.env.workspace = "D:/St_Johns/data.gdb"

# Geoprocessing tools return a result object of the derived 
#   output dataset. 
#
result = arcpy.CopyFeatures_management("roads", "urban_roads")

# A print statement will display the string 
#   representation of the output.
#
print result 

# To get the output value, the result object has a getOutput method
#
resultValue = result.getOutput(0)

 

Remarque :

La méthode getOutput de l'objet Result retourne une chaîne Unicode des objets de résultat ayant des valeurs en sortie. Cela s'avère particulièrement important lors de l'exécution d'un outil tel que GetCount, qui fournit le nombre d'enregistrements dans une table ou CalculateDefaultClusterTolerance, qui fournit une valeur de tolérance d'agrégat. Pour convertir la valeur dans le type attendu, elle doit être convertie à partir d'une chaîne Unicode à l'aide de fonctions Python intégrées telles que int() ou float().

import arcpy
from arcpy import env
import types

env.workspace = "c:/St_Johns/data.gdb"

# Many geoprocessing tools return a result object of the derived 
#   output dataset. A print statement will display the string 
#   representation of the output.
#
result = arcpy.GetCount_management("roads")
resultValue = result.getOutput(0)

# The result object's getOutput method returns values as a 
#   unicode string.  To convert to a different Python type, use 
#   built-in Python functions: str(), int(), long(), float()
#
count = int(resultValue)
print count
print types.TypeType(count) 

Propriétés et méthodes de l'objet Result

Propriétés et méthodes	Explication
inputCount	Renvoie le nombre d'entrées.
outputCount	Retourne le nombre de sorties.
messageCount	Retourne le nombre de messages.
maxSeverity	Retourne la gravité maximale. La gravité retournée peut être 0 (pas d'erreur ni d'avertissement généré), 1 (avertissements générés) ou 2 (erreurs générées).
resultID	Retourne l'ID de résultat unique. Si l'outil n'est pas un service de géotraitement, la propriété resultID est "".
status	Retourne l'état de la tâche sur le serveur. 0 - Nouvelle 1 - Soumise 2 - En attente 3 - Exécution 4 - Réussie 5 - Echouée 6 - Expirée 7 - Annulation 8 - Annulée 9 - Suppression 10 - Supprimée
cancel()	Annule la tâche sur le serveur.
getInput(index)	Renvoie une entrée donnée. S'il s'agit d'un objet de jeu d'enregistrements ou de données raster, un objet RecordSet ou RasterData est renvoyé.
getMapImageURL(ParameterList, Height, Width, Resolution)	Permet de recevoir l'image de service de carte pour une sortie donnée.
getMessage(index)	Retourne un message spécifique.
getMessages(severity)	Type de messages à retourner. 0=message, 1=avertissement, 2=erreur. Si aucune valeur n'est spécifiée, tous les types de messages sont renvoyés.
getOutput(index)	Renvoie une sortie donnée. S'il s'agit d'un objet de jeu d'enregistrements ou de données raster, un objet RecordSet ou RasterData est renvoyé.
getSeverity(index)	Retourne la gravité d'un message spécifique.

Propriétés et méthodes de l'objet Result

Obtention de résultats à partir d'un outil serveur

Comme d'autres outils de géotraitement, les outils serveur de géotraitement disposent d'un ensemble défini de paramètres qui fournissent à l'outil les informations nécessaires à son exécution. Lors de l'utilisation d'outils serveur asynchrones dans un script, la sortie peut être récupérée par la méthode getOutput du résultat.

Astuce :

La fonction IsSynchronous permet de déterminer si un outil est exécuté de manière synchrone ou asynchrone. Lorsqu'un outil est synchrone, les résultats sont retournés automatiquement, mais aucune autre action ne peut être effectuée avant la fin de son exécution.

Dans l'exemple suivant, la fonction GetParameterValue est utilisée pour obtenir un objet FeatureSet à partir d'un outil serveur. Cet objet FeatureSet contient la structure du paramètre en entrée de l'outil. L'objet FeatureSet est ensuite chargé avec une classe d'entités et l'outil serveur est exécuté sur le serveur. Le script se termine en utilisant la méthode getOutput de l'objet Result pour obtenir la sortie de l'outil qui est alors enregistrée localement à l'aide de la méthode save de FeatureSet.

import arcpy
import time

# Add a toolbox from a server
#
arcpy.ImportToolbox("http://flame7/arcgis/services;GP/BufferByVal", "mytools")

# Use GetParameterValue to get a featureset object with the default 
#   schema of the first parameter of the tool 'bufferpoints'
#
inFeatureSet = arcpy.GetParameterValue("bufferpoints", 0)

# Load a shapefile into the featureset
#
inFeatureSet.load("c:/base/roads.shp")

# Run a server tool named BufferPoints with featureset created above
#
result = arcpy.BufferPoints_mytools(inFeatureSet, "5 feet")

# Check the status of the result object every 0.2 seconds until it has a value 
#    of 4 (succeeded) or greater
#
while result.status < 4:
    time.sleep(0.2)

# Get the output FeatureSet back from the server and save to a local geodatabase
#
outFeatSet = result.getOutput(0)
outFeatSet.save("c:/temp/base.gdb/towers_buffer")

Obtention d'un résultat raster à partir d'un outil serveur

Les résultats raster sont renvoyés au format TIFF (Tagged Image File Format). Par défaut, lorsque vous utilisez getOutput, le fichier TIFF est enregistré dans le dossier TEMP de votre système. Pour contrôler l'emplacement du fichier TIFF, définissez l'environnement scratchWorkspace sur un dossier.

import arcpy 
import time

# Set the scratchworkspace to a folder.
#
arcpy.env.scratchWorkspace = "c:/temp/rasteroutput"

# Add a toolbox from a server
#
arcpy.ImportToolbox("http://flame7/arcgis/services;SlopeByVal", "mytools")

dem = "c:/dems/k_ne_g"

# Run a server tool named RunSlope
#
result = arcpy.RunSlope_mytools(dem)

# Check the status of the result object every 0.2 seconds until it has a value 
#    of 4 (succeeded) or greater
#
while result.status < 4:
    print result.status
    time.sleep(0.2)

# Raster output will be written to the scratchworkspace    
#
outTIFF = result.getOutput(0)

Obtention d'une carte de type image

Les services de géotraitement peuvent utiliser un service de carte obtenu pour créer une carte de type image numérique des résultats de tâche. Les cartes numériques contiennent des représentations visuelles de jeux de données géographiques qui communiquent des informations. Les cartes numériques sont transférées sur le Web en tant qu'images (.jpeg, par exemple). Une carte de type image contient, à nombre d'octets égal, beaucoup plus informations pouvant être interprétées par l'homme que les entités brutes figurant dans une classe d'entités. Les cartes de type image sont également gérables. Elles sont facilement compressibles et peuvent être fractionnées en unités gérables. Il existe également des méthodes établies pour les transporter et les afficher sur le Web.

Les cartes de type image, qui sont créées par un service de carte ArcGIS Server, sont issues de la publication d'un document ArcMap (.mxd). En raison de ses caractéristiques, vous pouvez créer une carte de type image pour les résultats de votre tâche de géotraitement, puis transférer l'image sur le Web à la place du jeu ou des jeux de données obtenus. Les services de géotraitement peuvent disposer d'un service de carte obtenu utilisé par ArcGIS Server pour créer des cartes de type image de vos données en sortie.

import arcpy
import time
import urllib

# Add a toolbox from a server
#
arcpy.ImportToolbox("http://flame7/arcgis/services;GP/BufferByVal", "mytools")

# Use GetParameterValue to get a featureset object with the default schema of the 
#   first parameter of the tool 'bufferpoints'
#
inFeatureSet = arcpy.GetParameterValue("bufferpoints", 0)

# Load a shapefile into the featureset
#
inFeatureSet.load("c:/base/roads.shp")

# Run a server tool named BufferPoints with featureset created above
#
result = arcpy.BufferPoints_mytools(inFeatureSet, "5 feet")

# Check the status of the result object every 0.2 seconds until it has a value 
#    of 4 (succeeded) or greater
#
while result.status < 4:
    time.sleep(0.2)
    print result.status

# Return a map service
#
mapimage = result.getMapImageURL(0)

# Use Python's urllib module's urlretrieve method to copy the image locally
#
urllib.urlretrieve(mapimage, "c:/base/road_buffer.jpg")