streamsx.geospatial package

Geospatial integration for IBM Streams

For details of implementing applications in Python for IBM Streams including IBM Cloud Pak for Data and the Streaming Analytics service running on IBM Cloud see:

class streamsx.geospatial.FlightPathEncounter(north_latitude, south_latitude, west_longitude, east_longitude, num_latitude_divs, num_longitude_divs, altitude_search_radius, search_radius, time_search_interval)

Bases: streamsx.topology.composite.Map

Composite map transformation for FlightPathEncounter

Tracks flying objects and calculates possible encounters between the objects in the future. Each incoming tuple contains the latest observation data for one object. The operator stores that data internally and extrapolates the flight path of the object into the future. Than it calculates intersections of the flight path with the paths of all the other objects stored in the operator. For each object that comes close to the input object an output tuple is generated that contains the two objects, their latest observation data and the timestamp in the future when the encounter will happen. In addition the distance between the objects at the calculated time is also included in the output. The conditions for detecting an encounter can be configured via operator parameters searchRadius and altitudeSearchRadius. The observations contain a unique identifier for each object as well as several parameters like longitude,latitude,altitude,heading and speed. Also each observation contains a timestamp.

You can use the preconfigured type EncounterEvents() for convenience as input and output schema.

Example with input stream “planes_stream” of type “FlighPathEncounterSchema”:

import streamsx.geospatial as geo
from streamsx.geospatial.schema import FlighPathEncounterSchema
...
events = planes_stream.map(geo.FlightPathEncounter(north_latitude=52.6,south_latitude=52.4,west_longitude=13.3,east_longitude=13.5,num_latitude_divs=5,num_longitude_divs=5,search_radius=10000,altitude_search_radius=400,time_search_interval=600000), schema=FlighPathEncounterSchema.EncounterEvents)

New in version 1.1.

north_latitude

The latitude of the north border of the bounding box for the spatial index used by the Encounter detector. Given in degrees. Must be between -90 (south pole) and 90 (north pole).

Type

float64

south_latitude

The latitude of the south border of the bounding box for the spatial index used by the Encounter detector. Given in degrees. Must be between -90 (south pole) and 90 (north pole).

Type

float64

west_longitude

The longitude of the west border of the bounding box for the spatial index used by the Encounter detector. Given in degrees. Must be between 0 (greenwich median) and 360.

Type

float64

east_longitude

The longitude of the east border of the bounding box for the spatial index used by the Encounter detector. Given in degrees. Must be between 0 (greenwich median) and 360.

Type

float64

num_latitude_divs

Number of latitude divisions (rows) for the spatial index used by the Encounter detector. Must be greater than one.

Type

int32

num_longitude_divs

Number of longitude divisions (columns) for the spatial index used by the Encounter detector. Must be greater than one.

Type

int32

altitude_search_radius

The altitiude distance around the flying objects path, searched for collosions with other objects. Given in meters.

Type

int32

search_radius

The radius around the flying objects path, searched for other objects for potential collisions. Given in meters.

Type

int32

time_search_interval

The time interval the flight path is extrapolated and searched for collisions with other objects. Given in milliseconds. Must be greater than one second.

Type

int32

property cleanup_interval

The flying objects are periodically cleaned up from the internal data tables. During cleanup objects are removed whose last observation is older than the current observation minus the ‘cleanup_interval’. If not specified the interval defaults to 3 times the value of the ‘time_search_interval’ parameter. Given in milliseconds. The cleanup is not performed on each incoming tuple, instead it is performed when the timestamp of the incoming observation is newer than the timesatmp of the last cleanup plus a third of the ‘cleanup_interval’ parameter. For example if the ‘cleanup_interval’ is set to 15 minutes (900000 milliseconds), the operation is invoked roughly every 5 minutes.

Type

int

property encounter_attribute

The name of an output attribute of type TUPLE that will contains the data for a detected encounter. The Tuple must be of type Observation3D()

Type

str

property encounter_distance_attribute

The name of an output attribute that will hold the closest lat/lon distance in meters between the objects this encounter was detected for.

Type

str

property encounter_time_attribute

The name of an output attribute that will hold the time in milliseconds relative to the timestamp of the observation for this encounter.

Type

str

property filter_by_bounding_box

Set this parameter to True if observations whith locations outside the bounding box of the detectors spatial index shall be ignored. The bounding box of the detector is specified by the south_latitude, north_latitude, west_longitude and east_longitude parameters. The default is False so all observations are processed. Note that processing observations outside of the box may decrease the spatial index performance.

