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 isFalse
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
-
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 theFlightPathEncounter()
.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.
-