Streams version 4.0 includes version 2.0 of the Geospatial toolkit. This release has some major differences from previous versions. This article will explain the most important changes. Also, it will outline which functions have been deprecated and their corresponding replacements in version 2.0.

Introduction of Well-Known Text

The toolkit has now been changed to primarily use SPL rstrings formatted as Well-Known Text (WKT) to represent geospatial data. WKT was defined by the Open Geospatial Consortium (OGC) and has also been adopted by the International Organization for Standardization (ISO) for spatial SQL.

Previously, the Geospatial toolkit included data types for Points, Lines, and Polygons, and functions to manipulate them. These functions and types were defined in the com.ibm.streams.geospatial.twodimension.geometry namespace.
This namespace and all the types and functions therein have been deprecated. In the new toolkit, the aforementioned geometric types are represented as strings in WKT format, unless otherwise indicated.

The functions to create Points, Polygons, LineStrings and LineSegments from earlier versions of the toolkit, as well as the corresponding types have been deprecated. The available replacement functions are as follows:

Deprecated function Equivalent in version 2
createPoint32
createPoint64
createPoint128
point
createLinearSimplePolygon32
createLinearSimplePolygon64
createLinearSimplePolygon128
polygonorientedPolygon
createLineSegment32
createLineSegment64
createLineSegment128
lineSegment

Thus, the following SPL statement:

PointPropertyType.point128 pw1 = createPoint128(40.758578, -73.985088);

would be replaced by:

rstring myPoint = point(-73.985088, 40.758578);

The createLineString* functions have also been deprecated. No replacement is available at this time, however, creating a WKT LineString from a list of points programmatically is fairly straightforward.

Using the new Geofence operator

The latest release of the toolkit also includes 4 new operators, one of which is the Geofence operator. As its name implies, this operator provides a simple method of detecting presence within a geofence, as well as entry and exit events. Applications based on version 1 of the toolkit that may have previously used the Join operator along with the isContained or distance functions to perform geofencing can now use the new operator.

The following is a sample demonstrating the use of the Geofence operator. Assume that the incoming data is specified in files in comma-separated values (CSV) format.

Sample usage of the Geofence operator.
Sample usage of the Geofence operator.

Polygons of interest are defined in a file and are ingested by the Geofence operator through the PolygonStream. Incoming location data to be fenced are defined in a different file and are ingested from the Location stream. For each incoming tuple from the Location stream, the operator will produce output indicating which of the predefined fences contain the location, as well as which of them have just been entered or exited.

For more information, including a demo of the new operator, see the video Geofence – Smart Marketing. Detailed documentation is available in the Streams Knowledge Center.

Distance Functions

Earlier versions of the toolkit included several functions to calculate the distance between two points, which each function using a different formula. This has been simplified. The following functions from the com.ibm.streams.geospatial.twodimension.geometry namespace have all been deprecated:

  • distance (with Metric argument)
  • distanceEllipsoidal
  • distanceGreatCircle
  • distanceHaversine

These have been replaced with one function: com.ibm.streams.geospatial.st::distance. This function determines which algorithm to use depending on the length of the distance. In addition, the Metric type to define the method of calculation is no longer required since the new function always uses the Spherical distance.

Summary of deprecated functions and their replacements

With the exception of the unit conversion functions and createLineString, mentioned earlier, all other deprecated functions have equivalents in the new toolkit. The following is a full list of deprecated functions and their equivalents.

Deprecated function Equivalent in version 2
azimuth azimuth
createLineSegment32/64/128 lineSegment
createPoint32/64/128 point
createLinearSimplePolygon32/64/128 polygonorientedPolygon
destinationPoint destinationPoint
distance
distanceEllipsoidal
distanceGreatCircle
distanceHaversine
distance
getLatitude/getLongitude getLatitude/getLongitude
isContained contains
mapPointToLineString nearestPoint

Conversion Functions

The functions in the com.ibm.streams.geospatial.conversions have also been deprecated. No replacements have been provided as these are trivial mathematical calculations.

Reference Information

See the full documentation for the Geospatial toolkit.

 

Join The Discussion