Type

bool

property observation_attribute

The name of an input attribute of type TUPLE that contains the data for the observation to process. The Tuple must be of type Observation3D()

Type

str

populate(topology, stream, schema, name, **options)

Populate the topology with this composite map transformation.

Parameters
  • topology – Topology containing the composite map.

  • stream – Stream to be transformed.

  • schema – Schema passed into map.

  • name – Name passed into map.

  • **options – Future options passed to map.

Returns

Single stream representing the transformation of stream.

Return type

Stream

property vm_arg

Arbitrary JVM arguments can be passed to the Streams operator

Type

str

streamsx.geospatial.region_match(stream, region_stream, schema=<streamsx.topology.schema.StreamSchema object>, event_type_attribute=None, region_name_attribute=None, id_attribute=None, latitude_attribute=None, longitude_attribute=None, timestamp_attribute=None, name=None)

Uses the RegionMatch operator to compare device data with configured regions.

Stores geographical regions (also called Geofences) together with a set of attributes per region. On the input stream it receives observations from moving devices and matches the device location against the stored regions. As a result it emits events if the device enters, leaves or is hanging out in a region. The regions can be added or removed via the region_stream. The events are send to output stream.

Example with input streams “device_stream” and “region_stream”:

import streamsx.geospatial as geo
...
res = geo.region_match(stream=device_stream, region_stream=region_stream)
Parameters
  • stream (streamsx.topology.topology.Stream) – Stream of tuples containing device data of schema streamsx.geospatial.schema.RegionMatchSchema.Devices, which is matched against all configured regions, to detect events.

  • region_stream (streamsx.topology.topology.Stream) – Stream of tuples containing regions of schema streamsx.geospatial.schema.RegionMatchSchema.Regions

  • schema (Schema) – Output streams schema, default schema is streamsx.geospatial.schema.RegionMatchSchema.Events

  • event_type_attribute (str) – Specify the name of an ouput Stream attribute of type ‘rstring’, that will receive the event type (ENTER,EXIT,HANGOUT) if a match is detected. If not specified the default attribute name is ‘matchEventType’.

  • region_name_attribute (str) – Specifies the name of an ouput Stream attribute of type ‘rstring’, that will receive the name of the region if a match is detected. If not specified the default attribute name is ‘regionName’.

  • id_attribute (str) – Specify the name of an attribute of type ‘rstring’ in the region_stream, that holds the unique identifier of the device. If not specified the default attribute name is ‘id’.

  • latitude_attribute (str) – Specify the name of an attribute of type ‘float64’ in the region_stream, that holds the latitude of the device. If not specified the default attribute name is ‘latitude’.

  • longitude_attribute (str) – Specify the name of an attribute of type ‘float64’ in the region_stream, that holds the longitude of the device. If not specified the default attribute name is ‘longitude’.

  • timestamp_attribute (str) – Specify the name of an attribute of type ‘timestamp’ in the region_stream, that holds the timestamp of the device measurement. If not specified the default attribute name is ‘timeStamp’.

  • name (str) – Operator name in the Streams context, defaults to a generated name.

Returns

Output Stream with specified schema

Return type

streamsx.topology.topology.Stream

class streamsx.geospatial.schema.FlighPathEncounterSchema

Bases: object

Structured stream schemas for FlightPathEncounter().

All schemas defined in this class are instances of streamsx.topology.schema.StreamSchema.

EncounterEvents = <streamsx.topology.schema.StreamSchema object>

The FlightPathEncounter() creates encounter events as output. An encounter consists of the original observation, the data for the encountered object and the distances in time and space between the colliding objects. This schema is provided for convenience as it can be used as input and output type for the FlightPathEncounter().

The schema defines following attributes

  • observation(StreamSchema) - The input observation encounters are calculated for. This is a tuple attribute of type Observation3D().

  • encounter(StreamSchema) - The data for the object that is encountered. This is a tuple attribute of type Observation3D().

  • encounterDistance(float64) - The latitude/longitude distance between the two objects at the time of the encounter. It is given in meters.

  • encounterTime(int64) - The time in the future the encounter will happen. It is an absolute time given in milliseconds since January 1st 1970 (Posix time).

Observation3D = <streamsx.topology.schema.StreamSchema object>

The FlightPathEncounter() processes observations of flying objects.

