Jointure spatiale (Analyse)

Niveau de licence :De baseStandardAvancé

Récapitulatif

Joint des attributs d'une entité vers une autre en fonction des relations spatiales. Les entités cible et les attributs joints des entités jointes sont écrits dans la classe d'entités en sortie.

Consultez des exemples graphiques expliquant les relations spatiales

Utilisation

Syntaxe

SpatialJoin_analysis (target_features, join_features, out_feature_class, {join_operation}, {join_type}, {field_mapping}, {match_option}, {search_radius}, {distance_field_name})
ParamètreExplicationType de données
target_features

Les attributs des entités cible et les attributs des entités jointes sont transférés vers la classe d'entités en sortie. Toutefois, un sous-ensemble d'attributs peut être défini dans le paramètre d'appariement des champs. Les entités cible peuvent correspondre à toute source de données spatiales prise en charge par ArcGIS.

Feature Layer
join_features

Les attributs des entités jointes sont joints aux attributs des entités cible. Reportez-vous à l'explication du paramètre Opération de jointure pour en savoir plus sur les répercussions du type d'opération de jointure sur l'agrégation des attributs joints.

Feature Layer
out_feature_class

Nouvelle classe d'entités contenant les attributs des entités jointes et cible. Par défaut, tous les attributs des entités cible et les attributs des entités jointes sont écrits dans la sortie. Toutefois, l'ensemble d'attributs à transférer peut être contrôlé par le paramètre d'appariement des champs.

Feature Class
join_operation
(Facultatif)

Détermine le mode de traitement des jointures entre les entités cible et les entités jointes dans la classe d'entités en sortie, si plusieurs entités jointes présentent une relation spatiale identique avec une même entité cible.

  • JOIN_ONE_TO_ONESi plusieurs entités jointes présentent une relation spatiale identique avec une même entité cible, les attributs des entités jointes multiples sont agrégés à l'aide d'une règle de combinaison d'appariement des champs. Par exemple, si une entité cible ponctuelle figure dans deux entités jointes surfaciques distinctes, les attributs des deux polygones sont agrégés avant leur transfert vers la classe d'entités ponctuelles en sortie. Si les polygones ont respectivement les valeurs attributaires 3 et 7 et qu'une règle de combinaison de somme est spécifiée, la valeur regroupée dans la classe d'entités en sortie est de 10. L'option JOIN_ONE_TO_ONE est la valeur par défaut.
  • JOIN_ONE_TO_MANYSi plusieurs entités jointes présentent une relation spatiale identique avec une même entité cible, la classe d'entités en sortie contient plusieurs copies (enregistrements) de l'entité cible. Par exemple, si une même entité cible ponctuelle figure dans deux entités jointes surfaciques distinctes, la classe d'entités en sortie contient deux copies de l'entité cible : un enregistrement avec les attributs d'un polygone, et un enregistrement avec les attributs de l'autre polygone.
String
join_type
(Facultatif)

Détermine si toutes les entités cible sont conservées dans la classe d'entités en sortie (jointure externe), ou uniquement celles ayant la relation spatiale spécifiée avec les entités jointes (jointure interne).

  • KEEP_ALLToutes les entités cible sont conservées dans la sortie (jointure externe). Il s'agit de l'option par défaut.
  • KEEP_COMMON Seules les entités cible ayant la relation spatiale spécifiée avec les entités jointes sont conservées dans la classe d'entités en sortie (jointure interne). Par exemple, si une classe d'entités ponctuelles est spécifiée pour les entités cible et une classe d'entités surfaciques pour les entités jointes avec l'option de correspondance WITHIN, la classe d'entités en sortie contient uniquement les entités cible contenues dans une entité jointe surfacique ; toutes les entités cible non contenues dans une entité jointe sont exclues de la sortie.
Boolean
field_mapping
(Facultatif)

Détermine les champs attributaires figurant dans la classe d'entités en sortie. La liste initiale contient tous les champs provenant à la fois des entités cible et des entités jointes. Vous pouvez ajouter, supprimer ou renommer les champs, ou modifier leurs propriétés. Les champs sélectionnés dans les entités cible sont transférés tels quels, mais les champs sélectionnés dans les entités jointes peuvent être agrégés par une règle de combinaison. Pour en savoir plus sur l'appariement de champs, reportez-vous aux rubriques Utilisation du contrôle d'appariement de champs et Appariement de champs en entrée aux champs en sortie. Vous pouvez spécifier plusieurs combinaisons de champs et de statistiques.

