SpatialFilter

Filters point, line, area, and text features based on spatial relationships.

Each input Candidate feature is compared against all Filter features, based on the given spatial tests to meet. Features that pass any or all tests are output through the Passed port; all other features are output through the Failed port.

Jump to Configuration

Typical Uses

Routing features, depending on whether a defined spatial relationship is true or false
Performing quality control on a dataset by checking for expected spatial relationships with another dataset
Performing a spatial join to transfer attributes from one feature to another based on their spatial relationship

How does it work?

The SpatialFilter compares two sets of features to see if their spatial relationships meet selected test conditions. The features being tested (Candidate features) are identified as having Passed or Failed the test.

For example, if you have a roads dataset (lines), and wanted to extract all the roads that passed through parks (polygons), you would direct the roads into the Candidate input port, and the parks into the Filter input port.

By selecting the test conditions Filter OGC-Intersects Candidate and Filter OGC-Contains Candidate, any road lines that fall within the parks or intersect the parks would be output via the Passed output port, and the remainder would exit through the Failed output port. You could simultaneously extract an attribute from the park polygon – park name, for example – and add it to the line feature.

Examples

Example: Finding points that are not contained by polygons

In this example, we identify address points that are not contained by a building footprint. The results could be used to find bad address points, or identify missing building polygons.

The two source datasets look like this:

The address points – the dataset to be tested – are connected to the Candidate input port. The building footprints are connected to the Filter port, and provide the geometry that the address points will be tested against.

In the SpatialFilter parameters dialog, we make the following selections:

Filter Type: Multiple Filters. There are multiple building polygons that we want to test against.
Pass Criteria: Pass Against One Filter. Each address point only needs to fall inside one polygon – not all of them.
Spatial Predicates to Test: Filter OGC-Contains Candidate. We want to check if each Candidate (address point) falls within a filter (building polygon).

These are the key parameters – the others are left as default for this example.

Address points that pass the test – that are within a polygon – are sent out through the Passed port, and have a new attribute called _predicate, set to “CONTAINS”.

Address points that fail the test – that are outside all polygons – are sent out through the Failed port. The results, with styling applied in the FME Data Inspector, look like this:

Usage Notes

See Spatial Relations Defined for more information on spatial predicates and an illustration of spatial relationships.
Spatial relations are based on the OGC specification and so are undefined for geometries that are not OGC valid.
Aggregates are accepted by a subset of predicates, but should be used with care. See Spatial Relations Defined for more information.

Choosing a Spatial Transformer

Many transformers can assess spatial relationships and perform spatial joins - analyzing topology, merging attributes, and sometimes modifying geometry. Generally, choosing the one that is most specific to the task you need to accomplish will provide the optimal performance results. If there is more than one way to do it (which is frequently the case), time spent on performance testing alternate methods may be worthwhile.

To correctly analyze spatial relationships, all features should be in the same coordinate system. The Reprojector may be useful for reprojecting features within the workspace.

Spatial Transformers Comparison

Transformer	Can Merge Attributes	Alters Geometry	Counts Related Features	Creates List	Supported Types*	Recommended For
SpatialFilter	Yes	No	No	No	Point Text Curve Area	Testing for the existence of spatial relationships between two sets of features, and routing them according to whether they pass or fail the test(s).
SpatialRelator	Yes	No	Yes	Yes	Point Text Curve Area	Identifying the nature of spatial relationships between two sets of features.
AreaOnAreaOverlayer	Yes	Yes	Yes	Yes	Area	Finding polygon overlaps and extracting them into new geometry.
LineOnAreaOverlayer	Yes	Yes	Yes	Yes	Curve and Area	Finding intersections between lines and polygons, splitting either where they intersect.
LineOnLineOverlayer	Yes	Yes	Yes	Yes	Curve	Finding intersections between line features, splitting them, and generating new line geometry as well as points representing the intersections.
PointOnAreaOverlayer	Yes	No	Yes	Yes	Point and Area Text and Area	Identifying points that fall within polygons, and merging attributes between them
PointOnLineOverlayer	Yes	Yes	Yes	Yes	Point and Curve Text and Curve	Identifying where points fall on lines, and splitting the lines into new geometry.
PointOnPointOverlayer	Yes	No	Yes	Yes	Point Text	Identifying points in the same location (within a tolerance), and merging attributes between them.
Intersector	Yes	Yes	Yes	Yes	Point Text Curve Area	Finding intersections between all input features, regardless of geometry (including self-intersections), splitting features, and creating new geometry.
Clipper	Yes	Yes	No	No	Point Text Curve Area Surface Solids Raster Point Cloud	Comparing features against a set of Clipper features, and splitting the features at or along the Clipper boundaries. Outputs both new and untouched geometry, identified as either Inside or Outside the Clipper.
NeighborFinder	Yes	In some cases	No	Yes	Point Text Curve Area	Identifying the nearest other feature(s) to each feature being considered, either in another set of features or within the same feature set.
TopologyBuilder	Yes	Yes	No	Yes	Point Text Curve Area	Analyzing spatial relationships between features to compute topology, splitting features and creating new geometry representing topologically significant nodes, edges, and faces, with associated attributes.

