Desktop Help 10.0 - Select Layer By Location (Data Management)

Summary

Selects features in a layer based on a spatial relationship to features in another layer.

Each feature in the Input Feature Layer is evaluated against the features in the Selecting Features layer or feature class; if the specified Relationship is met, the input feature is selected.

Graphic examples of relationships

Usage

The input must be a feature layer; it cannot be a feature class.
Valid inputs for this tool are layers in the ArcMap, ArcGlobe, or ArcScene table of contents, and also on layers created in ArcCatalog or in scripts using the Make Feature Layer tool.
The coordinate system in which the spatial relationship is evaluated may affect the result. Features that intersect in one coordinate system may or may not intersect in another.
- This tool evaluates spatial relationship in the coordinate system of the Input Feature Layer's data source (the feature class on disk). Set the output coordinate system environment to evaluate the spatial relationship in a different coordinate system.
- The Select By Location tools available in the Selection menu in ArcMap, ArcScene, and ArcGlobe evaluate spatial relationship in the coordinate system of that application's display (the current data frame). For the geoprocessing tool to match this behavior (and get identical results), set output coordinate system environment to Same as Display.
This tool can be used to select features based on their spatial relationships to other features within the same layer. For some examples, see: Select by location within a layer.
The Get Count tool can be used to find the number of features selected by the Select Layer By Location tool. This can be useful for determining if any features matched the desired spatial relationship before proceeding to further analysis as part of an automated workflow (that is, script or model).
For more information about using the three-dimensional spatial relationships (INTERSECT_3D and WITHIN_A_DISTANCE_3D), see Select by location 3D relationships.

Syntax

SelectLayerByLocation_management (in_layer, {overlap_type}, {select_features}, {search_distance}, {selection_type})

Parameter	Explanation	Data Type
in_layer	The layer containing the features that will be evaluated against the Selecting Features. The selection will be applied to this layer. The input can be a layer in the ArcMap table of contents, or a layer created in ArcCatalog or in scripts using the Make Feature Layer tool. The input cannot be the path to a feature class on disk.	Feature Layer; Mosaic Layer; Raster Catalog Layer
overlap_type (Optional)	The spatial relationship to be evaluated. INTERSECT —The features in the input layer will be selected if they intersect a selecting feature. This is the default. INTERSECT_3D —The features in the input layer will be selected if they intersect a selecting feature in three-dimensional space (x, y, and z). WITHIN_A_DISTANCE —The features in the input layer will be selected if they are within a specified distance of a selecting feature. Specify a distance in the Search Distance parameter. WITHIN_A_DISTANCE_3D —The features in the input layer will be selected if they are within a specified distance of a selecting feature in three-dimensional space. Specify a distance in the Search Distance parameter. CONTAINS —The features in the input layer will be selected if they contain a selecting feature. The input features must be polygons. COMPLETELY_CONTAINS —The features in the input layer will be selected if they completely contain a selecting feature. The input features must be polygons. CONTAINS_CLEMENTINI —This spatial relationship yields the same results as COMPLETELY_CONTAINS with one exception. If the selecting feature is entirely on the boundary of the input feature (no part is properly inside or outside), the feature will not be selected. CLEMENTINI defines the boundary polygon as the line separating inside and outside, the boundary of a line is defined as its end points, and the boundary of a point is always empty. WITHIN —The features in the input layer will be selected if they are within a selecting feature. The selecting features must be polygons. COMPLETELY_WITHIN —The features in the input layer will be selected if they are completely within or contained by a selecting feature. The selecting features must be polygons. WITHIN_CLEMENTINI —The result will be identical to WITHIN except if the entirety of the feature in the input layer is on the boundary of the feature in the selecting layer, the feature will not be selected. CLEMENTINI defines the boundary polygon as the line separating inside and outside, the boundary of a line is defined as its end points, and the boundary of a point is always empty. ARE_IDENTICAL_TO —The features in the input layer will be selected if they are identical (in geometry) to a selecting feature. BOUNDARY_TOUCHES —The features in the input layer will be selected if they have a boundary that touches a selecting feature. The input and selecting features must be lines or polygons. Additionally, the feature in the input layer must be either completely inside or outside the polygon from the selecting layer. SHARE_A_LINE_SEGMENT_WITH —The features in the input layer will be selected if they share a line segment with a selecting feature. The input and selecting features must be lines or polygons. CROSSED_BY_THE_OUTLINE_OF —The features in the input layer will be selected if they are crossed by the outline of a selecting feature. The input and selecting features must be lines or polygons. If polygons are used for the input or selecting layer, the polygon's boundary (line) will be used. Lines that cross at a point will be selected, not lines that share a line segment. HAVE_THEIR_CENTER_IN —The features in the input layer will be selected if their center falls within a selecting feature. The center of the feature is calculated as follows: for polygon and multipoint, the geometry's centroid is used, and for line input, the geometry's midpoint is used. CONTAINED_BY —This returns the same result as WITHIN. CONTAINED_BY is maintained to support backward compatibility with models and scripts built into releases prior to ArcGIS 9.3.	String
select_features (Optional)	The features in the Input Feature Layer will be selected based on their relationship to the features from this layer or feature class.	Feature Layer
search_distance (Optional)	This parameter is only valid if the Relationship parameter is set to one of the following: WITHIN_A_DISTANCE, WITHIN_A_DISTANCE_3D, INTERSECT, INTERSECT_3D, HAVE_THEIR_CENTER_IN, CONTAINS, or WITHIN.	Linear unit
selection_type (Optional)	Determines how the selection will be applied to the input and how to combine with an existing selection. Note that there is no option here to clear an existing selection. To clear a selection, use the CLEAR_SELECTION option on the Select Layer By Attribute tool. NEW_SELECTION —The resulting selection replaces any existing selection. This is the default. ADD_TO_SELECTION —The resulting selection is added to an existing selection, if one exists. If no selection exists, this is the same as the NEW_SELECTION option. REMOVE_FROM_SELECTION —The resulting selection is removed from an existing selection. If no selection exists, the operation will have no effect. SUBSET_SELECTION —The resulting selection is combined with the existing selection. Only records that are common to both remain selected. SWITCH_SELECTION —Switches the selection. All records that were selected are removed from the selection, and all records that were not selected are added to the selection. The Selecting Features and Relationship parameters are ignored when this option is selected.	String

