Syntax FACTORY_DEF SpatialFilterFactory [FACTORY_NAME ] [INPUT BASE FEATURE_TYPE [ ]* []*]+ [INPUT CANDIDATE FEATURE_TYPE [ ]* []*]+ PREDICATE [(INTERSECTS|DISJOINT|EQUALS|TOUCHES|CROSSES| OVERLAPS|CONTAINS|WITHIN|LEFT_RIGHT| |&|@)]+ [HANDLE_ARCS_ELLIPSES_AND_TEXT [(YES|NO)]] [USE_CANDIDATE_CENTER_OF_MASS (YES|NO)] [USE_BASE_CLOSEST_POINT (YES|NO)] [BASEID_ATTR ] [RELATIVE_POSITION_LIST_ATTR ] [REJECT_INVALID_GEOM (Yes|No)] [REJECT_INVALID_PREDICATES (Yes|No)] [REJECT_RASTERS (Yes|No)] [ALLOW_NULLS (Yes|NO)] [DIMENSION (FIRST_BASE|2|3)] [BOOLEAN_OPERATOR (AND|OR)] [USE_BOUNDING_BOX (YES|NO|BASES_ONLY|CANDIDATES_ONLY)] [MULTIPLE_BASES (YES|NO|BASES_FIRST)] [MERGE_BASE_ATTR (YES|NO)] [BASE_ATTR_PREFIX ] [PREDICATE_ATTR ] [CURVE_BOUNDARY_RULE (ENDPOINTS_MOD2|ENDPOINTS_ALL)] [GROUP_BY []+] [FLUSH_WHEN_GROUPS_CHANGE (Yes|No)] [OUTPUT (PASSED|FAILED) FEATURE_TYPE [ ]* []*]* Overview Note: The SpatialFilterFactory uses functionality from the GEOS library (http://geos.refractions.net/), which is distributed under the terms of the Free Software Foundation's LGPL license (http://www.gnu.org/licenses/lgpl.html). In order to comply with the terms of the LGPL, Safe Software Inc. has set up a website (http://www.safe.com/foss) to provide further information. Each SpatialFilterFactory accepts two kinds of features - Bases and Candidates - and tests topological (spatial) relationship predicates between them. For example, if you have a group of features that you want to check against a polygon to isolate those that are inside, the polygon feature would be directed into the BASE clause and the group of features would be directed into the CANDIDATE clause. The PREDICATE clause would be INSIDE. Those features that are inside the polygon would come out the PASSED output clause, and those which were not inside would come out the FAILED output clause. If there is more than one BASE feature, the behaviour depends on the value specified by BOOLEAN_OPERATOR; see below in the Clauses section for details. If there is more than one PREDICATE specified, each one is checked in the order they are specified until one is found that passes. All of the PREDICATEs are checked on each BASE before moving to check the next BASE. If none of the PREDICATEs is true for any of the BASE features, the CANDIDATE feature will come out the FAILED output clause. The SpatialFilterFactory does not remove attributes or alter the geometry of the CANDIDATE features. It may, however, add new attributes. When REJECT_INVALID_GEOM is Yes, the factory will output features with invalid geometries to the REJECTED output tag. When REJECT_INVALID_PREDICATES is Yes, the factory will also output candidate features with invalid predicates to the REJECTED output tag. ALLOW_NULLS specifies if nulls should be routed to the "Failed" port, instead of discarded or rejected. Input Tags The SpatialFilterFactory supports the following input tags. BASE Features used as the criteria for the test. CANDIDATE Features to be tested against the given criteria. Clauses The SpatialFilterFactory supports several configuration clauses. If MULTIPLE_BASES is set to NO, then only the first feature into the BASE input clause will be used. The rest will be ignored with a warning log message. If this is set to YES, then every base will be used but the CANDIDATEs will be temporarily cached until all the features have passed through the factory. If this clause is set to BASES_FIRST, then all the BASEs that arrive before the first CANDIDATE will be used, and any BASE features that arrive after the first CANDIDATE feature will be ignored with a warning log message. The default is setting is YES. BOOLEAN_OPERATOR determines how the factory handles multiple BASE features. If AND is given, each CANDIDATE is checked against each BASE and must pass against each one. If OR is given, each CANDIDATE is checked against each BASE, sequentially, until one is found that passes. The default is AND. If MERGE_BASE_ATTR YES is specified, then all PASSED features will have all the BASE attributes copied onto them, with the prefix specified by the BASE_ATTR_PREFIX clause. If the BASE_ATTR_PREFIX clause is not specified, or is an empty string, then the BASE attributes will not be given any prefix, and will only be copied to the candidate if those attributes do not already exist on the CANDIDATE. The default is setting is NO. If the PREDICATE_ATTR is specified, then all PASSED features will have the name of the first predicate that passed added to the feature as the specified attribute. The USE_BOUNDING_BOX predicate is used to indicate if the complete geometry of each feature should be used in the predicate evaluations or if the bounding boxes should be used instead. A value of YES means that the bounding boxes will be used for all BASEs and CANDIDATEs. A value of NO means that the complete geometry of both BASEs and CANDIDATEs will be used. A value of BASES_ONLY means that the bounding boxes of the BASEs will be compared against the complete geometry of the CANDIDATEs. A value of CANDIDATES_ONLY means that the complete geometry of the BASEs will be compared against the bounding boxes of the CANDIDATEs. If GROUP_BY attributes are specified, CANDIDATEs are only compared against BASEs with the same values in these attributes. If FLUSH_WHEN_GROUPS_CHANGE is also set to Yes, the factory will perform comparisons and flush results to output whenever a feature of a different group is encountered. The CURVE_BOUNDARY_RULE clause determines how the "boundary" of linear features is determined; see the Spatial Predicate Background section below for details. The PREDICATE clause lists the spatial predicates that will be used between the BASE and CANDIDATE features. Note: If the spatial predicate is passed as an attribute, then the CANDIDATE feature must have the spatial relation predicate, not the BASE. The definitions of each PREDICATE are given below. The Spatial Predicate Background section gives specific definitions of boundaries, exteriors, and interiors as they apply to specific feature types, and explains the concept of an intersection matrix. A PREDICATE clause value may also reference a CANDIDATE attribute or feature function, the value of either of which should contain a string of predicates separated by spaces. Spatial Predicate Background ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each feature, whether it is a point, line, or polygon, etc. has a definition of an INTERIOR, BOUNDARY and EXTERIOR. The EXTERIOR is everything that is not on the BOUNDARY or the INTERIOR. BOUNDARY Points Empty set. Lines CURVE_BOUNDARY_RULE ENDPOINTS_MOD2 The boundary is the set of all endpoints that occur an odd number of times. For a simple linear feature (i.e. not a multicurve), this means the boundary is comprised of the the start and end points, unless the line is closed (the start and end are the same point), in which case the boundary is the empty set. (This is the default if CURVE_BOUNDARY_RULE is unspecified.) CURVE_BOUNDARY_RULE ENDPOINTS_ALL The boundary is the set of all endpoints, regardless of the number of times they occur in the geometry. Polygons The border of a polygon, including the border of the holes. INTERIOR Points The point location. Lines The entire line except its boundary, as determined above. Polygons The inner surface of the polygon. The comparison of two features produces a 3 x 3 matrix known as the Dimensionally Extended 9 Intersection Matrix (DE-9IM), shown below: +-----------------+--------------------------------+ | | candidate | | +----------+----------+----------+ | | interior | boundary | exterior | +------+----------+----------+----------+----------+ | | interior | x0 | x1 | x2 | | +----------+----------+----------+----------+ | base | boundary | x3 | x4 | x5 | | +----------+----------+----------+----------+ | | exterior | x6 | x7 | x8 | +------+----------+----------+----------+----------+ The value of each element of the matrix indicates the dimension of the geometry produced by intersecting the given parts of the two features. The dimension is one of the following: -1 there is no interaction 0 the intersection produces a point 1 the intersection produces a line 2 the intersection produces a surface So for instance, if x1 is 1, then the intersection of the base's interior with the candidate's boundary produces a line. This could occur when both features are polygons and they overlap. Each of the predicates can be defined in terms of what the intersection matrix of the two features must look like. For this, use a pattern matrix. Each element of the pattern matrix can be one of the following: * the value of this element may be anything (-1, 0, 1, or 2) T the value of this element must be 0, 1, or 2 F the value of this element must be -1 0 the value of this element must be 0 1 the value of this element must be 1 2 the value of this element must be 2 The pattern matrix for the disjoint predicate is FF* FF* *** This means that neither feature's interior or boundary may interact with the other's interior or boundary. String Representations of Intersection Matrices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Any intersection matrix can be represented as a 9-character string. To generate the string representation of a particular intersection matrix, take each element starting from the top-left, going left-to-right for each row. For example, the string representation of the intersection matrix for the disjoint predicate (as seen above) is "FF*FF****". Definitions of PREDICATE Each of the supported predicates is described below, along with some associated examples and pattern matrices. Note: The examples are not exhaustive: there may be entirely different situations where a given predicate is true. In the examples, the base is labeled "A" and the candidate is labeled "B". INTERSECTS The two features are not disjoint, as defined below. DISJOINT The boundaries and interiors do not intersect. +---+ +---+ FF* | A | | B | FF* +---+ +---+ *** EQUALS The features have the same boundary and the same interior. +----+ T*F | AB | **F +----+ FF* TOUCHES The boundaries may intersect, or one boundary may intersect the other interior. The interiors do not touch. Undefined for point/point. +---+---+ FT* F** F** | A | B | *** or *T* or T** +---+---+ *** *** *** B +-------+---+------+ | A | +------------------+ CROSSES The interiors intersect and the base's interior intersects the candidate's exterior. Or in the case of line/line, the intersection of the interiors forms a point. Undefined for point/point or area/area. | A T*T 0** B | *** or *** (for two lines) -------+------ *** *** | | OVERLAPS The interiors intersect, but neither feature is contained by the other, nor are the features equal. Undefined for point/line, point/area, or line/area. +-----+ T*T 1*T | A | *** or *** (for two lines) | +--+--+ T** T** | | | | +--+--+ | | B | +-----+ CONTAINS +---------------+ T** | +---+ | *** | A | B | | FF* | +---+ | +---------------+ The interiors intersect and no part of the candidate intersects the base's exterior. (inverse of WITHIN) WITHIN +---------------+ T*F | +---+ | **F | B | A | | *** | +---+ | +---------------+ The interiors intersect and no part of the base intersects the candidate's exterior. (inverse of CONTAINS) In addition to the predicates listed above, spatial relations can also be specified using a string representation of an intersection matrix. Output Tags The SpatialFilterFactory supports the following output tags. PASSED CANDIDATE features where at least one of the specified predicates was TRUE with at least one of the BASE features. FAILED CANDIDATE features where all of the specified predicates were FALSE with all of the base features. TO BE RESOLVED USE_CANDIDATE_CENTER_OF_MASS, USE_BASE_CLOSEST_POINT, BASEID_ATTR, RELATIVE_POSITION_LIST_ATTR clauses added to Syntax section above, but not documented. LEFT_RIGHT added to syntax section above as parameter for PREDICATE clause, but not documented. Developer Notes The factory itself does not test any of the spatial predicates; all that testing is handed off to the SpatialPredicateAPI (foundation/framework/geometry/spatialpredicate/). Currently (2003/09/18), the SpatialPredicateAPI does not implement all the functionality that the SpatialFilterFactory requires. Specifically, the following factory functionality has certain limitations: -BEYOND and WITHIN are not implemented. -DIMENSION is always 2 Update, October 2004: GEOS library is used to implement non-bounding box comparisons, with the spatialop library used to interface with GEOS. The factory currently handles parsing the corresponding clauses for the above-mentioned functionality, and will issue a warning to the user indicating that the functionality is not currently implemented. In the SpatialFilter class implementation look for 'FIXME' commented blocks for the areas that require implementation.