Simulating erosion in Blender part IV, addon features.

The addon is getting its shape and the the results are promessing:

(Click to enlarge)

The result on the right was obtained by repeating the (default) settings on the left about 20 times. It is clearly visisble that gullies begin to form, some steep slopes settle at a stable angle and become wider and the central basin starts to fill with silt.

Available options

After selecting the addon and again each time you click the repeat button, the selected mesh is eroded according the selected settings. Each step, all types of erosion (diffusion, avalanches and hydraulic erosion) are iterated a number of times subjected to some probability. By lowering the probabilities in the Probabilities tab certain modes of erosion can be suppressed. The statistics tab shows the actual number of iterations performed after each step.

The ballon help for the options in Thermal erosion and Hydraulic erosion tabs should be self explanatory but careful experimentation gives you a better feel for the possibilities than a lengthy explanation can provide. Don't set the number of iterations too high or each step will take ages; better repeat the the step a few times to gradually get the end result you are looking for. (On my machine, a 6-core, 2.4GHz machine, 10 iterations on a 256x256 mesh typically take 2 ssconds with or without numexpr installed. For larger meshes like 1024x1024 or above, numexpr might help, not only to speed things up but also to reduce memory usage.)

Code availability & feedback

The code is available as an installable .zip file on GitHub. You can install it as a Blender addon by choosing File->User preferences->Addons->Install from file and selecting erosion.zip. Don't forget to enable the addon. The package is dependent on Numpy and having Numexpr and Psutil installed is recomended (the first for serious speedup, the latter for accurate timings, see the opening page of the erosion repository for more info). After the installation the addon is available if you select an object in the 3D View and choose Object->Erode.

Note that if you have installed the erosion addon before, reinstalling it might not get rid of all files in the previous installation. You might try to restart Blender after reinstalling or, if the old version still seems to be there, get rid of the installation directory (typically Your Blender Install Dir\scripts\addons\erosion) and install from scratch.

Besides commenting on this article it might be interesting to check out this BlenderArtists thread.

Previous articles

Articles in this are labeled with the tag erosion. The list up til now consists of:

Simulating erosion in Blender part III, a proper addon

In previous articles (Part I and Part II) I documented my first steps in modeling thermal and hydraulic erosion of meshes in Blender, typically ones created with the ANT landscape generator.

Up til now the code was packaged as a stand alone module meant to be run from the command line. The workflow was cumbersome because exporting a mesh, running the simulation and importing the mesh again is slow, error prone and boring so I went on the convert the code to a proper Blender addon that simply works like any operator in Blender.

This first version only implements the thermal diffusion part but the other functionality (landslides and hydraulic erosion) will follow shortly.

Installation

The code is available on GitHub as a .zip file erosion.zip. Download the file, open Blender and go to File->User preferences->Addons->Install from file and select the .zip file. Don't forget to enable the addon after you've installed it.

The addon depends heavily on the Numpy package and you should have installed this in your Blender python libs for it to work. The Numexpr and Psutil packages are optional but if installed should be in your Blender python directory as well, not just in your system's python dir! How to install external packages is out of scope of this this article (I am strongly in favor of including at least Numpy as part of Blender's bundled python packages but I am afraid it will be difficult to convince the developers :-) but for Windows I have documented what I did on the start page of the GitHub repository.

Usage

After installing the addon and enabling it it is available as an Erode entry in the Object menu of the 3D View as shown in the image below.

The options are in the Toolshelf region as usual and the easiest way to work is to apply the 'repeat last' button from the History tab until you are satisfied with the result. Note that it just works for subdivided planes as created for example by ANT (a closed mesh like a Cube will not work) and the mesh should be in Object mode (currently this is not checked!)

Simulating erosion in Blender part II, fluvial erosion

This second version of my erode.py script adds erosion by water (fluvial erosion, a.k.a. hydraulic erosion). It's not perfect yet, but this first steps already produces some quite interesting results as you can see in the next image:

The image shows a small section of a 256x256 ANT generated landscape. The original is on the left, the eroded version is on the right.(The input file in .raw format and thr commandline parameters to produce the result from the image are provided on GitHub as well, together with the erode script itself.)

Additional options

The script accepts some additional options to control the fluvial erosion (the other options are documented in this previous article).

OptionDefaultDescription
Ka 1.0 Angular dependence
Kc 0.9 Sediment capacity
Kdep 0.0 Deposition rate
Kr 0.1 Rain amount
Ks 0.1 Sediment solubility

Algorithm

Each iteration at each point of the mesh we add an amount of rain to any existing water at that point. Each point also has an amount of suspended sediment and this amount divided by the amount of water gives us the sediment concentration.

By comparing the total heights of rock plus water we calculate how much water flows to and from a point on the mesh and (by multiplying by the sediment concentration) how much sediment is transported.

