Geopoint Patch
Nstream provides GeoPoint
and MapTile
patches that greatly facilitate grouping agents by geolocation to then assist with map rendering.
This guide demonstrates how to group agents into map tiles and maintain a join lane downlinking it’s members.
Dependencies
Gradle
implementation 'io.nstream:nstream-adapter-geo:4.15.23'
Maven
<dependency>
<groupId>io.nstream</groupId>
<artifactId>nstream-adapter-geo</artifactId>
<version>4.15.23</version>
<type>module</type> <!-- Remove or comment this line for non-modular projects -->
</dependency>
How It Works
Each GeoPoint
agent, after updating geolocation, will use longitude and latitude to calculate the (x, y, z) co-ordinate of the map tile which contains it.
These co-ordinates can be used to create a unique address for each map tile (such as /map/1,2,3
), the GeoPointPatch
manages joining and leaving the corresponding MapTillePatch
.
Map tiles correspond to Vector Tiles which provide a method of delivering geographic data in small chunks to a client or browser. This allows Nstream map tiles to be used with standard map UI libraries such as Mapbox or Esri maps.
Nstream Map UI
Once GeoPointPatch
agents are configured correctly you can use the out-of-the-box Nstream map UI to visualize your agents on a map.
Simply visit:
https://cdn.nstream.io/map/index.html?host=<host>
replacing <host>
with the address of you Nstream application.
For an application running locally on port 9001:
https://cdn.nstream.io/map/index.html?host=warp://localhost:9001
.
Config
Most cases of grouping agents can be implemented using config only in the server.recon
.
This involves adding GeoPointPatch
and MapTilePatch
to the relevant nodes and setting some simple parameters.
Map Tile Patch
The MapTilePatch
agent contains a JoinValueLane
named agents
that will downlink the geo
lane of its members.
Simply define a node that includes the MapTilePatch
agent:
# server.recon
...
space: @fabric {
@plane(class:"nstream.adapter.runtime.AppPlane")
# Domain Agents
# Map tile agent that will be used to group 'sites'
@node {
pattern: "/map/:tile"
@agent(class: "nstream.adapter.common.geo.MapTilePatch")
}
}
Geo Point Patch
The GeoPointPatch
agent provides functionality to join and leave map tile agents (MapTilePatch
s).
Static Location
The geolocation of an agent will sometimes be constant and known beforehand (not determined at runtime), it is stationary.
In this case, we can provide a static longitude
and latitude
in the config of the GeoPointPatch
.
# server.recon
...
# Domain Agents
@node {
pattern: "/map/:tile"
@agent(class: "nstream.adapter.common.geo.MapTilePatch")
}
@node {
pattern: "/city/London"
@agent(class: "nstream.adapter.common.geo.GeoPointPatch") {
latitude: 51.01
longitude: 0.01
}
}
Dynamic Location
Some agents’ geolocation is not known beforehand and needs to be determined at runtime. It may also be the case that the geolocation of an agent will change, requiring them to leave and join map tiles dynamically. For this case, we define two properties:
-
extractLatitude
: a value selector to extract the latitude from an event. -
extractLongitude
: a value selector to extract the longitude from an event.
# server.recon
...
# Domain Agents
@node {
pattern: "/map/:tile"
@agent(class: "nstream.adapter.common.geo.MapTilePatch")
}
@node {
pattern: "/site/:id"
@agent(class: "nstream.adapter.common.geo.GeoPointPatch") {
extractLatitude: $lat
extractLongitude: $long
}
}
Geo Point Patch Config Options
Name | Description | Required | Default | Example |
---|---|---|---|---|
latitude |
Static latitude of the agent | false | 51.01 |
|
longitude |
Static longitude of the agent | false | 0.01 |
|
extractLatitude |
Value selector of latitude from an event | false | $lat |
|
extractLongitude |
Value selector of longitude from an event | false | $long |
|
extractValueFromEvent |
Value selector of a value from an event | false | $status |
|
minAgentZoom |
Minimum z-tile value to join | false | 0 |
4 |
maxAgentZoom |
Maximum z-tile value to join | false | 20 |
14 |
mapTileUriPattern |
Map tile URI pattern, one pattern part, matches a MapTilePatch URI pattern |
false | /map/:tile |
/map/tile/:tile |
Note: Although no fields are explicitly required, to generate any behavior either the static or dynamic latitude and longitude fields must be present.
Nstream is licensed under the Redis Source Available License 2.0 (RSALv2).