IBM Streams 4.2

Operator PointMapMatcher

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

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

The PointMapMatcher operator analyzes time based object location data to heuristically project points on a network of edges, as the original data may be imprecise. For each point, the mapped point is the best approximation of where on the edge network the entity is likely to be, provided some constraints.

This operator takes as input a set of locations reported by a moving object, perhaps through a GPS device. The information on known edges in the edge network can be provided as input. This takes the form of a set of points or nodes and the edges between them.

The output of this operator is configurable. However the most commonly used output function returns the the mapped latitude and longitude of the mapped point, along with the Id of the edge that was matched.

Since IBM Streams 4.2, the PointMapMatcher operator can run in local or shared map mode. The shared map mode is enabled with the storeName parameter.

  • In local map mode, the geometry data (network of edges) is stored in the operator memory and only this operator instance can access it.

    If many operator instances are required to, for example, solve a performance problem, the memory footprint is the number of the instances multiplied with the memory being required to store the geometry data.

    The PointMapMatcher operator performs as in earlier toolkit releases.

  • In shared map mode, the geometry data is located in a shared memory segment (a segment of physical memory) that multiple PointMapMatcher operators can attach to. The MapStore operator is used to store the geometry data in this shared memory segment.

    The PointMapMatcher operator does not support the geometry data port anymore, but runs queries that are received on port 0 only.

    The memory being required to store the geometry data is allocated once per host only. You can have many PointMapMatcher instances, running in shared map mode, that access the same shared memory segment.

    The MapStore and PointMapMatcher operators interact with each other, using a lock (mutex) to ensure that read and write access to the shared memory segment are mutual exclusive.

    Important: You must ensure that the PointMapMatcher 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");

Behavior in a consistent region and checkpointing

The PointMapMatcher 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 Mode

Summary

Ports
This operator has 2 input ports and 3 output ports.
Windowing
This operator optionally accepts a windowing configuration.
Parameters
This operator supports 10 parameters.

Required: distanceThreshold, matchingTimeCutoff, velocityThreshold

Optional: faultHandling, historySize, latitude, longitude, objectId, storeName, timeStamp

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 location data for an object. Every input tuple results in an output tuple, unless there is an error.

Data on this query port is processed as soon as map data is available and geometry updates are done.

For the local map mode, map data is received on the geometry input port, which is input port 1. A window punctuation marks the end of a geometry update.

For the shared map mode, the MapStore operator receives map data and stores it in a shared memory segment, so PointMapMatcher 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 PointMapMatcher 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.

For the local map mode, set the historySize parameter to specify the number of previous tuples that are taken into account while calculating matches.

For the shared map mode, apply one of the following window clauses to this input port. The window eviction policy is count-based and the specified count replaces the historySize parameter. You can optionally specify the partitionAge partition eviction policy, which means: If a tuple is not inserted into a partition for <age> seconds, the partition is deleted. The attribute that is specified with the objectId parameter selects the partition. There is no separate partitionBy parameter.

window <port>: sliding, count(<historySize>), count(1), partitioned;
window <port>: sliding, count(<historySize>), count(1), partitioned, partitionAge(<age>);

If a match is found, output describing the point on the edge network will be generated.

If no match is found, or if the data is invalid, the tuple will be ignored, and will be available on the error port. See the description for output port 1 for a list of possible errors.

If you specify a window clause that is not supported by the operator, you will get an error message during compilation.

Properties

Ports (1)

Receives geometry data for the edge network.

This port is supported for the local map mode only.

For the shared map mode, use the MapStore operator that provides a geometry data input port that is compatible to this input port.

These tuples are of the form:

tuple
<
   UpdateType updateType,
   UpdateFlags updateFlags,
   int64 objectId,
   float64 latitude,
   float64 longitude,
   int64 startNodeId,
   int64 endNodeId,
   boolean isOneWay
>;
  • updateType is either "NODE" or "EDGE"
  • updateFlags can either be "ADD", "REMOVE", or "CLEAR".
  • The remaining data is only used in the case of ADD or REMOVE.
  • Attributes latitude and longitude are only used for updates of type "NODE"
  • Attributes startNodeID, endNodeID, and isOneWay are only used if the update is of type "EDGE."
  • If the data is invalid, the tuple will be ignored, and will be available on output port 2.
  • Window punctuation indicates the end of a geometry update and that the edge network should be recalculated. The network is not recalculated unless punctuation is received. The exception is that updates with the CLEAR flag set will clear the map immediately.
  • It should be noted that nodes that are referenced by edges must be added before the referencing edge is added, otherwise the tuple that adds the edge will be considered invalid.
Properties

Output Ports

Output Functions
MapMatchedOutputFunctions
float64 getMappedLatitude()

