Syntax FACTORY_DEF ClipperFactory [FACTORY_NAME ] [INPUT (CLIPPER|CANDIDATE) FEATURE_TYPE [ ]* []*]+ [GROUP_BY []+] [FLUSH_WHEN_GROUPS_CHANGE (Yes|No)] [MULTIPLE_CLIPPERS (YES|NO)] [CLIPPERS_FIRST (YES|NO)] [OVERLAPPING_CLIPPERS (CLIP_INTERIM|CLIP_ORIGINAL|CLIP_OUTSIDE)] [INVALID_PARTS_HANDLING (REJECT_PARTS|REJECT_WHOLE)] [Z_VAL_SOURCE (CANDIDATE|CLIPPER|CANDIDATE_AND_CLIPPER)] [MISSING_Z_MODE (PLANAR|LINEAR|DROP|)] [CONNECT_Z_MODE (EXTEND|AVERAGE|SINGLE|IGNORE)] [M_VAL_SOURCE (CANDIDATE|CLIPPER|CANDIDATE_AND_CLIPPER)] [MISSING_M_MODE (LINEAR|NEAREST|DROP|)] [CLEANING_TOLERANCE (AUTO|)] [CANDIDATE_ON_BOUNDARY (INSIDE|OUTSIDE|BOTH)] [PRESERVE_RASTER_EXTENTS (YES|NO)] [RASTER_CELL_MODE (CENTER|BOUNDARY)] [CLIPPED_INDICATOR_ATTR ] [MERGE_CLIPPER_ATTRIBUTES [(YES|NO)]] [ATTR_ACCUM_MODE (MERGE|PREFIX_CLIPPER|CLIPPER_ONLY)] [ATTR_CONFLICT_RES (CANDIDATE|CLIPPER)] [CLIPPER_PREFIX ] [LIST_NAME ] [LIST_ATTRS_TO_INCLUDE []* ] [LIST_ATTRS_TO_INCLUDE_MODE (ALL|SELECTED)] [OUTPUT (INSIDE|OUTSIDE|REMNANTS|REJECTED) FEATURE_TYPE [ ]* []*]* Overview This factory is used to perform a geometric clipping operation on input features. It takes two types of features identified by the CLIPPER and CANDIDATE input tags. Input Tags The ClipperFactory supports the following input tags. CLIPPER Features used to geometrically clip Candidates. Can be areas, solids, collections of areas, collections of solids, or collections of areas and solids. CANDIDATE Features to be geometrically clipped by Clippers. Can be any geometry. Clauses GROUP_BY []+ Each Candidate will only be Clipped with Candidates whose attribute values match the candidates attribute values, for all of the provided attribute names. FLUSH_WHEN_GROUPS_CHANGE Only applies when GROUP_BY has attribute names specified. YES Complete processing for the current Clippers/Candidates immediately when features arrive whose attribute values (for the attribute names specified by GROUP_BY) do not match those of the current Clippers and Candidates. NO Wait for all features before completing the processing of any Clipper/Candidate groups. CLIPPERS_FIRST YES Clippers that arrive after a Candidate has been received will be rejected. Candidates will be processed as soon as they arrive. NO Clippers that show up at any time will be processed. Candidates will delay being processed until all Clippers can be considered. MULTIPLE_CLIPPERS YES All clippers will clip all candidates. Candidates will delay being processed until all Clippers can be considered NO Only the first clipper will be used. All other clippers will be rejected. Candidates can be processed as soon as a single clipper has arrived. OVERLAPPING_CLIPPERS CLIP_INTERIM Each clipper feature will clip the interim results (both inside and outside) produced by the previous clipper feature's interaction with all the candidates. The part of a candidate that's outside of all clippers will be output from the outside port. CLIP_ORIGINAL Each clipper feature will clip the original form of a candidate. Their intersection will be output via the inside port. The part of a candidate that's outside of all clippers will be output from the outside port. CLIP_OUTSIDE Each candidate will be clipped by the first clipper, then the part that's outside of the first clipper will be clipped by the second clipper, and so on. The part of a candidate that's outside of all clippers will be output from the outside port. INVALID_PART_HANDLING REJECT_PARTS_ONLY Only parts in a multi/aggregate feature that are invalid as input will be rejected. The rest of the feature will remain aggregated. Feature hierarchy will be maintained as much as possible. REJECT_WHOLE_FEATURE When a feature contains parts that are invalid as input, the whole feature will be rejected. ADD_NODATA YES adds a nodata band to represent the area that was not clipped from the raster NO don't add a nodata band, and just set all existing bands to zero to represent the clipped area Z_VAL_SOURCE This parameter applies to area/area clipping. If an area clipper intersects an area candidate, and at least one of them is 3D, it will specify where the z values for the resulting clipped piece should be taken/interpolated from. CANDIDATE Use the Z values from the candidate CLIPPER Use the Z values from the clipper CANDIDATE_AND_CLIPPER Use the Z values from both the candidate and the clipper MISSING_Z_MODE This parameter applies to area/area clipping. If an area clipper intersects an area candidate, and only 1 of them is a source for z values, then this parameter will specify how to add Z values to the boundary segments that still need them. PLANAR A plane is created from the coordinates with existing z values. Coordinates without z values are given z values that lie on that plane. LINEAR The z value of the newly constructed boundary is assumed to change linearly. Missing z values will be interpolated from the nearest neighbouring z values along the boundary. DROP Any missing z values on a boundary will cause all z values to be dropped. Any missing z values will be replaced with the custom value. CONNECT_Z_MODE This parameter applies to area/area clipping. If an area clipper and an area candidate intersect in 2D space, but don't intersect in 3D space, they are still treated as intersecting, and this parameter specifies how to connect segments from the two when creating the clipped results. EXTEND Vertices above/below vertical gaps will be connected with a vertical line. AVERAGE Vertices above/below vertical gaps will be snapped together to the midpoint of the vertical gap. SINGLE Vertices above/below vertical gaps will be snapped to one of the existing vertices. IGNORE Vertical gaps will be left. The segments on either side will be preserved by ensuring the boundary is a path. M_VAL_SOURCE This parameter applies to area/area clipping. If an area clipper intersects an area candidate, and at least one of them has measures, it will specify where the measure values for the resulting clipped piece should be taken/interpolated from. CANDIDATE Use the measure values from the candidate CLIPPER Use the measure values from the clipper CANDIDATE_AND_CLIPPER Use the measure values from both the candidate and the clipper MISSING_M_MODE This parameter applies to area/area clipping. If an area clipper intersects an area candidate, and at only one of them has a particular measure, it will specify how to populate the missing measures. LINEAR_INTERPOLATION Use the measure values from adjacent vertices to perform a linear interpolation to determine the missing measure value. NEAREST_VERTEX Use measure values from the nearest neighbouring vertex to determine the missing measure value. DROP_VALUES If an output feature has missing measure values on any vertices, all measure values are dropped. If an output feature has measure values on all vertices, all measure values are preserved. Use the value specified in this parameter on any vertices with a missing measure value. CLEANING_TOLERANCE If the CLEANING_TOLERANCE directive specifies a non-negative number, vertices within this tolerance might be merged. If the CLEANING_TOLERANCE is AUTO, a cleaning tolerance will be automatically generated based on the input geometries. CANDIDATE_ON_BOUNDARY If a candidate, or a portion of a candidate, lies on the boundary of a clipper, this parameter will specify how that candidate (or portion of candidate) should be classified. INSIDE Treat the portion of the candidate on the clipper's boundary as "inside" of the clipper OUTSIDE Treat the portion of the candidate on the clipper's boundary as "outside" of the clipper BOTH Treat the portion of the candidate on the clipper's boundary as both "inside" and "outside" of the clipper. This will duplicate that portion of the candidate for each clipper that it is on the boundary of. PRESERVE_RASTER_EXTENTS YES Clipped rasters are guaranteed to still have the full extents of the original raster candidate. NO Clipped rasters may have smaller extents than the original raster candidate RASTER_CELL_MODE Specifies what portion of the raster cell is used to determine clipping. CENTER The center of the cell determines its location. If the center is inside of the clipper, the cell is inside the clipper. If the center is outside of the clipper, the cell is outside the clipper. If the center is on the boundary of the clipper, the cell is on the boundary of the clipper. BOUNDARY The boundary of the cell determines its location. If the entire boundary is inside the clipper, the cell is inside the clipper. If the entire boundary is outside the clipper, the cell is outside the clipper. If the boundary is partially inside and partially outside the clipper, the cell is on the boundary of the clipper. CLIPPED_INDICATOR_ATTR This attribute (if specified) will be added with a value of yes to any features output via either the Inside or Outside port which were cut by the transformer, and a value of no to any output features which were not cut by the transformer. MERGE_CLIPPER_ATTRIBUTES YES Any candidates, or pieces of candidates, that are output through the INSIDE port will have attributes copied over from the clipper(s) that contained them. NO No outputs will receive attributes from the clippers. ATTR_ACCUM_MODE Only applies if MERGE_CLIPPER_ATTRIBUTES is YES MERGE Attributes from clippers will be copied without modification to the candidates, or pieces of candidates, they contain. PREFIX_CLIPPER Attributes from clippers will have their attribute names prefixed before being copied to the candidates, or pieces of candidates, they contain. CLIPPER_ONLY Candidates, or pieces of candidates, that are contained by one or more clippers will have their attributes removed before the Clipper's attributes are copied onto them. ATTR_CONFLICT_RES Only applies if MERGE_CLIPPER_ATTRIBUTES is YES CANDIDATE Only merge attributes from a Clipper to a Candidate if an attribute with the same name doesn't already exist on the Candidate. CLIPPER Merge (and potentially overwrite) attributes from Clipper to Candidate, regardless of naming conflicts. CLIPPER_PREFIX Only applies if MERGE_CLIPPER_ATTRIBUTES is YES and ATTR_ACCUM_MODE is PREFIX_CLIPPER. This value will be used to prefix Clipper attributes before merging. LIST_NAME If specified, will generate a list of Clipper attributes on candidates, or pieces of candidates, that are output via the INSIDE port. The Clipper attributes will come from the one or more containing Clippers. Whether or not there are more than one elements in the list will depend on the location of the clippers, and the value of OVERLAPPING_CLIPPERS LIST_ATTRS_TO_INCLUDE Only applies if LIST_NAME was specified and LIST_ATTRS_TO_INCLUDE_MODE is SELECTED []* These values specify which Clipper attributes to include in the lists being added to the Candidates. LIST_ATTRS_TO_INCLUDE_MODE Only applies if LIST_NAME was specified. ALL All Clipper attributes will be included in lists. SELECTED Only the attributes specified by LIST_ATTRS_TO_INCLUDE will be included in lists. Output Tags INSIDE Features that are entirely within a clipper, and partial features that are within a clipper are output here. OUTSIDE Features that are entirely outside all clippers, and partial features that are outside all clippers are output here. REMNANTS During the clipping operation, sometimes resulting pieces of geometry are produced that cannot be integrated into the output geometry being built. For example, when clipping a Donut, one of the holes may collapse down to a line or a point. This cannot be put back onto the Donut as a valid hole. These unused parts produced by intermediate processing are output from the Remnants port. Features that cannot be clipped (eg. IFMENull etc.) or features that we do not currently support (eg. Voxels) will be rejected by the factory. Output features from the port should be unmodified original input features, unless the "Invalid Parts Handling" setting is used. (In that case, the invalid parts are split off from the original feature and rejected.) Output should have fme_rejection_code, and fme_rejection_message and follow all other port guidelines.