Operator GeometryMapMatcher

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

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

The GeometryMapMatcher operator calculates edges of a road network that are within reach of a given area of interest (AOI). The road network needs to be stored as shared map data, using the MapStore operator. The area of interest needs to be supplied as a WKT geometry. A configurable input port attribute of type rstring holds this information. Road net edges are considered "within reach" of the AOI, if a car needs to travel less than a specified "on-track" distance to get to the AOI. The distance is specified in meters by a configurable input port attribute of type float64.

The operator implements the following steps:

1) The given geometry representing the AOI is projected on the road map. All road net edges covered at least partially by the geometry are used as initial search set. Optionally the geometry can be enlarged by using the geometryBuffer parameter.

2) For all edges in the initial search set, a reverse Dijkstra path search is performed, to find additional edges that can reach the inital edges within the distance specified by the distanceThreshold parameter.

The supported WKT geometries are points, polygons and the (proprietary) bounding box: 


POINT (1.0 1.0)
BOUNDINGBOX (1.0 1.0, 2.0,2.0)
POLYGON ((1.0 1.0, 1.0 2.0, 2.0 2.0, 2.0 1.0, 1.0 1.0))

Because the map data is located in a shared memory segment (a segment of physical memory) that multiple GeometryMapMatcher and PointMapMatcher operators can use, the memory footprint for large maps can be reduced. See the documentation of the MapStore operator for details.

Behavior in a consistent region and checkpointing

The GeometryMapMatcher operator can be neither an operator within the reachability graph of a consistent region, nor the start of a consistent region.

The operator supports neither periodic, nor operator-driven checkpointing.

Shared map handling

The GeometryMapMatcher operator works similar to the PointMapMatcher operator. Both can use the same shared map data supplied by a MapStore operator.

Important: You must ensure that the GeometryMapMatcher and the corresponding MapStore operator (which means that both have the same storeName parameter value) are running on the same host. Use the following placement statement for both operators (replace someHostColocationId with your own id): 


config placement : hostColocation("someHostColocationId");

For detailed information about the shared map handling see the subpage below, and the documentation of the MapStore operator.

Shared Map handling details

Summary

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

Required: storeName

Optional: distanceThreshold, faultHandling, geometry, geometryBuffer

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)

Receives geometry data for an area of interest. This geometry is projected on the edge network and all edges are returned in the tuple on output. Every input tuple results in an output tuple, unless there is a severe error.

Data on this port is processed as soon as map data is available. The MapStore operator receives map data and stores it in a shared memory segment, so GeometryMapMatcher operators can access it. The MapStore operator locks a mutex as soon as a geometry update starts, and unlocks the mutex as soon as the update ends. The GeometryMapMatcher operator stops the query processing as soon as the mutex is locked, and resumes with the unlock. A window punctuation that arrives on this input port reopens the shared memory segments.

Properties

Output Ports

Assignments
This operator allows any SPL expression of the correct type to be assigned to output attributes.
Output Functions
GeometryMatchedOutputFunctions
<any T> T AsIs(T)

Returns the parameter value.

list<GeometryMapMatcherTypes.EdgeData> getEdgeList()

Returns the list of edges. Each edge is of type GeometryMapMatcherTypes.EdgeData. This type contains both, the edge ID as int64 and the distance to the AOI as float64. See the predefined EdgeData type in GeometryMapMatcherTypes

GeometryMapMatcherTypes.ResultCode getResultCode()

Returns the result of the operation. For a description of the codes see GeometryMapMatcherTypes

Ports (0)

Output port 0 produces data as a response to incoming data from the input port 0. The output is configurable via GeometryMatchedOutputFunctions output functions. All attributes from the input tuple are passed through as they are, unless a custom output function is used to assign the results of the calculation or the error status.

Properties

Parameters

Required: storeName

Optional: distanceThreshold, faultHandling, geometry, geometryBuffer

distanceThreshold

Name of the attribute containing a maximimum "on-track" distance for edges to be considered in reach of the AOI. It has to be of type float64 and gives the distance in meters. If not specified, it is assumed that the input stream has an attribute named distanceThreshold.

Properties

faultHandling

Specifies how to handle shared map store access faults. Valid values are:

  • wait (default)

    Logs the fault and retries immediately to attach to the shared map store.

  • drop

    Logs the fault and drops the tuple. Retries to attach to the shared map store with the next tuple.

  • abort

    Logs the fault and aborts the operator.

Properties

geometry

Name of the attribute containing the geometry to match. It has to be of type rstring and the geometry needs to be encoded in WKT. If not specified, it is assumed that the input stream has an attribute named geometry.

Properties

geometryBuffer

Name of the attribute containing the size of an additional buffer around the given geometry. It is given in meters. The buffer is considered when finding the initial edges in the road net graph, that make up the Point of interest. For geometries other than POINT() it is recommended to use zero for this value. The attribute has to be of type float64. If not specified, it is assumed that the input stream has an attribute named geometryBuffer.

Properties

storeName

Specifies the unique name of the shared map store.

Use the MapStore operator to create the shared map store and to load map data. The MapStore operator must have the same storeName parameter value as the GeometryMapMatcher operator.

Important: You must ensure that the MapStore and the GeometryMapMatcher operators, that belong together because they use the same store name, are running on the same host. Use the following placement statement for both operators (replace someHostColocationId with your own id): 


config placement : hostColocation("someHostColocationId");

With the first tuple on input port 0, the GeometryMapMatcher operator attaches to the shared map store. See the faultHandling parameter for details regarding the operator behavior in case of access problems.

Properties

Libraries

PROJ4 library
Library Name: proj
Library Path: ../../impl/lib/external/proj4
Include Path: ../../impl/include/external, ../../impl/include/external/proj4/incl
ST library
Library Name: st
Library Path: ../../impl/lib
Include Path: ../../impl/include/st
MapController
Library Path: ../../impl/lib/control
Include Path: ../../impl/include/control