ORS Tools QGIS plugin

Set of tools for QGIS to use the openrouteservice (ORS) API.

ORS Tools gives you easy access to the following API's:

• Directions
• Isochrones
• Matrix
• Traveling Salesman

The wiki offers a tutorial on usage.

In case of issues/bugs, please use the issue tracker.

For general questions, please ask in our forum.

See also:

• Rate limits
• ORS user dashboard
• API documentation
• ORS openrouteservice-py on PyPi
• ORS Tools plugin in QGIS repo

Functionalities

General

Use QGIS to generate input for routing, isochrones and matrix calculations powered by ORS.

You'll have to create an openrouteservice account and get a free API key first: https://openrouteservice.org/sign-up. After you have received your key, add it to the default openrouteservice provider via Web ► ORS Tools ► Provider Settings or click the settings button in the ORS Tools dialog.

The plugin offers either a GUI in the Web menu and toolbar of QGIS to interactively use the ORS API from the map canvas.

For batch operations you can find an ORS Tools folder in the Processing Toolbox.

Customization

Additionally, you can register other ORS providers, e.g. if you're hosting a custom ORS backend.

Configuration takes place either from the Web menu entry ORS Tools ► Provider settings. Or from the Config button in the GUI.

Getting Started

Requirements

QGIS version: v3.4 or above

ORS API key

Installation

In the QGIS menu bar click Plugins ► Manage and Install Plugins....

Then search for openrouteservice and install ORS Tools.

Alternatively, install the plugin manually:

• Download ZIP file from GitHub
• Unzip folder contents and copy ORStools folder to:
  • Linux: ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins
  • Windows: C:\Users\USER\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins
  • Mac OS: Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins

Development Setup

Requirements:

• QGIS-LTR (3.16)

  Recommended plugins:

  • plugin reloader
  • First Aid (community PyCharm edition only)
• PyCharm or similar IDE

Clone repository

On PyCharm startup create a new project with Get From VHS and paste the repository url https://github.com/GIScience/orstools-qgis-plugin

or clone manually and open the folder with your IDE

# clone the repository
git clone https://github.com/GIScience/orstools-qgis-plugin.git

Set up environment and python interpreter

Use the Python from your QGIS installation as interpreter in a new virtual environment

1. PyCharm ► Preferences ► Project ► Python Interpreter
2. click cogwheel and choose Add...
3. select Virtualenv Environment(default)
4. set env folder to e.g. ~/Workspaces/qgis (this environment can be used for multiple QGIS plugins if needed)
5. set Base interpreter to the one QGIS uses (QGIS ► Preferences ► System ► Current environment variables ► PYTHONHOME + bin/python3.8)
   • (Mac) /Applications/QGIS-LTR.app/Contents/MacOS/bin/python3.8
   • (Linux) might work with the system python (See QGIS cookbook)
   • (Windows) to be determined (Best also use the cookbook)
6. check Inherit global site-packages and if you want Make available to all projects
7. click Ok
8. in the overview of project interpreters, select the just created one (qgis) and click the last button showing interpreter paths
9. add the binary folder inside QGIS contents to the environment path, to expose cli commands like pyuic5, pyrcc5, ogr2ogr and more:
   • (Mac) /Applications/QGIS-LTR.app/Contents/MacOS/bin
   • (Linux) to be determined
   • (Windows) to be determined

Link plugin to QGIS

To not copy around files all the time, create a symlink in the QGIS plugin folder to the ORStools folder of the repository

ln -s ORStools <qgis_plugins_path>

where <qgis_plugins_path> is one of:

• Linux: ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/ORStools
• Windows: C:\Users\USER\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\ORStools
• Mac OS: Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/ORStools

CI

Testing

The repository tests on the QGis Versions 3.16, 3.22 and the latest version. Until now, it's only possible to test one version at a time.

Linux

On linux machines you can run the tests with your local QGIS installation.

1. Install QGIS and make sure it's available in your currently activated environment.

You will need an ORS-API key. Either set it as an environment variable or do export ORS_API_KEY=[Your API key here] before you run the tests.

To run the tests do:

cd orstools-qgis-plugin
pytest

Windows

Do all the following steps in a WSL. To run tests locally you can use a conda installation of the QGis version you want to test. You will also have to install xvfb to run the tests on involving an interface. Lastly, we need Pytest to run tests in general.

To do the above run use these commands:

1. Install a version of anaconda, preferrably miniforge.

2. Create and prepare the environment.

# create environment
conda create --name qgis_test
# activate environment
conda activate qgis_test
# install pip
conda install pip

3. Install QGis using mamba.

   conda install -c conda-forge qgis=[3.16, 3.22, latest] # choose one

4. Install xvfb

   sudo apt-get update
   sudo apt install xvfb

5. Install Pytest using pip in testing environment.

   pip install -U pytest

To run the tests you will need an ORS-API key:

cd orstools-qgis-plugin
export ORS_API_KEY=[Your API key here] && xvfb-run pytest

Debugging

In the PyCharm community edition you will have to use logging and printing to inspect elements. The First Aid QGIS plugin can probably also be used additionally.

The professional PyCharm edition offers remote debugging with breakpoints which lets you inspect elements during runtime, and step through the code execution.

To use the debugger create a new run configuration:

1. click the dropdown next to the run button
2. select Edit configurations
3. click + and select Python Debug Server
4. give the configuration a name and set the Port to 53100 and leave the IDE host name at localhost
5. copy the command to connect to the debug server (2.)
6. remember the version number of the pydevd-pycharm you will need (1.)
7. click ok