Each observation needs to conform to the Observation3D type. The schema defines following attributes

  • entityId(str) - The unique identifier of the flying object. You may use the ICAO field from an ADSB feed.

  • latitude(float64) - The latitude of the object in degrees. Allowed values are in the range from -90 to 90.

  • longitude(float64) - The longitude of the object in degrees. Allowed values are in the range from -180 to 180.

  • altitude(float64) - The altitude of the object in meters. Allowed values are greater or equal 0. If you need to convert from feet to meters, multiply the feet by 0.3048.

  • observationTime(int64) - The time stamp of the last observation of this object. Given in milliseconds as Posix time (milliseconds since January 1st 1970).

  • azimuth(float64) - The azimuth of the object. This is the clockwise angle between the objects motion direction and a line from the object to the north pole. Given in degrees (for example if the plane is flying to the east, this will be 90 degrees). Allowed values are 0 to 360.

  • groundSpeed(float64) - The groundSpeed of the object in meters per second. There is a dependency between this value and the timeSearchInterval parameter of the operator. At the given speed the object must not travel more than 20000 kilometers within the given timeSearchInterval. For example with a time search interval of 15 minutes (900000 ms) the object speed must not be faster than 80000 km/h (~22000 m/s). For all practical purposes this should not be a serious limitation. If you need to convert from knots to meters/second multiply the knots by 0.514444.

  • altitudeChangeRate(float64) - The altitudeChangeRate of the object in meters per second. Positive values denote increasing altitude.

class streamsx.geospatial.schema.RegionMatchSchema

Bases: object

Structured stream schemas for region_match().

The schema Events is the default schema for the output stream.

The schemas

are schemas for the input streams.

All schemas defined in this class are instances of streamsx.topology.schema.StreamSchema.

Devices = <streamsx.topology.schema.StreamSchema object>

This schema can be used as input for region_match().

The schema defines following attributes

  • id(str) - the device id

  • latitude(float64) - the latitude of the device

  • longitude(float64) - the longitude value of the device

  • timeStamp(timestamp) - the timestamp

  • matchEventType(str) - the match event type

  • regionName(str) - the region name

EncounterEvents = <streamsx.topology.schema.StreamSchema object>

This schema can be used as output for FlightPathEncounter().

The schema defines following attributes

  • id(str) - the device id

  • latitude(float64) - the latitude of the device

  • longitude(float64) - the longitude value of the device

  • timeStamp(timestamp) - the timestamp

  • matchEventType(str) - the match event type

  • regionName(str) - the region name

Events = <streamsx.topology.schema.StreamSchema object>

This schema can be used as output for region_match().

The schema defines following attributes

  • id(str) - the device id

  • latitude(float64) - the latitude of the device

  • longitude(float64) - the longitude value of the device

  • timeStamp(timestamp) - the timestamp

  • matchEventType(str) - the match event type

  • regionName(str) - the region name

Observation3D = <streamsx.topology.schema.StreamSchema object>

This schema can be used as output for FlightPathEncounter().

The schema defines following attributes

  • id(str) - the device id

  • latitude(float64) - the latitude of the device

  • longitude(float64) - the longitude value of the device

  • timeStamp(timestamp) - the timestamp

  • matchEventType(str) - the match event type

  • regionName(str) - the region name

Regions = <streamsx.topology.schema.StreamSchema object>

This schema can be used for region_match() to configure a region.

The schema defines following attributes

  • id(str) - The unique identifier of the region.

  • polygonAsWKT(str) - The geometry of the region as WKT string. For example: POLYGON((13.413140166512107 52.53577235025506,13.468071807137107 52.53577235025506,13.468071807137107 52.51279486997035,13.413140166512107 52.51279486997035,13.413140166512107 52.53577235025506))

  • removeRegion(bool) - A flag indicating if the region shall be removed. If false the region will be added. If true it will be removed. On removal only the regionId field is needed.

  • notifyOnEntry(bool) - A flag indicating if an ENTRY event shall be generated when a device enters the region.

  • notifyOnExit(bool) - A flag indicating if an EXIT event shall be generated when a device leaves the region.

  • notifyOnHangout(bool) - A flag indicating if a HANGOUT event shall be generated when a device stays in the region for some time.

  • minimumDwellTime(int64)- The minimum time in seconds a device has to be observed in a certain region, before a ‘Hangout’ event is reported.

  • timeout(int64) - Device timeout in seconds. In case a device was last observed more than timeout seconds ago, the device is treated as stale and is removed before the new observation is processed. If this value is zero, no timeout handling is performed.

Indices and tables