* Note that Curve includes Lines, Arcs, and Paths. Area includes Polygons, Donuts, and Ellipses.

Configuration

Input Ports

Output Ports

Parameters

Group Processing

Group By

If Group By attributes are specified, candidates are only compared against filters with the same values in these attributes. Both the Candidates and Filters must having matching attribute names and values.

Complete Groups

Select the point in processing at which groups are processed:

When All Features Received	This is the default behavior. Processing will only occur in this transformer once all input is present.
When Group Changes (Advanced)	This transformer will process input groups in order. Changes of the value of the Group By parameter on the input stream will trigger processing on the currently accumulating group. This may improve overall speed (particularly with multiple, equally-sized groups), but could cause undesired behavior if input groups are not truly ordered.

Tests

Filter Type	Defines whether a single filter or multiple filters will be given, as well as clarifies the feature order that is expected. Multiple Filters – the SpatialFilter assumes Candidate and Filter features may come in any mixed order, and must wait until all features have entered before performing any filtering. Filters First – the SpatialFilter assumes that all Filter features enter before any Candidate features, and will be able to process the Candidate features immediately as they arrive. Single Filter – the SpatialFilter assumes that after the first and only Filter feature has entered, only Candidate features will enter, and will be able to process the Candidate features immediately as they arrive.
Pass Criteria	Specifies whether a candidate must have a predicate match against all Filters or against at least one Filter.
Support Mode	Support Aggregates – both multis and aggregate geometries will be supported. However, the only supported predicates will be OGC-Contains, OGC-Disjoint, OGC-Equals, OGC-Intersects, OGC-Touches, and OGC-Within. The OGC-Overlaps predicate and the OGC-Crosses predicate will not be supported. 9-character masks representing Dimensionally Extended 9 Intersection Matrices will also not be supported. Support All Predicates – all the predicates described in the Spatial Relations Defined page will be supported. However, aggregate and multi geometries will not be supported.
Spatial Predicates to Test	Defines which tests to perform. Choices include: Filter OGC-Intersects Candidate Filter OGC-Equals Candidate Filter OGC-Touches Candidate Filter OGC-Contains Candidate Filter is OGC-Within Candidate Filter OGC-Crosses Candidate Filter OGC-Overlaps Candidate Filter is OGC-Disjoint From Candidate If the Support Mode is Support All Predicates, you may also test relationships using arbitrary 9-character masks. Such masks consist of the rows of a Dimensionally Extended 9 Intersection Matrix. Note that in order to use these masks with the SpatialFilter, you must assign them to an attribute on the Candidate features, and include the value of that attribute in the Tests to Perform clause (you cannot specify them directly). Multiple predicates may be specified in one attribute by separating them with a space. For more information about predicates, see Spatial Relations Defined.
Use Bounding Box	Defines whether the tests are performed using Candidate features' true coordinates or their bounding boxes.
Curve Boundary Rule	This attribute specifies how to determine the boundary of curve and multicurve geometries. The Default Rule is that any curve endpoints that occur an odd number of times in the geometry as a whole will be considered its boundary – that is, a linear loop (a line whose start point equals its endpoint) will not have any boundary. The other rule specifies that the curve's or multicurve's boundary is the set of all its endpoints.

Merge Attributes

Defines whether attribute merging will take place. If this is enabled, every Candidate that matches a Filter receives that Filter's attributes. The result is an operation known as a Spatial Join.

Accumulation Mode

Enabled if merging attributes. Options include:

Merge Filter: The candidate feature will retain all of its own un-conflicted attributes, and will additionally acquire any un-conflicted attributes that the filter feature has. This mode will handle conflicted attributes based on the Conflict Resolution parameter.
Prefix Filter: The candidate feature will retain all of its own attributes. In addition, the candidate will acquire attributes reflecting the filter feature’s attributes, with the name prefixed with the Prefix parameter.
Only Use Filter: The candidate feature will have all of its attributes removed, except geometry attributes that start with fme_. Then, all of the attributes and associated values of the filter feature will be placed onto the candidate.