8. install the exact version package in the interpreter package list (PyCharm ► Preferences ► Project ► Python Interpreter ► +)

   or install from the terminal

   # replace the version with the one listed in the run configuration
   pip install pydevd-pycharm~=211.7142.13

9. create a live template to quickly insert break points (PyCharm ► Preferences ► Editor ► Live Templates)
   • collapse Python and click +
   • set abbreviation to e.g. br add description and set Template text to

     import pydevd_pycharm
     pydevd_pycharm.settrace('localhost', port=53100, stdoutToServer=True, stderrToServer=True)

10. create a debug branch and commit that loads the pydev-pycharm code

    # create debug branch
    git checkout -b debug

    add in ORStools/ORStoolsPlugin.py before all imports and adjust path with your user and app location if PyCharm was not installed via JetBrains toolbox

    DEBUG = True
    
    if DEBUG:
        import sys
        sys.path.append('/Users/{your_user}/Library/Application Support/JetBrains/Toolbox/apps/PyCharm-P/ch-0/211.7142.13/PyCharm.app/Contents/debug-eggs/pydevd-pycharm.egg')
        # add breakpoints like:
        import pydevd_pycharm
        pydevd_pycharm.settrace('localhost', port=53100, stdoutToServer=True, stderrToServer=True)

    avoid raising exceptions in ORStools/gui/ORStoolsDialog.py to not crash QGIS every time one is raised

    # below other imports
    from ..ORStoolsPlugin import DEBUG
    
    # surround raise with if block around run_gui_control()
    if not DEBUG:
        raise

    commit changes

    git add . && git commit -m "Debug commit"

    Important: When using the remote debugger of PyCharm you have to disable the First Aid plugin, as it interferes with the remote debugger.

Workflow

To debug you now only need to cherry-pick the debug commit to the branch you are working on and place any changes on top.

# this will cherry pick the last commit of the debug branch
git cherry-pick debug

Make sure the local debug branch is up to date with the main branch by rebasing regularly

# you will be on debug branch afterwards
git rebase main debug

Before starting QGIS, you need to run the "QGIS debug" configuration you created.
Afterwards you can open QGIS and press the plugin reloader button (configured to reload ORStools). It should break at the breakpoint introduced in the debug commit.

In general, you can now use normal breakpoints of the IDE with left click in the gutter (or ctrl/cmd + F8).

If you are debugging the processing algorithms, which run in another thread, you will have to add another manual breakpoint in e.g. ORStools/proc/isochrones_layer_proc.py by typing br (or whatever you configured in your live template), pressing enter and reload the plugin in QGIS.

In short: Use IDE breakpoints if they work, if not use manual and IDE breakpoints afterwards.

Once you finalized your changes, remove the manual breakpoints again and drop the debug commit.

You can do this with one of the following

• pressing alt/option + 9 and right-click the debug commit on your branch and choose Drop Commit
• git stash && git reset --hard HEAD^ && git stash pop
• commit your changes and git rebase -i HEAD^^, prepend the debug commit with a d and save

Interface development

For designing the Dialog the Qt designer shipping with qgis is used. It has relevant classes such as QgsMapLayerComboBox already imported properly.

Mac

• use /Applications/QGIS-LTR.app/Contents/MacOS/bin/designer instead of /Applications/QGIS-LTR.app/Contents/MacOS/Designer.app (trying to get other Qt Designer or Qt Creator installations to use the correct QGIS classes was unsuccessful)
• if you want a shortcut in Applications do

  cd /Applications
  ln -s QGIS-LTR.app/Contents/MacOS/bin/designer "Qt Designer.app"

Windows

• should create you a shortcut to the Qt Designer with the installation

Linux

• use designer command

Workflow

Proceed similar for other .ui files:

1. open the ORStools/gui/ORStoolsDialogUI.ui file in the Designer and save your changes after editing.
2. convert the .ui file to .py file by using pyuic5 (which should also be accessible as command from your terminal if PyCharm uses the qgis env but using it as a module makes sure the correct one is used in case you have other PyQt installations on your machine)

   # make sure you are in the gui folder
   cd ORStools/gui
   # convert to .py and set correct import
   python -m PyQt5.uic.pyuic --import-from . -o ORStoolsDialogUI.py ORStoolsDialogUI.ui

3. in case you edit resources such as images you also need to convert the resources.qrc file

   # also within the gui folder
   python -m PyQt5.pyrcc_main -o resources_rc.py resources.qrc

4. if you edited or added new widgets you will have to change or include them in ORStools/gui/directions_gui.py as well

Translation

Translation uses the QT Linguist for translating GUI and source code strings. All translation-related content resides in ORStools/i18n. Translation is controlled by ORStools/gui/translate.pro, stating all UI-forms and sourcefiles that include strings to be translated. To add a translation, add orstools_<LANGUAGE_TAG>.ts to the list of translation in this file.

Workflow

1. Generate the .ts-files (Translation Source) from translate.pro via

   pylupdate5 -noobsolete -verbose translate.pro

   Note that this will drop obsolete strings, skip -noobsolete if you want to keep them.

2. Inspect the changes this has on the existing *.ts-files. pylupdate5 will remove translation comments and might restructure the translation.
3. Translate the *.ts-files using QT Linguist via

   linguist orstools_<LANGUAGE_TAG>.ts

4. Compile the *.ts-file to a *.qm Qt Translation file via

   lrelease orstools_<LANGUAGE_tag>.ts

License

This project is published under the GPLv3 license, see LICENSE.md for details.

By using this plugin, you also agree to the terms and conditions of openrouteservice.

Acknowledgements

This project was first started by Nils Nolde.