Filter by Geometry

The Filter by Geometry tool Filter by geometry tool filters features by a spatial relationship with other features in the same feed or those of another feed or dataset. Features that the spatial relationship evaluates as true are retained.

Examples

  • A real-time analytic uses the Filter by Geometry tool to retain only the incoming records from a feed in which the feature geometry intersects a polygon dataset of port areas.
  • A big data analytic uses the Filter by Geometry tool to retain only features in which the feature geometry enters a polygon dataset representing service areas.
  • Determine when shipping vessels from one feed are inside a moving severe weather cell from another feed.

Usage notes

  • The tool can compare the spatial relationship of features to point, line, or polygon features.
  • The tool evaluates a user-defined spatial relationship between the target features and a specified join dataset.
  • If a Spatial Relationship value of enter or exit is selected, checking First observation can trigger enter or First observation can trigger exit indicates that the first target feature received satisfies the filter condition if it is inside any join feature (in the case of enter) or outside all join features (in the case of exit), despite having no prior target feature to which to compare the current target feature's location. The default is false (not checked).
  • If the Spatial Relationship parameter is set to enter or exit in a real-time analytic, the tool will operate in a stateful manner, which enables it to compare sequential observations to one another to detect that a change in state, for example, is a current condition different from that of the previous observation. With other spatial relationships in real-time analytics, the tool does not need to compare observations with previous observations, so it can run in a stateless manner, which is less resource intensive.
  • When operating in a stateful manner, the Filter by Geometry tool maintains a state store of the current observation for each track ID. When a new observation is received it is compared to the current observation of the same track ID, if present. If the new observation has a newer timestamp than the current observation in the state store, the current observation is replaced. If it has an identical timestamp to the current observation for the same track ID, the tool does not distinguish between the two observations. This means the tool will not replace the current observation in the state store with the new observation, the new observation will not be added to the state store and future observations for this track ID will be compared to the current observation that remained in the state store until a new observation arrives with a later timestamp. A warning will be logged by the tool when this occurs.
  • The Target Time Window parameter in a real-time analytic should be set to at least as long as the longest anticipated interval between observations for any given track. Observations older than this duration will be removed from memory to manage resources.
  • If a feed is connected to the join port, distance calculations will be performed dynamically based on the changing features in both the target and join feeds.
  • In dynamic geofencing, the Join Time Window parameter must be set. If the join feed does not have a field tagged as END_TIME and the last known observation for a join feature is older than this window, it will be removed from the tool's memory and will not be included in the analysis. If the join feed has a field tagged as END_TIME, the feature will age out of the geofence store according to the value in the field tagged as END_TIME or at the close of the join time window, whichever comes first.
  • Adding a join feed to a tool must be done in the model view. Analytics with tools using join feeds cannot be viewed or edited in the workflow view.

Parameters

ParameterDescriptionData type

Input Layer

Specifies the layer that will be filtered.

Features

Join Layer

Specifies the layer to process a spatial relationship against.

Features

Spatial Relationship

Specifies the criteria used to spatially filter the target features. Spatial relationships include the following:

  • disjoint
  • enter
  • equals
  • exit
  • intersects
  • near geodesic
  • near planar
  • touches
  • within

Note:

A target feature must satisfy its spatial relationship against all join features when disjoint or exit has been specified and there is more than one join feature. For any other spatial relationship and where there is more than one join feature, a target feature can satisfy its spatial relationship to any individual join feature.

String

Target Time Window

When operating in a stateful manner, this parameter specifies the longest anticipated period of time between observations for each track.

String

Join Time Window

The time window for the join feed (dynamic geofencing). If the last known observation for a join feature is older than the time window specified, it will be removed and will not be included in the analysis. If the join feed has a field marked as END_TIME, this parameter is optional.

String

Output layer

The Filter by Geometry tool does not alter incoming features; the output layer will contain the same fields and attribute values as the incoming features.