SWORD‑le Pipeline

Tools for the generation of the SWORD Localy Expertised database for SWOT

sword-le is a geospatial processing pipeline designed to industrialize the selection, correction, and merging reaches coming from:

1. SWORD : SWORD Explorer(https://www.swordexplorer.com/)

2. REPLACEMENT dataset : BD TOPAGE https://www.data.gouv.fr/datasets/bd-topage-r => A manual pre‑selection step is required to choose the relevant TOPAGE reaches to use for each study area. These selected reaches will be used to correct or replace corresponding SWORD reaches inside and/or outside the mask.

3. POLYGON mask : defining the study area is applied to filter and process the reaches. => The polygon mask must be carefully defined. It corresponds to a vector layer that can be easily created in QGIS. This layer should cover the reaches to be corrected and be designed so that the upstream and downstream SWORD reaches intersect at a point with the corresponding replacement reaches. This ensures proper connectivity and continuity between original and replacement reaches, in accordance with the logic implemented in the swordle.py

Installing / Getting started

The pipeline runs in a dedicated Conda environment defined

• Python 3.10
• Main libraries: geopandas, shapely, fiona, pyproj, geopy, matplotlib, tqdm

git clone https://github.com/csgroup-oss/sword-le
cd sword_le/
conda create -n sword_le_env 
conda activate sword_le_env 
pip install . #need pyproject.toml

Initial Configuration

• All input shapefiles must be in EPSG:4326
• Valid geometries (LineString / MultiLineString)

Developing

git clone https://github.com/csgroup-oss/sword-le
cd sword_le/

Features

The pipeline is executed from the command line.

python swordle_prod_upgrade.py \
    --mask /path/to/mask.shp \
    --sword /path/to/sword_reaches.shp \
    --logic 2 \
    --replacement /path/to/topage_extraction.shp \
    --default-attributes /path/to/default_attributes.json \
    --results /path/to/output_folder/

Configuration

Here you should write what are all of the configurations a user can enter when using the project.

• --mask : Polygon mask defining the study area
• --sword : Input SWORD reaches
• --logic : Choice of the logic : find_upstream_downstream_reaches_using_mask
• --replacement : reaches used to correct or replace SWORD segments
• --default-attributes : JSON file with default attributes depending on the version of SWORD
• --results : Output directory

About the --logic parameter

The pipeline includes two different algorithms for identifying the upstream and downstream SWORD reaches at the mask boundary:

• Logic 1 (--logic 1) Uses the function: find_upstream_downstream_reaches_using_mask_logic1

• Logic 2 (--logic 2, default) Uses the function: find_upstream_downstream_reaches_using_mask_logic2

The parameter allows to explicitly select which logic to apply depending on the study area.

Outputs

The pipeline automatically generates multiple shapefiles for diagnostics and final delivery.

Diagnostic Shapefiles

• test_rep_masked_out.shp
• test_rep_masked_in.shp
• test_src_masked_out.shp
• test_src_up_reach.shp
• test_src_dw_reach.shp
• test_rep_keeped.shp
• test_src_keeped.shp
• test_points.shp

These layers help analyze reach selection, masking effects, and correction logic.

Corrected Reaches

• test_new_up_reach.shp
• test_new_dw_reach.shp

Corrected upstream and downstream reaches generated by the pipeline.

Final Output

• test_complete.shp

Final deliverable combining:

• Corrected upstream and downstream reaches
• Internal valid reaches
• All remaining valid SWORD reaches

Testing

Unit tests / Integration Test

Unit tests and integration tests rely on external datasets hosted on Zenodo. Please download the required data from the following location before running them: https://zenodo.org/records/20398326

Alternatively, with the makefile located in the tests/data directory, the data is automatically downloaded and unzipped :

cd test/data/
make

The data are sourced from the following databases:

• SWOT River Database (SWORD) : https://www.swordexplorer.com/ License : Creative Commons 4.0 International License (CC by)

• Topage database : https://www.data.gouv.fr/datasets/bd-topage-r License : Licence Ouverte / Open Licence version 2.0

To run the unit and integration tests, we move into the sword-le/ directory and execute the following command:

pytest -vv -s tests/

Links

• Repository: https://github.com/csgroup-oss/sword-le
• Issue tracker: https://github.com/csgroup-oss/sword-le/issues

Copyright & Licensing

Copyright 2026, CS GROUP

This project is licensed under the Apache License 2.0. The full text of the license is available in the LICENSE.txt file.