This repository contains the code for training and evaluating RiverScope models.

For more information and for downloading the dataset, please refer to RiverScope

1. Create a conda environment: conda create -n riverscope python=3.9
2. Activate environment: conda activate riverscope
3. Install all packages in the env with: pip install -r requirements.txt

1. Download necessary checkpoints: link.
   • Place it in checkpoints such that it looks something like: riverscope-models/checkpoints/moco_v3/*.pth
2. Download the RiverScope data
3. Run training: python train_planet.py --dist-url 'tcp://127.0.0.1:8001' --dist-backend 'nccl' --multiprocessing-distributed --world-size 1 --rank 0 --data_dir <data path from prev step>
   • You can additionally specify the segment_model, backbone, head, resize_size (resize_size depends on which model to use).
   • To specify other parameters according to the table you can use the following arguments. We include options in the table below (each parameter corresponds to the first four columns in the table).
     • --segment_model
     • --backbone
     • --head
     • --resize_size
   • By default, training will use linear adapter, but this can be changed by specifying --adaptor to one of the following: linear, no_init, drop
   • The training will output 3 files: 1 log file, the latest checkpoint file, and the best checkpoint file (based on validation F1 score)
   • Results will be saved to results/planet-water by default (you can change it in --out parameter)
   • The file script_train_planet.sh can also be run as a batch job. This script also contains the optimal learning rates for each of the model configurations.

If you do not wish to train your own model, you can also use pre-trained model checkpoints below. The corresponding optimal threshold based on the validation set is also included.

There are two options:

1. Run: python water_eval_planet.py --ckpt_path <ckpt path>
   • This script will automatically find the best threshold using the PlanetScope validation set
   • Alternatively, you can specify a threshold, e.g., python water_eval_planet.py --ckpt_path <ckpt path> --thresh 0.5
   • This will save the metrics to the --out (default is results/planet-test-eval) with filename the same as the checkpoint name
2. If you want to save the images (so you can run the river width estimation), run: python water_eval_planet.py --ckpt_path <ckpt path> --to_save_imgs 1
   • This will save both the csv and the segmentation mask per image in the folder results/planet-test-eval/<ckpt_name>

1. Make sure you ran Option 2 in the water segmentation evaluation. If not, go back and run that first.
2. Run: python river_width_estimate.py --satellite_src "planet" --raster_src "results/planet-test-eval/<ckpt_name>" --is_gt 0 --raster_idx -1
   • This will save results to specified --out (by default, it's results/planet-test-eval-width). Inside the folder with the same name as the checkpoint
   • This will produce two sets of files per image: 1 csv file containing estimated width per node ("width_m" column is the estimated width in meters for the corresponding "node_id"), 1 png file to visualize estimated widths
3. Ground truth widths are available at RiverScope_dataset/PlanetScope/derived_gt_widths-test.csv for a given node_id and reach_id

Included below are the results of training and evaluating multiple models with the same configurations (5 runs per model). The number inside the parenthesis is the standard deviation.

The below show the median, mean, and standard deviation of the absolute errors in width estimation (in meters). These are the statistics across abount 400 nodes in the test set evaluation.

Sentinel-2 trained model:

1. Download necessary checkpoints (same as RiverScope): link
   • Place it in checkpoints such that it looks something like: riverscope-models/checkpoints/moco_v3/*.pth
2. Download the data from SatlasPretrain
3. Download data splits from here
   • Place it in the riverscope-models folder such that the path would be riverscope-models/data_splits_sentinel2/*.csv
4. Run training: python train_satlas_sentinel2.py --dist-url 'tcp://127.0.0.1:8001' --dist-backend 'nccl' --multiprocessing-distributed --world-size 1 --rank 0 --data_dir <data path from prev step>
   • specify data_dir as the path of downloaded data from Step 2
   • The training will output 3 files: 1 log file, the latest checkpoint file, and the best checkpoint file (based on validation F1 score)
5. You can then evaluate on the given Sentinel-2 files on the RiverScope dataset (on the test set)

If you found this useful, please consider citing our work:

@dataset{daroya_2025_15376394,
  author       = {Daroya, Rangel and
                  Rowley, Taylor and
                  Flores, Jonathan and
                  Friedmann, Elisa and
                  Bennitt, Fiona and
                  An, Heejin and
                  Simmons, Travis and
                  Hughes, Marissa Jean and
                  Kluetmeier, Camryn L and
                  Kica, Solomon and
                  Vélez, J. Daniel and
                  Esenther, Sarah E. and
                  Howard, Thomas E. and
                  Ye, Yanqi and
                  Turcotte, Audrey and
                  Gleason, Colin and
                  Maji, Subhransu},
  title        = {RiverScope: High-Resolution River Masking Dataset},
  month        = may,
  year         = 2025,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.15376394},
  url          = {https://doi.org/10.5281/zenodo.15376394},
}