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` |
`polygon` `orientedPolygon` |

`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

**operator along with the**

`Join `

**or**

`isContained `

**functions to perform geofencing can now use the new operator.**

`distance `

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.

Polygons of interest are defined in a file and are ingested by the ** Geofence **operator through the

**. Incoming location data to be fenced are defined in a different file and are ingested from the**

`PolygonStream`

**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.**

`Location `

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` |
`polygon` `orientedPolygon` |

`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.