grd2stream QGIS Plugin - User Guide

What is grd2stream?

grd2stream is a QGIS plugin that generates flowlines from velocity grid data. It allows you to:

Select seed points to generate flowlines showing direction of flow
Work with various raster formats through GDAL compatibility
Configure flowline calculation parameters and save them as presets

Platform Support:

macOS/Linux: Fully supported
Windows: Currently in development; you can configure parameters but execution will only display the command needed

Getting Started

First-Time Setup

When you first run the plugin on Linux or macOS, it will check for required components:

If needed, the plugin will offer to install GMT6 (via Miniconda) into an isolated environment
It will also install the grd2stream command-line utility
These installations won't affect any existing GMT installations on your system

Basic Usage

Click the grd2stream icon in the QGIS toolbar
Select two raster layers representing X and Y velocity components
Configure your parameters (or load a preset)
Choose how to select your seed point (map click or manual coordinates)
The plugin will calculate and display the flowline as a vector layer

Configuration Options

Input Parameters

Parameter	Description	Default
Raster 1	X-component velocity grid	Required
Raster 2	Y-component velocity grid	Required
Backward Steps	Trace flowline in both upstream and downstream directions	Off
Step Size	Distance increment for integration steps	min(x_inc, y_inc) / 5
Max Integration Time	Maximum time for integration process	Unlimited
Max Steps	Maximum number of steps to calculate	10,000
Output Format	Data columns in output layer	x y dist

Output Formats

Default: x y dist (coordinates and distance along flowline)
Extended: x y dist v_x v_y (includes velocity components)
Full: x y dist v_x v_y time (includes integration time)

Working with Presets

Save time by storing and reusing configurations:

Save Preset: After configuring parameters, click "Save as Preset" and name it
Load Preset: Click "Load Preset" to select from saved configurations
Last Settings: Click "Use Last Settings" to quickly reapply previous configuration

Troubleshooting

Windows Users: Currently, the plugin can only display the command that would be executed. Full Windows support is under development.

Common Issues

No flowline generated: Ensure seed point is placed in an area with non-zero velocity data
Missing dependencies: Allow the plugin to install required components when prompted
Unexpected results: Verify that both input rasters have the same extent, resolution, and coordinate system

For detailed logs, check the QGIS Python console.

License Information

grd2stream QGIS plugin is licensed under GNU GPL v3.

The plugin includes the grd2stream command-line utility by Thomas Kleiner, licensed under the BSD 3-Clause License. See the full license text in lib/LICENSE.txt.