Operator Geofence

Specialized toolkits - release 4.3.1.0-prod20190605 > com.ibm.streams.geospatial 3.3.2 > com.ibm.streams.geospatial > Geofence

Primitive operator image not displayed. Problem loading file: ../../image/tk$com.ibm.streams.geospatial/op$com.ibm.streams.geospatial$Geofence.svg

The Geofence operator is used to manage user-defined geographical regions called geofences and provide information as entities move in and out of of these regions. Geofences in this operator are uniquely identified by a user-supplied fence id and a polygon defined as a string, while an entity can be any object in motion.

An entity is defined by its unique id and its location. If a fence's polygon fully contains the location that is associated an entity, the entity is said to be present in the fence. This statement is true even if the entity's location is a polygon and not a simple point. The entity's location can be a pair of latitude and longitude coordinates or a geometry.

Output modes

The operator has two different forms of output, events and membership. By default, the operator produces a list of all the fences that an entity is currently contained in. This behavior is called membership mode.

In events mode, the operator still produces the list of the fences an entity is in, but also produces a list of fences it has entered or exited. An entity exits a fence if it was previously contained in the fence, but with the most recent update to its location, it is no longer present therein. Similarly, an entity enters a fence if it is now present in a fence it was previously not contained in. Configuring the operator in membership mode can provide a performance improvement.

This operator has 2 input ports. The first port, port 0, is also known as the entity stream. It receives information about entities and their location and determines which fences the entity is present in. The second port, port 1, is also known as the fence stream. It is a control port and is used to to create and update geofences. It will only produce output if the optional error port is in use.

There is one mandatory output port, output port 0, and one optional error port, output port 1. Output port 0 produces a tuple for every incoming tuple on the entity stream. It also provides information about the tuple's membership in fences, depending on which output functions are used. Output port 1 is optional, and if used, will submit a tuple describing any errors that occur during the processing of a tuple from one of the input ports.

Behavior in a consistent region

The Geofence operator can be an operator within the reachability graph of a consistent region. It cannot be the start of a consistent region. However, if the operator producing the fence stream itself is not in a consistent region, it is possible that any fences added to the operator between checkpoints might be lost if the Geofence opereator is reset before the next checkpoint occurs.

Summary

Ports
This operator has 2 input ports and 2 output ports.
Windowing
This operator does not accept any windowing configurations.
Parameters
This operator supports 8 parameters.

Optional: fenceId, fencePolygon, fenceUpdateAction, geometry, id, latitude, longitude, outputMode

Metrics
This operator does not report any metrics.

Properties

Implementation
C++
Threading
Always - Operator always provides a single threaded execution context.

Input Ports

Ports (0)

This port receives information about entities to determine which of the defined geofences, if any, contains the entity. The information also indicates which fences the entity has entered or exited. This port is called the entity port or entity stream. The CurrentFences function returns a list of all the geofences that contain the entity. If there is an error parsing the location information for an entity, the output is an empty list for any output functions called, with the exception of AllFences().

Properties

Ports (1)

This port receives information to create and update geofences. This is called the fence port or fence stream.

Properties

Output Ports

Output Functions
GeofenceOutput
<any T> T AsIs()

Default output function

map<rstring, rstring> AllFences()

This function returns a map (fence id, geometry) of all the defined fences and their geometries. If no fences are currently defined, the map might be empty.

list<rstring> FencesEntered()

This function returns a list of the identifiers for each fence that the entity entered. To use this function, the outputMode parameter must be set to events. Initially, the operator assumes that all entities are outside of all fences. Thus, the first time an entity is processed by the operator, the CurrentFences() and FencesEntered() functions have the same result. The FencesExited() function returns an empty list. If an entity with the same ID was previously processed, the list includes any fences that the entity is now contained in but was previously not contained in. If the entity has not entered any fences, the list is empty.

list<rstring>FencesExited()

This function returns a list of the identifiers of each fence the entity has exited. To use this function, the outputMode parameter must be set to events. If the entity has not exited any geofences, the list is empty.

list<rstring> CurrentFences()

This function returns a list of the identifiers of each fence that contains the entity. This list also includes the fences that it has currently entered. If the entity is not present in any geofences, the list returned is empty. You can call this function regardless of the current setting of the outputMode parameter.

Ports (0)

