Syntax FACTORY_DEF SpatialRelationshipFactory [FACTORY_NAME ] [INPUT BASE FEATURE_TYPE [ ]* []*]+ [INPUT CANDIDATE FEATURE_TYPE [ ]* []*]+ PREDICATE [(INTERSECTS|EQUALS|TOUCHES|CROSSES|OVERLAPS|CONTAINS| WITHIN||&|@)]+ [LIST_NAME ] [LIST_ATTRS_TO_INCLUDE []* ] [LIST_ATTRS_TO_INCLUDE_MODE (ALL|SELECTED)] [SUCCESS_ATTR ] [REJECT_INVALID_GEOM (Yes|No)] [IGNORE_NULLS [(YES|NO)]] [REJECT_INVALID_PREDICATES (Yes|No)] [REJECT_RASTERS (Yes|No)] [ALLOW_NULLS (Yes|No)] [DIFFERING_ATTRIBUTES []+] [CALCULATE_CARDINALITY [(YES|NO)]] [CURVE_BOUNDARY_RULE (ENDPOINTS_MOD2|ENDPOINTS_ALL)] [HANDLE_ARCS_ELLIPSES_AND_TEXT [(YES|NO)]] [GROUP_BY [+]*] [FLUSH_WHEN_GROUPS_CHANGE (Yes|No)] [MERGE_INCOMING_ATTR (yes|no)] [ATTR_ACCUM_MODE (HANDLE_CONFLICT|PREFIX_INCOMING|INCOMING_ONLY)] [ATTR_CONFLICT_RES (ORIGINAL_IF_CONFLICT|INCOMING_IF_CONFLICT)] [INCOMING_ATTR_PREFIX ] [OUTPUT TAGGED FEATURE_TYPE [ ]* []*]* Overview This factory accepts two kinds of features - Bases and Candidates - and tests topological (spatial) relationships between them. These relationships are also known as Egenhofer relationships. The factory tags (but does not otherwise change) the BASE features when these relationships are present. All the BASE features are output via the TAGGED port, with a new list attribute appended. Each input CANDIDATE feature is compared against the BASE features, based on the specified spatial tests. When one of the comparisons is true, an entry will be added to the BASE's list attribute as follows: {i}.de9im = [DE9IM string] {i}.pass{0} = [first true PREDICATE] {i}.pass{1} = [second true PREDICATE] ... {i}.pass{n} = [(n+1)th true PREDICATE] All the attributes of the matching CANDIDATE feature will also be added to the list. Furthermore, each BASE receives the attributes of the CANDIDATE(s) that passed the relationship. When attributes are merged down from CANDIDATE to BASE features, existing attributes are not replaced. Therefore if the CANDIDATEs and BASEs have attributes with the same name, then the values will not be transferred down. An example scenario for this factory would be if you had a group of states and rivers, and you wanted to determine which rivers were completely contained in which states. Then, the states would be directed into the BASE clause and the rivers would be directed into the CANDIDATE clause. The PREDICATE clause would be CONTAINS. Each BASE attribute would then receive a new list attribute, with one entry for each river that is contained in it. Note: The SpatialRelationshipFactory does not remove attributes or alter the geometry of the BASE features; it simply adds attributes. Also note that the SpatialRelationshipFactory must wait until all features have entered the factory before it can begin processing. If the MERGE_INCOMING_ATTR is YES, then any conflicts between features with same attributes are to be resolved. The ATTR_ACCUM_MODE's value is the way of resolving the conflicts and its possible values are: HANDLE_CONFLICT, PREFIX_INCOMING and INCOMING_ONLY. If HANDLE_CONFLICT is chosen, we need to provide ATTR_CONFLICT_RES, and its possible values are: ORIGINAL_IF_CONFLICT and INCOMING_IF_CONFLICT. If PREFIX_INCOMING, we need to provide prefix with INCOMING_ATTR_PREFIX. Input Tags The SpatialRelationshipFactory supports the following input tags. BASE Features used as the criteria for the test (i.e., the features which will be tagged with a list describing the relationships). CANDIDATE Features to be tested against the given criteria (i.e., the features that may appear as entries in the lists). Clauses The SpatialRelationshipFactory supports the following clauses: The PREDICATE clause lists the spatial predicates that will be used for comparisons between the base and candidate features. See the documentation for the SpatialFilterFactory to see an explanation of the available option. Note: DISJOINT is not a valid choice for the SpatialRelationshipFactory. If you wish to run multiple tests, the predicates should be separated by spaces, e.g. "MEET OVERLAP CONTAINS". This clause may also specify a CANDIDATE attribute, which should contain a string of predicates; then, each CANDIDATE will be tested for the predicates given in its own attribute--in a space-separated list. Additionally, a function name may be specified, where the function should return a string of predicates. In addition to the predefined predicates, you may also specify 9-character masks. Such masks consist of the rows of a Dimensionally Extended 9 Intersection Matrix (see the SpatialFilterFactory chapter for more details on these matrices). That is, if you wanted to check for the relationship described by the following matrix: T0* *2* F** you would use the mask T0**2*F**. These masks must contain only the following characters: *, T, F, 0, 1, 2. Furthermore, these masks must not represent a potentially-disjoint relationship. That is, at least one of the first, second, fourth, or fifth characters must be a T, 0, 1, or 2. The LIST_NAME clause specifies the name of the list attribute that will be added to the BASE features. The optional LIST_ATTRS_TO_INCLUDE_MODE will specify if ALL attributes should be added to a list, or if only the SELECTED attributes (specified with the LIST_ATTRS_TO_INCLUDE clause) should be added to the list. If this value is not specified, it defaults to ALL. The SUCCESS_ATTR clause specifies the name of an attribute that will be added to each base which stores the number of candidates that had at least one true relationship with that base. The DIFFERING_ATTRIBUTES clause controls which attributes must have different values before a match is declared. If the CALCULATE_CARDINALITY clause is specified, then for each - match, the "cardinality" of this intersection is computed. Three attributes are added to the corresponding list entry: card_point, card_line, and card_area. These will each be given an integer value specifying how many points, lines, and areas result from the intersection. An area results from two overlapping areas. A line results, for instance, from two areas that touch, sharing a line segment, or two overlapping lines, or a line crossing an area. A point results from such interactions as two areas touching only at a vertex, two crossing lines, or a point contained in a line or in an area. The CURVE_BOUNDARY_RULE clause determines how the "boundary" of linear features is determined; see the Spatial Predicate Background section in the SpatialFilterFactory chapter for details. The GROUP_BY clause is used to indicate that only BASEs and CANDIDATEs which have the same value for certain attributes should be compared. That is, if GROUP_BY attributes are specified, candidates are only compared to bases that have the same values in these attributes. If the GROUP_BY clause is specified, FLUSH_WHEN_GROUPS_CHANGE (when set to Yes) will cause the factory to process and output the current group immediately when an attribute that does not belong to the current group is encountered. 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 processed (ie. quietly ignored if they are suppliers), or always rejected/discarded Output Tags The SpatialRelationshipFactory supports the following output tag. TAGGED These will be the BASE features, with the new attributes added. One list entry will be made for each of the candidates that has at least one matching predicate. TO BE RESOLVED HANDLE_ARCS_ELLIPSES_AND_TEXT clause added to Syntax section above, but not documented. This clause is now deprecated, but must be kept for legacy purposes.