Geovisualisation

The rich set of features provided by the Maps App makes it very easy to OVE to visualise geospatial data. In this tutorial we will learn how to visualise some of the open data in the geospatial domain using OVE.

Step 1: Installing OVE

Before starting the tutorial, we need an installation of OVE. If you already have an OVE installation and would like to use that, please proceed to the next step.

For this tutorial, it is sufficient to install OVE into a Docker environment. To install OVE, we need the following prerequisites:

Docker is available in two versions: a free Community Edition (CE), and an Enterprise Edition (EE) that includes commercial support. The Community Edition should be sufficient for most users of OVE, and can be installed by following the instructions for Docker Desktop for Windows, Docker Desktop for Mac or Docker CE for Linux. If you are using a version of Windows or Mac OS that does not meet the requirements listed for the Docker Desktop installer (either because it is too old, or because it is the Home edition of Windows, rather than Pro, Enterprise or Education), you should instead install the legacy Docker Toolbox.

After installing the prerequisites, OVE can then installed by downloading the specific installation script from the list below:

Once downloaded, the installation script may not be executable on Linux and Mac operating systems. As a resolution, run the following command:

chmod u+x *-setup

Important: Before using the installer, please refer the documentation and select the version of OVE that best suits your requirements. By default, the installer will select the stable versions of the OVE components at the point in time it was released. But, some tutorials may not be supported on older versions. As a resolution, you can use the latest version, which will let you work with the latest unstable version of the code. This tutorial requires an OVE version of 0.5.0 or later.

If you have already installed an older version of OVE and want to upgrade to a newer version, please shutdown the older version (prior to installing the newer version) by running the following command:

docker-compose -f docker-compose.setup.ove.yml down

Running the the executable installation script that you just downloaded will start the step-by-step installation process. For unsupported platforms or to change port numbers and for additional information, please refer the OVE installation guide.

If you have just upgraded to a newer version of OVE, please run the following command before starting OVE:

docker-compose -f docker-compose.setup.ove.yml pull

Once installed, start OVE by running the commands suggested by the installer:

docker-compose -f docker-compose.setup.ove.yml up -d

Step 2: Installing other prerequisites

For this tutorial, we will also need the following prerequisites:

Once you have installed them, please clone the OVE Tutorials repository by running the following on a command line:

git clone https://github.com/ove/ove-tutorials
cd ove-tutorials

Step 3: Generate the Map Configuration files including your IP address

First of all, you need to find your IP address. This can be done by running the following on a command line (within the ove-tutorials directory):

python -m getIP

If you are unable to run the above command, please check if you have installed Python and also added it to your PATH, which is provided as an option in some installers. If you have successfully installed Python, check if you are in the ove-tutorials directory. If the command does not work for any other reason, you can run ifconfig or ipconfig and find your IP address.

We then need to change directory to geovisualisation. All the files that we will be using in this tutorial can be found inside this directory.

cd geovisualisation

Within this directory, you will find two GeoJSON files, hampshireCrime.json and hampshireRoads.json as well as two OVE Map Configuration files, crime_map_config_original.json and roads_map_config_original.json. You will also find several Python scripts.

The IP addresses of the OVE Map Configuration files can be replaced by running a Python script. Please replace <IP> with your IP address (that you identified by running the instructions above). To change the IP addresses of the OVE Map Configuration files run the following on a command line:

python -m fixIP <IP>

This will generate two new OVE Map Configuration files, crime_map_config.json and roads_map_config.json. You will find that these new files have your IP address instead of localhost in the originals. You can run the above script more than once, if your IP address changes over time. Running the script more than once will regenerate these files.

If the script fails to execute for any reason, simply make copies of the originals and replace localhost with your IP address in the copies.

Step 4: Host the Geospatial data and Map Configurations

Before launching the application you will need to host the content that you plan to load. In this demo, we will be hosting the GeoJSON files, hampshireCrime.json and hampshireRoads.json as well as the two OVE Map Configuration files that we generated in the previous step, crime_map_config.json and roads_map_config.json. This can be done by running the following on a command line (within the geovisualisation directory):

python -m server

This will start a simple web server on your computer on port 8000. If everything works well, you should see the Serving HTTP on 0.0.0.0 port 8000 ... line printed on your command line. If you are unable to use this port, simply run the following command to use another port.

python -m server <PORT>

Please also remember to replace the port numbers on the crime_map_config.json and roads_map_config.json files to match the new port number if you are not using port 8000.

You can stop the server by interrupting it using ctrl+c on your keyboard. We need to keep the server running before we can proceed to the next step.

Step 5: Launching Map Configurations

In this step we will be using the Launcher UI to launch each map configuration into the OVE environment. This UI can be accessed by opening the http://localhost:8080/ui/launcher URL on a web browser. If you changed the port numbers when installing OVE, you will need to replace 8080 with the corresponding port number. If you did not install OVE locally, you will need to replace localhost:8080 with the OVE_CORE_HOST:PORT combination corresponding to the remote OVE installation that you want to use.

