Executing spatial queries

In this topic

• Approaches to executing spatial queries on features and feature classes
• Prerequisites for code examples in this topic
• Spatial query examples
  • Finding features within a polygon
  • Querying for features with relation to multiple geometries
  • Buffering and querying
  • Defining a spatial relationship with a shape comparison language string
  • Evaluating a specific spatial relationship using IRelationalOperator
• Using spatial caching to optimize spatial queries
• Spatial relationships and feature class tolerance

Approaches to executing spatial queries on features and feature classes

• Spatial filters - Use the ISpatialFilter interface to return all features in a feature class that satisfy a specified spatial relationship with an inbound search geometry. A common way to perform a spatial query using a spatial filter is to create the spatial filter and use it as a parameter for IFeatureClass.Search and IFeatureClass.Select, or similar methods on feature layers, selection sets, and so on. These methods return a feature cursor or selection set with all the features that satisfy the specified relationship. See the following illustration:
  
  

• Relational operators - Relational operators compare two geometries and return a Boolean value, which indicates if the necessary relationship exists. Some relationships require the input geometries to be the same dimension, while others have more flexible dimensional constraints. Most of the predefined relational operators are mutually exclusive Clementini operators. The IRelationalOperator interface is available in the Geometry library and has many methods to evaluate if two input geometries satisfy a spatial relationship with one another. See the following illustration:
  
  

Prerequisites for code examples in this topic

• In many of the code examples, geometries are retrieved based on hard-coded ObjectIDs. In real-world applications or tools, this is rarely the case. Possible ways to find the ObjectID of a specific feature include building a form that allows for manual entry by the user (or reading console input or a file in the case of non-user interface [UI] applications) if one exists, getting the selected feature or features from the application's map, using a query filter to find the feature or features that match certain criteria, or building a custom selection tool.
• The Geometry library contains high-level and low-level geometries. High-level geometries include points, polylines, polygons, multipoints, envelopes, and geometry bags. Low-level geometries include geometries that are components of high-level geometries, such as paths, rings, arcs, and curves. The distinction is important in the context of this topic because the ISpatialFilter interface requires a high-level geometry as a query geometry, and only high-level geometries implement the IRelationalOperator interface.

Spatial query examples

• Finding features within a polygon - Shows the names of major highways that pass through a political region.
• Querying for features with relation to multiple geometries - Given the ObjectIDs of four features from a feature class of blocks, finds the parcels that are located within those blocks.
• Buffering and querying - Finds cities with populations greater than 500,000 within 500 kilometers of Osaka, Japan, by applying a buffer to the city and identifying the cities that fall within the buffer.
• Defining a spatial relationship with a shape comparison language string - Uses a feature class with temporal data where features with identical geometries exist and selects all features that match a specific geometry.
• Evaluating a specific spatial relationship using IRelationalOperator - Evaluates whether a highway planned for construction crosses over marshland using the IRelationalOperator interface and two input geometries.

Finding features within a polygon

// Get the feature and its geometry given an ObjectID.
IFeature stateFeature=stateFeatureClass.GetFeature(14);
IGeometry queryGeometry=stateFeature.ShapeCopy;

// Create the spatial filter; "highwayFeatureClass" is the feature class containing
// the highway data. Set the SubFields property to "FULL_NAME" as only that field
// is shown.
ISpatialFilter spatialFilter=new SpatialFilterClass();
spatialFilter.Geometry=queryGeometry;
spatialFilter.GeometryField=highwayFeatureClass.ShapeFieldName;
spatialFilter.SpatialRel=esriSpatialRelEnum.esriSpatialRelIntersects;
spatialFilter.SubFields="FULL_NAME";

// Find the position of the "FULL_NAME" field in the highway feature class.
int nameFieldPosition=highwayFeatureClass.FindField("FULL_NAME");

