sdl60660/river-runner

Uses USGS/MERIT Basin data to visualize the path of a rain droplet to its endpoint.

River Runner

This project visualizes the path of a rain droplet from any point in the world to its end point (usually an ocean or an inland water features). It will find the closest river/stream flowline coordinate to a click/search and then animate along that flowline's downstream path. The data used in this project comes from the River Runner API, which is based on several open source projects and datasets. Similar data, initially used for the project, came from the USGS's NHDPlus data and their NLDI API

I've used mapbox to animate the downstream path, but needed to make all sorts of adjustments for elevation and bearing changes to prevent jerkiness/nausea (just moving from point to point feels a little like flying through turbulence while shaking your head side-to-side).

I've hosted a dataset with NHDPlus Value Added Attributes on Firebase, which allows me to group flowlines into their parent features and determine distances quickly.

Note: The newly-released, global version of this project is in beta. We currently have relatively poor coverage of river names outside of the United States, which we are hoping to fill out, as well as some UX edge-cases and bugs that we hope to resolve.

Examples

Here are a couple of examples of what it looks like in action.

This is a section of the path from eastern Turkey to the Persian Gulf:

Here's part of the path from Southwest Arizona down to the Mexican border:

You can look at a heatmap of previous searches here or find a list of some of our favorite paths here

Running this on your own

If you'd like to run this locally and play around with it, just run the following commands in your terminal (assuming you have npm installed):

