com.esri.arcgis.geodatabase
Interface ISpatialFilter
- All Superinterfaces:
- IQueryFilter, Serializable
- All Known Implementing Classes:
- ImageQueryFilter, ISpatialFilterProxy, SpatialFilter, TemporalQueryFilter, TimeQueryFilter
public interface ISpatialFilter
- extends IQueryFilter, Serializable
Provides access to members that return and modify the type of spatial relationship that the filter will use.
Description
ISpatialFilter is a QueryFilter that includes both spatial and attribute constraints. Therefore, a SpatialFilter can be used to restrict the set of features retrieved from a feature class using both spatial and attribute restrictions. ISpatialFilter inherits from IQueryFilter so you can optionally specify a string defining a where clause, include a list of columns to be retrieved or specify the spatial reference in which to output the geometry of the resulting features. See the IQueryFilter interface for help on the inherited methods and properties.
The most common ways to perform a spatial query using a spatial filter is to create the spatial filter using this interface and use it as a parameter for IFeatureClass::Search, IFeatureClass::Select or similar methods on feature layers, selection sets, etc.
The Geometry and SpatialRel properties are required.
Geometry is the source geometry in relation to which the spatial selection will be performed. GeometryField is a string corresponding to the name of the field containing the geometries to be compared to the source geometry. Finally the spatial relationship is specified with the SpatialRel property passing it an esriSpatialRelEnum .
A SearchOrder can be specified using an esriSearchOrder. When an attribute query is specified it will specify which of the attritute or spatial part of the query is executed first. A judicious choice may significantly improve the performances. This is only available with SDE datasources.
The SpatialRelDescription can optionally be populated with a string to define spatial relationships that are not possible using the esriSpatialRelEnum values. In this case the SpatialRel parameter must be set to esriSpatialRelRelation. See the help on the SpatialRelDescription property for details on string formatting.
The esriGeometry library provides other ways to perform a spatial selection. See, for instance, the example associated with ITopologicalOperator that performs a spatial selection on polylines that share a line segment.
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
- See Also:
IQueryDef,
com.esri.arcgis.catalogUI.IGxObjectFilter,
IFeatureClass.getFeatures(java.lang.Object, boolean),
IFeatureClass.search(com.esri.arcgis.geodatabase.IQueryFilter, boolean),
IFeatureClass.featureCount(com.esri.arcgis.geodatabase.IQueryFilter),
IQueryFilter
getSearchOrder
int getSearchOrder()
throws IOException,
AutomationException
- The search order used by the filter.
Description
SearchOrder gets the order in which spatial searches are applied by the RDBMS (ArcSDE). This property only affects ArcSDE Geodatabase data. It has no effect on Personal or File Geodatabase, Coverage or Shapefile data.
Remarks
SearchOrder gets the order in which spatial searches are applied by the RDBMS (ArcSDE). The spatial component of the search should generally be applied before the attribute component. The more spatially restrictive of the two should be used. In the following query, "Find all wells with particulate counts between 1000 and 1200 in within 5 miles of a school", the esriSearchOrderAttribute enumerator is more effective. If the filter geometry is the outline of the city of Modesto, California and the attribute query is "street_name = 'Main St.'" then esriSearchOrderSpatial should be used, as there are a large number of "Main St." records at a national level.
Please note that esriSearchOrderSpatial is the default option. The following esriSearchOrder enumeration values are used to set the search order:
esriSearchOrderAttribute
Sets the search order to attribute first.
esriSearchOrderSpatial
Sets the search order to spatial first.
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
Supported Platforms
Windows, Solaris, Linux
- Returns:
- A com.esri.arcgis.geodatabase.esriSearchOrder constant
- Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
setSearchOrder
void setSearchOrder(int order)
throws IOException,
AutomationException
- The search order used by the filter.
Description
SearchOrder
Sets the order in which spatial searches are applied by the RDBMS (ArcSDE).
Remarks
SearchOrder
Sets the order in which spatial searches are applied by the RDBMS (ArcSDE). The spatial component of the search should generally be applied before the attribute component. The more spatially restrictive of the two should be used. In the following query, "Find all wells with particulate counts between 1000 and 1200 in within 5 miles of a school", the esriSearchOrderAttribute enumerator is more effective. If the filter geometry is the outline of the city of Modesto, California and the attribute query is "street_name = 'Main St.'" then esriSearchOrderSpatial should be used, as there are a large number of "Main St." records at a national level.
NOTE: esriSearchOrderSpatial is the default.
The following esriSearchOrder enumeration values are used to set the search order:
esriSearchOrderAttribute
Sets the search order to attribute first.
esriSearchOrderSpatial
Sets the search order to spatial first.
Example (VB6):
pSpatialFiler.SearchOrder = esriSearchOrderAttribute
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
Supported Platforms
Windows, Solaris, Linux
- Parameters:
order - A com.esri.arcgis.geodatabase.esriSearchOrder constant (in)
- Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
getSpatialRel
int getSpatialRel()
throws IOException,
AutomationException
- The spatial relationship checked by the filter.
Description
Tolerances
Most spatial relationships are defined by the intersection of boundaries, interior and exterior. All shapes have an interior. Lines and polygons have a boundary. Most spatial relations use a tolerance when examining the spatial relationship between two features. In most cases this tolerance is the XY tolerance of the search feature. All geometries within the tolerance are seen as intersecting. In the overlaps case the tolerance sets the minimum overlap. Geometries that overlap less than the tolerance will not be seen as overlapping.
Relationships that use the XY tolerance:
esriSpatialRelIntersects
esriSpatialRelEnvelopeIntersects
esriSpatialRelTouches
esriSpatialRelOverlaps
esriSpatialRelCrosses
esriSpatialRelWithin
esriSpatialRelContains
The esriSpatialRelRelation uses the XY resolution. Usually ten times smaller than the XY tolerance.
esriSpatialRelIndexIntersects does not use a tolerance.
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
Supported Platforms
Windows, Solaris, Linux
- Returns:
- A com.esri.arcgis.geodatabase.esriSpatialRelEnum constant
- Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
setSpatialRel
void setSpatialRel(int spatialRel)
throws IOException,
AutomationException
- The spatial relationship checked by the filter.
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
Supported Platforms
Windows, Solaris, Linux
- Parameters:
spatialRel - A com.esri.arcgis.geodatabase.esriSpatialRelEnum constant (in)
- Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
getGeometry
IGeometry getGeometry()
throws IOException,
AutomationException
- The query geometry used to filter results.
Description
Only high-level geometries, envelopes and geometry bags can be used. High-level geometries are polygons, polylines, points, and multipoints. Low-level geometries including paths, rings, arcs and curves, and lines can not be used. To test whether a geometry is applicable, see if it implements the IRelationalOperator interface; if it does, it can be used.
Remarks
If a geometry bag is being used as the filter's query geometry, a spatial index should be created for the bag prior to any evaluation using the filter. This can be done by casting the geometry bag to the ISpatialIndex interface, setting the AllowIndexing property to true, and calling the Invalidate method.
Note that at ArcGIS 9.3 and later, setting this property to null will cause an error.
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
Supported Platforms
Windows, Solaris, Linux
- Returns:
- A reference to a com.esri.arcgis.geometry.IGeometry
- Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
setGeometryByRef
void setGeometryByRef(IGeometry geometry)
throws IOException,
AutomationException
- The query geometry used to filter results.
Description
Only high-level geometries, envelopes and geometry bags can be used. High-level geometries are polygons, polylines, points, and multipoints. Low-level geometries including paths, rings, arcs and curves, and lines can not be used. To test whether a geometry is applicable, see if it implements the IRelationalOperator interface; if it does, it can be used.
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
Supported Platforms
Windows, Solaris, Linux
- Parameters:
geometry - A reference to a com.esri.arcgis.geometry.IGeometry (in)
- Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
setGeometryExByRef
void setGeometryExByRef(IGeometry geometry,
boolean rhs2)
throws IOException,
AutomationException
- The query geometry used to filter results.
Description
Only high-level geometries, envelopes and geometry bags can be used. High-level geometries are polygons, polylines, points, and multipoints. Low-level geometries including paths, rings, arcs and curves, and lines can not be used. To test whether a geometry is applicable, see if it implements the IRelationalOperator interface; if it does, it can be used.
Remarks
The boolean parameter represents the FilterOwnsGeometry property.
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
Supported Platforms
Windows, Solaris, Linux
- Parameters:
geometry - A reference to a com.esri.arcgis.geometry.IGeometry (in)rhs2 - The rhs2 (in)
- Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
isFilterOwnsGeometry
boolean isFilterOwnsGeometry()
throws IOException,
AutomationException
- Indicates whether the filter owns the query geometry.
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
Supported Platforms
Windows, Solaris, Linux
- Returns:
- The spatialFilterOwnsGeometry
- Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
getGeometryField
String getGeometryField()
throws IOException,
AutomationException
- The name of the Geometry field to which the filter applies.
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
Supported Platforms
Windows, Solaris, Linux
- Returns:
- The geomField
- Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
setGeometryField
void setGeometryField(String geomField)
throws IOException,
AutomationException
- The name of the Geometry field to which the filter applies.
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
Supported Platforms
Windows, Solaris, Linux
- Parameters:
geomField - The geomField (in)
- Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
getSpatialRelDescription
String getSpatialRelDescription()
throws IOException,
AutomationException
- The array elements which describe the spatial relation between the query geometry and the requested geometries. There are 9 chars in this string which can be either 'F', 'T' or '*'; e.g., TT*FFT***' represents CONTAIN.
Description
A nine character string containing describing the spatial
relationships to be tested by the spatial
filter. Required when setting the SpatialRel property
to use the esriSpatialRelRelation enumerator.
Remarks
The SpatialRelDescription allows the comparison of any spatial relationship between two geometries. A spatial relationship is defined by the intersections between the boundary, interior, and exterior of the query geometry and the requested geometry.
All of the spatial relationships defined by the esriSpatialRelEnum enumeration can be duplicated using this property.
Interior:
The interior of a shape is defined as the entire shape minus its boundary. All shapes have interior.
Boundary:
Linear and area shapes have boundaries, but point shapes do not. The boundary of linear shapes consists of the end points of all linear parts. The boundary of area shapes consists of the linear boundary of the polygon shell(s).
Exterior:
The area outside a shape. All shapes have an exterior.
Each element for the first shape, the query geometry, may be tested against each element of the second shape, the requested geometry, giving nine possible spatial intersections as listed in the table below:
|
Query Geometry |
Requested Geometry |
| 1 |
interior |
interior |
| 2 |
interior |
boundary |
| 3 |
interior |
exterior |
| 4 |
boundary |
interior |
| 5 |
boundary |
boundary |
| 6 |
boundary |
exterior |
| 7 |
exterior |
interior |
| 8 |
exterior |
boundary |
| 9 |
exterior |
exterior |
The nine-characters string expected by ISpatialFilter::SpatialRelDescription, is used to specify whether the intersection of each of the elements in the array is true (T), false (F), or not tested (*).
For instance, in 'FFFTTT***', relationships 1-3 must be false, relationships 4-6 must be true, and relationships 7-9 are not tested.
Note that any two shapes' exteriors always intersect.
Example Strings
Shares a boundary: '****T***'
Shares a boundary and interiors intersect: 'T***T****'
Shares a boundary and interiors do not intersect: 'F***T****'
Does not touch the boundary and interiors intersect: 'T***F****'
| Relation |
Query Geometry |
Requested Geometry |
String |
| Contains |
Line |
Line |
TT*FFT*** |
| Contains |
Point |
Line |
TT*FFT*** |
| Contains |
Point |
Point |
T******** |
| Contains |
Line |
Poly |
TT*FFT*** |
| Contains |
Poly |
Poly |
TT*FFT*** |
| Crosses |
Line |
Line |
TF*FF**** |
| Crosses |
Poly |
Line |
TT**F**** |
| Crosses |
Line |
Poly |
TT**T**** |
| Overlaps |
Line |
Line |
TT*T***** |
| Overlaps |
Point |
Point |
T******** |
| Overlaps |
Poly |
Poly |
TT*T***** |
| Touch |
Line |
Line |
FF*FT**** |
| Touch |
Poly |
Line |
FF*FT**** |
| Touch |
Line |
Poly |
FF*FT**** |
| Touch |
Poly |
Poly |
FF*FT**** |
| Within |
Line |
Line |
TF**F**** |
| Within |
Point |
Line |
T******** |
| Within |
Point |
Point |
T******** |
| Within |
Line |
Poly |
TF**F**** |
| Within |
Poly |
Poly |
TF**F**** |
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
Supported Platforms
Windows, Solaris, Linux
- Returns:
- The spatialRelDescription
- Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
setSpatialRelDescription
void setSpatialRelDescription(String spatialRelDescription)
throws IOException,
AutomationException
- The array elements which describe the spatial relation between the query geometry and the requested geometries. There are 9 chars in this string which can be either 'F', 'T' or '*'; e.g., TT*FFT***' represents CONTAIN.
Product Availability
Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.
Supported Platforms
Windows, Solaris, Linux
- Parameters:
spatialRelDescription - The spatialRelDescription (in)
- Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.