// Execute the query and iterate through the cursor's results.
using(ComReleaser comReleaser=new ComReleaser())
{
    IFeatureCursor highwayCursor=highwayFeatureClass.Search(spatialFilter, false);
    comReleaser.ManageLifetime(highwayCursor);
    IFeature highwayFeature=null;
    while ((highwayFeature=highwayCursor.NextFeature()) != null)
    {
        String name=Convert.ToString(highwayFeature.get_Value(nameFieldPosition));
        Console.WriteLine("Highway found: {0}", name);
    }
}

' Get the feature and its geometry given an ObjectID.
Dim stateFeature As IFeature=stateFeatureClass.GetFeature(14)
Dim queryGeometry As IGeometry=stateFeature.Shape

' Create the spatial filter; "highwayFeatureClass" is the feature class containing
' the highway data. Set the SubFields property to "FULL_NAME" as only that field
' is shown.
Dim spatialFilter As ISpatialFilter=New SpatialFilterClass()
spatialFilter.Geometry=queryGeometry
spatialFilter.GeometryField=highwayFeatureClass.ShapeFieldName
spatialFilter.SpatialRel=esriSpatialRelEnum.esriSpatialRelIntersects
spatialFilter.SubFields="FULL_NAME"

' Find the position of the "FULL_NAME" field in the highway feature class.
Dim nameFieldPosition As Integer=highwayFeatureClass.FindField("FULL_NAME")

' Execute the query and iterate through the cursor's results.
Using comReleaser As ComReleaser=New ComReleaser()
Dim highwayCursor As IFeatureCursor=highwayFeatureClass.Search(spatialFilter, False)
comReleaser.ManageLifetime(comReleaser)
Dim highwayFeature As IFeature=highwayCursor.NextFeature()
While Not highwayFeature Is Nothing
    Dim Name As String=Convert.ToString(highwayFeature.Value(nameFieldPosition))
    Console.WriteLine("Highway found: {0}", Name)
    highwayFeature=highwayCursor.NextFeature()
End While
End Using

Querying for features with relation to multiple geometries

// Create a geometry bag and give it the same spatial reference as the
// blocks feature class.
IGeometryBag geometryBag=new GeometryBagClass();
IGeometryCollection geometryCollection=(IGeometryCollection)geometryBag;
IGeoDataset geoDataset=(IGeoDataset)blocksFeatureClass;
ISpatialReference spatialReference=geoDataset.SpatialReference;
geometryBag.SpatialReference=spatialReference;

// Get a feature cursor for the three blocks and put their geometries into the geometry bag.
// A non-recycling cursor is used, as the features' geometries are stored
// for later use.
int[] blockObjectIDs=
{
    11043, 11049, 11057
};
using(ComReleaser comReleaser=new ComReleaser())
{
    IFeatureCursor blocksCursor=blocksFeatureClass.GetFeatures(blockObjectIDs,
        false);
    comReleaser.ManageLifetime(blocksCursor);
    IFeature blockFeature=null;
    object missingType=Type.Missing;
    while ((blockFeature=blocksCursor.NextFeature()) != null)
    {
        geometryCollection.AddGeometry(blockFeature.Shape, ref missingType, ref
            missingType);
    }
}

' Create a geometry bag and give it the same spatial reference as the
' blocks feature class.
Dim geometryBag As IGeometryBag=New GeometryBagClass()
Dim geometryCollection As IGeometryCollection=CType(geometryBag, IGeometryCollection)
Dim geoDataset As IGeoDataset=CType(blocksFeatureClass, IGeoDataset)
Dim spatialReference As ISpatialReference=geoDataset.SpatialReference
geometryBag.SpatialReference=spatialReference