1. git clone https://github.com/sdl60660/river-runner.git
2. cd river-runner
3. npm install
4. npm run dev (then follow the link to the local server, probably http://localhost:5000).
5. If you're running this on your own or forking into a new app, please replace the Mapbox Access Token strings in src/access_tokens.js with your own. You can generate a couple of tokens (for free), by creating a Mapbox account and visiting this page. You'll need to generate two separate tokens to replace the ones in the existing file, but it does not matter which serves as the primary token and which serves as the secondary token.

Supporters

Thank you to Mapbox for sponsoring this project!

Updates

• January 2022: The global version of this tool is now released and in beta! While some lingering issues are resolved and it remains in beta, it can be found on this branch, while the original, US-only version is preserved here in Github, and at its original URL: https://river-runner.samlearner.com/. This is to avoid any breaking changes to existing share links/paths due to any discrepancies and because minor US issues persist on the global version, mainly when paths involve dams, canals, or conduits.

If you'd like to be notified about major updates to the tool, you can sign up for an email list here.

river-runner's Issues

Colorado River Flow

I live at the headwaters of the Colorado River. Around 70% of the water in our watershed is pumped through tunnels under the Continental Divide to the east side of the divide. This creates a misconception on the part of people on the Front Range that makes them ignorant about where their water comes from. Anyway this can be fixed to show that the majority of those raindrops in our watershed do not go west.

Spins forever on Ketchum, Idaho

If I click on the mountains in central Idaho, I sometimes get "can't find a flowpath" and sometimes it just spins forever (>30 minutes).

The Himalayas have spikey geometry

Transboundary rivers hang app

I tried a trans-boundary basin (Red River ) that flows north into Canada and it hung the app.

Data issue with San Marcos river

First of all, a fantastic project.

Not sure if this is the right place to report "data" issues, but when selecting San Marcos, TX, it incorrectly reports the San Marcos River (47 km) flowing into Brushy Creek (78 km).

Brushy Creek is a tributary of the San Marcos, joining the San Marcos river just upstream of Stairtown, TX, as you can see on this Topo Map

Hitch between flight and run start for routes that start in elevated areas

Has to do with zoom level differences before/after 3d terrain has loaded

Incorporate new Mapbox GL 2.3.0 features to optimize elevation queries and add subtle fog for long distances?

Should be able to optimize the way that I'm querying for elevation samples along route and at least reduce client/API load. Fog effect may be helpful, as well: https://www.mapbox.com/blog/mapbox-gl-js-v2-3-0-distance-fog-elevation-querying-and-terrain-performance-improvements

Western Canadian River Names are Incorrect

(see the attachment) For example, in River Runner, the names of various branches of the the South Saskatchewan River and the Saskatchewan River (when the raindrop falls in the headwaters of the Old Man River at 50.11402,-114.70464) are mostly called "St Mary's River" (See the first column.) This is incorrect. The third column shows the correct names at each major confluence. The second column shows the coordinates of each major confluence. The St. Mary's River is a minor tributary entering the Old Man near Lethbridge, Alberta.

Another error is that the Red River of the North ends where it flows into Lake Winnipeg but River Runner has it going through Lake Winnipeg and on to Hudson Bay through what is known as the Nelson River.

What can be done to fix this behaviour? There are many other examples of this kind dependin on where the raindrop fall. River Runner is a great app but it won't be truly great until these bugs are squashed. Is there anything I can do to help?

Tributary Names South Saskatchewan River Basin and Nelson River basin.pdf

Add attribution for map data

It looks like the poi map data (not the imagery) is sourced from OSM, but you haven't provided attribution as required by OSM's license.

I viewed the page on a mobile browser.

For more information, please see https://www.openstreetmap.org/copyright

River Aire UK route

My drop, from Leeds, jumps out of the river Aire, below Leeds in the UK, and trundles overland for a while between Allerton Bywater and Knottingley.

Hebrew is backwards

Might not be an issue on your end at all, but I noticed Israel appears like this:
לארשי
But it should be:
׳שראל

All Hebrew is reading left to right instead of right to left. I cannot confirm the issue affects other RTL languages, but I would assume so.

Bug on locator map highlighting

Sections are staying highlighted on the locator minimap after the runner passes them. Seems to be happening in a way it wasn't before the latest changes.

Hitch on transition between artificial camera coordinates and route coordinates

Ends and resets abruptly; forced re-navigation

Before I can process what I'm seeing, the run ends at a coastline and resets to show the entire continental US. It's jarring.

To watch the same run again, or to do another run in an area near the first, the user is forced to restart zooming and searching.

Ideally, IMO, when the run is paused, the user should be able to interact with the map; continuing the run moves the view back to following the run. At the end, the run should just stop and remain viewing the end. Maybe an interface element to "run again" which returns the user to the start.

"Mono Lake, CA" causes an error during the initial calculations. Probably has to do with starting right on a stopping feature. Needs to either resolve or tell the user there's been an error and reset.

Endorheic Basins (Example: Lake Atitlán, Guatemala)

Lake Atitlán is a very deep, very picturesque lake in the Guatemalan Highlands (think Lake Como, but ringed by several immense volcanoes), the result of a caldera explosion many years ago. It does not drain into the Pacific Ocean (at least not directly).

There are many such basins around the world (https://en.wikipedia.org/wiki/Endorheic_basin).

The application should reflect these flows, if possible, so that a rain drop placed in the Atitlan basin, flows to the lake, and stops there. It would be an incredible update to show the many people living around these lakes or swamps that their water doesn't actually go all that far. Unfortunately, agricultural runoff in the Atitlan basin doesn't "disappear" (does it ever though?). It just flows a few kilometers and builds up in the lake, threatening this unique ecosystem! The same applies to other fragile ecosystems, including desert basins, swamps, etc.

Aside from that, excellent application for teaching!

San Joaquin river may be ending at incorrect stop feature (Briones Reservoir)

This may be due to having too few stop features in the dataset, or it's being too liberal about assigning a feature vs. just calling it an "unnamed inland feature". Should be able to add another ~50,000 stopping features if I simplify them.

Please make the 3-d visualization optional

I'd love a way to just have the route shown without then needing to do the whole 3-d "move along the route" thing.

Difficult to visually track blue path

It's sometimes hard to see the blue line while the rest of the screen is moving, and it'd be better if it had thicker line weight.

Still getting issues with very short flowpaths

Very rare and only seems to happen with basically non-existent flowpaths, but need to either add a fix or add error handling to keep it from hanging in search step (see "Pope Valley, CA")