Gpdviz

Gpdviz is a generic, lightweight tool for web-based visualization of geo-located point data streams in real-time.

Status: Functional but still considered experimental.

Data providers use the Gpdviz REST API to register sensor systems, data streams, and observations. This API is specified using OpenAPI 2.0. The visualization is updated in real-time using WebSockets.

Assuming Gpdviz is deployed at http://example.net/gpdviz:

url	purpose
http://example.net/gpdviz/mysysid/	Visualization of sensor system with ID mysysid
http://example.net/gpdviz/api	The REST API endpoint
http://example.net/gpdviz/api-docs	API documentation

Data model

The main entities in the data model are: sensor systems, data streams, variable definitions, and observations.

• A sensor system has associated metadata (name, description, etc.) and consists of a set of data streams.

• A data stream has associated metadata (name, description, map/chart styles, etc.) and consists of a set of variable definitions and associated observations.

• A variable definition consists of a name, units, and chart style.

• An observation is timestamped and can capture scalar data (e.g., temperature values), as well as features and geometries (in GeoJson format).

Operations for data providers

• Register/unregister sensor systems
• Add/remove data streams
• Add/remove variable definitions
• Register observations

The Gpdviz server maintains a registry with the provided information for each sensor system including a window of most recent reported observations for each stream in the system. Users will be able to see the latest reported state whenever they open the particular URL corresponding to the desired sensor system, and in real time see any subsequent updates reported by the provider.

Running

Direct execution

To execute Gpdviz you will need a Java runtime environment, access to a PostgreSQL server, and ability to create a database and a user on that server for Gpdviz purposes.

Download the latest executable JAR gpdviz-x.y.z.jar from https://github.com/gpdviz/gpdviz/releases/.

• Gpdviz expects a number of parameters for its regular execution. These parameters are to be indicated in a local conf/gpdviz.conf file. A template of such file, with a description of the various parameters, can be generated as follows:

    $ java -jar gpdviz-x.y.z.jar generate-conf
  

• Edit conf/gpdviz.conf as needed.

• Create the database and user indicated in gpdviz.conf, with the user being granted all privileges on the database.

• Execute the Gpdviz server:

    $ java -jar gpdviz-x.y.z.jar run-server
  

Docker

With a Docker engine on your target system, you will only need to define some parameters (via environment variables) and launch the services defined in docker-compose.yml. This set-up includes the PostgreSQL server and database. Please see https://hub.docker.com/r/gpdviz/gpdviz/.

Demo

This httpie-based bash script can be used as a demo of a data provider. Define the GPDVIZ_SERVER environment variable prior to running this script.

For a similar demo in Python, see https://github.com/gpdviz/gpdviz_python_client_example, which uses the client module https://github.com/gpdviz/gpdviz_python_client automatically generated from the OpenAPI specification.

Development

Gpdviz implementation is based on:

• Akka-HTTP
• Slick
• PostgreSQL
• ScalaJS
• Leaflet
• Highcharts

Build and run

$ npm install jsdom source-map-support
$ sbt
> package   # to copy js resources to jvm's classpath needed for the webapp
> gpdvizJVM/runMain gpdviz.Gpdviz generate-conf
> gpdvizJVM/runMain gpdviz.Gpdviz create-tables
> gpdvizJVM/runMain gpdviz.Gpdviz add-some-data
> gpdvizJVM/runMain gpdviz.Gpdviz run-server

For the demo with sensor system ID "ss1":

• Open http://localhost:5050/ss1/ in your browser.

• On another terminal, either run the bash script:

    $ data/ss1.demo.sh
  

  or the similar client in python as explained at https://github.com/gpdviz/gpdviz_python_client_example

Dist

To generate the executable JAR jvm/target/scala-2.12/gpdviz-x.y.z.jar:

$ sbt gpdvizJVM/assembly

For the dockerized version, see docker/readme.md.

Model

Data model details are still wip.

API

OpenAPI spec generated by swagger-akka-http.

Swagger UI

A Swagger UI instance is embedded as follows:

• copy Swagger UI dist/* contents to jvm/src/main/resources/swaggerui/;
• adjust the url entry in swaggerui/index.html to refer to the generated spec: url: window.location + "/swagger.json"
• rebuild

Under local development:

• generated spec at http://localhost:5050/api-docs/swagger.json
• Swagger UI at http://localhost:5050/api-docs

history

Original idea.