' Get a feature cursor for the three blocks and put their geometries into the geometry bag.
' A non-recycling cursor is used, as the features' geometries are stored
' for later use.
Dim blockObjectIDs As Integer()={11043, 11049, 11057}
Using comReleaser As ComReleaser=New ComReleaser()
Dim blocksCursor As IFeatureCursor=blocksFeatureClass.GetFeatures(blockObjectIDs, False)
comReleaser.ManageLifetime(blocksCursor)
Dim blockFeature As IFeature=blocksCursor.NextFeature()
Dim missingType As Object=Type.Missing
While Not blockFeature Is Nothing
    geometryCollection.AddGeometry(blockFeature.Shape, missingType, missingType)
    blockFeature=blocksCursor.NextFeature()
End While
End Using

// Cast the geometry bag to the ISpatialIndex interface and call the Invalidate method
// to generate a new spatial index.
ISpatialIndex spatialIndex=(ISpatialIndex)geometryBag;
spatialIndex.AllowIndexing=true;
spatialIndex.Invalidate();

' Cast the geometry bag to the ISpatialIndex interface and call the Invalidate method
' to generate a new spatial index.
Dim spatialIndex As ISpatialIndex=CType(geometryBag, ISpatialIndex)
spatialIndex.AllowIndexing=True
spatialIndex.Invalidate()

// Create the spatial filter. The SubFields property specifies that only
// the Shape field is retrieved, since the features' attributes aren't being inspected.
ISpatialFilter spatialFilter=new SpatialFilterClass();
spatialFilter.Geometry=geometryBag;
spatialFilter.GeometryField=parcelsFeatureClass.ShapeFieldName;
spatialFilter.SpatialRel=esriSpatialRelEnum.esriSpatialRelContains;
spatialFilter.SubFields="Shape";

// Use IFeatureClass.FeatureCount to get a parcel count.
int parcelCount=parcelsFeatureClass.FeatureCount(spatialFilter);
Console.WriteLine("Parcels in the three blocks: {0}", parcelCount);

' Create the spatial filter. The SubFields property specifies that only
' the Shape field is retrieved, since the features' attributes aren't being inspected.
Dim spatialFilter As ISpatialFilter=New SpatialFilterClass()
spatialFilter.Geometry=geometryBag
spatialFilter.GeometryField=parcelsFeatureClass.ShapeFieldName
spatialFilter.SpatialRel=esriSpatialRelEnum.esriSpatialRelContains
spatialFilter.SubFields="Shape"

' Use IFeatureClass.FeatureCount to get a parcel count.
Dim parcelCount As Integer=parcelsFeatureClass.FeatureCount(spatialFilter)
Console.WriteLine("Parcels in the three blocks: {0}", parcelCount)

Buffering and querying

// Find the feature for Osaka and get its geometry.
IFeature osakaFeature=citiesFeatureClass.GetFeature(2263);
IGeometry osakaGeometry=osakaFeature.ShapeCopy;

// Use the ITopologicalOperator interface to create a buffer.
ITopologicalOperator topoOperator=(ITopologicalOperator)osakaGeometry;
IGeometry buffer=topoOperator.Buffer(500000);

' Find the feature for Osaka and get its geometry.
Dim osakaFeature As IFeature=citiesFeatureClass.GetFeature(2263)
Dim osakaGeometry As IGeometry=osakaFeature.ShapeCopy

' Use the ITopologicalOperator interface to create a buffer.
Dim topoOperator As ITopologicalOperator=CType(osakaGeometry, ITopologicalOperator)
Dim buffer As IGeometry=topoOperator.Buffer(500000)

// Create the spatial filter.
ISpatialFilter spatialFilter=new SpatialFilterClass();
spatialFilter.Geometry=buffer;
spatialFilter.GeometryField=citiesFeatureClass.ShapeFieldName;
spatialFilter.SpatialRel=esriSpatialRelEnum.esriSpatialRelContains;
spatialFilter.SubFields="CITY_NAME, POP_CLASS";
spatialFilter.WhereClause="POP_RANK < 4";

