# Portal Router -- QGIS Plugin

**Portal Router** is a QGIS plugin for computing routes through complex
land-use environments using polygon constraints.

The plugin separates the QGIS graphical interface from a heavy routing
computation engine executed in an external Python environment.

------------------------------------------------------------------------

## Features

-   Interactive QGIS interface with map-based point selection
-   External Python routing engine (Conda compatible)
-   Land-use aware routing
-   Corridor-based clipping for large datasets
-   Fast A\* routing using grid and k-nearest neighbor graph
-   GeoJSON route output automatically loaded into QGIS

------------------------------------------------------------------------

## Requirements

-   QGIS **3.28 or newer**
-   External Python **3.9 -- 3.12**
-   Conda / Miniconda recommended

Required Python packages:

    geopandas
    shapely
    scipy
    networkx
    pyproj
    fiona

------------------------------------------------------------------------

## Installation

### Linux

Copy the plugin folder to:

    ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/

Restart QGIS and enable the plugin.

Create the routing environment:

    conda create -n portal_router python=3.10
    conda activate portal_router
    conda install geopandas shapely scipy networkx pyproj fiona

------------------------------------------------------------------------

### Windows

Copy the plugin folder to:

    C:\Users\<USER>\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\

Restart QGIS.

Create the Conda environment:

    conda create -n portal_router python=3.10
    conda activate portal_router
    conda install geopandas shapely scipy networkx pyproj fiona

Select the `python.exe` from this environment inside the plugin
settings.

------------------------------------------------------------------------

### macOS

Copy the plugin folder to:

    ~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/

Restart QGIS.

Install dependencies using Conda (conda-forge recommended).

Apple Silicon users should install all packages from `conda-forge`.

------------------------------------------------------------------------

## Usage

1.  Load a polygon land-use layer.
2.  Ensure the layer contains a field named **`kind`** or **`Type`**.
3.  Open **Portal Router** from the QGIS toolbar.
4.  Select start and end points on the map.
5.  Configure routing parameters.
6.  Select the external Python interpreter and `routing_runner.py`.
7.  Run the routing process.

The resulting route will be added to QGIS as a **GeoJSON layer**.

------------------------------------------------------------------------

## Land‑Use Model

  Type      Behaviour
  --------- ----------------------------------------------
  public    walkable
  bridge    walkable
  private   interior blocked (shared boundaries allowed)
  river     completely blocked

------------------------------------------------------------------------

## Troubleshooting

**No PUBLIC polygons found**\
Check the attribute values in the land‑use layer.

**No path exists**\
Increase buffer size, spacing, or maximum routing distance.

**GDAL errors**\
Ensure the selected interpreter is the Conda environment Python, not the
QGIS internal Python.

------------------------------------------------------------------------

## License

MIT License

Copyright (c) 2026 Clemence Uwitonze
