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.13.21'

Maven

<dependency>
  <groupId>io.nstream</groupId>
  <artifactId>nstream-adapter-geo</artifactId>
  <version>4.13.21</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 (MapTilePatchs).

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

Note: Although no fields are explicitly required, to generate any behavior either the static or dynamic latitude and longitude fields must be present.