Syntax

   FACTORY_DEF <ReaderKeyword> SolidIntersectionFactory
   [FACTORY_NAME <factory name>] 
   [INPUT CLIPPER FEATURE_TYPE <feature type>
      [<attribute name> <attribute value>]*
      [<feature function>]*]+
   [INPUT CLIPPEE FEATURE_TYPE <feature type>
      [<attribute name> <attribute value>]*
      [<feature function>]*]+
   [REJECT_INVALID_GEOM <Yes|No>]
   [MULTICLIP (YES|NO|CLIPPERS_FIRST)]
   [CLIPPER_ATTR_PREFIX <attribute prefix value>]
   [CLIPPEE_ON_BOUNDARY (INSIDE|OUTSIDE|BOTH)]
   [MERGE_CLIPPER_ATTRIBUTES [(YES|NO)]]
   [OUTPUT_NO_CLIPPERS_AS_OUTSIDE]
   [OUTSIDE_NO_CLIPPERS_ATTR <attribute name>]
   [DO_NOT_AGGREGATE [(YES|NO)]]
   [GROUP_BY [<attribute name>]+]
   [FLUSH_WHEN_GROUPS_CHANGE (Yes|No)]
   [OUTPUT (CLIPPED_INSIDE|CLIPPED_OUTSIDE|
      INSIDE|OUTSIDE|UNUSED|REJECTED)
      FEATURE_TYPE <feature type>
      [<attribute name> <attribute value>]*
      [<feature function>]*]*

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 
   CLIPPEE input tags.
   
   Clipping features are identified by the tag CLIPPER. These features identify 
   the area against which all CLIPPEE features are processed. The CLIPPER can be 
   a solid or multi-solid feature. Any non-solid clipping features that are 
   encountered are destroyed and a warning is output. 
   
   The "clippee" features are identified by the tag CLIPPEE. These are clipped 
   in such a way that features totally within the CLIPPER feature are output 
   from the factory via the INSIDE tagged output clause. Valid clippee features 
   for the SolidIntersectionFactory are points, solids, point clouds, and 
   aggregates of these geometries. Any invalid features will be output out the 
   REJECTED port. The clipping operates in one of three ways according to the 
   style of multiclipping selected by the tag MULTICLIP. If the default option 
   of NO is selected, only one input clipper will be accepted. For each instance 
   of the factory, the first solid feature that matches the CLIPPER 
   specification is used as the clipping solid, and other solid features are 
   destroyed and ignored. 
   
      Tip: Since CLIPPEE features must be held by the factory until the CLIPPER 
      feature arrives, take care wherever possible to ensure that the CLIPPER 
      feature arrives before any CLIPPEE features.
   
   When REJECT_INVALID_GEOM is Yes, the factory will output invalid features to
   Rejected port.

   If the YES option for the MULTICLIP tag is selected, multiple CLIPPER 
   features may be given to the clipping factory. The CLIPPERs will be applied 
   to all the CLIPPEEs in the order that they are input. In this mode, all the 
   CLIPPEE features are held in a cache until all the CLIPPERs and CLIPPEEs have 
   arrived into the clipping factory. Then, when we are sure that all clippers 
   have arrived, clipping begins.
   
   The CLIPPERS_FIRST option for the MULTICLIP tag is the third and final mode 
   which is a modification of the YES option that allows for better efficiency. 
   If selected, the clipping factory will expect the first feature input to be 
   CLIPPERs. Once the first CLIPPEE feature is given, all subsequent CLIPPER 
   features will be output immediately by the REJECTED tagged output clause. In 
   this mode, no CLIPPEE features are held, and clipping begins when the first 
   CLIPPEE arrives.
   
   CLIPPEE features that intersect the CLIPPER features are broken up into 
   pieces, with those pieces on the inside of the CLIPPER features being output 
   by the CLIPPED_INSIDE tags. Those portions outside the clipping solid are 
   output via the CLIPPED_OUTSIDE tagged output clauses.
   
   If a CLIPPEE feature is found to be inside a CLIPPER, or is clipped inside a 
   CLIPPER, the inside parts are no longer clipped by other CLIPPERs. As such, 
   results may vary depending on the order that the CLIPPERs are given to the 
   clipping factory.
   
   Features completely outside all of the CLIPPER features are output by the 
   OUTSIDE tagged output clause. Features that are clipped outside of a CLIPPER 
   will have their outside parts clipped by any subsequent CLIPPERs.
   
   If MERGE_CLIPPER_ATTRIBUTES is specified, then whenever a clippee is found to 
   be inside or clipped inside a CLIPPER, the attributes of the clipper will be 
   copied to the inside parts of the output features. The CLIPPER_ATTR_PREFIX 
   directive specifies a string prefix to be added to the attributes of a 
   CLIPPER that are copied to a CLIPPEE. If attributes of the same name already 
   exist on the CLIPPEE, they will be overridden. If this prefix is not 
   specified or is empty, the attributes will still be copied to the output 
   features, but they will not overwrite any existing attributes of the same 
   name.
   
   The CLIPPEE_ON_BOUNDARY directive directs what action should be taken with 
   clippee features that lie entirely on the boundary of the clipper. If the 
   value INSIDE is given, then these features that lie on the boundary are 
   output via the INSIDE tagged output clause. If the value OUTSIDE is given, 
   then these features that lie on the boundary are output via the OUTSIDE 
   tagged output clause. If BOTH is given, points on the boundary are duplicated 
   and output as both INSIDE and OUTSIDE. If the CLIPPEE_ON_BOUNDARY directive 
   is not specified, the default behavior is INSIDE.
   
   All of the output tags are optional.
   
   If the GROUP_BY clause is given, then each CLIPPEE will only be clipped by 
   CLIPPERs that contain the same values as itself in the attributes specified 
   by this clause.

   If the GROUP_BY clause is specified, and FLUSH_WHEN_GROUPS_CHANGE is set to Yes,
   the factory will flush the current group whenever a feature from a different
   group is encountered.

TO BE RESOLVED

   OUTPUT_NO_CLIPPERS_AS_OUTSIDE, OUTSIDE_NO_CLIPPERS_ATTR clauses added to 
   Syntax section above, but not documented.