Getting Started

• VeRoViz may be installed via pip as follows:

  pip install veroviz

• To test your installation, use the following Python commands:

  import veroviz as vrv
  vrv.checkVersion()
  

  If the installation was successful, you should receive a message indicating that "you are up-to-date with the latest available version".

This step is optional, but recommended. The VeRoViz Python package can automatically generate dynamic 3D visualizations using Cesium, an open-source JavaScript library for rendering 3D maps.

If you don't install Cesium, you can still generate static 2D Leaflet maps. However, 3D time-dynamic maps are much more exciting!

Install the Cesium Application

The following instructions are adapted from https://cesiumjs.org/downloads

1. Download the latest release of CesiumJS from https://cesiumjs.org/downloads.
2. Extract (unzip) the .zip archive. Make note of where you save it.
3. Install the LTS version of node.js, from https://nodejs.org/en/download/.
4. From a command/terminal window, navigate to the main "cesium" directory (see your notes from Step 2). Then, issue the following command:

   npm install

Test Your Cesium Installation

1. From a command/terminal window, navigate to the main "cesium" directory (as in Step 4, above).
2. Start the node.js web server:

   node server.cjs

3. Open a web browser and visit http://localhost:8080/Apps/HelloWorld.html. You should see the Cesium Hello World app.

Add the VeRoViz Cesium Viewer Plugin

The VeRoViz Cesium Viewer is a local website that is configured to display output from the VeRoViz Python package in Cesium.

1. Download the VeRoViz Cesium Viewer from https://veroviz.org/downloads/veroviz_cesium_viewer.zip.
2. Extract (unzip) the .zip archive. It contains a directory named "veroviz". This directory should be moved into the main "cesium" directory. The result should look like this:

Test the VeRoViz Cesium Viewer

1. From a command/terminal window, navigate to the main "cesium" directory. Start the node.js web server (if it's not already running):

   node server.cjs

2. Open a web browser and visit the VeRoViz Cesium plugin page: http://localhost:8080/veroviz.
3. Click the folder icon on the left side of the page. Then, click the "Choose File" button. Navigate to the "Cesium/veroviz/demo" directory and choose ";veroviz;demo.vrv". Finally, click "Load/Run" to run the demo.

This step is optional, but is highly recommended if you want access to reliable/realistic routing data.

VeRoViz currently supports integration with the following data providers. You might choose to use only a subset of these.

MapQuest

OpenRouteService (ORS)

Open Source Routing Machine (OSRM)

Open Weather Map (OWM)

Elevation-API

This step is optional.

System environment variables allow you to save frequently-used information (such as API keys or paths to your Cesium installation directory). By saving these as environment variables, you don't need to copy/paste these values into each new Python script. Additionally, referencing API keys through environment variables makes it easy to share code with others without having to remove your private information.

The following environment variables are suggested, and are used throughout the VeRoViz documentation. We follow the convention of using ALL CAPS for these variables:

• MAPQUESTKEY - Your API key for MapQuest.
• ORSKEY - Your API key for OpenRouteService.
• CESIUMDIR - The full path to your "Cesium" installation directory.
• ELEVAPIKEY - Your API key for Elevation-API.
• OPENWEATHERKEY - Your API key for OpenWeatherMap.

Instructions Vary by Operating System

Reading Environment Variables in Python

In your python scripts (or Jupyter notebooks), you may read the environment variables as follows:

import os
MAPQUEST_KEY = os.environ['MAPQUESTKEY']
ORS_KEY      = os.environ['ORSKEY']
CESIUM_DIR   = os.environ['CESIUMDIR']
OWM_KEY      = os.environ['OPENWEATHERKEY']
ELEVAPI_KEY  = os.environ['ELEVAPIKEY']

This step is optional, but can be beneficial if you require significant volumes of routing data (beyond what is typically supported by the free APIs referenced above).

Openrouteservice has online APIs for calculating travel directions, time/distance matrices, elevation, geocoding, and isochrones. You may also install their routing machine locally via docker. A local installation of ORS removes the data limits associated with online API keys, but will also require you to maintain the routing engine (and map data) on your machine.

This step is optional, but can be beneficial if you require significant volumes of routing data (beyond what is typically supported by the free APIs referenced above).

pgRouting is an open-source database application that must be installed locally on the user's computer. You will need to install pgRouting before using related functions.

We recommend that users update their local pgRouting database frequently, as the source data (from OpenStreetMap) changes over time.

If you find odd results when using pgRouting, (e.g. unexpected travel times of "0") or if nodes are not being snapped properly to roads, please check if the data in the pgRouting database is sufficient to cover the region of interest. VeRoViz can not calculate the coordinates outside the boundary of pgRouting data.