Syntax FACTORY_DEF OverlayFactory [FACTORY_NAME ] [INPUT (SURFACE|POLYGON|POINT|LINE) FEATURE_TYPE [ ]* []*]+ [HANDLE_ARCS_AND_ELLIPSES [(YES|NO)]] [MODE [(QUICK|COMPLETE)]] [VERIFY_INDEX] [VERBOSE] [ACCUMULATE_ATTRIBUTES (all|none|one)] [MERGE_MEASURES (YES|NO)] [MEASURE_TYPE (CONTINUOUS|DISCRETE)] [LIST_NAME ] [LIST_ATTRS_TO_INCLUDE []* ] [LIST_ATTRS_TO_INCLUDE_MODE (ALL|SELECTED)] [CANDIDATE_LIST_NAME ] [CANDIDATE_LIST_ATTRS_TO_INCLUDE []* ] [CANDIDATE_LIST_ATTRS_TO_INCLUDE_MODE (ALL|SELECTED)] [OVERLAP_COUNT_ATTRIBUTE ] [SEPARATE_COLLINEAR_SEGMENTS [(YES|NO)]] [TOLERANCE ] [NORMAL_TOLERANCE ] [OFFSET_TOLERANCE ] [POLYS_FIRST [(YES|NO)]] [GROUP_BY []+]* [FLUSH_WHEN_GROUPS_CHANGE (Yes|No)] [ATTR_ACCUM_MODE (HANDLE_CONFLICT|PREFIX_INCOMING|INCOMING_ONLY)] [ATTR_CONFLICT_RES (ORIGINAL_IF_CONFLICT|INCOMING_IF_CONFLICT)] [CLIPPER_PREFIX ] [REJECT_INVALID_GEOM [(yes|no)]] [CLEANING_TOLERANCE (NONE|AUTO|)] [OUTPUT_REMNANTS] [OUTPUT (SURFACE|POLYGON|POINT|LINE|ILLEGAL_GEOM|IGNORED_GEOM|REMNANTS) FEATURE_TYPE [ ]* []*]* Overview This factory performs an overlay operation. During the overlay, all intersections and overlaps of the input features are computed, and the attributes of features that interact are merged. Merging adds new attributes to a feature but it will not replace or alter existing attributes. If necessary, new features will be created for each area or line segment created as a result of the overlay. When new points are added during the intersection calculations, if the original lines had measures, the new points will have the same measures, interpolated between the nearest points by distance along the connecting segment. For adding points to arcs, the distance around the perimeter of the arc is used. If VERIFY_INDEX is present, a sequential scan is done to verify the spatial index results. If VERBOSE is present, more statistics are output. This factory has six distinct modes of operation: Mode 1: Polygon Overlay Mode 2: Point on Polygon Overlay Mode 3: Line on Polygon Overlay Mode 4: Point on Line Overlay Mode 5: Point Overlay Mode 6: Line Overlay Mode 7: Surface Overlay The mode of the factory is determined by which combination of input tags are present. Any aggregates input to the factory are split up and treated as though they were separate features. This factory merges attributes between features being overlayed. The merging is based on the 3 parameters, ATTR_ACCUM_MODE, ATTR_CONFLICT_RES, and CLIPPER_PREFIX. The merging may take the original or incoming attributes, possibly prefixed, based on the combinations of these various parameters. The ACCUMULATE_ATTRIBUTE clause is responsible for choosing an attribute accumulation option for no requestor/supplier transformers. If NONE is selected, the transformer will drop all incoming attributes; if ALL is selected, the transformer will merge all incoming attributes; if ONE is selected, the transformer will get attributes from one of the features. The optional LIST_NAME clause is used to associate attributes with incoming feature. When the output feature is created, all attributes of each feature joining the output are added as members of the specified attribute list. 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. If REJECT_INVALID_GEOM is Yes, then the features will be rejected. If the CLEANING_TOLERANCE keyword does not exist or has the value "NONE", no cleaning will be performed. If the CLEANING_TOLERANCE directive specifies a non-negative number, geometries within this tolerance will be merged. If the CLEANING_TOLERANCE is AUTO, a cleaning tolerance will be automatically generated based on the input geometries. If the OUTPUT_REMNANTS keyword is specified, remnants will be output via the REMNANTS output tag. Mode 1: Polygon Overlay This mode is entered only when the POLYGON input tag is present in the factory definition. In this mode, input polygons are analyzed and new polygons are formed for each area that results when the original polygons are overlayed on top of each other. The resulting polygons have all their attributes merged. If the LIST_NAME clause is present, each output area will have an attribute list containing the attributes from each area it overlaps. As well, if the OVERLAP_COUNT_ATTRIBUTE clause is present, an attribute will be added indicating the number of input features the area overlaps. In this mode, only the POLYGON output tag is used. If any other output tags are specified, they will cause an error during factory creation. Mode 2: Point on Polygon Overlay This mode is entered when the POLYGON and POINT input tags are present in the factory definition. In this mode, each input point is tested against each input polygon. If the polygon contains the point, the attributes of the point are merged with the polygon and the attributes of the polygon are merged with the point. If the LIST_NAME clause is present, the attributes of each polygon containing the point are added to the point's list, and the attributes of each point contained by a polygon are added to the polygon's list. As well, if the OVERLAP_COUNT_ATTRIBUTE clause is present, an attribute will be added to each polygon indicating the number of points it contained, and similarly each point will have an attribute which holds the number of polygons it was inside. If the POLYS_FIRST clause is present with a value of YES, then the Point On Polygon Overlay process expects to receive all polygon features before any point features are received. Any polygons received after the first point has been processed will be logged with a warning and discarded. Points that lie on the boundary of a polygon are considered to be contained in the polygon. In this mode, the POLYGON and POINT output tags are available to be used. Mode 3: Line on Polygon Overlay This mode is entered when the POLYGON and LINE input tags are present in the factory definition. In this mode, each line is segmented at the polygon boundaries. Then each resulting line is checked against all the original polygons. If the polygon contains the resultant line, the attributes of the line are merged with the polygon and the attributes of the polygon are merged with the line. If the LIST_NAME clause is present, the attributes of each polygon containing the line are added to the line's list, and the attributes of each line contained by a polygon are added to the polygon's list. As well, if the OVERLAP_COUNT_ATTRIBUTE clause is present, an attribute will be added to each polygon indicating the number of lines it contained, and similarly each line will have an attribute that holds the number of polygons it was inside. Lines that lie on the boundary of a polygon (collinear) are considered to be contained in the polygon. In this mode, the POLYGON and LINE output tags are available to be used. Mode 4: Point on Line Overlay This mode is entered when the POINT and LINE input tags are present in the factory definition. In this mode, each line is segmented at the points if on the line or at the closest coordinates to the points. Then each resulting line is checked against all the points. If the TOLERANCE clause is present, the value is compared to the distance from the lines to the points and the lines will be segmented if the distance is less than or equal to the TOLERANCE value. When such a match occurs, the attributes of the segmented lines are merged with the points and the attributes of the points are merged with the lines. If the LIST_NAME clause is present, the attributes of each point used to segment the line are added to the line's list, and the attributes of each line that the point segmented are added to the point's list. As well, if the OVERLAP_COUNT_ATTRIBUTE clause is present, an attribute will be added to each line indicating the number of points it was segmented by, and similarly each point will have an attribute that holds the number of lines it segmented. By default, measures and elevation will be merged in the same manner as Attributes. Specifying whether or not to merge measures/elevation with the MERGE_MEASURES keyword will overwrite the default behaviour. The MEASURE_TYPE keyword will specify whether measures should be treated as discrete, or continuous. In this mode, the POINT and LINE output tags are available to be used. Mode 5: Point Overlay This mode is entered when only the POINT input tag is present in the factory definition. In this mode, input points within the TOLERANCE distance specified are matched up with each other. Each output point has the attributes of all other points within the tolerance merged onto it.. If the LIST_NAME clause is present, each output point will also have an attribute list containing the attributes from each point which is within the TOLERANCE distance. As well, if the OVERLAP_COUNT_ATTRIBUTE clause is present, an attribute will be added indicating the number of nearby points. This mode provides similar functionality to the ProximityFactory. In this mode, only the POINT output tag is used. If any other output tags are specified, they will cause an error message during the translation. Mode 6: Line Overlay This mode is entered when only the LINE input tag is present in the factory definition. In this mode, input lines are intersected and matched up with each other. In places where the lines were collinear, one line segment is output with all the original feature attributes merged. Points are also created at the locations where lines touched, again with all the original feature attributes merged. If the LIST_NAME clause is present, each output POINT will have an attribute list containing the attributes from each line that touched it. As well, if the OVERLAP_COUNT_ATTRIBUTE clause is present, an attribute will be added indicating the number of lines touching the output feature.. If the SEPARATE_COLLINEAR_SEGMENTS clause is specified, any line segments which are collinear are not merged together; instead, one copy is output for each original feature which shared that segment. If the SEPARATE_COLLINEAR_SEGMENTS clause is not specified, any line segments which are collinear are merged. If the LIST_NAME clause is present, all output lines will have an attribute list containing the attributes from each collinear line that was merged. If the SEPARATE_COLLINEAR_SEGMENTS clause is specified, then the output lines will NOT have an attribute list, regardless of the LIST_NAME clause. In this mode, the POINT and LINE output tags are available to be used. If any other output tags are specified, they will cause an error message during the translation. Mode 7: Surface Overlay In this mode we overlay surfaces against surfaces. Input Tags The OverlayFactory supports the following input tags. LINE Linear features to be overlayed in a fashion determined by the combination of input tags, as specified above. POINT Point features to be overlayed in a fashion determined by the combination of input tags, as specified above. POLYGON Area features to be overlayed in a fashion determined by the combination of input tags, as specified above. SURFACE Surface features to be overlayed. Output Tags The OverlayFactory supports the following output tags. LINE Any linear features input to or created by the overlay operation. POINT Any point features input to or created by the overlay operation. POLYGON Any area features input to or created by the overlay operation. SURFACE Overlaid surface features. ILLEGAL_GEOM Any features that were input with a geometry type not matching the input tag (for instance, a line input with the POLYGON tag.) IGNORED_GEOM Currently only used for Point on Polygon overlaying with AREAS_FIRST set to YES, to tag polygon features that are received after the first point feature, and subsequently ignored. REMNANTS If OUTPUT_REMNANTS is specified, remnants will be output via this tag. Clauses NORMAL_TOLERANCE In SURFACE mode, if two planes are nearly co-planar, but their normals are slightly apart, use this clause to set a tolerance in degrees. OFFSET_TOLERANCE In SURFACE mode, if two planes are parallel, but slightly offset from one another, use this clause to set a tolerance in ground units. GROUP_BY This clause allows for overlaying geometries depending on one or more attributes on the input features. Overlaying will only be performed on input features whose group by attributes (as specified by this clause) are identical. FLUSH_WHEN_GROUPS_CHANGE If the GROUP_BY clause is specified, this clause (when set to Yes) will cause the factory to process and output the current group immediatedly when an attribute that does not belong to the current group is encountered. TO BE RESOLVED MODE added to Syntax section above, but not documented.