// Find the position of the CITY_NAME and POP_CLASS fields in the feature class.
int cityNamePosition=citiesFeatureClass.FindField("CITY_NAME");
int popClassPosition=citiesFeatureClass.FindField("POP_CLASS");

// Execute the query.
using(ComReleaser comReleaser=new ComReleaser())
{
    IFeatureCursor featureCursor=citiesFeatureClass.Search(spatialFilter, true);
    comReleaser.ManageLiftetime(featureCursor);
    IFeature feature=null;
    while ((feature=featureCursor.NextFeature()) != null)
    {
        String cityName=Convert.ToString(feature.get_Value(cityNamePosition));
        String popClass=Convert.ToString(feature.get_Value(popClassPosition));
        Console.WriteLine("{0} --- Population: {1}", cityName, popClass);
    }
}

' Create the spatial filter.
Dim spatialFilter As ISpatialFilter=New SpatialFilterClass()
spatialFilter.Geometry=buffer
spatialFilter.GeometryField=citiesFeatureClass.ShapeFieldName
spatialFilter.SpatialRel=esriSpatialRelEnum.esriSpatialRelContains
spatialFilter.SubFields="CITY_NAME, POP_CLASS"
spatialFilter.WhereClause="POP_RANK < 4"

' Find the position of the CITY_NAME and POP_CLASS fields in the feature class.
Dim cityNamePosition As Integer=citiesFeatureClass.FindField("CITY_NAME")
Dim popClassPosition As Integer=citiesFeatureClass.FindField("POP_CLASS")

' Execute the query.
Using comReleaser As ComReleaser=New ComReleaser()
Dim featureCursor As IFeatureCursor=citiesFeatureClass.Search(spatialFilter, True)
comReleaser.ManageLifetime(featureCursor)
Dim feature As IFeature=featureCursor.NextFeature()
While Not feature Is Nothing
    Dim cityName As String=Convert.ToString(feature.Value(cityNamePosition))
    Dim popClass As String=Convert.ToString(feature.Value(popClassPosition))
    Console.WriteLine("{0} --- Population: {1}", cityName, popClass)
End While
End Using

Defining a spatial relationship with a shape comparison language string

Illustration	String	Description
	T********	The interiors of the geometries must intersect.
	T***T****	The boundaries of the geometries must intersect and their interiors must intersect.
	F***T****	The boundaries of the geometries must intersect and their interiors must not intersect.
	FF*FF****	The geometries must be completely disjointed.

// Get the feature with the known ObjectID (California).
IFeature caFeature=featureClass.GetFeature(4);
IGeometry caGeometry=caFeature.Shape;

// Create a spatial filter with a shape comparison language spatial relationship string.
ISpatialFilter spatialFilter=new SpatialFilterClass();
spatialFilter.Geometry=caGeometry;
spatialFilter.GeometryField=featureClass.ShapeFieldName;
spatialFilter.SpatialRel=esriSpatialRelEnum.esriSpatialRelRelation;
spatialFilter.SpatialRelDescription="TFFFTFFF*";
spatialFilter.SubFields="Start_Date, Population";

// Find the positions of the Start_Date and Population fields in the class.
int startDatePosition=featureClass.FindField("Start_Date");
int populationPosition=featureClass.FindField("Population");

// Execute the query.
ISelectionSet selectionSet=featureClass.Select(spatialFilter,
    esriSelectionType.esriSelectionTypeSnapshot,
    esriSelectionOption.esriSelectionOptionNormal, null);

' Get the feature with the known ObjectID (California).
Dim caFeature As IFeature=featureClass.GetFeature(4)
Dim caGeometry As IGeometry=caFeature.Shape

' Create a spatial filter with a 9IM spatial relationship.
Dim spatialFilter As ISpatialFilter=New SpatialFilterClass()
spatialFilter.Geometry=caGeometry
spatialFilter.GeometryField=featureClass.ShapeFieldName
spatialFilter.SpatialRel=esriSpatialRelEnum.esriSpatialRelRelation
spatialFilter.SpatialRelDescription="TFFFTFFF*"
spatialFilter.SubFields="Start_Date, Population"

