Description

The clipper takes a number of clip boundaries (clippers) and a number of features to be clipped (clippees). As of FME 2013 the output is split into two groups - prior to FME 2013 the output was split into four groups:

  • INSIDE (all clippee features that are completely inside a clipper feature)
  • OUTSIDE (all clippee features that are completely outside all clipper features)
  • Clippee features that intersect a clipper boundary are split up in the parts. Those parts that fall inside the clipper are output via the INSIDE port and those parts that fall outside the clipper feature are output via the OUTSIDE port.

Where a clippee feature crosses the boundaries of a clipper feature it is split up into separate parts.
The "Clippees on Clipper Boundary" setting indicates whether clippee features that coincide with a clipper boundary are considered to be inside or outside. If set to "Treat as Inside and Outside" then point and line segments on the boundary are duplicated and output as both INSIDE and OUTSIDE.
 

Clippers First

In normal use, the Clipper takes in Clipper and Clippee features one at a time and holds them in memory until the entire group is complete. At that point processing takes place. It has to hold features in memory because processing can't begin until all Clipper features have been read, and there is no way to know when that occurs.

The 'Clippers First' setting (under Clipper Type) tells FME that the flow of data is

A) all Clipper features, then
B) all Clippee features.


The Clipper reads features one at a time as before, but as soon as a Clippee feature is encountered, it can assume that the set of Clippers is exhausted. Now Clippee features can be processed one at a time without having to hold the entire group in memory. The only features stored in memory are the Clippers - and there are generally fewer of those.

So how does a user ensure that all Clipper features are first? There are three ways:

  1. Clippers and Clippees are normally held in separate datasets. FME reads all datasets in the order shown in the navigation pane; top dataset first. Therefore, by moving the Clipper dataset to the top of the list, (right-click it and choose the option to 'move up in list') a user can force those features to be read first.
  2. If the Clippers are held in the same stream of data (but obviously split up before entering the Clipper), then the Sorter transformer can be used to promote the Clipper features in front of the Clippees.
  3. The FeatureHolder transformer put before features entering the Clippee port is an alternative for the Sorter.

When used this way, the Clipper becomes a successful alternative to the PointOnAreaOverlayer.

Clippers First Example

The attached workspace (ClippersFirst.fmwt) shows an example use of the Clipper transformer.

This example demonstrates the Clippers First type of Clipper. The idea is that by forcing the Clippers to arrive first, the Clipper transformer can process Clippees immediately. Without this setting (e.g. if Clipper Type = Multiple Clippers) the Clipper transformer has to cache all incoming features because it cannot be certain that there are no more Clippers yet to arrive. The benefit is improved performance - the process is usually faster and uses less memory.

Here we force Clippers to be first simply by setting 'Create at End' on Creator_2 (which is creating the clippee features) to 'Yes' so the Clippees are sent to the Clipper transformer after the Clipper features.

Workspace Screenshot

User-added image

Log Files - Memory Usage

The log file reports the amount of memory used during translation:

For the Multiple Clippers...

2007-01-31 10:46:49|  55.5|  0.0|INFORM|Translation was SUCCESSFUL with 1 warning(s) (0 feature(s)/0 coordinate(s) output)
2007-01-31 10:46:49|  55.5|  0.0|INFORM|FME Session Duration: 57.3 seconds. (CPU: 53.7s user, 0.8s system)
(Peak process memory usage: 109760 kB, current process memory usage: 26888 kB)


For the Clippers First...

2007-01-31 10:49:46|  43.3|  0.0|INFORM|Translation was SUCCESSFUL with 1 warning(s) (0 feature(s)/0 coordinate(s) output)
2007-01-31 10:49:46|  43.3|  0.0|INFORM|FME Session Duration: 43.7 seconds. (CPU: 42.2s user, 0.6s system)
(Peak process memory usage: 17772 kB, current process memory usage: 15844 kB)


So the good news here is multiple. We've shown a quicker translation (57 seconds vs 43) and we've proved the reduced memory usage (approx 85% reduction).

Note that these numbers may vary depending on your machine and version of FME installed.
 


Unexpected Aggregates

Be aware that if a single feature is split into individual parts, and more than one of these parts falls inside the clip boundary (e.g. a line feature wandering across the clipper at several locations) you will get an aggregate feature (i.e. group) of all the separate parts inside each clipper.

This can be useful, but also a problem when you don't know about it (e.g. write aggregates to DXF and you'll get insert features instead of the individual lines).

Unexpected Aggregates Example

The attached workspace (ClipperCreateAggregates.fmwt) shows an example use of the Clipper transformer.

This example illustrates use of the Create Aggregates setting. The Clippee here crosses over the Clipper a number of times. When Create Aggregates = Yes then an aggregate feature is created of all parts from the same source Clippee.

Workspace Screenshot

User-added image

Output Screenshot

Here Create Aggregates = Yes. An aggregate is created of the OUTSIDE parts. On querying one they are all selected (here coloured green). The INSIDE parts would be similarly grouped.

User-added image

Here Create Aggregates = No. The queried OUTSIDE part (again coloured green) remains as an individual feature. The INSIDE parts would be similarly ungrouped.

User-added image