Returns the WGS84 encoded latitude value of the matched point on the road.

float64 getMappedLongitude()

Returns the WGS84 encoded longitude value of the matched point on the road.

int64 getMappedEdgeId()

Returns the Id of the edge on which the matched point lies.

float64 getRawLatitude()

Returns the WGS84 encoded latitude value of the entity, before any edge matching.

float64 getRawLongitude()

Returns the WGS84 encoded longitude value of entity, before any edge matching.

float64 getDistanceOnTrack()

Returns the distance along the object's track on the matched edge. This distance is relative to the direction of travel. If the object is traveling from the start point of the edge to the end point, the distance will be relative to the start point. If the object is traveling from the end point of the edge to the start point, the distance will be relative to the end point of the edge.

boolean getDirectionOfTravel()

Returns true if the entity is traveling from the start point of the edge to the end point, and false otherwise.

<any T> T AsIs(T)

No op

Ports (0)

Output port 0 produces data as a response to incoming data from the query input port. The output is configurable via MapMatchedOutputFunctions output functions.

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.

Properties

Ports (1...2)

Output port 1 contains error output for entity data.

Tuples for which there are no valid match will be submitted to this port, along with a return code indicating the reason the matching failed.

The schema for this port must contain an attribute of type int32 called returnCode, which will be assigned the return code from matching.

The possible values of the return code are:

  • -2 if the velocity cutoff was reached
  • -3 if the distance cutoff was reached
  • -4 if the object is unknown (due to an internal error).
  • -1008 for an unexpected error, for example the operator failed to access the shared map data

Output port 2 is supported for the local map mode only and contains error output for geometry data that is received on the geometry data input port. Erroneous geometry tuples will be submitted to this port.

Possible error scenarios are:

  • An internal error when adding or removing a node
  • An internal error when adding or removing an edge
  • An internal error when clearing the map
Assignments
This operator allows any SPL expression of the correct type to be assigned to output attributes.

Properties

Parameters

Required: distanceThreshold, matchingTimeCutoff, velocityThreshold

Optional: faultHandling, historySize, latitude, longitude, objectId, storeName, timeStamp

distanceThreshold

Dictates the distance threshold for matching in meters. A coordinate is considered for matching only when its distance to the nearest edge is less than this threshold.

This parameter must be specified at compile or submission time. The value must be greater than zero.

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.

This parameter is supported for the shared map mode only.

Properties

historySize

Indicates the number of previous tuples to to use for each reported match. This is an aid in matching the object's position to the correct edge based on its previously reported locations.

For the local map mode, this parameter must be specified at compile or submission time. The minimum/default value is 1.

For the shared map mode, this parameter must not be used. Instead, specify the window statement that is described for the query input port.

Properties

latitude

Attribute for the object's latitude at the indicated time, encoded in WGS84.

If not specified, it is assumed that the input stream has an attribute named latitude.

Properties

longitude

Attribute for the object's longitude at the indicated time, encoded in WGS84.

If not specified, it is assumed that the input stream has an attribute named longitude.

Properties

matchingTimeCutoff

Indicates the maximum allowed time difference between two successive coordinates, in milliseconds. If the time delta is greater than this threshold, the previous history will be cleared.

The value must be greater than zero.

Properties

objectId

Attribute specifying the id that represents a unique object in the input stream.

If not specified, it is assumed that the input stream has an attribute named objectId.

For shared memory mode, the attribute is used for partitioning the input tuples into subwindows, where all window and parameter configurations apply to the subwindows, independently.

Properties

storeName

Enables the shared map mode and specifies the unique name of the shared map store.

If this parameter is not specified, the operator runs in local map mode, which means that the operator requires a query and a geometry data input port.

If this parameter is specified, the operator has a query input port only. Therefore, it cannot load map data into the operator's heap memory anymore. See the query input port for more details.

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 PointMapMatcher operator.

Important: You must ensure that the MapStore and the PointMapMatcher 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 query tuple on input port 0, the PointMapMatcher operator attaches to the shared map store. See the faultHandling parameter for details regarding the operator behavior in case of access problems.

Properties

timeStamp

This attribute is the time in UTC milliseconds, at which the object's location is reported.

If not specified, it is assumed that the input stream has an attribute named timeStamp.

Properties

velocityThreshold

Indicates the velocity threshold for matching, in meters per second. A coordinate is considered for matching only when the object's current velocity (measured with respect to previous point) is less than this threshold.

This parameter must be specified at compile or submission time. The value must be greater than zero.

Properties

Libraries

PROJ4 library
Library Name: proj
Library Path: ../../impl/lib/external/proj4
Include Path: ../../impl/include/proj4
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