With these values we adjust the water height and ghe amount if suspended sediment at a given point and recalculate the new sediment concentration. We the compare this concentration to the effective sediment capacity and deposit some sediment if the concentration is higher and dissolve some rock if it is lower.

The effective sediment capacity of flowing water in this model is the product of the base sediment capacity Kc, the sine of the slope a of the heightmap and the speed of the moving water v. How much the slope influences the result is tweaked by the angular dependence Ka:
Kc * sin(Ka * a) * v

Note that faster moving water already has a larger capac2for suspended sediment but on steeper slopes sediment settles less well, effectively increasing the sediment capacith of the water even more.

Reference

Although the code presented here does not use the GPU but relies on Numpy and Numexpr for speed up, the following article proved to be an excellent reference:
Fast Hydraulic Erosion Simulation and Visualization on GPU by Mei et al.
There are however quite some differences, especially in the calculation of the flow field and the order in which the steps if the algorithm are executed.

Future developments

The results so far are promising but we are not there yet. The algorithms need to be fine tuned but I feel experimenting is easier with direct visual feedback so I think I will concentrate on turning this script into a Blender add-on first.

Simulating erosion in Blender part I: Thermal erosion

For some time I wanted to create a script that could erode meshes to complement landscape add-ons like ANT.

The first step is presented here: erode.py, a python script that simulates thermal erosion, i.e. the landslides on steep hill slopes and the gradual breaking up of large boulders by freeze/thaw processes (called diffusion in the code).

It's currently a stand alone script and not yet a proper Blender add-on but it does read and produce raw mesh data that can be exported/imported in Blender (by the raw input/output bundled add-on). It can read hand crafted heightmaps but it is also possible to create some artificial shapes. In its current form the script is intended to verify the algorithms used and get a feel for the simulation parameters.

Code availability and dependencies

The script is available on GitHub. It needs Python 3.2 or newer and depends heavily on NumPy. The code is even multithreaded when the NumExpr package is installed as well and this can make a huge difference for larger grids.

Examples

Some examples are shown below. The first mesh is a mesh generated with ANT. In the second one we applied a few iterations of just the landslide algorithm, which removes the steepest slopes and in the final example we also applied diffusion, softening the landscape as a whole.

Usage

The script isn't very user friendly at the moment but does have a fair number of options:


usage: erode.py [-h] [-I ITERATIONS] [-Kd KD] [-Kh KH] [-Kp KP] [-ri] [-ro]
[-i] [-t] [-infile INFILE] [-outfile OUTFILE] [-Gn GRIDSIZE]
[-Gp GRIDPEAK] [-Gs GRIDSHELF] [-Gm GRIDMESA] [-Gr GRIDRANDOM]
[-m THREADS] [-u] [-a] [-n]

Erode a terrain while assuming zero boundary conditions.

optional arguments:
-h, --help show this help message and exit

-I ITERATIONS the number of iterations
-Kd KD Diffusion constant
-Kh KH Maximum stable cliff height
-Kp KP Avalanche probability for unstable cliffs

-ri use Blender raw format for input
-ro use Blender raw format for output
-i use an inputfile (instead of just a synthesized grid)
-infile INFILE input filename
-outfile OUTFILE output filename
-t do not write anything to an output file

-Gn GRIDSIZE Gridsize (always square)
-Gp GRIDPEAK Add peak with given height
-Gs GRIDSHELF Add shelf with given height
-Gm GRIDMESA Add mesa with given height
-Gr GRIDRANDOM Add random values between 0 and given value

-m THREADS number of threads to use
-u perfom unittests
-a show some statistics of input and output meshes
-n use numexpr optimizations

Exporting and using an ANT generated mesh

Create a landscape mesh
For example with ANT but of course you can sculpt one as well or import a DEM
Export the mesh
File->Export->Raw. Make sure you enabled the add-on
Erode it
See example commandline below
Import the mesh
File->Import->Raw

Assuming you exported the grid to a file called untitled.raw, you could erode that file and put the result in a file called out.raw using the following command line:


python erode.py -Kd 0.001 -Kh 0.03 -i -infile untitled.raw -ri -outfile out.raw -ro -I 10

(Which model parameters (especially Kh) to use depends of course on the input mesh.)

Future developments/Roadmap

Erosion due to whethering isn't all that interesting in itself but serves to test the basic data structures in the script. Water erosion is the final goal so the roadmap for this script is short: fluvial erosion (creation of canyons and gullies and the deposition of sediment due to rain) will be next and when that works I'll rework the script to a proper addon. After that we'll see if there is demand for other features. I would like to add meandering but based on my current research I think that's quite some effort so I'll see if I can find the time.

Reference

This work was inspired by the work of Musgrave et al.. A more in depth an physically meaningful source worth reading is textbook by Pelletier.