IBM Streams 4.2

Operator SpatialGridIndex

SPL standard and specialized toolkits > com.ibm.streams.geospatial 3.0.2 > com.ibm.streams.geospatial > SpatialGridIndex

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

The SpatialGridIndex operator stores objects and their location. Objects are uniquely identified by a user-supplied string id. The operator also is capable of responding to queries on objects by their location, and retrieves all objects whose location is within a specified distance of a given geometry.

Use of this operator also requires that a region of interest known as a bounding box be defined. Only objects whose location is within this region will be added to the index. The bounding box is defined by two sets of latitude and longitude points, which represent the northeast and southwest corners of the box.

The specified bounding box is further divided into a grid. The internal dimensions of the grid are configured using the numRows and numColumns parameters, where numRows and numColumns are the number of latitude-wise and longitude-wise divisions of the grid, respectively.

Output is only generated if a query is received and the query result contained at least one object. The output for each query is a stream of objects found within the queried range and their geometries, followed by a punctuation if punctPerQuery is true.

Behavior in a consistent region

  • The SpatialGridIndex operator can be an operator within the reachability graph of a consistent region. It cannot be the start of a consistent region.

Summary

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

Required: bboxEastLongitude, bboxNorthLatitude, bboxSouthLatitude, bboxWestLongitude, numColumns, numRows

Optional: objectGeometry, objectId, objectTag, objectUpdateFlag, punctPerQuery, queryGeometry, queryRange

Metrics
This operator does not report any metrics.

Properties

Implementation
C++
Threading
Never - Operator never provides a single threaded execution context.

Input Ports

Ports (0...1)

This operator has 2 input ports. Port 0 is used to receive information about objects to track in the index. It is also referred to as the object port or object stream. Port 1 receives queries as input. This port is referred to as the query port or query stream. For each object in the index found as a result of a query, a tuple is submitted to Output Port 0. If the query port receives a query and finds no objects matching the criteria, or if the tuple contains invalid attributes, no output will be generated, unless punctPerQuery is true. If this is the case a punctuation will be generated.

Properties

Output Ports

Assignments
This operator 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.
Output Functions
SpatialGridIndexOutputFunctions
rstring RetrievedObjectId()

Returns the id of an object that matched the query.

rstring RetrievedObjectGeometry()

Returns the geometry for the retrieved object.

rstring RetrievedObjectTag()

Returns the data stored with the retrieved object.

<any T> T AsIs(T)

No op

Ports (0)

This operator has 1 output port which produces data as a response to incoming data from the query port. The output is the id and geometry of all objects found matching the input query criteria.

Properties

Parameters

This operator supports 13 parameters.

Required: bboxEastLongitude, bboxNorthLatitude, bboxSouthLatitude, bboxWestLongitude, numColumns, numRows

Optional: objectGeometry, objectId, objectTag, objectUpdateFlag, punctPerQuery, queryGeometry, queryRange

bboxEastLongitude

Parameter defining the east-most longitude of the bounding box. The difference between this value and the west-most longitude cannot exceed 180 degrees.

Properties

bboxNorthLatitude

Parameter defining the north-most latitude of the bounding box.

Properties

bboxSouthLatitude

Parameter defining the south-most latitude of the bounding box.

Properties

bboxWestLongitude

Parameter defining the west-most longitude of the bounding box. The difference between this value and the east-most longitude cannot exceed 180 degrees.

Properties

numColumns

This parameter specifies the number of columns the bounding box will have. For example. if the bounding box has a longitude range of 5 degrees, and numColumns is 5, the underlying grid used for the index will have 5 columns. This parameter must be specified at compile or submission time.

Properties

numRows

This parameter specifies the number of columns the bounding box will have. For example. if the bounding box has a latitude range of 5 degrees, and numRows is 5, the underlying grid used for the index will have 5 rows. This parameter must be specified at compile or submission time.

Properties

objectGeometry

This attribute on the object stream that specifies the well-known text representation for the object to add to the index. If the object's geometry falls outside the region defined by the bounding box, it is ignored and not added to the index. If not specified, it is assumed the input stream contains an attribute called objectGeometry.

Properties

objectId

Attribute on the object stream that contains the id for the object being added to/updated in the index. If not specified, it is assumed that the object stream contains an attribute named objectId.

Properties

objectTag

This attribute provides an optional arbitrary tag to be stored with the object.

Properties

objectUpdateFlag

Attribute from the object stream that contains the update flag for the incoming object. To remove an object from the index, set the attribute value to 0, to add / update an object, set the attribute value to 1. The valid values are 0 or 1. If this parameter is not specified, it is assume that the object stream contains an attribute named objectUpdateFlag.

Properties

punctPerQuery

Optional parameter. Set to true if a punctuation should be generated after all the output tuples for a query have been submitted. Note that a punctuation will be generated even if there are no objects in the index that matched the query.

Properties

queryGeometry

This attribute comes in from the query stream. It contains the string representation of the query geometry. If not specified, the query stream must contain an attribute named queryGeometry.

Properties

queryRange

This attribute comes in from the query stream. It defines the size of the area, in meters, around the query geometry within which to search for objects. If not specified, the query stream must contain an attribute named queryRange.

Properties

Libraries

ST 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
Geospatial toolkit helper library
Library Name: geospatialToolkit
Library Path: ../../impl/lib
Include Path: ../../impl/include/toolkit