If the Launcher UI does not load, this may be because the IP address has changed on your local installation. This can be fixed by restarting Docker and relaunching OVE by running the commands suggested by the installer. If you are using a remote OVE installation, you will need to contact the person administering it.

Once the Launcher UI has loaded follow the steps below.

  • Step 1: select the Maps application.
  • Step 2: use the LocalNine space with x: 0, y: 0, w: 4320, h: 2424 (please type these in). If you are using the remote OVE installation or if you have configured other spaces, please select your space of choice and change w and h to their maximum values.
  • Step 3: select the New state configuration mode and set the Asset URL to one of http://YOUR_IP:8000/roads_map_config.json or http://YOUR_IP:8000/crime_map_config.json. Replace YOUR_IP with your IP address.
  • Step 4: delete existing sections and open the controller (i.e. Yes and Yes).
  • Step 5: press Launch.

This will launch the controller of the Maps App. Please note that the controller may not automatically launch if you have any pop-up blockers on your web browser.

At this point, only the base layer will be selected in the controller. To see the vector overlays, add &layers=0,1 to the URL and reload the page. You will then see some highlighted roads or some crime hotspots near the city of Southampton in the UK.

You can repeat this step if your map configuration has changed or if you want to launch the application on another space or to alter the dimensions. It may be easier to keep pressing Previous on the Launcher UI until you reach the desired step to avoid having to repeat all the steps. You can now proceed to the next step, which is also the last step in this tutorial.

Step 6: Viewing results on OVE

The last step will be to view the results on OVE. If you are using a remote OVE installation, it is most likely the the viewers would already be loaded, and you can skip this step.

If you have installed locally, you will need to explicitly launch the LocalNine space (or another space that you selected previously). Open the http://localhost:8080 URL to visit the OVE landing page. If you changed the port numbers when installing OVE, you will need to replace 8080 with the corresponding port number. Navigate to find the space you are interested in and open the URLs noted under The OVE Clients corresponding to this space have the URLs. If you selected the LocalNine space, you will have to open 9 URLs in total.

As an alternative to launching an entire space, you could also preview it by selecting the Preview option found in front of the name of space on the OVE landing page. This will launch a single page preview of the space.

Please allow 15 - 20 seconds for your space (or its preview) to display the map for the first time. You will find that the map loads much faster subsequently.

You now can repeat the previous step to switch between the two sample datasets that are provided in this tutorial.

Bonus Step: Previewing Airbnb data from Boston

In this bonus step, we will learn how to work with public datasets. We will be using a sample dataset provided by kaggle. We will be looking at the Airbnb Listings from Boston.

Step A: Download the CSV File

To start, download listings. You may need an account on kaggle to download this file.

Extract the downloaded zip archive and copy the listings.csv to the geovisualisation directory.

Step B: Convert the CSV file into a GeoJSON file

Then, run the following on a command line to generate a GeoJSON file for these listings:

python -m pip install -r requirements.txt
python -m convert

The script above is capable of producing GeoJSON files from any CSV files. To convert another file simply modify the convert.py script. You could also convert a file at another location by running:

python -m pip install -r requirements.txt
python -m convert <file_path.csv>

Step C: Create the Map Configuration for Listings

Make a copy of the crime_map_config.json as listings_map_config.json by running:

cp crime_map_config.json listings_map_config.json

Edit the listings_map_config.json file using your favourite text editor. Replace hampshireCrime.json with listings.json and ["-157081.37129179656", "6606026.977066623"] with ["-7909957.677026466", "5214901.036122"]. This will make our map point at suburban Boston instead of Southampton and display Airbnb listings instead of crime data. We will only be displaying listings that are of type Entire home/apt. This can be changed by modifying the convert.py script.

Step D: Launch the Map Configuration and View Results

Now you can re-run Step 5 and launch the application with the http://YOUR_IP:8000/listings_map_config.json asset URL. Replace YOUR_IP with your IP address. You can zoom and pan the map using the controller of the Maps App to explore the dataset. You will be able to observe interesting trends such as the areas where Airbnb is popular and areas where it is not.

Summary

In this tutorial we learned how to use OVE for geovisualisation. We explored two datasets hampshireCrime.json and hampshireRoads.json. The bonus step looks at some Open Data from kaggle.

You can modify the convert.py script to convert other CSV files into GeoJSON, or download GeoJSON files from kaggle and other sources, or use other data formats such as TopoJSON, GML, KML, WKT CRS, OSM, IGC or Esri. You can also convert these other formats into GeoJSON.

The hampshireCrime.json was produced using a modified version of the convert.py script to convert the CSV file downloaded from data.police.uk. We used the data for the month of August 2016 from the Hampshire Constabulary and filtered the results to include crimes of type Criminal damage and arson. The hampshireRoads.json was produced by converting the OSM file from Geofabrik using the osmtogeojson command line tool.

The crime_map_config.json provides an example on using the Leaflet configuration module while the roads_map_config.json provides an example on using the OpenLayers configuration model. The Maps App will automatically select the appropriate library to suit the configuration model you choose. For more advanced configurations, to change the base map, or to use more than one vector overlay refer to the documentation of the OVE Maps App.