Conflict Resolution

Enabled if merging attributes. Options include:

Use Candidate: If a conflict occurs, the candidate feature values will be maintained.
Use Filter: If a conflict occurs, the values of the filter feature will be transferred onto the original.

Prefix

Enabled if merging attributes and Accumulation Mode is set to Prefix Filter. Defines a prefix to add onto all attributes that are merged from Filters to Candidates.

Advanced

Preserve Feature Order

This parameter controls the order in which features exit a transformer.

When a transformer has more than one output port, features usually exit one port at a time. At times, it may be useful to keep the order that features arrived in, switching from port to port as necessary. This allows feature order to be preserved, though at a potential cost in processing efficiency.

Select a method for feature ordering.

Per Output Port (Default)

Only preserve the input order of features as they occur within the group of features exiting a given output port.

All features exiting an output port retain their ordering relative to each other (within the group), but not relative to features exiting other output ports.

This option is generally the most efficient, where large chunks of features will exit an output port together (taking advantage of bulk mode).

As features exiting different output ports may not be strictly output in the order they arrived, output ordering may be unpredictable.

Across Output Ports

Strictly preserve the input order of features, regardless of which output port they exit. Features will be output singly in the same order they arrived, switching from port to port as necessary. This option is generally less efficient as the processing gains of bulk mode are less likely to apply - however, feature order is predictable.

Editing Transformer Parameters

Transformer parameters can be set by directly entering values, using expressions, or referencing other elements in the workspace such as attribute values or user parameters. Various editors and context menus are available to assist. To see what is available, click beside the applicable parameter.

How to Set Parameter Values

Defining Values

There are several ways to define a value for use in a Transformer. The simplest is to simply type in a value or string, which can include functions of various types such as attribute references, math and string functions, and workspace parameters.

Using the Text Editor

The Text Editor provides a convenient way to construct text strings (including regular expressions) from various data sources, such as attributes, parameters, and constants, where the result is used directly inside a parameter.

Text Editor

Using the Arithmetic Editor

The Arithmetic Editor provides a convenient way to construct math expressions from various data sources, such as attributes, parameters, and feature functions, where the result is used directly inside a parameter.

Arithmetic Editor

Conditional Values

Set values depending on one or more test conditions that either pass or fail.

Parameter Condition Definition Dialog

Content

Expressions and strings can include a number of functions, characters, parameters, and more.

When setting values - whether entered directly in a parameter or constructed using one of the editors - strings and expressions containing String, Math, Date/Time or FME Feature Functions will have those functions evaluated. Therefore, the names of these functions (in the form @<function_name>) should not be used as literal string values.

Content Types

String Functions	These functions manipulate and format strings.
Special Characters	A set of control characters is available in the Text Editor.
Math Functions	Math functions are available in both editors.
Date/Time Functions	Date and time functions are available in the Text Editor.
Math Operators	These operators are available in the Arithmetic Editor.
FME Feature Functions	These return primarily feature-specific values.
FME Parameters	FME and workspace-specific parameters may be used.
Creating and Modifying User Parameters	Create your own editable parameters.

Dialog Options - Tables

Table Tools

Transformers with table-style parameters have additional tools for populating and manipulating values.

Row Reordering

Enabled once you have clicked on a row item. Choices include:

Add a row
Remove a row
Move current row up one
Move current row down one
Move current row to top
Move current row to bottom

Cut, Copy, and Paste

Enabled once you have clicked on a row item. Choices include:

Cut a row - delete and copy to clipboard
Copy a row to the clipboard
Paste a row from the clipboard

Cut, copy, and paste may be used within a transformer, or between transformers.

Filter

Start typing a string, and the matrix will only display rows matching those characters. Searches all columns. This only affects the display of attributes within the transformer - it does not alter which attributes are output.

Import

Import populates the table with a set of new attributes read from a dataset. Specific application varies between transformers.

Reset/Refresh

Generally resets the table to its initial state, and may provide additional options to remove invalid entries. Behavior varies between transformers.

Note: Not all tools are available in all transformers.

For more information, see Transformer Parameter Menu Options.

Reference

Processing Behavior	Group-Based
Feature Holding	Yes
Dependencies
Aliases
History

FME Community

The FME Community is the place for demos, how-tos, articles, FAQs, and more. Get answers to your questions, learn from other users, and suggest, vote, and comment on new features.

Search for all results about the SpatialFilter on the FME Community.

Examples may contain information licensed under the Open Government Licence – Vancouver, Open Government Licence - British Columbia, and/or Open Government Licence – Canada.