This operator has one mandatory output port, output port 0. Attributes from the input tuple are passed to the output tuple if they exist and extra attributes can be populated by using the output functions. All output functions can be used only on output port 0.

Assignments
This port set allows any SPL expression of the correct type to be assigned to output attributes. Attributes not assigned in the output clause will be automatically assigned from the attributes of the input ports that have the same name and type. If there is no such input attribute, an error is reported at compile-time.

Properties

Ports (1)

The Geofence operator has one optional output port, output port 1. If an error occurs while processing incoming tuples from the fence stream or the entity stream, a tuple that describes the error is submitted to this port. The resulting tuple contains two attributes of type rstring: id and message. These attributes are the ID of the entity or fence and the message that describes the error.

Assignments
This port set requires that assignments made to output attributes must evaluate at compile-time to a constant.

Properties

Parameters

Optional: fenceId, fencePolygon, fenceUpdateAction, geometry, id, latitude, longitude, outputMode

fenceId

This parameter specifies an attribute from the fence port, port 1. The attribute defines the unique identifier of the fence to be added, updated, or removed from the operator. If this parameter is not specified, the operator assumes that an attribute named fenceId exists on the fence port. That attribute is used as the unique identifier for the fence that is being added or updated.

Properties

fencePolygon

This parameter is specified on the fence port, port 1. It is the WKT string representation of the polygon that covers the area to be fenced. You need to take care of the orientation of the polygon. Normally the points of the polygon should be arranged in a counter-clockwise manner, to define the area inside of the polygon as the fence area. If the points are arranged in a clockwise manner, the area outside of the polygon is the fence area. See also the "left hand rule". If you are in doubt about the orientation of your input polygons, you can use the SPL function polygon() in this toolkit, to re-orient a polygon so that it always covers the smaller area.

If there is an error parsing the polygon, the fence is ignored. If the error occurred during an update to an existing fence, the update is cancelled. If this parameter is not specified, the operator assumes that the fence stream contains an attribute named fencePolygon.

Properties

fenceUpdateAction

This parameter is specified on the fence port, port 1. It indicates whether the specified geofence should be added, updated, or removed from the operator. A value of 1 adds or updates the fence and a value of 0 removes it. If this parameter is not specified, the operator assumes that the fence stream contains an attribute named fenceUpdateAction.

Properties

geometry

This parameter specifies an attribute from the entity stream, port 0. It is a well-known text representation of the current location of the entity. If you specify this parameter, the operator uses the geometry attribute as the current location of the entity. If the geometry attribute is not available, the operator assumes that the current location is specified as latitude and longitude on the entity stream.

Properties

id

This parameter specifies an attribute from the entity stream, port 0. It represents the unique identifier of an entity. If you do not specify this parameter, the operator assumes that the entity stream contains an attribute named "id".

Properties

latitude

This parameter specifies an attribute from the entity stream, port 0. Its value represents the latitude of the current location of the entity. If you specify this parameter, you must also specify the longitude parameter. If you do not specify this parameter, the operator assumes that the entity stream either contains an attribute named "latitude" or that it uses the geometry parameter.

Properties

longitude

This parameter specifies an attribute from the entity stream, port 0. Its value represents the longitude of the current location of the entity. If you specify this parameter, you must also specify the latitude parameter. If you do not specify this parameter, the operator assumes that the entity stream either contains an attribute named "longitude" or that it uses the geometry parameter.

Properties

outputMode

This parameter determines the kind of output produced by the operator. The two options are events and membership. A value of events indicates that the operator produces information about fence entry and exit events. If one or more of the FencesEntered or FencesExited functions are used, this parameter must be set to events.

If this parameter value is events, the operator stores the last location of each entity. If this parameter value is membership, the operator does not store entity location information and it reports only on the current fences that an entity is present in. It does not produce any information about fence entry or exit. The default value is membership.

If you are not interested in computing the exit and entry information for each tuple and you are using only the CurrentFences function, specifying a value of membership for this parameter can result in performance improvements.

Properties

Libraries

Spatiotemporal library
Library Name: st
Library Path: ../../impl/lib
Include Path: ../../impl/include/st, .
PROJ4 library
Library Name: proj
Library Path: ../../impl/lib/external/proj4
Include Path: ../../impl/include/external, ../../impl/include/external/proj4/incl
Geospatial toolkit helper library
Library Name: geospatialToolkit
Library Path: ../../impl/lib
Include Path: ../../impl/include/toolkit