Field Mappings
match_option
(Facultatif)

Définit les critères utilisés pour l'appariement des enregistrements. Les options de correspondance sont les suivantes :

  • INTERSECTLes entités des entités jointes sont appariées si elles intersectent une entité cible. Il s'agit de l'option par défaut.
  • INTERSECT_3D Les entités dans les entités jointes sont appariées si elles intersectent une entité cible dans un espace tridimensionnel (x, y et z).
  • WITHIN_A_DISTANCELes entités dans les entités jointes sont appariées si elles se trouvent à une distance spécifiée d'une entité cible. Indiquez une distance dans le paramètre Rayon de recherche.
  • WITHIN_A_DISTANCE_3DLes entités dans les entités jointes sont appariées si elles se trouvent à une distance spécifiée d'une entité cible dans un espace tridimensionnel. Indiquez une distance dans le paramètre Rayon de recherche.
  • CONTAINSLes entités des entités jointes sont appariées si une entité cible les englobe. Les entités cible doivent être des polygones ou des polylignes. Pour cette option, les entités cible ne peuvent pas être ponctuelles, et les entités jointes ne peuvent être surfaciques que lorsque les entités cible le sont également.
  • COMPLETELY_CONTAINSLes entités des entités jointes sont appariées si une entité cible les englobe entièrement. Le polygone peut contenir entièrement toute entité. Le point ne peut contenir entièrement aucune entité et même pas un point. Une polyligne peut contenir entièrement toute polyligne et tout point.
  • CONTAINS_CLEMENTINICette relation spatiale renvoie les mêmes résultats que COMPLETELY_CONTAINS, mais si l'entité jointe se trouve entièrement à la limite de l'entité cible (sans aucune partie véritablement à l'intérieur ou à l'extérieur), l'entité n'est pas appariée. CLEMENTINI définit le polygone de limite comme la ligne qui sépare l'intérieur et l'extérieur ; la limite d'une ligne est définie par ses extrémités et la limite d'un point est toujours vide.
  • WITHINLes entités des entités jointes sont appariées si une entité cible se trouve à l'intérieur d'elles. Cet opérateur est l'inverse de CONTAINS. Pour cette option, les entités cible ne peuvent être que des polygones lorsque les entités jointes le sont également. Un point peut être une entité jointe uniquement s'il est une cible.
  • COMPLETELY_WITHINLes entités des entités jointes sont appariées si une entité cible se trouve entièrement à l'intérieur d'elles. Cet opérateur est l'inverse de COMPLETELY_CONTAINS.
  • WITHIN_CLEMENTINILe résultat est identique à celui obtenu avec WITHIN, sauf que si la totalité de l'entité dans les entités jointes est à la limite de l'entité cible, l'entité n'est pas appariée. CLEMENTINI définit le polygone de limite comme la ligne qui sépare l'intérieur et l'extérieur ; la limite d'une ligne est définie par ses extrémités et la limite d'un point est toujours vide.
  • ARE_IDENTICAL_TOLes entités dans les entités jointes sont appariées si elles sont identiques à une entité cible. Les entités jointe et cible doivent présenter le même type de forme : point-point, ligne-ligne et polygone-polygone.
  • BOUNDARY_TOUCHESLes entités dans les entités jointes sont appariées si elles comportent une limite qui touche une entité cible. Les entités jointe et cible doivent être des lignes ou des polygones. En outre, l'entité des entités jointes doit se trouver à l'extérieur ou entièrement à l'intérieur du polygone cible.
  • SHARE_A_LINE_SEGMENT_WITHLes entités dans les entités jointes sont appariées si elles partagent un segment de ligne avec une entité cible. Les entités jointe et cible doivent être des lignes ou des polygones.
  • CROSSED_BY_THE_OUTLINE_OFLes entités dans les entités jointes sont appariées si une entité cible est intersectée par leur contour. Les entités jointe et cible doivent être des lignes ou des polygones. Si des polygones sont utilisés pour les entités jointe et cible, la limite (ligne) du polygone est utilisée. Les lignes qui se croisent au niveau d'un point sont appariées, contrairement à celles qui partagent un segment de ligne.
  • HAVE_THEIR_CENTER_INLes entités des entités jointes sont appariées si le centre d'une entité cible se trouve entièrement à l'intérieur d'elles. Le centre de l'entité est calculé comme suit : pour les polygones et multi-points, c'est le centroïde de la géométrie qui est utilisé, tandis que pour les lignes en entrée, c'est le centre de la géométrie qui est utilisé.
  • CLOSESTL'entité dans les entités jointes les plus proches d'une entité cible est appariée. Pour en savoir plus, reportez-vous aux conseils d'utilisation.