' Find the positions of the Start_Date and Population fields in the class.
Dim startDatePosition As Integer=featureClass.FindField("Start_Date")
Dim populationPosition As Integer=featureClass.FindField("Population")

' Execute the query.
Dim selectionSet As ISelectionSet=featureClass.Select(spatialFilter, esriSelectionType.esriSelectionTypeSnapshot, _
                                    esriSelectionOption.esriSelectionOptionNormal, Nothing)

Evaluating a specific spatial relationship using IRelationalOperator

// Get the marsh and highway features from their respective classes.
IFeature marshFeature=vegFeatureClass.GetFeature(518);
IFeature highwayFeature=roadsFeatureClass.GetFeature(39);

// Get the geometries of the two features.
IGeometry marshGeometry=marshFeature.Shape;
IGeometry highwayGeometry=highwayFeature.Shape;

// Cast the highway's geometry to IRelationalOperator and determine if
// it crosses the marsh's geometry.
IRelationalOperator relationalOperator=(IRelationalOperator)highwayGeometry;
Boolean crosses=relationalOperator.Crosses(marshGeometry);
Console.WriteLine("Highway crosses marsh: {0}", crosses);

' Get the marsh and highway features from their respective classes.
Dim marshFeature As IFeature=vegFeatureClass.GetFeature(518)
Dim highwayFeature As IFeature=roadsFeatureClass.GetFeature(39)

' Get the geometries of the two features.
Dim marshGeometry As IGeometry=marshFeature.Shape
Dim highwayGeometry As IGeometry=highwayFeature.Shape

' Cast the highway's geometry to IRelationalOperator and determine if
' it crosses the marsh's geometry.
Dim relationalOperator As IRelationalOperator=CType(highwayGeometry, IRelationalOperator)
Dim crosses As Boolean=relationalOperator.Crosses(marshGeometry)
Console.WriteLine("Highway crosses marsh: {0}", crosses)

Using spatial caching to optimize spatial queries

• Open the feature classes required by the queries. When the spatial cache is filled, only the features from the open feature classes are included.
• Fill the cache for the extent.
• Execute the queries.
• Empty the cache.

// Open the feature classes used by the queries.
IFeatureClass blocksFeatureClass=featureWorkspace.OpenFeatureClass("Blocks");
IFeatureClass parcelsFeatureClass=featureWorkspace.OpenFeatureClass("Parcels");

// Fill the spatial cache.
ISpatialCacheManager spatialCacheManager=(ISpatialCacheManager)featureWorkspace;

// Check if the cache has been filled.
if (!spatialCacheManager.CacheIsFull)
{
    // If not full, fill the cache.
    spatialCacheManager.FillCache(cacheExtent);
}

// Execute spatial queries.

// Empty the cache.
spatialCacheManager.EmptyCache();

' Open the feature classes used by the queries.
Dim blocksFeatureClass As IFeatureClass=featureWorkspace.OpenFeatureClass("Blocks")
Dim parcelsFeatureClass As IFeatureClass=featureWorkspace.OpenFeatureClass("Parcels")

' Fill the spatial cache.
Dim spatialCacheManager As ISpatialCacheManager=CType(featureWorkspace, ISpatialCacheManager)

' Check if the cache has been filled.
If spatialCacheManager.CacheIsFull Then
    
    ' If not full, fill the cache.
    spatialCacheManager.FillCache(cacheExtent)
End If

' Execute spatial queries.

' Empty the cache.
spatialCacheManager.EmptyCache()

Spatial relationships and feature class tolerance

See Also:

• ESRI.ArcGIS.ADF.Connection.Local
• ESRI.ArcGIS.Geodatabase
• ESRI.ArcGIS.Geometry