River Builder is free, open-source design software available to you via Github at https://github.com/RiverBuilder/RiverBuilder.
Feb 1, 2021: River Builder 1.2 is now released on Github. An updated user's manual explaining how to use all the new features from versions 1.1 and 1.2 is still being finalized.
Dec 1, 2020: River Builder 1.1 is now released on Github.
Jan 1, 2020: River Builder 1.0 for Python3 is now released as free, open-source softeware on Github. A full user's manual is provided.
July 1, 2019: All development of River Builder has now moved from R to Python3. The R version will remain available from CRAN but will not be supported.
Jan 1, 2018: River Builder 0.1 for R is publicly available for free at https://cran.r-project.org/package=RiverBuilder
Welcome to the website devoted to River Builder- the world's first open-source procedural software for creating river terrains exactly to specification, including comprehensive support for organized fluvial patterns mindful of geomorphic covariance structures. The software includes valley scale, reach scale, and subreach scale capabilities.
Design Software For River Scientists and Engineers
Designing river projects has long been the purview of artist-engineers highly trained in the craft of drawing, such as with computer-aided design (CAD) software. Steep learning curves have kept many people who know rivers best from directly engaging in river design. River Builder not only enables more advanced natural designs, but it puts the key tool in the hands of those most qualified to take advantage of it, with a minimal learning curve to use the software. The real challenge lies in knowing what to design; software should facilitate that, not get in the way of it.
Why Design Rivers and River Valleys?
Whether you think humans should tinker with nature or not, the fact is that people are actively re-aligning rivers every day, while also directly and indirectly causing vastly more rivers and their valleys to degrade. Here is a list of a few reasons why society might want to design rivers and even wholesale river valleys.
- Valley filled with mine-waste,
- Urban pipe daylighting,
- Channel re-location,
- Flood blow-out,
- Mountain meadow pond-and-plug,
- Research & Experimentation
- Video game landscapes
- Movie graphics
Designing alluvial river channels that behave naturally is a central challenge facing river scientists and engineers as well as animators and video game developers in the 21st century. Though organized and responsive to driving forces, rivers exhibit complex patterns and processes from the scale of an individual grain of sediment to that of an entire continent. Despite roughly a century of research it remains highly uncertain as to which patterns and processes are most important to design explicitly versus which ones should be allowed to emerge on their own after construction. Nevertheless, our understanding of the fluvial patterns and processes as well as our ability to quantify them is increasing rapidly. We can now design much more dynamic rivers than ever before.
A synthetic river designed only according to reach-scale metrics of central tendency is called a “Vanilla River”. Although vanilla can be a delicious flavor, it is colloquially considered bland or generic, generally lacking in desirably variations and complexity. This is apropos, because in fact few river processes are driven by the central tendency of reach-scale river metrics. Instead, they are driven by local to reach scale patterns of topographic variability. Thus, few natural rivers look like synthetic Vanilla Rivers and we must turn to a more sophisticated understanding of topographic complexity to design rivers that reflect their natural patterning.
This software is capable of designing Vanilla Rivers, if that is desired. For use in real rivers, we do not recommend stopping there
Building Variability in Digital Rivers
Brown and Pasternack (2014) coined the term "Geomorphic Covariance Structure" (GCS) to mean the bivariate pattern of any two river variables along a pathway. It is not the statistical covariance, which is a single number, but instead a new concept involving the complete bivariate spatial series from which a statistical covariance could be computed if desired. The theory of Geomorphic Covariance Structures (GCSs) is not only useful for assessing the layers of topographic patterning of real rivers (Brown and Pasternack, 2014, 2017) but also for the design of synthetic rivers with more natural landforms that drive the real diversity of physical processes (Brown et al., 2014, 2015).
This software is capable of implementing GCSs to produce rivers with organized, coherent patterns of variability. This is where the real power of this software lies. However, the software does not tell you what GCSs you need to produce different outcomes. You must have in mind what you want and an understanding of what GCS metrics are required to achieve that vision.
Inner Channel Special Features
River Builder allows users to place a variety of objects in the "inner channel" zone of a design. All objects can be given positive or negative values to yield objects protruding up from the bed or making troughs and holes in the bed.
A “bed element” is defined herein as a roughly rounded square object, like a boulder or scour pool, so it can be protruding above the riverbed or making a hole down below it. Bed elements are organized into “bed element groups” based on a size class. A user may specify an unlimited number of bed element groups, each with its own characteristic size. The image below shows a simple example of bed elements placed into the inner channel of a straight river design with gently undulating banks.
Natural riverbeds are rough, by which is meant that the surface is textured and the topography is not a perfectly uniform elevation. River Builder 1.2 allows users to add bed roughness as a comprehensive coverage to the inner channel. Bed Roughness is a “random” Perlin noise added to the elevation of the inner channel bed. The image below uses the same channel design as for bed elements, but replaces the boulders with generalized bed roughness.
River Builder can make stepped channels, but to greatly simplify the design process there is now an additional tool called “FunctionGenerator.py”. No coding skill is required to use it. The details of how to implement it are covered in the user's manual. You can make individual waterfalls or stepped channels with a variety of riser and tread geometries. Two examples are shown below. A simple step-plane bed channel onthe left and a single high waterfalls dropping into a narrow canyon on the right.
The next image below shows an example with steps, multi-sized boulder groups, and bed roughness all in one design.
In River Builder 1.2, a “dam” is nothing more than a nearly vertical wall blocking the inner channel bed. In river management, there are a wide variety of such simple barriers, such as sills, weirs, check dams, etc. River Builder is certainly not a tool for designing sophisticated major dams, but this new feature adds more capabilities to the tool and was easy to add. Dams span the inner channel with a fixed crest elevation across the ineer channel.
River Builder Workflow
In contrast to CAD, River Builder has been designed to be as simple as possible to use to make it accessible for scientists and engineers. There is no artistry, approximated drawing, or endless menus and icons to choose from that take years to master. If you want a specific value for something, you get it, because design is "procedural", not aided artistry. However, River Buidler cannot tell you what to design, so you stil have to know what you want to create based on your knowledge and experience with rivers. here is the workflow one goes through in designing a river with River Builder. Details are in the user's manual.
River Builder Example Gallery
The images below show a variety of simple channels and river valleys made with just a few minutes of effort in River Builder. The hard part is knowing what you want to create, but once you've got that then River Builder makes it exactly as you specify.
Simple Meandering- a small step up from Vanilla
This first example shows a simple meandering channel with undulating riffle-pool relief and natural out-of-phase width variation locked to that. Also, the cross-section is asymmetric and adjusts down-river according to channel curvature. The floodplain is flat to keep the focus on the channel design. Nothing special here, but easily done.
Piecewise Varying Centerline in Deeply Carved Valley
Natural and human-impacted rivers commonly change their centerline alignment and other variables at both deterministic and arbitrary locations down a valley. In this example we created a deeply carved valley like you might find in the arid western US, and then nested within that a meandering channel with piecewise varying alignment. From the left, it changes from a gooseneck meander to a Perlin meander. We also allowed for noise perturbations along the bank in the rendering to make a more natural bank look. Meanwhiloe, the valley walls have asymmetric undulations between left and right sides.
Nested GCSs at 2 Scales
This next example is from a journal article we published. Looking at the blue area of each image, there is a baseflow channel with linked bed elevation and width oscillations. That is then nested inside a bankfull channel that also has linked bed and width oscilaltions, but not necessary the same linkage as for the baseflow channel. These examples show that a simple design tool like a basic GCS can yield remarkably complex and intellectually challenghing rivers; and this is only considering one GCS at two spatial scales. River Builder can do that for several variables simultaneously. River Builder for Python has no limitation on the number of nested scales a designer may use.
Perlin Channel Alignment
This could be a lowland partially confined 1st to 3rd order stream or a thread in a multi-threaded high elevation mountian meadow.
Harmonic Additive Synthesis
This is the S10 case that shows an example of harmonic additive synthesis of the centerline alignment with an asymmetric cross-section that is deepest wherevere the local centerline curvature peaks. The meandering river is also nested within a curving river valley.
S5 Example Tweaked
This example takes the S5 parameters from our first article and tweaks them for visual presentation. I used ArcScene to make the final appearance
Partially Confined Canyon
This example places a channel with multiple layers of variation into a partially confined canyon whose banks and hillsides also have multiple layers of variation.
Gooseneck Channel Meandering & Valley Sinuosity
Most software can only create curves with one lateral y-coordinate for each longitudinal x-coordinate. River Builder can create gooseneck meandering with a wide range of parameterization options. In this example, not only is the channel meandering, but that is itself nested within a sinuous valley.
To learn more about the scientific underpinnings of River Builder, refer to the literature cited below.
- Brown, R. A. and Pasternack, G. B. 2019. How to build a digital river. Earth-Science Reviews 194: 283-305. DOI: 10.1016/j.earscirev.2019.04.028.
- Brown, R. A., Pasternack, G. B., Wallender, W. W. 2014. Synthetic river valleys: creating prescribed topography for form-process inquiry and river rehabilitation design. Geomorphology 214: 40-55. 10.1016/j.geomorph.2014.02.025.
- Pasternack, G. B., Zhang, M. 2021. River Builder User’s Manual For Version 1.2.0. University of California, Davis, CA.
Designing with GCS's
- Brown, R. A., Pasternack, G. B., Lin, T. 2015. The topographic design of river channels for form-process linkages for river restoration. Environmental Management, 57 (4): 929-942. doi: 10.1007/s00267-015-0648-0.
- Brown, R. A., Pasternack, G. B. 2017. Bed and width oscillations form coherent patterns in a partially confined, regulated gravel–cobble-bedded river adjusting to anthropogenic disturbances, Earth Surface Dynamics, 5, 1-20, doi:10.5194/esurf-5-1-2017.
- Pasternack, G. B., Baig, D., Webber, M., Brown, R. 2018. Hierarchically nested river landform sequences. Part 1: Theory. Earth Surface Processes and Landforms. DOI: 10.1002/esp.4411.
- Pasternack, G. B., Baig, D., Webber, M., Brown, R. 2018. Hierarchically nested river landform sequences. Part 2: Bankfull channel morphodynamics governed by valley nesting structure. Earth Surface Processes and Landforms. DOI: 10.1002/esp.4410.
Current development is focusing on building complementary tools that aid with designing river corridors from reference sites by reverse engineering their topographic features and turning that informaiton into River Builder input. We are also working on creating a set of templates for a variety of river types for users to have as a starting point for designing their projects.