Pelagos Client is a stand-alone web application for visualizing large time series datasets on top of a zoomable world map. A datasets can be provided either as a single static file, a tree of tile files or by a dynamic tile generation server with an optional static cache.
WebGL data rendering allowing large dataset and fast rendering
Map pan and zoom
Timeslider to pan and zoom in time to any time range
Multiple data layers
Mouse-over and selection information for objects
Dynamic data mapping UI
Data styling using GLSL shader language
Optional search UI (requires server side query handling code)
The site itself does not require any specific server-side components for hosting; all the application is packaged as a static site and all you need to do to deploy it is to drop some files on an apache, nginx or any static file server.
You do need however some development environment prerequisites to build those static files by downloading all library dependencies, concatenate and minify scripts, etc. You also need the development environment up and running if you want to generate test datasets, run the unit or integration tests, etc.
You have 2 options to setup your development environment. You can either use the preferred virtualized development environment, which requires you to setup vagrant, or you can install all requirements in your machine.
Quick virtualized test server
The following steps will get you up and running with a test tileset as quickly as possible:
vagrant up vagrant ssh # The following inside the vagrant ssh shell cd /vagrant make dev-server
Now got to http://localhost:8000/index.html?workspace=/ui_tests/data/testtiles/workspace in your webserver.
The workspace and tileset files you're viewing are located in /ui_tests/data/testtiles/. If you have another dataset you can place it alongside this one and adjust your URL accordingly.
You can build the application assets, run all the tests and start a development server inside a Vagrant virtualized machine. This is the preferred way of setting up your development environment, as no dependencies will be installed in your machine, and no configuration is needed. For that will need:
- Vagrant to manage the virtualized development environment. This requires installing VirtualBox as well. If you are using ubuntu, don't install it from the standard Debian repositories, as it is an outdated version incompatible with our vagrantfile. Use the official packages instead.
Once these are installed you can set up and start the virtual machine:
Start the virtualized environment with
vagrant up. This will take a while, as the entire development environment is downloaded and configured.
SSH into the virtual machine with
vagrant sshand jump to the project folder with
Any of the tasks described here, such as
make dev-sever or
make all are
meant to be run inside the virtual machine at the
Non-virtualized setup (on ubuntu)
If you want to instead run everything on your local machine, you will need to
install a couple of libraries and other prerequisites. You can do that by
sudo make prerequisites. Take a look at the makefile in this project
to see exactly what is installed and how before running this task as it will install software packages globally on your machine.
Running the application
You can start a local development server for the application with
make dev-server. Remember to run the command inside the ssh session if you are
using the virtualized environment. Once the server is up, You can access the
/path/to/workspace is an URL to a JSON file containing a workspace
definition. For more information about this check out the workspace
Example data is available in the
data branch of this repo. A test workspace
is also generated automatically by the
make dev-server task, check out the
output from the task, as it prints the exact url where this test workspace is
Data can also be generated using the vectortile Python library if you want to build your own custom workspace.
You can download external libraries that the visualization depends on into
js/libs using the
make dependencies task.
You don't need to build (minify) the application to run it, but it speeds it up greatly by minimizing download time. You can download all dependencies and do this through the
make all task.
This will do the following:
Download and install external libraries as per
Compile all visualization and data loading code in the
jsdirectory. It will minify, concatenate and optimize everything using the dojo build system. The output of all this will be at the js-build direcotry.
The project contains both automated unit and integration tests.
Unit tests are run with
Integration tests are run with
To develop new tests, run
make test-server. This starts a server like
make dev-serverdoes, opens a browser connected to a selenium webdriver and a python command line with a selenium driver in the variable "driver". This command does not work in a virualized vagrant environment, as it needs to communicate with your local chrome instance.