Code Sample

SelectLayerByLocation example 1 (Python window)

The following Python window script demonstrates how to use the SelectLayerByLocation function in immediate mode.

import arcpy

# First, make a layer from the feature class
arcpy.MakeFeatureLayer_management("c:/kamsack.gdb/parcel", "parcel_lyr")

# Then add a selection to the layer based on location to features in another feature class 
arcpy.SelectLayerByLocation_management ("parcel_lyr", "have_their_center_in", "c:/kamsack.gdb/city_limits")

SelectLayerByLocation example 2 (stand-alone script)

The following stand-alone script shows how to use the SelectLayerByLocation function in a workflow to extract features to a new feature class based on location and an attribute query.

# Name: ExtactFeaturesByLocationAndAttribute.py
# Description: Extract features to a new feature class based on a Location and an attribute query

# Import arcpy and set path to data
import arcpy
arcpy.env.workspace = "c:/data/mexico.gdb"

# Make a layer and select cities which overlap the chihuahua polygon
arcpy.MakeFeatureLayer_management('cities', 'cities_lyr') 
arcpy.SelectLayerByLocation_management('cities_lyr', 'intersect', 'chihuahua')
 
# Within the previous selection sub-select cities which have population > 10,000
arcpy.SelectLayerByAttribute_management('cities_lyr', 
                                        'SUBSET_SELECTION', '"population" > 10000')

# If features matched criteria write them to a new feature class
matchcount = int(arcpy.GetCount_management('cities_lyr').getOutput(0)) 
if matchcount == 0:
    print('no features matched spatial and attribute criteria')
else:
    arcpy.CopyFeatures_management('cities_lyr', 'chihuahua_10000plus')
    print('{0} cities that matched criteria written to {0}'.format(
                                                  matchcount, chihuahua_10000plus))

Environments

Current Workspace, Output Coordinate System

Licensing Information

ArcView: Yes

ArcEditor: Yes

ArcInfo: Yes

10/27/2014

Select Layer By Location (Data Management)