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:
- linux-python3-v0.5.0-setup
- linux-python2-v0.5.0-setup
- osx-python3-v0.5.0-setup
- osx-python2-v0.5.0-setup
- windows-python3-v0.5.0-setup.exe
- windows-python2-v0.5.0-setup.exe
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 changew
andh
to their maximum values. - Step 3: select the
New state configuration
mode and set the Asset URL to one ofhttp://YOUR_IP:8000/roads_map_config.json
orhttp://YOUR_IP:8000/crime_map_config.json
. ReplaceYOUR_IP
with your IP address. - Step 4: delete existing sections and open the controller (i.e.
Yes
andYes
). - 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.