Repository files navigation

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

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

• Directions
• Isochrones
• Matrix
• Traveling Salesman

Thewiki offers a tutorial on usage.

In case of issues/bugs, please use theissue tracker.

For general questions, please ask in ourforum.

See also:

• Rate limits
• ORS user dashboard
• API documentation
• ORS openrouteservice-py onPyPi
• ORS Tools plugin inQGIS repo

Use QGIS to generate input forrouting,isochrones andmatrix 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 defaultopenrouteservice provider viaWeb ►ORS Tools ►Provider Settings or click the settings button in the ORS Tools dialog.

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

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

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 entryORS Tools ►Provider settings. Or from theConfig buttonin the GUI.

QGIS version:v3.4 or above

ORS API key

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

Then search foropenrouteservice and installORS Tools.

Alternatively, install the plugin manually:

• Download ZIP file from GitHub
• Unzip folder contents and copyORStools 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

• QGIS-LTR (3.16)

  Recommended plugins:

  • plugin reloader
  • First Aid (community PyCharm edition only)

• PyCharm or similar IDE

On PyCharm startup create a new project withGet From VHS and paste the repository urlhttps://github.com/GIScience/orstools-qgis-plugin

or clone manually and open the folder with your IDE

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

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

1. PyCharm ►Preferences ►Project ►Python Interpreter
2. click cogwheel and chooseAdd...
3. selectVirtualenv 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 (SeeQGIS cookbook)
   • (Windows) to be determined (Best also use thecookbook)
6. checkInherit global site-packages and if you wantMake available to all projects
7. clickOk
8. in the overview of project interpreters, select the just created one (qgis) and click the last button showinginterpreter paths
9. add the binary folder inside QGIS contents to the environment path, to expose cli commands likepyuic5,pyrcc5,ogr2ogr and more:
   • (Mac)/Applications/QGIS-LTR.app/Contents/MacOS/bin
   • (Linux) to be determined
   • (Windows) to be determined

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

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

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

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 doexport ORS_API_KEY=[Your API key here] before you run the tests.

To run the tests do:

cd orstools-qgis-pluginpytest

Do all the following steps in aWSL. To run tests locally you can use aconda installation of the QGis version you want to test.You will also have to installxvfb to run the tests on involving an interface.Lastly, we needPytest to run tests in general.

To do the above run use these commands:

1. Install a version of anaconda, preferrablyminiforge.

2. Create and prepare the environment.

# create environmentconda create --name qgis_test# activate environmentconda activate qgis_test# install pipconda install pip

3. Install QGis using mamba.

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

4. Installxvfb

sudo apt-get updatesudo apt install xvfb

5. InstallPytest using pip in testing environment.

pip install -U pytest

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

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

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

Theprofessional PyCharm edition offers remote debugging with breakpoints which lets you inspect elements during runtime, andstep through the code execution.

To use the debugger create a new run configuration:

1. click the dropdown next to the run button

2. selectEdit configurations

3. click+ and selectPython Debug Server

4. give the configuration a name and set thePort to53100 and leave theIDE host name atlocalhost

5. copy the command to connect to the debug server (2.)

6. remember the version number of thepydevd-pycharm you will need (1.)

7. clickok

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

   or install from the terminal

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

9. create a live template to quickly insert break points (PyCharm ►Preferences ►Editor ►Live Templates)

   • collapsePython and click+
   • set abbreviation to e.g.br add description and setTemplate text to

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

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

    # create debug branchgit checkout -b debug

    add inORStools/ORStoolsPlugin.py before all imports and adjust path with your user and app location if PyCharmwas not installed via JetBrains toolbox

    DEBUG=TrueifDEBUG:importsyssys.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:importpydevd_pycharmpydevd_pycharm.settrace('localhost',port=53100,stdoutToServer=True,stderrToServer=True)

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

    # below other importsfrom ..ORStoolsPluginimportDEBUG# surround raise with if block around run_gui_control()ifnotDEBUG:raise

    commit changes

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

Important: When using the remote debugger of PyCharm you have todisable the First Aid plugin, as it interfereswith the remote debugger.

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

# this will cherry pick the last commit of the debug branchgit cherry-pick debug

Make sure the localdebug branch is up to date with themain branch by rebasing regularly

# you will be on debug branch afterwardsgit 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 withleft 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 manualbreakpoint in e.g.ORStools/proc/isochrones_layer_proc.py by typingbr (orwhatever you configured in your live template), pressing enter andreload 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

• pressingalt/option + 9 and right-click the debug commit on your branch and chooseDrop Commit
• git stash && git reset --hard HEAD^ && git stash pop
• commit your changes andgit rebase -i HEAD^^, prepend the debug commit with ad and save

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

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

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

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

• usedesigner command

Proceed similar for other.ui files:

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

   # make sure you are in the gui foldercd ORStools/gui# convert to .py and set correct importpython -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 theresources.qrc file

   # also within the gui folderpython -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 inORStools/gui/directions_gui.pyas well

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

1. Generate the.ts-files (Translation Source) fromtranslate.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

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

By using this plugin, you also agree to theterms and conditions ofopenrouteservice.

This project was first started byNils Nolde.