{"id":13857029,"url":"https://github.com/GIScience/orstools-qgis-plugin","last_synced_at":"2025-07-13T19:34:02.813Z","repository":{"id":43400567,"uuid":"82691440","full_name":"GIScience/orstools-qgis-plugin","owner":"GIScience","description":"Plugin for QGIS with a set of tools to use openrouteservice API´s, based on openstreetmap","archived":false,"fork":false,"pushed_at":"2024-03-26T11:36:39.000Z","size":1483,"stargazers_count":86,"open_issues_count":33,"forks_count":31,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-04-09T15:12:04.322Z","etag":null,"topics":["isochrones","openrouteservice","qgis-plugin","qgis-processing-provider","qgis3","qgis3-plugin","routing"],"latest_commit_sha":null,"homepage":"https://plugins.qgis.org/plugins/ORStools/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GIScience.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-02-21T14:51:21.000Z","updated_at":"2024-04-15T10:54:57.174Z","dependencies_parsed_at":"2023-01-29T23:00:20.892Z","dependency_job_id":"7bfa9089-ffd7-4030-adbf-c9e0f80c838d","html_url":"https://github.com/GIScience/orstools-qgis-plugin","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Forstools-qgis-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Forstools-qgis-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Forstools-qgis-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Forstools-qgis-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GIScience","download_url":"https://codeload.github.com/GIScience/orstools-qgis-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":213988313,"owners_count":15666960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["isochrones","openrouteservice","qgis-plugin","qgis-processing-provider","qgis3","qgis3-plugin","routing"],"created_at":"2024-08-05T03:01:23.328Z","updated_at":"2025-07-13T19:34:02.794Z","avatar_url":"https://github.com/GIScience.png","language":"Python","readme":"# ORS Tools QGIS plugin\n\n![Testing](https://github.com/GIScience/orstools-qgis-plugin/actions/workflows/test.yml/badge.svg?branch=main)\n![Ruff](https://github.com/GIScience/orstools-qgis-plugin/actions/workflows/ruff.yml/badge.svg?branch=main)\n\n![ORS Tools](https://user-images.githubusercontent.com/23240110/122937401-3ee72400-d372-11eb-8e3b-6c435d1dd964.png)\n\nSet of tools for QGIS to use the [openrouteservice](https://openrouteservice.org) (ORS) API.\n\nORS Tools gives you easy access to the following API's:\n\n- [Directions](https://openrouteservice.org/dev/#/api-docs/v2/directions/{profile}/geojson/post)\n- [Isochrones](https://openrouteservice.org/dev/#/api-docs/v2/isochrones/{profile}/post)\n- [Matrix](https://openrouteservice.org/dev/#/api-docs/v2/matrix/{profile}/post)\n- [Traveling Salesman](https://openrouteservice.org/dev/#/api-docs/optimization/post)\n\nThe [wiki](https://github.com/GIScience/orstools-qgis-plugin/wiki/ORS-Tools-Help) offers a tutorial on usage.\n\nIn case of issues/bugs, please use the [issue tracker](https://github.com/GIScience/orstools-qgis-plugin/issues).\n\nFor general questions, please ask in our [forum](https://ask.openrouteservice.org/c/sdks/qgis).\n\nSee also:\n- [Rate limits](https://openrouteservice.org/restrictions/)\n- [ORS user dashboard](https://openrouteservice.org/dev/#/home)\n- [API documentation](https://openrouteservice.org/dev/#/api-docs)\n- ORS openrouteservice-py on [PyPi](https://pypi.python.org/pypi/openrouteservice)\n- ORS Tools plugin in [QGIS repo](https://plugins.qgis.org/plugins/ORStools/)\n\n## Functionalities\n\n### General\n\nUse QGIS to generate input for **routing**, **isochrones** and **matrix calculations** powered by ORS.\n\nYou'll have to create an openrouteservice account and get a free API key first: \u003chttps://openrouteservice.org/sign-up\u003e.\nAfter you have received your key, add it to the default `openrouteservice` provider via `Web` ► `ORS Tools` ►\n`Provider Settings` or click the settings button in the ORS Tools dialog.\n\nThe plugin offers either a GUI in the `Web` menu and toolbar of QGIS to interactively use the ORS API\nfrom the map canvas.\n\nFor batch operations you can find an `ORS Tools` folder in the Processing Toolbox.\n\n### Customization\n\nAdditionally, you can register other ORS providers, e.g. if you're hosting a custom ORS backend.\n\nConfiguration takes place either from the Web menu entry *ORS Tools* ► *Provider settings*. Or from the *Config* button\nin the GUI.\n\n## Getting Started\n\n### Requirements\n\nQGIS version: **v3.4** or above\n\n[ORS API key](https://account.heigit.org)\n\n### Installation\n\nIn the QGIS menu bar click `Plugins` ► `Manage and Install Plugins...`.\n\nThen search for `openrouteservice` and install `ORS Tools`.\n\nAlternatively, install the plugin manually:\n  - [Download](https://github.com/GIScience/orstools-qgis-plugin/archive/main.zip) ZIP file from GitHub\n  - Unzip folder contents and copy `ORStools` folder to:\n    - Linux: `~/.local/share/QGIS/QGIS3/profiles/default/python/plugins`\n    - Windows: `C:\\Users\\USER\\AppData\\Roaming\\QGIS\\QGIS3\\profiles\\default\\python\\plugins`\n    - Mac OS: `Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins`\n\n## Development Setup\n\n### Requirements:\n- QGIS-LTR (3.16)\n  \n  Recommended plugins:\n  - [plugin reloader](https://plugins.qgis.org/plugins/plugin_reloader/)\n  - [First Aid](https://plugins.qgis.org/plugins/firstaid/) (community PyCharm edition only)\n- PyCharm or similar IDE\n\n### Clone repository\n\nOn PyCharm startup create a new project with `Get From VHS` and paste the repository url\n`https://github.com/GIScience/orstools-qgis-plugin`\n    \nor clone manually and open the folder with your IDE\n```shell\n# clone the repository\ngit clone https://github.com/GIScience/orstools-qgis-plugin.git\n```\n\n### Set up environment and python interpreter\nUse the Python from your QGIS installation as interpreter in a new virtual environment\n1. `PyCharm` ► `Preferences` ► `Project` ► `Python Interpreter`\n1. click cogwheel and choose `Add...`\n1. select `Virtualenv Environment`(default)\n1. set env folder to e.g. `~/Workspaces/qgis` (this environment can be used for multiple QGIS plugins if needed)\n1. set Base interpreter to the one QGIS uses (`QGIS` ► `Preferences` ► `System` ► `Current environment variables` ►\n    `PYTHONHOME` + `bin/python3.8`)\n    - (Mac) `/Applications/QGIS-LTR.app/Contents/MacOS/bin/python3.8`\n    - (Linux) might work with the system python (See [QGIS cookbook](https://docs.qgis.org/3.16/en/docs/pyqgis_developer_cookbook/plugins/ide_debugging.html#debugging-with-pycharm-on-ubuntu-with-a-compiled-qgis))\n    - (Windows) to be determined (Best also use the [cookbook](https://docs.qgis.org/3.16/en/docs/pyqgis_developer_cookbook/plugins/ide_debugging.html))\n1. check `Inherit global site-packages` and if you want `Make available to all projects`\n1. click `Ok`\n1. in the overview of project interpreters, select the just created one (qgis) and click the last button showing\n   interpreter paths\n1. add the binary folder inside QGIS contents to the environment path, to expose cli commands like `pyuic5`,\n  `pyrcc5`, `ogr2ogr` and more:\n    - (Mac) `/Applications/QGIS-LTR.app/Contents/MacOS/bin`\n    - (Linux) to be determined\n    - (Windows) to be determined\n\n### Link plugin to QGIS\nTo not copy around files all the time, create a symlink in the QGIS plugin folder to the ORStools folder of the\nrepository\n```shell\nln -s ORStools \u003cqgis_plugins_path\u003e\n```\nwhere `\u003cqgis_plugins_path\u003e` is one of:\n- Linux: `~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/ORStools`\n- Windows: `C:\\Users\\USER\\AppData\\Roaming\\QGIS\\QGIS3\\profiles\\default\\python\\plugins\\ORStools`\n- Mac OS: `Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/ORStools`\n\n### CI\n#### Testing\nThe repository tests on the QGis Versions *3.16*, *3.22* and the *latest* version. \nUntil now, it's only possible to test one version at a time.\n\n#### Linux\nOn linux machines you can run the tests with your local QGIS installation.\n\n1. Install QGIS and make sure it's available in your currently activated environment.\n\nYou 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. \n\nTo run the tests do:\n```shell\ncd orstools-qgis-plugin\npytest\n```\n\n#### Windows\nDo all the following steps in a [*WSL*](https://learn.microsoft.com/en-us/windows/wsl/install). To run tests locally you can use a [conda installation](https://github.com/opengisch/qgis-conda-builder) of the QGis version you want to test.\nYou will also have to install *xvfb* to run the tests on involving an interface. \nLastly, we need [*Pytest*](https://docs.pytest.org/en/8.0.x/) to run tests in general. \n\nTo do the above run use these commands:\n1. Install a version of anaconda, preferrably [*miniforge*](https://github.com/conda-forge/miniforge).\n\n2. Create and prepare the environment.\n\n```shell\n# create environment\nconda create --name qgis_test\n# activate environment\nconda activate qgis_test\n# install pip\nconda install pip\n```\n\n3. Install QGis using mamba.\n```shell\nconda install -c conda-forge qgis=[3.16, 3.22, latest] # choose one\n```\n\n4. Install *xvfb*\n```shell\nsudo apt-get update\nsudo apt install xvfb\n```\n\n5. Install *Pytest* using pip in testing environment.\n```shell\npip install -U pytest\n```\n\nTo run the tests you will need an ORS-API key:\n```shell\ncd orstools-qgis-plugin\nexport ORS_API_KEY=[Your API key here] \u0026\u0026 xvfb-run pytest\n```\n\n### Debugging\nIn the **PyCharm community edition** you will have to use logging and printing to inspect elements.\nThe First Aid QGIS plugin can probably also be used additionally.\n\nThe **professional PyCharm edition** offers remote debugging with breakpoints which lets you inspect elements during runtime, and\nstep through the code execution.\n\nTo use the debugger create a new run configuration:\n1. click the dropdown next to the run button\n1. select `Edit configurations`\n1. click `+` and select `Python Debug Server`\n1. give the configuration a name and set the `Port` to `53100` and leave the `IDE host name` at `localhost`\n1. copy the command to connect to the debug server (`2.`)\n1. remember the version number of the `pydevd-pycharm` you will need (`1.`)\n1. click `ok`\n1. install the exact version package in the\n   interpreter package list (`PyCharm` ► `Preferences` ► `Project` ► `Python Interpreter` ► `+`)\n   \n    or install from the terminal\n   ```shell\n   # replace the version with the one listed in the run configuration\n   pip install pydevd-pycharm~=211.7142.13\n    ```\n1. create a live template to quickly insert break points (`PyCharm` ► `Preferences` ► `Editor` ► `Live Templates`)\n    - collapse `Python` and click `+`\n    - set abbreviation to e.g. `br` add description and set `Template text` to \n    ```shell\n    import pydevd_pycharm\n    pydevd_pycharm.settrace('localhost', port=53100, stdoutToServer=True, stderrToServer=True)\n    ```\n1. create a debug branch and commit that loads the pydev-pycharm code\n    ```shell\n    # create debug branch\n    git checkout -b debug\n    ```\n    add in `ORStools/ORStoolsPlugin.py` before all imports and adjust path with your user and app location if PyCharm\n   was not installed via JetBrains toolbox\n    ```python\n    DEBUG = True\n    \n    if DEBUG:\n        import sys\n        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')\n        # add breakpoints like:\n        import pydevd_pycharm\n        pydevd_pycharm.settrace('localhost', port=53100, stdoutToServer=True, stderrToServer=True)\n    ```\n    avoid raising exceptions in `ORStools/gui/ORStoolsDialog.py` to not crash QGIS every time one is raised\n    ```python\n    # below other imports\n    from ..ORStoolsPlugin import DEBUG\n   \n    # surround raise with if block around run_gui_control()\n    if not DEBUG:\n        raise\n    ```\n   commit changes\n   ```shell\n    git add . \u0026\u0026 git commit -m \"Debug commit\"\n   ```\n**Important**: When using the remote debugger of PyCharm you have to **disable the First Aid plugin**, as it interferes\nwith the remote debugger.\n\n#### Workflow\n\nTo debug you now only need to `cherry-pick` the debug commit to the branch you are working on and place any changes\non top.\n```shell\n# this will cherry pick the last commit of the debug branch\ngit cherry-pick debug\n```\n\nMake sure the local `debug` branch is up to date with the `main` branch by rebasing regularly \n```shell\n# you will be on debug branch afterwards\ngit rebase main debug\n```\n\nBefore starting QGIS, you need to run the \"QGIS debug\" configuration you created.  \nAfterwards you can open QGIS and press the plugin reloader button (configured to reload ORStools).\nIt should break at the breakpoint introduced in the debug commit.\n\nIn general, you can now use normal breakpoints of the IDE with [left click in the gutter](https://www.jetbrains.com/help/pycharm/using-breakpoints.html#set-line-breakpoint)\n(or ctrl/cmd + F8).\n\nIf you are debugging the processing algorithms, which run in another thread, you will have to add another manual\nbreakpoint in e.g. `ORStools/proc/isochrones_layer_proc.py` by typing `br` (or\nwhatever you configured in your live template), pressing enter and **reload the plugin** in QGIS.\n\nIn short: Use IDE breakpoints if they work, if not use manual and IDE breakpoints afterwards.\n\nOnce you finalized your changes, remove the manual breakpoints again and drop the debug commit.\n\nYou can do this with one of the following\n- pressing `alt/option + 9` and right-click the debug commit on your branch and choose `Drop Commit`\n- `git stash \u0026\u0026 git reset --hard HEAD^ \u0026\u0026 git stash pop`\n- commit your changes and `git rebase -i HEAD^^`, prepend the debug commit with a `d` and save\n\n### Interface development\n\nFor designing the Dialog the Qt designer shipping with qgis is used. It has relevant classes such as\n[QgsMapLayerComboBox](https://qgis.org/pyqgis/3.2/gui/Map/QgsMapLayerComboBox.html) already imported properly.\n\n#### Mac\n- use `/Applications/QGIS-LTR.app/Contents/MacOS/bin/designer` instead of\n  `/Applications/QGIS-LTR.app/Contents/MacOS/Designer.app` (trying to get other Qt Designer\n  or Qt Creator installations to use the correct QGIS classes was unsuccessful)\n- if you want a shortcut in Applications do\n    ```shell\n    cd /Applications\n    ln -s QGIS-LTR.app/Contents/MacOS/bin/designer \"Qt Designer.app\"\n    ```\n\n#### Windows\n- should create you a shortcut to the Qt Designer with the installation\n\n#### Linux\n- [use `designer` command](https://github.com/GIScience/orstools-qgis-plugin/wiki/Developer-Information)\n\n#### Workflow\nProceed similar for other `.ui` files:\n\n1. open the `ORStools/gui/ORStoolsDialogUI.ui` file in the Designer and save your changes after editing.\n1. convert the `.ui` file to `.py` file by using `pyuic5` (which should also be accessible as command from your terminal\n   if PyCharm uses the [qgis env](#set-up-environment-and-python-interpreter) but using it as a module makes sure the\n   correct one is used in case you have other PyQt installations on your machine)\n   ```shell\n   # make sure you are in the gui folder\n   cd ORStools/gui\n   # convert to .py and set correct import\n   python -m PyQt5.uic.pyuic --import-from . -o ORStoolsDialogUI.py ORStoolsDialogUI.ui\n   ```\n1. in case you edit resources such as images you also need to convert the `resources.qrc` file\n    ```shell\n    # also within the gui folder\n    python -m PyQt5.pyrcc_main -o resources_rc.py resources.qrc\n    ```\n1. if you edited or added new widgets you will have to change or include them in `ORStools/gui/directions_gui.py`\n   as well\n\n### Translation\nTranslation uses the QT Linguist for translating GUI and source code strings. All translation-related content resides in `ORStools/i18n`.\nTranslation is controlled by `ORStools/gui/translate.pro`, stating all UI-forms and sourcefiles that include strings to be translated.\nTo add a translation, add `orstools_\u003cLANGUAGE_TAG\u003e.ts` to the list of translation in this file.\n\n#### Workflow\n1. Generate the `.ts`-files (Translation Source) from `translate.pro` via\n    ```shell\n   pylupdate5 -noobsolete -verbose translate.pro\n    ```\n   Note that this will drop obsolete strings, skip `-noobsolete` if you want to keep them.\n2. Inspect the changes this has on the existing `*.ts`-files. `pylupdate5` will remove translation comments and might restructure the translation.\n3. Translate the `*.ts`-files using QT Linguist via\n    ```shell\n   linguist orstools_\u003cLANGUAGE_TAG\u003e.ts\n    ```\n4. Compile the `*.ts`-file to a `*.qm` Qt Translation file via\n    ```shell\n    lrelease orstools_\u003cLANGUAGE_tag\u003e.ts\n    ```\n\n## License\n\nThis project is published under the GPLv3 license, see [LICENSE.md](https://github.com/GIScience/orstools-qgis-plugin/blob/main/LICENSE.md) for details.\n\nBy using this plugin, you also agree to the [terms and conditions](https://openrouteservice.org/terms-of-service/) of\nopenrouteservice.\n\n## Acknowledgements\n\nThis project was first started by [Nils Nolde](https://github.com/nilsnolde).\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGIScience%2Forstools-qgis-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGIScience%2Forstools-qgis-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGIScience%2Forstools-qgis-plugin/lists"}