grd2stream – a QGIS Plugin

Generate streamlines from gridded datasets w/ precision & ease

Get Started

The grd2stream QGIS plugin allows users to comfortably generate multiple flowlines from rasters by selecting seed points. This plugin leverages the power of GMT6 (Generic Mapping Tools) to ensure compatibility with all GDAL file formats!

The core functionality is based on the grd2stream command-line utility, which utilizes Runge-Kutta integration methods.

Table of Contents

Overview

Key features and capabilities

Installation

Setup guide and requirements

Platform Support

Compatibility information

Architecture

Technical design details

Usage

How to use the plugin

Presets

Working with configuration presets

Technical Details

Integration methods and file formats

Troubleshooting

Common issues and solutions

Overview

Isolated Environment

Isolated GMT6 environment that does not interfere with existing installations

Flowline Calculation

Generate flowlines from any GDAL-compatible raster datasets containing X and Y component data

Interactive Selection

Interactive seed point selection via map clicks or manual coordinate entry

Customizable Parameters

Configurable integration parameters (step size, max steps, etc.)

Preset Management

Save and load parameter presets for repeated use

Installation & Requirements

QGIS Plugin Installation

Open QGIS

Launch your QGIS application

Access Plugin Manager

Go to Plugins → Manage and Install Plugins

Search for grd2stream

Type "grd2stream" in the search box

Install Plugin

Click "Install Plugin" and wait for completion

Dependencies

The plugin requires:

Note: On Linux and macOS, the plugin can automatically install these dependencies in an isolated Miniconda environment.

Platform Support

Current Status

Linux

Fully Supported

Automatic installation of dependencies via Miniconda

macOS

Fully Supported

Automatic installation of dependencies via Miniconda

Windows

In Development

Currently only planning/parameter configuration available. Command execution not yet supported.

Windows Limitations

On Windows, the plugin currently cannot execute the grd2stream command. However, you can still:

Full Windows support is being developed and will be available in a future update.

Technical Architecture

Component Overview

The plugin consists of several key components:

Conda Environment

Handles installation and management of GMT6 and grd2stream

QGIS Plugin Interface

The UI components that integrate with QGIS

Flowline Module

Core functionality for generating flowlines

Preset Manager

Handles saving and loading of parameter configurations

Dependency Management

On Linux and macOS, the plugin:

Install Miniconda

Installs Miniconda3 to ~/miniconda3 (if not already installed)

Create Environment

Creates a "GMT6" Conda environment with GMT6 and required dependencies

Install grd2stream

Installs the grd2stream utility in the Conda environment

This approach ensures that:

Using the Plugin

Basic Workflow

Launch Plugin

Click the grd2stream icon in the QGIS toolbar

Setup Dependencies

First-time users on Linux/macOS may be prompted to install dependencies

Select Input Rasters

Choose X-component and Y-component raster dataset

Configure Parameters

Set parameters or load a preset configuration

Select Seed Point

Click on the map or enter coordinates manually

Generate Flowline

The plugin calculates and adds the flowline as a vector layer

Parameter Configuration

Required Parameters

Parameter Description
Raster 1 & Raster 2 The X and Y component rasters
Seed Point The starting location for the flowline

Optional Parameters

Parameter Description
Backward Steps Enable to trace the flowline in both upstream and downstream directions
Step Size Distance increment for integration steps (default is min(x_inc, y_inc) / 5)
Max Integration Time Maximum time for the integration process
Max Steps Maximum number of steps to calculate (default is 10,000)
Output Format Choose what data columns to include in the output layer

Output Formats

Default (no option)

x y dist

  • X and Y coordinates
  • Distance along the flowline

Extended (-l)

x y dist v_x v_y

  • All default columns
  • X and Y vector components at each point

Full (-t)

x y dist v_x v_y time

  • All extended columns
  • Integration time for each point

Working with Presets

Saving Presets

  1. Configure parameters in the main dialog
  2. Click "Save as Preset"
  3. Enter a name for your preset
  4. Confirm to save

Loading Presets

  1. Click "Load Preset" in the main dialog
  2. Select a preset from the list
  3. Click "Select"

Managing Presets

  • View: See detailed settings for each preset
  • Edit: Modify parameters for existing presets
  • Delete: Remove presets that are no longer needed

Using Last Settings

The "Use Last Settings" button quickly reapplies:

  • The last manually configured settings, or
  • The last preset that was used

Note: Presets are stored in a presets.json file in the plugin directory and persist between QGIS sessions.

Technical Details

Integration Method

The plugin uses the grd2stream utility, which implements:

Supported File Formats

The plugin can work with any raster format supported by GDAL, including:

GeoTIFF
NetCDF
HDF5
GRIB
ASCII Grid
Many others

Tip: For NetCDF and similar multi-dimensional formats, you can select the specific variable by choosing the appropriate band in the input dialog.

Output Processing

Executes the grd2stream command with the specified parameters

Captures the command output (a text stream of coordinates and attributes)

Parses the output and converts it to a QGIS vector layer

Adds the vector layer to the current project

Troubleshooting

Common Issues

No Flowline Generated

Issue:

Plugin runs but no flowline appears

Possible causes:
  • Seed point placed in an area with zero or undefined values
  • Input rasters do not represent valid component data
  • Step size too large for the data resolution
Solutions:
  • Try a different seed point location
  • Verify raster data correctly represents X and Y component values
  • Reduce step size

Installation Problems

Issue:

Dependency installation fails

Possible causes:
  • Network connectivity issues
  • Insufficient disk space
  • Permission issues in home directory
Solutions:
  • Check internet connection
  • Ensure at least 1GB free disk space
  • Check QGIS Python console for detailed error messages

Windows Support

Issue:

Plugin shows command but doesn't execute it

Cause:

Windows execution support is still under development

Solution:

Currently not available; Windows support will be added in a future update

Checking Logs

For detailed troubleshooting, follow these steps to access and analyze plugin logs:

  1. Open the QGIS Python Console (Plugins → Python Console)
  2. Look for messages related to grd2stream
  3. Check detailed execution logs and error messages

Development Information

Plugin Structure

__init__.py

Plugin initialization

grd_2_stream.py

Main plugin class and QGIS integration

flowline_module.py

Core functionality

dialog_selection.py

UI for parameter selection

dialog_preset.py

UI for preset management

help_widget.py

Help documentation display

Contributing

Contributions to the plugin are welcome! Priority areas include:

Windows support implementation

License Information

Plugin License

The grd2stream QGIS plugin is licensed under the GNU General Public License v3.0 (GPL-3.0).

Third-Party Components

The plugin includes:

grd2stream command-line tool by Thomas Kleiner:

  • Licensed under the BSD 3-Clause License
  • See the full license text in lib/LICENSE.txt

Copyright

© 2013-2025 Abraham Wondimu, Anna Menshikova, Maxim Poliakov, Simon Povh & Thomas Kleiner