String
search_radius
(Facultatif)

Les entités jointes sont prises en compte pour la jointure spatiale si elles se trouvent à une distance égale ou inférieure à cette valeur d'une entité cible. Le rayon de recherche est valide uniquement lorsque la relation spatiale (option de correspondance) spécifiée est INTERSECT ou CLOSEST. L'utilisation d'un rayon de recherche de 100 mètres avec la relation spatiale INTERSECT revient à dire : si une entité jointe est à moins de 100 mètres d'une entité cible, l'entité jointe est appariée.

Linear unit
distance_field_name
(Facultatif)

Nom d'un champ à ajouter à la classe d'entités en sortie, contenant la distance entre l'entité cible et l'entité jointe la plus proche. Cette option est valide uniquement lorsque la relation spatiale (option de correspondance) spécifiée est CLOSEST. La valeur de ce champ est -1 si aucune entité ne fait l'objet d'une correspondance dans un rayon de recherche. Si aucun nom de champ n'est spécifié, le champ n'est pas ajouté à la classe d'entités en sortie.

String

Exemple de code

1er exemple d'utilisation de l'outil SpatialJoin (fenêtre Python)

Le script ci-dessous illustre l'utilisation de la fonction SpatialJoin dans une fenêtre Python.

import arcpy

target_features = "C:/data/usa.gdb/states"
join_features = "C:/data/usa.gdb/cities"
out_feature_class = "C:/data/usa.gdb/states_cities"

arcpy.SpatialJoin_analysis(target_features, join_features, out_feature_class)
2e exemple d'utilisation de l'outil SpatialJoin (script autonome)

Le script autonome ci-dessous illustre l'utilisation de la fonction SpatialJoin pour la jointure des attributs de villes aux états.

# Name: SpatialJoin_Example2.py
# Description: Join attributes of cities to states based on spatial relationships.
# Requirements: os module

# Import system modules
import arcpy
import os

# Set local variables
workspace = r"C:\gpqa\mytools\spatialjoin\usa.gdb"
outWorkspace = r"C:\gpqa\mytools\spatialjoin\output.gdb"
 
# Want to join USA cities to states and calculate the mean city population
# for each state
targetFeatures = os.path.join(workspace, "states")
joinFeatures = os.path.join(workspace, "cities")
 
# Output will be the target features, states, with a mean city population field (mcp)
outfc = os.path.join(outWorkspace, "states_mcp2")
 
# Create a new fieldmappings and add the two input feature classes.
fieldmappings = arcpy.FieldMappings()
fieldmappings.addTable(targetFeatures)
fieldmappings.addTable(joinFeatures)
 
# First get the POP1990 fieldmap. POP1990 is a field in the cities feature class.
# The output will have the states with the attributes of the cities. Setting the
# field's merge rule to mean will aggregate the values for all of the cities for
# each state into an average value. The field is also renamed to be more appropriate
# for the output.
pop1990FieldIndex = fieldmappings.findFieldMapIndex("POP1990")
fieldmap = fieldmappings.getFieldMap(pop1990FieldIndex)
 
# Get the output field's properties as a field object
field = fieldmap.outputField
 
# Rename the field and pass the updated field object back into the field map
field.name = "mean_city_pop"
field.aliasName = "mean_city_pop"
fieldmap.outputField = field
 
# Set the merge rule to mean and then replace the old fieldmap in the mappings object
# with the updated one
fieldmap.mergeRule = "mean"
fieldmappings.replaceFieldMap(pop1990FieldIndex, fieldmap)
 
# Delete fields that are no longer applicable, such as city CITY_NAME and CITY_FIPS
# as only the first value will be used by default
x = fieldmappings.findFieldMapIndex("CITY_NAME")
fieldmappings.removeFieldMap(x)
y = fieldmappings.findFieldMapIndex("CITY_FIPS")
fieldmappings.removeFieldMap(y)
 
#Run the Spatial Join tool, using the defaults for the join operation and join type
arcpy.SpatialJoin_analysis(targetFeatures, joinFeatures, outfc, "#", "#", fieldmappings)

Environnements

Thèmes connexes

Informations de licence

ArcGIS for Desktop Basic : Oui
ArcGIS for Desktop Standard : Oui
ArcGIS for Desktop Advanced : Oui
9/12/2013