Quickstart

This page takes you from nothing to your first analysis in about fifteen minutes. You will install Terraflux, open a ready-made model of a forest, run it, change one of its settings and watch the result change, run the same analysis on a real land cover map, save it, and run it again from the command line. You do not need to know GIS software: every step says where to click. When you are done, the tutorials take you further.

1. Install (3 minutes)#

Download the file for your system from the download page:

Everything Terraflux needs comes with it, including GDAL (the library that reads and writes map files): there is nothing else to install, neither Python nor R. Other formats (a portable zip for Windows, a tar.gz for Linux without root), the command line on macOS, and what to do when something does not start are in Installing Terraflux.

2. Open Terraflux (1 minute)#

Start Terraflux from the Start menu (Windows), Applications (macOS) or your desktop's menu (Linux). The window opens empty:

Enlarge

A model in Terraflux is a chain of nodes, boxes that each do one thing (read a map, reclassify it, analyse it), joined by connections that carry maps from one to the next. You will not build one from scratch today: you will start from a template, a model that is ready to run.

3. Open a template and run it (2 minutes)#

Enlarge

The template opens and runs by itself, in a fraction of a second. You now see this:

Enlarge

What happened? The three nodes in the Model pane ran from left to right:

1. landscape drew a map of 300 x 300 cells with three classes, farming, water and forest, by chance (a neutral landscape model), so that the template runs without any data;
2. forest reclassified it: forest became 2, everything else 1;
3. mspa ran GuidosToolbox's morphological spatial pattern analysis (MSPA; Soille & Vogt, 2009), which splits the forest into core (green: forest far enough from any edge), edge (black), perforations (blue: the edges of holes inside a forest), bridges (red: strips joining two cores), loops, branches and islets (small woods with no core at all).

The Viewer shows the result, with the number of cells of each class beside it: the template keeps it as a Plot, MSPA, a view of the result saved with the model (the Viewer's header says Plot: MSPA). Your own views are kept the same way, with Plots › Save as a new plot (see Plots and figures).

Click any node to see its own result in the Viewer: landscape shows the three classes, forest the two that MSPA reads. Checking every step like this is the best habit you can learn in Terraflux.

4. Change a setting (2 minutes)#

The core of a forest depends on how deep you think edge effects reach into it. MSPA calls this the edge width, in cells.

The model runs again at once (the box update after every edit in the Model pane's bar is ticked), and only the nodes after mspa run: the map and its reclassification come from Terraflux's cache. Drag the handle below to compare the two results:

edge_width = 1

edge_width = 3

That one number changed the core forest by 60%. Every setting of every operator has an explanation: hover over its name in the Node pane, or look it up in the operator reference.

5. Use your own map (4 minutes)#

The template drew its map by chance. Now run the same analysis on a real one. There is a template made for that:

Here is the result for the excerpt of CORINE Land Cover around Hanover, Germany, used in the getting-started tutorials (2000 x 2000 cells of 25 m). Its forests are three classes, 23, 24 and 25, so the rules are 23..25 -> 2 and * -> 1:

Enlarge

6. Save the model (1 minute)#

The model is a small text file. Open it in any text editor: every node, setting and note is there, in plain words. You can send it to a colleague with the map, and they will get the same result.

7. Run it from the command line (2 minutes)#

Terraflux is also a command, terraflux, that runs model files without opening the window: for long runs, servers, and running the same model on many maps. Open a terminal (on Windows: PowerShell from the Start menu) in the folder of the model and type:

$ terraflux --version
terraflux 0.80.0

$ terraflux check my-mspa.toml
my-mspa.toml: no errors

$ terraflux run my-mspa.toml
MSPA of your map: inputs read (0.0 s)
done in 0.3 s

check verifies every node, connection and file without running anything; run runs the model, and its raster.write node writes clc_mspa.tif next to the model. On macOS the command needs one more step, and on Windows a new terminal after the installation: see Installing Terraflux.

What next?#

You have used the three things every analysis in Terraflux is made of: a model, its settings and its results.

• A tour of Terraflux: every pane, key and menu of the window.
• Your first raster: what a raster is, and what the viewer tells you about it.
• Your first model: build a model by hand, and run it on other maps from the command line.
• MSPA: what each MSPA class means for species, and how to report it.
• All the tutorials, by subject: landscape metrics, connectivity, prioritization, species distributions, land change.

References#

• Soille, P., & Vogt, P. (2009). Morphological segmentation of binary patterns. Pattern Recognition Letters, 30(4), 456–459. https://doi.org/10.1016/j.patrec.2008.10.015