diff --git a/CHANGELOG.md b/CHANGELOG.md index 2a77c2cec5..42c90de4fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,7 @@ Releasing is documented in RELEASE.md ## [unreleased] ### Added +- documentation on how to create country border files for avoid borders feature ([#2133](https://github.com/GIScience/openrouteservice/issues/2133) ### Changed diff --git a/docs/public/grid_africa_clip.png b/docs/public/grid_africa_clip.png new file mode 100644 index 0000000000..b6aecfcac7 Binary files /dev/null and b/docs/public/grid_africa_clip.png differ diff --git a/docs/public/grid_africa_grid.png b/docs/public/grid_africa_grid.png new file mode 100644 index 0000000000..76ec2443fb Binary files /dev/null and b/docs/public/grid_africa_grid.png differ diff --git a/docs/public/grid_africa_hierarchy.png b/docs/public/grid_africa_hierarchy.png new file mode 100644 index 0000000000..00562a35f6 Binary files /dev/null and b/docs/public/grid_africa_hierarchy.png differ diff --git a/docs/public/grid_africa_join.png b/docs/public/grid_africa_join.png new file mode 100644 index 0000000000..fc5e2ce22a Binary files /dev/null and b/docs/public/grid_africa_join.png differ diff --git a/docs/public/grid_africa_manual_merge.png b/docs/public/grid_africa_manual_merge.png new file mode 100644 index 0000000000..a0d24393f5 Binary files /dev/null and b/docs/public/grid_africa_manual_merge.png differ diff --git a/docs/run-instance/data.md b/docs/run-instance/data.md index 19dcb1f7a8..4030beaefc 100644 --- a/docs/run-instance/data.md +++ b/docs/run-instance/data.md @@ -29,6 +29,18 @@ Data relating to the avoid borders features is derived from administrative bound Configuration parameters: [ `ors.engine.profiles..ext_storages.Borders`](configuration/engine/profiles/build.md#borders) +To ensure `avoid_borders` functions correctly, the following are required: + +- **CSV headers & column order:** The loader skips the first row (header). Columns are positional (header text is not used to map fields). + - `ids_iso.csv` (3 columns): `id`, `name`, `name:en`. + - `open_borders.csv` (2 columns): `name:en` (country A), `name:en` (country B). +- Formatting & encoding: Comma-separated, double-quote fields when needed (e.g. names with commas). Use UTF-8 and trim whitespace; names are compared by exact string equality (case-sensitive). +- Rebuild: Any change to border files requires a full graph rebuild. + +- **Performance considerations:** + Large or highly detailed polygons can make graph creation slow or stall. + For extensive regions, borders should be simplified or subdivided into smaller polygons. See [this tutorial](example-setups/countries_grid.md) for guidance. + ### GTFS The public transport profile integrates [GTFS](https://developers.google.com/transit/gtfs) data for the public transit part. GTFS feeds can be obtained e.g. from sites like https://gtfs.de/ (for Germany), or from local public transport operators. @@ -62,6 +74,3 @@ which can be configured with the property [`ors.engine.elevation.cache_path`](co Log output is written to auto-rotated log files. See chapter [logging](configuration/logging.md) for details on configuring the location of log files. - - - diff --git a/docs/run-instance/example-setups/countries_grid.md b/docs/run-instance/example-setups/countries_grid.md new file mode 100644 index 0000000000..2088f2c74d --- /dev/null +++ b/docs/run-instance/example-setups/countries_grid.md @@ -0,0 +1,107 @@ +# Creating a Country-Based Grid for openrouteservice + +This tutorial explains how to prepare a country-based grid dataset for openrouteservice. + +## Step 1: Prepare the Country Data + +1. Load your country dataset into **QGIS**. +2. If your data consists of multiple **GeoJSON** files, merge them into a single vector layer: + + * Go to **Vector → Data Management Tools → Merge Vector Layers**. + * Under *Input Layers*, select all GeoJSON files. + +## Step 2: Create Grids + +You will create two rectangular grids covering the same extent as your country layer. + +1. Go to **Vector → Research Tools → Create Grid**. +2. For the first grid: + + * Type: *Rectangle (Polygon)* + * Grid size: **10 degrees** + * Extent: *Same as the country layer* + * Save as: *hierarchy grid* +3. For the second grid: + + * Type: *Rectangle (Polygon)* + * Grid size: **1 degree** + * Extent: *Same as the country layer* + * Save as: *cell grid* + * +![grid_africa_grid](../../public/grid_africa_grid.png) + +![grid_africa_hierarchy](../../public/grid_africa_hierarchy.png) + +## Step 3: Assign Hierarchy IDs + +Join the two grids so that each 1° cell knows which 10° cell it belongs to. + +1. Go to **Vector → Data Management Tools → Join Attributes by Location**. +2. Set the parameters: + + * **Base layer:** cell grid + * **Join layer:** hierarchy grid + * **Geometric predicate:** *intersect* +3. Run the tool. +4. In the output, rename the joined field `id_2` to `hierarchy`: + + * Right-click the layer → *Properties → Fields* → click the *edit pencil* and rename. + +## Step 4: Clip to Country Borders + +1. Go to **Vector → Geoprocessing Tools → Clip**. +2. Set the parameters: + + * **Input layer:** grid created in the previous step + * **Overlay layer:** country layer +3. Run the tool. + + * The output will be a grid clipped by country borders (some cells remain square, others follow borders). + +![grid_africa_clip](../../public/grid_africa_clip.png) + +## Step 5: Combine Country Names and Grid Attributes + +1. Go to **Vector → Geoprocessing Tools → Union**. +2. Set the parameters: + + * **Input layer:** the clipped grid + * **Overlay layer:** the country layer +3. Run the union. + + * This step combines country names with hierarchy and cell IDs. + * It may take some time depending on your dataset size. + +![grid_africa_join.png](../../public/grid_africa_join.png) + +The attribute table should now look like this: + +| id | hierarchy | NAME | +| -- |-----------| ------- | +| 1 | 1 | Morocco | +| 2 | 1 | Morocco | +| 3 | 2 | Algeria | +| 4 | 2 | Algeria | +| 5 | 3 | Tunisia | +| 6 | 3 | Tunisia | +| 7 | 4 | Libya | +| 8 | 4 | Libya | +| 9 | 5 | Egypt | +| 10 | 5 | Egypt | + + +## Step 6: Export the Final Dataset + +Export the final union layer as a **GeoJSON** file. +When exporting, ensure that at least the following fields are included: + +* **name** – country name +* **hierarchy** – hierarchy ID + +This GeoJSON file can now be used within openrouteservice or related workflows. + +## Step 7: Manually merge inner country cells (optional) + +By selecting and merging inner country cells, you can reduce the number of features in the final GeoJSON file. + +![grid_africa_manual_merge.png](../../public/grid_africa_manual_merge.png)