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
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
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.
Within this directory, you will find two GeoJSON files,
hampshireRoads.json as well as two OVE
Map Configuration files,
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,
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,
hampshireRoads.json as well as the two OVE
Map Configuration files that we generated in the previous step,
roads_map_config.json. This can be done by running the following on a command line (within the
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
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
- Step 2: use the
LocalNinespace with x:
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
hto their maximum values.
- Step 3: select the
New state configurationmode and set the Asset URL to one of
YOUR_IPwith your IP address.
- Step 4: delete existing sections and open the controller (i.e.
- Step 5: press
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.
Step A: Download the CSV File¶
Extract the downloaded zip archive and copy the
listings.csv to the
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
listings_map_config.json by running:
cp crime_map_config.json listings_map_config.json
listings_map_config.json file using your favourite text editor. Replace
["-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
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.
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.
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.
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.